From eeba240bfa148050eaa588f737814f750bf2101f Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Mon, 17 Nov 2025 13:54:22 +0100
Subject: [PATCH 1/6] mining: add getCoinbase()

Introduce a new method intended to replace getCoinbaseTx(), which
provides a struct with everything clients need to construct a coinbase.
This is safer than providing a raw dummy coinbase that clients then have
to manipulate.

A new helper method ExtractCoinbaseTemplate() processes the dummy
coinbase transaction generated by BlockAssembler::CreateNewBlock
and produces a CoinbaseTemplate.

Expand the interface_ipc.py functional test to document its usage
and ensure equivalence.
---
 doc/release-notes-33819.md                   |   6 ++
 src/interfaces/mining.h                      |  16 +++
 src/ipc/capnp/mining.capnp                   |  11 ++
 src/node/interfaces.cpp                      |   9 ++
 src/node/miner.cpp                           |  45 +++++++++
 src/node/miner.h                             |  11 ++
 src/node/types.h                             |  42 ++++++++
 test/functional/interface_ipc.py             | 101 ++++++++++++++++++-
 test/functional/test_framework/blocktools.py |   4 +-
 9 files changed, 240 insertions(+), 5 deletions(-)
 create mode 100644 doc/release-notes-33819.md

diff --git a/doc/release-notes-33819.md b/doc/release-notes-33819.md
new file mode 100644
index 000000000000..7b04846085b5
--- /dev/null
+++ b/doc/release-notes-33819.md
@@ -0,0 +1,6 @@
+Mining IPC
+----------
+
+- Adds `getCoinbase()` which clients should use instead of `getCoinbaseTx()`. It
+  contains all fields required to construct a coinbase transaction, and omits the
+  dummy output which Bitcoin Core uses internally. (#33819)
diff --git a/src/interfaces/mining.h b/src/interfaces/mining.h
index 6e0376915d8a..a0efdba8d9c3 100644
--- a/src/interfaces/mining.h
+++ b/src/interfaces/mining.h
@@ -42,8 +42,24 @@ class BlockTemplate
     // Sigop cost per transaction, not including coinbase transaction.
     virtual std::vector<int64_t> getTxSigops() = 0;
 
+    /** Return fields needed to construct a coinbase transaction */
+    virtual node::CoinbaseTemplate getCoinbase() = 0;
+    /**
+     * Return dummy coinbase transaction.
+     *
+     * @note deprecated: use getCoinbase()
+     **/
     virtual CTransactionRef getCoinbaseTx() = 0;
+    /**
+     * Return scriptPubKey with SegWit OP_RETURN.
+     */
     virtual std::vector<unsigned char> getCoinbaseCommitment() = 0;
+    /**
+     * Return which output in the dummy coinbase contains the SegWit OP_RETURN.
+     *
+     * @note deprecated. Scan outputs from getCoinbase() outputs field for the
+     *       SegWit marker.
+     */
     virtual int getWitnessCommitmentIndex() = 0;
 
     /**
diff --git a/src/ipc/capnp/mining.capnp b/src/ipc/capnp/mining.capnp
index ed01e44a32aa..399c7e26eaff 100644
--- a/src/ipc/capnp/mining.capnp
+++ b/src/ipc/capnp/mining.capnp
@@ -27,6 +27,7 @@ interface BlockTemplate $Proxy.wrap("interfaces::BlockTemplate") {
     getBlock @2 (context: Proxy.Context) -> (result: Data);
     getTxFees @3 (context: Proxy.Context) -> (result: List(Int64));
     getTxSigops @4 (context: Proxy.Context) -> (result: List(Int64));
+    getCoinbase @12 (context: Proxy.Context) -> (result: CoinbaseTemplate);
     getCoinbaseTx @5 (context: Proxy.Context) -> (result: Data);
     getCoinbaseCommitment @6 (context: Proxy.Context) -> (result: Data);
     getWitnessCommitmentIndex @7 (context: Proxy.Context) -> (result: Int32);
@@ -51,3 +52,13 @@ struct BlockCheckOptions $Proxy.wrap("node::BlockCheckOptions") {
     checkMerkleRoot @0 :Bool $Proxy.name("check_merkle_root");
     checkPow @1 :Bool $Proxy.name("check_pow");
 }
+
+struct CoinbaseTemplate $Proxy.wrap("node::CoinbaseTemplate") {
+    version @0 :UInt32 $Proxy.name("version");
+    sequence @1 :UInt32 $Proxy.name("sequence");
+    scriptSigPrefix @2 :Data $Proxy.name("script_sig_prefix");
+    witness @3 :Data $Proxy.name("witness");
+    valueRemaining @4 :Int64 $Proxy.name("value_remaining");
+    requiredOutputs @5 :List(Data) $Proxy.name("required_outputs");
+    lockTime @6 :UInt32 $Proxy.name("lock_time");
+}
diff --git a/src/node/interfaces.cpp b/src/node/interfaces.cpp
index 059f4894f703..63ad02b93da3 100644
--- a/src/node/interfaces.cpp
+++ b/src/node/interfaces.cpp
@@ -83,6 +83,7 @@ using interfaces::Node;
 using interfaces::WalletLoader;
 using node::BlockAssembler;
 using node::BlockWaitOptions;
+using node::CoinbaseTemplate;
 using util::Join;
 
 namespace node {
@@ -863,6 +864,7 @@ class BlockTemplateImpl : public BlockTemplate
     explicit BlockTemplateImpl(BlockAssembler::Options assemble_options,
                                std::unique_ptr<CBlockTemplate> block_template,
                                NodeContext& node) : m_assemble_options(std::move(assemble_options)),
+                                                    m_coinbase_template(ExtractCoinbaseTemplate(*Assert(block_template))),
                                                     m_block_template(std::move(block_template)),
                                                     m_node(node)
     {
@@ -889,6 +891,11 @@ class BlockTemplateImpl : public BlockTemplate
         return m_block_template->vTxSigOpsCost;
     }
 
+    CoinbaseTemplate getCoinbase() override
+    {
+        return m_coinbase_template;
+    }
+
     CTransactionRef getCoinbaseTx() override
     {
         return m_block_template->block.vtx[0];
@@ -929,6 +936,8 @@ class BlockTemplateImpl : public BlockTemplate
 
     const BlockAssembler::Options m_assemble_options;
 
+    const CoinbaseTemplate m_coinbase_template;
+
     const std::unique_ptr<CBlockTemplate> m_block_template;
 
     bool m_interrupt_wait{false};
diff --git a/src/node/miner.cpp b/src/node/miner.cpp
index 14e5ce0a7be5..9a915a5f75d8 100644
--- a/src/node/miner.cpp
+++ b/src/node/miner.cpp
@@ -591,4 +591,49 @@ std::optional<BlockRef> WaitTipChanged(ChainstateManager& chainman, KernelNotifi
     // avoid deadlocks.
     return GetTip(chainman);
 }
+
+node::CoinbaseTemplate ExtractCoinbaseTemplate(const node::CBlockTemplate& block_template)
+{
+    CTransactionRef coinbase_tx{block_template.block.vtx[0]};
+    node::CoinbaseTemplate coinbase{};
+
+    coinbase.version = coinbase_tx->version;
+    Assert(coinbase_tx->vin.size() == 1);
+    coinbase.script_sig_prefix = coinbase_tx->vin[0].scriptSig;
+    // The CoinbaseTemplate interface guarantees a size limit. Raising it (e.g.
+    // if a future softfork needs to commit more than BIP34) is a
+    // (potentially silent) breaking change for clients.
+    if (!Assume(coinbase.script_sig_prefix.size() <= 8)) {
+        LogWarning("Unexpected %d byte scriptSig prefix size.",
+                    coinbase.script_sig_prefix.size());
+    }
+
+    if (coinbase_tx->HasWitness()) {
+        const auto& witness_stack{coinbase_tx->vin[0].scriptWitness.stack};
+        // Consensus requires the coinbase witness stack to have exactly one
+        // element of 32 bytes.
+        Assert(witness_stack.size() == 1 && witness_stack[0].size() == 32);
+        coinbase.witness = uint256(witness_stack[0]);
+    }
+
+    coinbase.sequence = coinbase_tx->vin[0].nSequence;
+
+    // Extract only OP_RETURN coinbase outputs (witness commitment, merge
+    // mining, etc). BlockAssembler::CreateNewBlock adds a dummy output with
+    // the full reward that we must exclude.
+    for (const auto& output : coinbase_tx->vout) {
+        if (!output.scriptPubKey.empty() && output.scriptPubKey[0] == OP_RETURN) {
+            coinbase.required_outputs.push_back(output);
+        } else {
+            // The (single) dummy coinbase output produced by CreateBlock() has
+            // an nValue set to nFee + the Block Subsidy.
+            Assume(coinbase.value_remaining == 0);
+            coinbase.value_remaining = output.nValue;
+        }
+    }
+
+    coinbase.lock_time = coinbase_tx->nLockTime;
+
+    return coinbase;
+}
 } // namespace node
diff --git a/src/node/miner.h b/src/node/miner.h
index 0790835d8f15..d80276029c61 100644
--- a/src/node/miner.h
+++ b/src/node/miner.h
@@ -259,6 +259,17 @@ std::optional<BlockRef> GetTip(ChainstateManager& chainman);
 /* Waits for the connected tip to change until timeout has elapsed. During node initialization, this will wait until the tip is connected (regardless of `timeout`).
  * Returns the current tip, or nullopt if the node is shutting down. */
 std::optional<BlockRef> WaitTipChanged(ChainstateManager& chainman, KernelNotifications& kernel_notifications, const uint256& current_tip, MillisecondsDouble& timeout);
+
+/*
+ * Extract relevant fields from the dummy coinbase transaction in the template.
+ *
+ * Extracts only OP_RETURN coinbase outputs, i.e. the witness commitment. If
+ * BlockAssembler::CreateNewBlock() is patched to add more OP_RETURN outputs
+ * e.g. for merge mining, those will be included. The dummy output that spends
+ * the full reward is excluded.
+ */
+node::CoinbaseTemplate ExtractCoinbaseTemplate(const node::CBlockTemplate& block_template);
+
 } // namespace node
 
 #endif // BITCOIN_NODE_MINER_H
diff --git a/src/node/types.h b/src/node/types.h
index 6c2687626c98..f7de25a7009e 100644
--- a/src/node/types.h
+++ b/src/node/types.h
@@ -16,10 +16,13 @@
 #include <consensus/amount.h>
 #include <cstddef>
 #include <cstdint>
+#include <optional>
 #include <policy/policy.h>
+#include <primitives/transaction.h>
 #include <script/script.h>
 #include <uint256.h>
 #include <util/time.h>
+#include <vector>
 
 namespace node {
 enum class TransactionError {
@@ -99,6 +102,45 @@ struct BlockCheckOptions {
     bool check_pow{true};
 };
 
+struct CoinbaseTemplate {
+    /* nVersion */
+    uint32_t version;
+    /* nSequence for the only coinbase transaction input */
+    uint32_t sequence;
+    /**
+     * Bytes which are to be placed at the beginning of scriptSig. Guaranteed
+     * to be less than 8 bytes (not including the length byte). This allows
+     * clients to add up to 92 bytes.
+     */
+    CScript script_sig_prefix;
+    /**
+     * The first (and only) witness stack element of the coinbase input.
+     *
+     * Omitted for block templates without witness data.
+     *
+     * This is currently the BIP 141 witness reserved value. A future soft fork
+     * may move the witness reserved value elsewhere, but there will still be a
+     * coinbase witness.
+     */
+    std::optional<uint256> witness;
+    /**
+     * Block subsidy plus fees, minus any non-zero required_outputs.
+     *
+     * Currently there are no non-zero required_outputs, see below.
+     */
+    CAmount value_remaining;
+    /*
+     * To be included as the last outputs in the coinbase transaction.
+     * Currently this is only the witness commitment OP_RETURN, but future
+     * softforks could add more.
+     * If a patch to BlockAssembler::CreateNewBlock() adds outputs e.g. for
+     * merge mining, those will be included. The dummy output that spends
+     * the full reward is excluded.
+     */
+    std::vector<CTxOut> required_outputs;
+    uint32_t lock_time;
+};
+
 /**
  * How to broadcast a local transaction.
  * Used to influence `BroadcastTransaction()` and its callers.
diff --git a/test/functional/interface_ipc.py b/test/functional/interface_ipc.py
index 230366495296..967e812feb78 100755
--- a/test/functional/interface_ipc.py
+++ b/test/functional/interface_ipc.py
@@ -4,16 +4,38 @@
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
 """Test the IPC (multiprocess) interface."""
 import asyncio
+from dataclasses import dataclass
 from io import BytesIO
 from pathlib import Path
 import shutil
-from test_framework.messages import (CBlock, CTransaction, ser_uint256, COIN)
+from test_framework.blocktools import NULL_OUTPOINT
+from test_framework.messages import (
+    CBlock,
+    CTransaction,
+    CTxIn,
+    CTxOut,
+    CTxInWitness,
+    ser_uint256,
+    COIN,
+)
 from test_framework.test_framework import BitcoinTestFramework
 from test_framework.util import (
     assert_equal,
     assert_not_equal
 )
 from test_framework.wallet import MiniWallet
+from typing import Optional
+
+# Stores the result of getCoinbase()
+@dataclass
+class CoinbaseTemplateData:
+    version: int
+    sequence: int
+    scriptSigPrefix: bytes
+    witness: Optional[bytes]
+    valueRemaining: int
+    requiredOutputs: list[bytes]
+    lockTime: int
 
 # Test may be skipped and not have capnp installed
 try:
@@ -88,6 +110,25 @@ async def parse_and_deserialize_coinbase_tx(self, block_template, ctx):
         tx.deserialize(coinbase_data)
         return tx
 
+    async def parse_and_deserialize_coinbase(self, block_template, ctx) -> CoinbaseTemplateData:
+        # Note: the template_capnp struct will be garbage-collected when this
+        # method returns, so it is important to copy any Data fields from it
+        # which need to be accessed later using the bytes() cast. Starting with
+        # pycapnp v2.2.0, Data fields have type `memoryview` and are ephemeral.
+        template_capnp = (await block_template.result.getCoinbase(ctx)).result
+        witness: Optional[bytes] = None
+        if template_capnp._has("witness"):
+            witness = bytes(template_capnp.witness)
+        return CoinbaseTemplateData(
+            version=int(template_capnp.version),
+            sequence=int(template_capnp.sequence),
+            scriptSigPrefix=bytes(template_capnp.scriptSigPrefix),
+            witness=witness,
+            valueRemaining=int(template_capnp.valueRemaining),
+            requiredOutputs=[bytes(output) for output in template_capnp.requiredOutputs],
+            lockTime=int(template_capnp.lockTime),
+        )
+
     def run_echo_test(self):
         self.log.info("Running echo test")
         async def async_routine():
@@ -102,6 +143,53 @@ async def async_routine():
             echo.destroy(ctx)
         asyncio.run(capnp.run(async_routine()))
 
+    async def build_coinbase_test(self, template, ctx, miniwallet):
+        self.log.debug("Build coinbase transaction using getCoinbase()")
+        coinbase_template = await self.parse_and_deserialize_coinbase(template, ctx)
+        coinbase = CTransaction()
+        coinbase.version = coinbase_template.version
+        coinbase.vin = [CTxIn()]
+        coinbase.vin[0].prevout = NULL_OUTPOINT
+        coinbase.vin[0].nSequence = coinbase_template.sequence
+        # Typically a mining pool appends its name and an extraNonce
+        coinbase.vin[0].scriptSig = coinbase_template.scriptSigPrefix
+
+        # We currently always provide a coinbase witness, even for empty
+        # blocks, but this may change, so always check:
+        has_witness = coinbase_template.witness is not None
+        if has_witness:
+            coinbase.wit.vtxinwit = [CTxInWitness()]
+            coinbase.wit.vtxinwit[0].scriptWitness.stack = [coinbase_template.witness]
+
+        # First output is our payout
+        coinbase.vout = [CTxOut()]
+        coinbase.vout[0].scriptPubKey = miniwallet.get_output_script()
+        coinbase.vout[0].nValue = coinbase_template.valueRemaining
+        # Add SegWit OP_RETURN. This is currently always present even for
+        # empty blocks, but this may change.
+        found_witness_op_return = False
+        # Compare SegWit OP_RETURN to getCoinbaseCommitment()
+        coinbase_commitment = (await template.result.getCoinbaseCommitment(ctx)).result
+        for output_data in coinbase_template.requiredOutputs:
+            output = CTxOut()
+            output.deserialize(BytesIO(output_data))
+            coinbase.vout.append(output)
+            if output.scriptPubKey == coinbase_commitment:
+                found_witness_op_return = True
+
+        assert_equal(has_witness, found_witness_op_return)
+
+        coinbase.nLockTime = coinbase_template.lockTime
+
+        # Compare to dummy coinbase provided by the deprecated getCoinbaseTx()
+        coinbase_legacy = await self.parse_and_deserialize_coinbase_tx(template, ctx)
+        assert_equal(coinbase_legacy.vout[0].nValue, coinbase_template.valueRemaining)
+        # Swap dummy output for our own
+        coinbase_legacy.vout[0].scriptPubKey = coinbase.vout[0].scriptPubKey
+        assert_equal(coinbase.serialize().hex(), coinbase_legacy.serialize().hex())
+
+        return coinbase
+
     def run_mining_test(self):
         self.log.info("Running mining test")
         block_hash_size = 32
@@ -150,6 +238,7 @@ async def async_routine():
             assert_equal(len(txfees.result), 0)
             txsigops = await template.result.getTxSigops(ctx)
             assert_equal(len(txsigops.result), 0)
+            # Inspect dummy coinbase returned by (deprecated) getCoinbaseTx()
             coinbase_data = BytesIO((await template.result.getCoinbaseTx(ctx)).result)
             coinbase = CTransaction()
             coinbase.deserialize(coinbase_data)
@@ -214,10 +303,13 @@ async def interrupt_wait():
             check_opts = self.capnp_modules['mining'].BlockCheckOptions()
             template = await mining.result.createNewBlock(opts)
             block = await self.parse_and_deserialize_block(template, ctx)
-            coinbase = await self.parse_and_deserialize_coinbase_tx(template, ctx)
-            balance = miniwallet.get_balance()
-            coinbase.vout[0].scriptPubKey = miniwallet.get_output_script()
+
+            coinbase = await self.build_coinbase_test(template, ctx, miniwallet)
+
+            # Reduce payout for balance comparison simplicity
             coinbase.vout[0].nValue = COIN
+            balance = miniwallet.get_balance()
+
             block.vtx[0] = coinbase
             block.hashMerkleRoot = block.calc_merkle_root()
             original_version = block.nVersion
@@ -276,6 +368,7 @@ async def interrupt_wait():
             template5.result.destroy(ctx)
             template6.result.destroy(ctx)
             template7.result.destroy(ctx)
+
         asyncio.run(capnp.run(async_routine()))
 
     def run_test(self):
diff --git a/test/functional/test_framework/blocktools.py b/test/functional/test_framework/blocktools.py
index eb1d3b0542b4..ffae22afde3b 100644
--- a/test/functional/test_framework/blocktools.py
+++ b/test/functional/test_framework/blocktools.py
@@ -63,6 +63,8 @@
 # From BIP141
 WITNESS_COMMITMENT_HEADER = b"\xaa\x21\xa9\xed"
 
+NULL_OUTPOINT = COutPoint(0, 0xffffffff)
+
 NORMAL_GBT_REQUEST_PARAMS = {"rules": ["segwit"]}
 VERSIONBITS_LAST_OLD_BLOCK_VERSION = 4
 MIN_BLOCKS_TO_KEEP = 288
@@ -154,7 +156,7 @@ def create_coinbase(height, pubkey=None, *, script_pubkey=None, extra_output_scr
     script. This is useful to pad block weight/sigops as needed. """
     coinbase = CTransaction()
     coinbase.nLockTime = height - 1
-    coinbase.vin.append(CTxIn(COutPoint(0, 0xffffffff), script_BIP34_coinbase_height(height), MAX_SEQUENCE_NONFINAL))
+    coinbase.vin.append(CTxIn(NULL_OUTPOINT, script_BIP34_coinbase_height(height), MAX_SEQUENCE_NONFINAL))
     coinbaseoutput = CTxOut()
     coinbaseoutput.nValue = nValue * COIN
     if nValue == 50:

From 1f0bf0407ab0b4a1e811576fd247ba928fd527cb Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Mon, 17 Nov 2025 10:37:54 +0100
Subject: [PATCH 2/6] mining: deprecate getCoinbaseCommitment()

Add default_witness_commitment to CoinbaseTemplate for use in the
getblocktemplate RPC.
---
 src/interfaces/mining.h          | 2 ++
 src/node/interfaces.cpp          | 1 +
 src/node/miner.cpp               | 2 ++
 src/node/types.h                 | 7 +++++++
 src/rpc/mining.cpp               | 5 +++--
 test/functional/interface_ipc.py | 9 +++++----
 6 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/src/interfaces/mining.h b/src/interfaces/mining.h
index a0efdba8d9c3..1e1c3341cdce 100644
--- a/src/interfaces/mining.h
+++ b/src/interfaces/mining.h
@@ -52,6 +52,8 @@ class BlockTemplate
     virtual CTransactionRef getCoinbaseTx() = 0;
     /**
      * Return scriptPubKey with SegWit OP_RETURN.
+     *
+     * @note deprecated: use the required_outputs field from getCoinbase()
      */
     virtual std::vector<unsigned char> getCoinbaseCommitment() = 0;
     /**
diff --git a/src/node/interfaces.cpp b/src/node/interfaces.cpp
index 63ad02b93da3..27ccd68d33db 100644
--- a/src/node/interfaces.cpp
+++ b/src/node/interfaces.cpp
@@ -903,6 +903,7 @@ class BlockTemplateImpl : public BlockTemplate
 
     std::vector<unsigned char> getCoinbaseCommitment() override
     {
+        Assume(m_coinbase_template.default_witness_commitment == m_block_template->vchCoinbaseCommitment);
         return m_block_template->vchCoinbaseCommitment;
     }
 
diff --git a/src/node/miner.cpp b/src/node/miner.cpp
index 9a915a5f75d8..60463dd7b9df 100644
--- a/src/node/miner.cpp
+++ b/src/node/miner.cpp
@@ -634,6 +634,8 @@ node::CoinbaseTemplate ExtractCoinbaseTemplate(const node::CBlockTemplate& block
 
     coinbase.lock_time = coinbase_tx->nLockTime;
 
+    coinbase.default_witness_commitment = block_template.vchCoinbaseCommitment;
+
     return coinbase;
 }
 } // namespace node
diff --git a/src/node/types.h b/src/node/types.h
index f7de25a7009e..735755e39d28 100644
--- a/src/node/types.h
+++ b/src/node/types.h
@@ -139,6 +139,13 @@ struct CoinbaseTemplate {
      */
     std::vector<CTxOut> required_outputs;
     uint32_t lock_time;
+
+    /**
+     * Default witness commitment
+     *
+     * For getblocktemplate RPC, not exposed via IPC.
+     */
+    std::vector<unsigned char> default_witness_commitment;
 };
 
 /**
diff --git a/src/rpc/mining.cpp b/src/rpc/mining.cpp
index 2639b9161298..2fa9f79c2ca8 100644
--- a/src/rpc/mining.cpp
+++ b/src/rpc/mining.cpp
@@ -1015,8 +1015,9 @@ static RPCHelpMan getblocktemplate()
         result.pushKV("signet_challenge", HexStr(consensusParams.signet_challenge));
     }
 
-    if (!block_template->getCoinbaseCommitment().empty()) {
-        result.pushKV("default_witness_commitment", HexStr(block_template->getCoinbaseCommitment()));
+    auto default_witness_commitment{block_template->getCoinbase().default_witness_commitment};
+    if (!default_witness_commitment.empty()) {
+        result.pushKV("default_witness_commitment", HexStr(default_witness_commitment));
     }
 
     return result;
diff --git a/test/functional/interface_ipc.py b/test/functional/interface_ipc.py
index 967e812feb78..41f4cb9ff455 100755
--- a/test/functional/interface_ipc.py
+++ b/test/functional/interface_ipc.py
@@ -8,7 +8,10 @@
 from io import BytesIO
 from pathlib import Path
 import shutil
-from test_framework.blocktools import NULL_OUTPOINT
+from test_framework.blocktools import (
+    NULL_OUTPOINT,
+    WITNESS_COMMITMENT_HEADER,
+)
 from test_framework.messages import (
     CBlock,
     CTransaction,
@@ -168,13 +171,11 @@ async def build_coinbase_test(self, template, ctx, miniwallet):
         # Add SegWit OP_RETURN. This is currently always present even for
         # empty blocks, but this may change.
         found_witness_op_return = False
-        # Compare SegWit OP_RETURN to getCoinbaseCommitment()
-        coinbase_commitment = (await template.result.getCoinbaseCommitment(ctx)).result
         for output_data in coinbase_template.requiredOutputs:
             output = CTxOut()
             output.deserialize(BytesIO(output_data))
             coinbase.vout.append(output)
-            if output.scriptPubKey == coinbase_commitment:
+            if len(output.scriptPubKey) >= 6 and output.scriptPubKey[2:6] == WITNESS_COMMITMENT_HEADER:
                 found_witness_op_return = True
 
         assert_equal(has_witness, found_witness_op_return)

From 91503e4e5051b02aa36683d67fc09270702f180c Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Mon, 17 Nov 2025 10:36:12 +0100
Subject: [PATCH 3/6] mining: drop getCoinbaseTx(), etc

Drop the following mining interface methods in favor of getCoinbase():

- getCoinbaseTx()
- getCoinbaseCommitment()
- getWitnessCommitmentIndex()
---
 src/interfaces/mining.h          | 29 ++++++++++-------------------
 src/ipc/capnp/mining.capnp       |  9 ++++++---
 src/node/interfaces.cpp          | 16 ----------------
 test/functional/interface_ipc.py | 12 ------------
 4 files changed, 16 insertions(+), 50 deletions(-)

diff --git a/src/interfaces/mining.h b/src/interfaces/mining.h
index 1e1c3341cdce..521ec5ade14a 100644
--- a/src/interfaces/mining.h
+++ b/src/interfaces/mining.h
@@ -44,25 +44,16 @@ class BlockTemplate
 
     /** Return fields needed to construct a coinbase transaction */
     virtual node::CoinbaseTemplate getCoinbase() = 0;
-    /**
-     * Return dummy coinbase transaction.
-     *
-     * @note deprecated: use getCoinbase()
-     **/
-    virtual CTransactionRef getCoinbaseTx() = 0;
-    /**
-     * Return scriptPubKey with SegWit OP_RETURN.
-     *
-     * @note deprecated: use the required_outputs field from getCoinbase()
-     */
-    virtual std::vector<unsigned char> getCoinbaseCommitment() = 0;
-    /**
-     * Return which output in the dummy coinbase contains the SegWit OP_RETURN.
-     *
-     * @note deprecated. Scan outputs from getCoinbase() outputs field for the
-     *       SegWit marker.
-     */
-    virtual int getWitnessCommitmentIndex() = 0;
+
+    virtual void getCoinbaseTx() {
+        throw std::runtime_error("Old mining interface (@5) not supported. Please update your client!");
+    }
+    virtual void getCoinbaseCommitment() {
+        throw std::runtime_error("Old mining interface (@6) not supported. Please update your client!");
+    };
+    virtual void getWitnessCommitmentIndex() {
+        throw std::runtime_error("Old mining interface (@7) not supported. Please update your client!");
+    }
 
     /**
      * Compute merkle path to the coinbase transaction
diff --git a/src/ipc/capnp/mining.capnp b/src/ipc/capnp/mining.capnp
index 399c7e26eaff..c50eba9da7f4 100644
--- a/src/ipc/capnp/mining.capnp
+++ b/src/ipc/capnp/mining.capnp
@@ -28,9 +28,12 @@ interface BlockTemplate $Proxy.wrap("interfaces::BlockTemplate") {
     getTxFees @3 (context: Proxy.Context) -> (result: List(Int64));
     getTxSigops @4 (context: Proxy.Context) -> (result: List(Int64));
     getCoinbase @12 (context: Proxy.Context) -> (result: CoinbaseTemplate);
-    getCoinbaseTx @5 (context: Proxy.Context) -> (result: Data);
-    getCoinbaseCommitment @6 (context: Proxy.Context) -> (result: Data);
-    getWitnessCommitmentIndex @7 (context: Proxy.Context) -> (result: Int32);
+
+    # DEPRECATED in favor of getCoinbase(), server returns an error:
+    getCoinbaseTx @5 () -> ();
+    getCoinbaseCommitment @6 () -> ();
+    getWitnessCommitmentIndex @7 () -> ();
+
     getCoinbaseMerklePath @8 (context: Proxy.Context) -> (result: List(Data));
     submitSolution @9 (context: Proxy.Context, version: UInt32, timestamp: UInt32, nonce: UInt32, coinbase :Data) -> (result: Bool);
     waitNext @10 (context: Proxy.Context, options: BlockWaitOptions) -> (result: BlockTemplate);
diff --git a/src/node/interfaces.cpp b/src/node/interfaces.cpp
index 27ccd68d33db..70e034f31f4e 100644
--- a/src/node/interfaces.cpp
+++ b/src/node/interfaces.cpp
@@ -896,22 +896,6 @@ class BlockTemplateImpl : public BlockTemplate
         return m_coinbase_template;
     }
 
-    CTransactionRef getCoinbaseTx() override
-    {
-        return m_block_template->block.vtx[0];
-    }
-
-    std::vector<unsigned char> getCoinbaseCommitment() override
-    {
-        Assume(m_coinbase_template.default_witness_commitment == m_block_template->vchCoinbaseCommitment);
-        return m_block_template->vchCoinbaseCommitment;
-    }
-
-    int getWitnessCommitmentIndex() override
-    {
-        return GetWitnessCommitmentIndex(m_block_template->block);
-    }
-
     std::vector<uint256> getCoinbaseMerklePath() override
     {
         return TransactionMerklePath(m_block_template->block, 0);
diff --git a/test/functional/interface_ipc.py b/test/functional/interface_ipc.py
index 41f4cb9ff455..a503dacef3a7 100755
--- a/test/functional/interface_ipc.py
+++ b/test/functional/interface_ipc.py
@@ -182,13 +182,6 @@ async def build_coinbase_test(self, template, ctx, miniwallet):
 
         coinbase.nLockTime = coinbase_template.lockTime
 
-        # Compare to dummy coinbase provided by the deprecated getCoinbaseTx()
-        coinbase_legacy = await self.parse_and_deserialize_coinbase_tx(template, ctx)
-        assert_equal(coinbase_legacy.vout[0].nValue, coinbase_template.valueRemaining)
-        # Swap dummy output for our own
-        coinbase_legacy.vout[0].scriptPubKey = coinbase.vout[0].scriptPubKey
-        assert_equal(coinbase.serialize().hex(), coinbase_legacy.serialize().hex())
-
         return coinbase
 
     def run_mining_test(self):
@@ -239,11 +232,6 @@ async def async_routine():
             assert_equal(len(txfees.result), 0)
             txsigops = await template.result.getTxSigops(ctx)
             assert_equal(len(txsigops.result), 0)
-            # Inspect dummy coinbase returned by (deprecated) getCoinbaseTx()
-            coinbase_data = BytesIO((await template.result.getCoinbaseTx(ctx)).result)
-            coinbase = CTransaction()
-            coinbase.deserialize(coinbase_data)
-            assert_equal(coinbase.vin[0].prevout.hash, 0)
             self.log.debug("Wait for a new template")
             waitoptions = self.capnp_modules['mining'].BlockWaitOptions()
             waitoptions.timeout = timeout

From 2ece972a3f78cb7faaf75b6271016316ead572f4 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Fri, 14 Nov 2025 10:55:44 +0100
Subject: [PATCH 4/6] mining: clear dummy coinbase by default

Clear dummy coinbase from block templates by default so it's not exposed to callers of getBlock().

Have RPC and test code opt-in to keeping the dummy coinbase where needed.
---
 src/node/interfaces.cpp  |  6 ++++++
 src/node/types.h         |  8 ++++++++
 src/rpc/mining.cpp       | 13 ++++++++++---
 src/test/miner_tests.cpp |  1 +
 4 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/src/node/interfaces.cpp b/src/node/interfaces.cpp
index 70e034f31f4e..e850d00f9dfd 100644
--- a/src/node/interfaces.cpp
+++ b/src/node/interfaces.cpp
@@ -869,6 +869,12 @@ class BlockTemplateImpl : public BlockTemplate
                                                     m_node(node)
     {
         assert(m_block_template);
+
+        if (m_assemble_options.clear_coinbase) {
+            // Clear dummy coinbase so it's not exposed to callers of getBlock()
+            CMutableTransaction empty_tx;
+            m_block_template->block.vtx[0] = MakeTransactionRef(std::move(empty_tx));
+        }
     }
 
     CBlockHeader getBlockHeader() override
diff --git a/src/node/types.h b/src/node/types.h
index 735755e39d28..088423cdfb18 100644
--- a/src/node/types.h
+++ b/src/node/types.h
@@ -67,6 +67,14 @@ struct BlockCreateOptions {
      * coinbase_max_additional_weight and coinbase_output_max_additional_sigops.
      */
     CScript coinbase_output_script{CScript() << OP_TRUE};
+    /**
+     * Whether to clear the dummy coinbase from the block template.
+     *
+     * IPC clients are expected to call getCoinbase() rather than use the dummy
+     * transaction directly. It's cleared by default, but RPC and test code
+     * can opt-in to keeping it.
+     */
+    bool clear_coinbase{true};
 };
 
 struct BlockWaitOptions {
diff --git a/src/rpc/mining.cpp b/src/rpc/mining.cpp
index 2fa9f79c2ca8..fce99e8084e6 100644
--- a/src/rpc/mining.cpp
+++ b/src/rpc/mining.cpp
@@ -165,7 +165,10 @@ static UniValue generateBlocks(ChainstateManager& chainman, Mining& miner, const
 {
     UniValue blockHashes(UniValue::VARR);
     while (nGenerate > 0 && !chainman.m_interrupt) {
-        std::unique_ptr<BlockTemplate> block_template(miner.createNewBlock({ .coinbase_output_script = coinbase_output_script }));
+        std::unique_ptr<BlockTemplate> block_template(miner.createNewBlock({
+            .coinbase_output_script = coinbase_output_script,
+            .clear_coinbase = false
+        }));
         CHECK_NONFATAL(block_template);
 
         std::shared_ptr<const CBlock> block_out;
@@ -376,7 +379,11 @@ static RPCHelpMan generateblock()
     {
         LOCK(chainman.GetMutex());
         {
-            std::unique_ptr<BlockTemplate> block_template{miner.createNewBlock({.use_mempool = false, .coinbase_output_script = coinbase_output_script})};
+            std::unique_ptr<BlockTemplate> block_template{miner.createNewBlock({
+                .use_mempool = false,
+                .coinbase_output_script = coinbase_output_script,
+                .clear_coinbase = false
+            })};
             CHECK_NONFATAL(block_template);
 
             block = block_template->getBlock();
@@ -871,7 +878,7 @@ static RPCHelpMan getblocktemplate()
         time_start = GetTime();
 
         // Create new block
-        block_template = miner.createNewBlock();
+        block_template = miner.createNewBlock({.clear_coinbase = false});
         CHECK_NONFATAL(block_template);
 
 
diff --git a/src/test/miner_tests.cpp b/src/test/miner_tests.cpp
index a3c576dd2a3b..b33825aeb93c 100644
--- a/src/test/miner_tests.cpp
+++ b/src/test/miner_tests.cpp
@@ -692,6 +692,7 @@ BOOST_AUTO_TEST_CASE(CreateNewBlock_validity)
     CScript scriptPubKey = CScript() << "04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f"_hex << OP_CHECKSIG;
     BlockAssembler::Options options;
     options.coinbase_output_script = scriptPubKey;
+    options.clear_coinbase = false;
 
     // Create and check a simple template
     std::unique_ptr<BlockTemplate> block_template = mining->createNewBlock(options);

From 99ead21f40dea2982cfb808dfab9923b39345635 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Tue, 4 Nov 2025 15:52:45 +0100
Subject: [PATCH 5/6] ipc: pass missing context to Mining methods

Adding a context parameter ensures that these methods are run in
their own thread and don't block other calls.

This is especially important for checkBlock() which may receive a
slow to validate block from an untrusted origin (the IPC connection
itself is assumed to trusted).

This is a breaking change both ways:
- clients must use the updated capnp file
- updated clients can't call these methods
  on an unupgraded node
---
 src/ipc/capnp/mining.capnp       |  4 ++--
 test/functional/interface_ipc.py | 10 +++++-----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/ipc/capnp/mining.capnp b/src/ipc/capnp/mining.capnp
index c50eba9da7f4..bd0da922936d 100644
--- a/src/ipc/capnp/mining.capnp
+++ b/src/ipc/capnp/mining.capnp
@@ -17,8 +17,8 @@ interface Mining $Proxy.wrap("interfaces::Mining") {
     isInitialBlockDownload @1 (context :Proxy.Context) -> (result: Bool);
     getTip @2 (context :Proxy.Context) -> (result: Common.BlockRef, hasResult: Bool);
     waitTipChanged @3 (context :Proxy.Context, currentTip: Data, timeout: Float64) -> (result: Common.BlockRef);
-    createNewBlock @4 (options: BlockCreateOptions) -> (result: BlockTemplate);
-    checkBlock @5 (block: Data, options: BlockCheckOptions) -> (reason: Text, debug: Text, result: Bool);
+    createNewBlock @4 (context :Proxy.Context, options: BlockCreateOptions) -> (result: BlockTemplate);
+    checkBlock @5 (context :Proxy.Context, block: Data, options: BlockCheckOptions) -> (reason: Text, debug: Text, result: Bool);
 }
 
 interface BlockTemplate $Proxy.wrap("interfaces::BlockTemplate") {
diff --git a/test/functional/interface_ipc.py b/test/functional/interface_ipc.py
index a503dacef3a7..f5b7537d8aeb 100755
--- a/test/functional/interface_ipc.py
+++ b/test/functional/interface_ipc.py
@@ -221,7 +221,7 @@ async def async_routine():
             opts.useMempool = True
             opts.blockReservedWeight = 4000
             opts.coinbaseOutputMaxAdditionalSigops = 0
-            template = mining.result.createNewBlock(opts)
+            template = mining.result.createNewBlock(ctx, opts)
             self.log.debug("Test some inspectors of Template")
             header = await template.result.getBlockHeader(ctx)
             assert_equal(len(header.result), block_header_size)
@@ -290,7 +290,7 @@ async def interrupt_wait():
 
             current_block_height = self.nodes[0].getchaintips()[0]["height"]
             check_opts = self.capnp_modules['mining'].BlockCheckOptions()
-            template = await mining.result.createNewBlock(opts)
+            template = await mining.result.createNewBlock(ctx, opts)
             block = await self.parse_and_deserialize_block(template, ctx)
 
             coinbase = await self.build_coinbase_test(template, ctx, miniwallet)
@@ -305,7 +305,7 @@ async def interrupt_wait():
             self.log.debug("Submit a block with a bad version")
             block.nVersion = 0
             block.solve()
-            res = await mining.result.checkBlock(block.serialize(), check_opts)
+            res = await mining.result.checkBlock(ctx, block.serialize(), check_opts)
             assert_equal(res.result, False)
             assert_equal(res.reason, "bad-version(0x00000000)")
             res = await template.result.submitSolution(ctx, block.nVersion, block.nTime, block.nNonce, coinbase.serialize())
@@ -315,7 +315,7 @@ async def interrupt_wait():
             block.solve()
 
             self.log.debug("First call checkBlock()")
-            res = await mining.result.checkBlock(block.serialize(), check_opts)
+            res = await mining.result.checkBlock(ctx, block.serialize(), check_opts)
             assert_equal(res.result, True)
 
             # The remote template block will be mutated, capture the original:
@@ -345,7 +345,7 @@ async def interrupt_wait():
             miniwallet.rescan_utxos()
             assert_equal(miniwallet.get_balance(), balance + 1)
             self.log.debug("Check block should fail now, since it is a duplicate")
-            res = await mining.result.checkBlock(block.serialize(), check_opts)
+            res = await mining.result.checkBlock(ctx, block.serialize(), check_opts)
             assert_equal(res.result, False)
             assert_equal(res.reason, "inconclusive-not-best-prevblk")
 

From 40d1886584d3d7c89fa5656e325222edd51c2f89 Mon Sep 17 00:00:00 2001
From: Sjors Provoost <sjors@sprovoost.nl>
Date: Mon, 17 Nov 2025 15:54:53 +0100
Subject: [PATCH 6/6] mining: make non-mandatory coinbase commitment opt-in

Previously the dummy coinbase returned by the Mining IPC interface
always had a witness and SegWit OP_RETURN output. This is unnecessary
for empty blocks as well as for blocks without any SegWit spends.

This commit makes this behavior configurable via
always_add_coinbase_commitment on BlockCreateOptions. It defaults to false,
making this a potentially breaking change to clients. The presence of this
field in requests makes it incompatible with Bitcoin Core v30, so it's a
breaking change in any case.

Preserve historical getblocktemplate RPC behavior. Although it doesn't return a
coinbase transaction, it does always provide a default_witness_commitment. This
is set in BlockAssembler::CreateNewBlock() via a call GenerateCoinbaseCommitment(),
which has the side-effect of adding a coinbase witness.
---
 src/ipc/capnp/mining.capnp          |  1 +
 src/node/miner.cpp                  |  7 ++++++-
 src/node/types.h                    |  9 +++++++++
 src/rpc/mining.cpp                  | 11 ++++++++---
 src/test/fuzz/utxo_total_supply.cpp |  1 +
 src/test/util/setup_common.cpp      |  1 +
 test/functional/interface_ipc.py    | 25 +++++++++++++++++++------
 7 files changed, 45 insertions(+), 10 deletions(-)

diff --git a/src/ipc/capnp/mining.capnp b/src/ipc/capnp/mining.capnp
index bd0da922936d..56813594ecc0 100644
--- a/src/ipc/capnp/mining.capnp
+++ b/src/ipc/capnp/mining.capnp
@@ -44,6 +44,7 @@ struct BlockCreateOptions $Proxy.wrap("node::BlockCreateOptions") {
     useMempool @0 :Bool $Proxy.name("use_mempool");
     blockReservedWeight @1 :UInt64 $Proxy.name("block_reserved_weight");
     coinbaseOutputMaxAdditionalSigops @2 :UInt64 $Proxy.name("coinbase_output_max_additional_sigops");
+    alwaysAddCoinbaseCommitment @3 :Bool $Proxy.name("always_add_coinbase_commitment");
 }
 
 struct BlockWaitOptions $Proxy.wrap("node::BlockWaitOptions") {
diff --git a/src/node/miner.cpp b/src/node/miner.cpp
index 60463dd7b9df..28032131d26c 100644
--- a/src/node/miner.cpp
+++ b/src/node/miner.cpp
@@ -169,7 +169,12 @@ std::unique_ptr<CBlockTemplate> BlockAssembler::CreateNewBlock()
     Assert(nHeight > 0);
     coinbaseTx.nLockTime = static_cast<uint32_t>(nHeight - 1);
     pblock->vtx[0] = MakeTransactionRef(std::move(coinbaseTx));
-    pblocktemplate->vchCoinbaseCommitment = m_chainstate.m_chainman.GenerateCoinbaseCommitment(*pblock, pindexPrev);
+    if (m_options.always_add_coinbase_commitment || std::any_of(
+        pblock->vtx.begin(), pblock->vtx.end(),
+        [&](const CTransactionRef tx) { return tx->HasWitness(); }
+    )) {
+        pblocktemplate->vchCoinbaseCommitment = m_chainstate.m_chainman.GenerateCoinbaseCommitment(*pblock, pindexPrev);
+    }
 
     LogPrintf("CreateNewBlock(): block weight: %u txs: %u fees: %ld sigops %d\n", GetBlockWeight(*pblock), nBlockTx, nFees, nBlockSigOpsCost);
 
diff --git a/src/node/types.h b/src/node/types.h
index 088423cdfb18..6e9cf041f2a5 100644
--- a/src/node/types.h
+++ b/src/node/types.h
@@ -67,6 +67,7 @@ struct BlockCreateOptions {
      * coinbase_max_additional_weight and coinbase_output_max_additional_sigops.
      */
     CScript coinbase_output_script{CScript() << OP_TRUE};
+
     /**
      * Whether to clear the dummy coinbase from the block template.
      *
@@ -75,6 +76,14 @@ struct BlockCreateOptions {
      * can opt-in to keeping it.
      */
     bool clear_coinbase{true};
+
+    /*
+     * Whether blocks without SegWit transactions (e.g. empty blocks) should
+     * have a SegWit commitment, i.e. the coinbase witness and OP_RETURN.
+     *
+     * @note IPC clients should omit this field for compatibility with v30.0
+     */
+    bool always_add_coinbase_commitment{false};
 };
 
 struct BlockWaitOptions {
diff --git a/src/rpc/mining.cpp b/src/rpc/mining.cpp
index fce99e8084e6..322def0b7214 100644
--- a/src/rpc/mining.cpp
+++ b/src/rpc/mining.cpp
@@ -167,7 +167,8 @@ static UniValue generateBlocks(ChainstateManager& chainman, Mining& miner, const
     while (nGenerate > 0 && !chainman.m_interrupt) {
         std::unique_ptr<BlockTemplate> block_template(miner.createNewBlock({
             .coinbase_output_script = coinbase_output_script,
-            .clear_coinbase = false
+            .clear_coinbase = false,
+            .always_add_coinbase_commitment = true
         }));
         CHECK_NONFATAL(block_template);
 
@@ -382,7 +383,8 @@ static RPCHelpMan generateblock()
             std::unique_ptr<BlockTemplate> block_template{miner.createNewBlock({
                 .use_mempool = false,
                 .coinbase_output_script = coinbase_output_script,
-                .clear_coinbase = false
+                .clear_coinbase = false,
+                .always_add_coinbase_commitment = true
             })};
             CHECK_NONFATAL(block_template);
 
@@ -878,7 +880,10 @@ static RPCHelpMan getblocktemplate()
         time_start = GetTime();
 
         // Create new block
-        block_template = miner.createNewBlock({.clear_coinbase = false});
+        block_template = miner.createNewBlock({
+            .clear_coinbase = false,
+            .always_add_coinbase_commitment = true
+        });
         CHECK_NONFATAL(block_template);
 
 
diff --git a/src/test/fuzz/utxo_total_supply.cpp b/src/test/fuzz/utxo_total_supply.cpp
index 1348962ad5cd..94ba99398669 100644
--- a/src/test/fuzz/utxo_total_supply.cpp
+++ b/src/test/fuzz/utxo_total_supply.cpp
@@ -45,6 +45,7 @@ FUZZ_TARGET(utxo_total_supply)
     };
     BlockAssembler::Options options;
     options.coinbase_output_script = CScript() << OP_FALSE;
+    options.always_add_coinbase_commitment = true;
     const auto PrepareNextBlock = [&]() {
         // Use OP_FALSE to avoid BIP30 check from hitting early
         auto block = PrepareBlock(node, options);
diff --git a/src/test/util/setup_common.cpp b/src/test/util/setup_common.cpp
index 21a67bc2902b..089014c7119b 100644
--- a/src/test/util/setup_common.cpp
+++ b/src/test/util/setup_common.cpp
@@ -404,6 +404,7 @@ CBlock TestChain100Setup::CreateBlock(
 {
     BlockAssembler::Options options;
     options.coinbase_output_script = scriptPubKey;
+    options.always_add_coinbase_commitment = true;
     CBlock block = BlockAssembler{chainstate, nullptr, options}.CreateNewBlock()->block;
 
     Assert(block.vtx.size() == 1);
diff --git a/test/functional/interface_ipc.py b/test/functional/interface_ipc.py
index f5b7537d8aeb..f5526b794623 100755
--- a/test/functional/interface_ipc.py
+++ b/test/functional/interface_ipc.py
@@ -146,8 +146,10 @@ async def async_routine():
             echo.destroy(ctx)
         asyncio.run(capnp.run(async_routine()))
 
-    async def build_coinbase_test(self, template, ctx, miniwallet):
-        self.log.debug("Build coinbase transaction using getCoinbase()")
+    async def build_coinbase_test(self, template, ctx, miniwallet, *, expect_witness: bool):
+        self.log.debug("Build coinbase transaction using getCoinbase() " +
+                       ("with" if expect_witness else "without") + " a witness")
+
         coinbase_template = await self.parse_and_deserialize_coinbase(template, ctx)
         coinbase = CTransaction()
         coinbase.version = coinbase_template.version
@@ -168,8 +170,7 @@ async def build_coinbase_test(self, template, ctx, miniwallet):
         coinbase.vout = [CTxOut()]
         coinbase.vout[0].scriptPubKey = miniwallet.get_output_script()
         coinbase.vout[0].nValue = coinbase_template.valueRemaining
-        # Add SegWit OP_RETURN. This is currently always present even for
-        # empty blocks, but this may change.
+        # Add SegWit OP_RETURN if provided
         found_witness_op_return = False
         for output_data in coinbase_template.requiredOutputs:
             output = CTxOut()
@@ -179,6 +180,7 @@ async def build_coinbase_test(self, template, ctx, miniwallet):
                 found_witness_op_return = True
 
         assert_equal(has_witness, found_witness_op_return)
+        assert_equal(has_witness, expect_witness)
 
         coinbase.nLockTime = coinbase_template.lockTime
 
@@ -227,7 +229,17 @@ async def async_routine():
             assert_equal(len(header.result), block_header_size)
             block = await self.parse_and_deserialize_block(template, ctx)
             assert_equal(ser_uint256(block.hashPrevBlock), newblockref.result.hash)
-            assert len(block.vtx) >= 1
+
+            # Template block.vtx only contains a (dummy) coinbase
+            assert_equal(len(block.vtx), 1)
+            # Check that coinbase for an empty block doesn't have a witness")
+            await self.build_coinbase_test(template, ctx, miniwallet, expect_witness=False)
+            # Unless requested otherwise
+            opts.alwaysAddCoinbaseCommitment = True
+            template = mining.result.createNewBlock(ctx, opts)
+            await self.build_coinbase_test(template, ctx, miniwallet, expect_witness=True)
+            opts.alwaysAddCoinbaseCommitment = False
+
             txfees = await template.result.getTxFees(ctx)
             assert_equal(len(txfees.result), 0)
             txsigops = await template.result.getTxSigops(ctx)
@@ -262,6 +274,7 @@ async def async_routine():
             template6 = await waitnext
             block4 = await self.parse_and_deserialize_block(template6, ctx)
             assert_equal(len(block4.vtx), 3)
+
             self.log.debug("Wait for another, but time out, since the fee threshold is set now")
             template7 = await template6.result.waitNext(ctx, waitoptions)
             assert_equal(template7.to_dict(), {})
@@ -293,7 +306,7 @@ async def interrupt_wait():
             template = await mining.result.createNewBlock(ctx, opts)
             block = await self.parse_and_deserialize_block(template, ctx)
 
-            coinbase = await self.build_coinbase_test(template, ctx, miniwallet)
+            coinbase = await self.build_coinbase_test(template, ctx, miniwallet, expect_witness=True)
 
             # Reduce payout for balance comparison simplicity
             coinbase.vout[0].nValue = COIN