on a potential soft-fork that changes consensus around Coinbase witness

[plebhash]

This started as a discussion on #153.

The discussion started to go in the direction of potential spec changes (similar to what was proposed in #15). Given that the original goal of #153 was simply to establish some conventions without changing spec, I'm bringing those discussion points here so we can proceed with #153 while sticking to its original scope.

[plebhash]

BIP141 has a section called Commitment structure that says the following:

The commitment is recorded in a scriptPubKey of the coinbase transaction. It must be at least 38 bytes, with the first 6-byte of 0x6a24aa21a9ed, that is:

  1-byte - OP_RETURN (0x6a)
  1-byte - Push the following 36 bytes (0x24)
  4-byte - Commitment header (0xaa21a9ed)
 32-byte - Commitment hash: Double-SHA256(witness root hash|witness reserved value)

39th byte onwards: Optional data with no consensus meaning

and the coinbase's input's witness must consist of a single 32-byte array for the witness reserved value.

If there are more than one scriptPubKey matching the pattern, the one with highest output index is assumed to be the commitment.

If all transactions in a block do not have witness data, the commitment is optional.

The commitment hash takes the Coinbase's witness reserved value as part of its pre-image.

On most mainnet blocks today, that is TIPICALLY 0x000...000.

---

BIP141 also has a section called Extensible commitment structure that says:

The new commitment in coinbase transaction is a hash of the witness root hash and a witness reserved value. The witness reserved value currently has no consensus meaning, but in the future allows new commitment values for future softforks. For example, if a new consensus-critical commitment is required in the future, the commitment in coinbase becomes:

 Double-SHA256(Witness root hash|Hash(new commitment|witness reserved value))

For backward compatibility, the Hash(new commitment|witness reserved value) will go to the coinbase witness, and the witness reserved value will be recorded in another location specified by the future softfork. Any number of new commitment could be added in this way.

which means this field could eventually carry something different than 0x000...000.

---

Now the problem with the current Sv2 Template Distribution Protocol:

We expect the Template Provider to provide the witness commitment on NewTemplate.coinbase_tx_outputs. This is a reasonable design decision, given that forcing other Sv2 roles (e.g.: Pool or JDC) to calculate the witness commitment would delay job creation due to:

• a RequestTransactionData/.Success round-trip would be necessary
• we'd have to wait for the calculation of the Witness Root

But these Sv2 roles also need to construct the Coinbase transaction, and in that process they need to decide what the witness will look like.

Today, writing 0x000...000 is a safe assumption, simply because we can ASSUME that's what TP is going to send.

But eventually this field might start carrying consensus-critical meaning due to some soft-fork. When that day comes, Sv2 roles will have no way to know what value they should use for Coinbase witness so that it matches the pre-image of the witness commitment.

#15 proposed adding a NewTemplate.witness_reserved_value field, which would mitigate this problem and make Sv2 future-proof with regards to this potential soft-fork.

[plebhash]

if I were to write something similar to #15, I'd call this field NewTemplate.coinbase_witness instead of NewTemplate.witness_reserved_value

that's because BIP141 says:

The new commitment in coinbase transaction is a hash of the witness root hash and a witness reserved value. The witness reserved value currently has no consensus meaning, but in the future allows new commitment values for future softforks. For example, if a new consensus-critical commitment is required in the future, the commitment in coinbase becomes:

 Double-SHA256(Witness root hash|Hash(new commitment|witness reserved value))

For backward compatibility, the Hash(new commitment|witness reserved value) will go to the coinbase witness, and the witness reserved value will be recorded in another location specified by the future softfork. Any number of new commitment could be added in this way.

Essentially, whoever receives NewTemplate needs to know the contents of the Coinbase witness, which now can be whatever (and it's tipically 0x000...000), and in the future would carry Hash(new commitment|witness reserved value)

In other words, witness reserved value happens to be the in the Coinbase witness today, but it could be somewhere else tomorrow. And what we really want to know is the Coinbase witness so that we can create a Coinbase that will be coherent with the witness commitment.

[plebhash]

on #153 @Sjors wrote:

I opened Sjors/sv2-tp#10 which adds coinbase_witness_reserved_value on the TP side. It's a U256 unlike in #15, because the consensus rule require exactly one stack element of exactly that size. I'd be curious to see what the matching SRI changes would look like.

There's absolutely no rush to do this, since there are currently no soft fork proposals that change the witness reserve value. And I can trivially keep the PR rebased. However, the switch to IPC may be a good opportunity to make a breaking change.

[plebhash]

ditto:

• on a potential soft-fork that changes consensus around Coinbase witness #156 (reply in thread)
• Sv2NewTemplate: add coinbase_witness Sjors/sv2-tp#10 (comment)

[Sjors]

If this was proposed, the best deployment sequence is probably:

1. Make SRI accept both variants of the NewTemplate message (continue to assume it's 0x00 when absent)
2. Release a new TP version that adds the coinbase_witness field (which actually obtains it from the coinbase transaction provided by the node, this can only be done via IPC since the getblocktemplate RPC doesn't contain a coinbase)
3. Eventually deprecate SRI support for older TP versions by making coinbase_witness madatory

[plebhash]

on #153 @Sjors wrote:

Another way you can test the impact of the assumed witness reserved value is by patching Bitcoin Core:

diff --git a/src/validation.cpp b/src/validation.cpp
index 8fcc719a68..c231899fd3 100644
--- a/src/validation.cpp
+++ b/src/validation.cpp
@@ -4079,7 +4079,7 @@ bool CheckBlock(const CBlock& block, BlockValidationState& state, const Consensu
 void ChainstateManager::UpdateUncommittedBlockStructures(CBlock& block, const CBlockIndex* pindexPrev) const
 {
     int commitpos = GetWitnessCommitmentIndex(block);
-    static const std::vector<unsigned char> nonce(32, 0x00);
+    static const std::vector<unsigned char> nonce(32, 0x01);
     if (commitpos != NO_WITNESS_COMMITMENT && DeploymentActiveAfter(pindexPrev, *this, Consensus::DEPLOYMENT_SEGWIT) && !block.vtx[0]->HasWitness()) {
         CMutableTransaction tx(*block.vtx[0]);
         tx.vin[0].scriptWitness.stack.resize(1);
@@ -4092,7 +4092,7 @@ std::vector<unsigned char> ChainstateManager::GenerateCoinbaseCommitment(CBlock&
 {
     std::vector<unsigned char> commitment;
     int commitpos = GetWitnessCommitmentIndex(block);
-    std::vector<unsigned char> ret(32, 0x00);
+    std::vector<unsigned char> ret(32, 0x01);
     if (commitpos == NO_WITNESS_COMMITMENT) {
         uint256 witnessroot = BlockWitnessMerkleRoot(block, nullptr);
         CHash256().Write(witnessroot).Write(ret).Finalize(witnessroot);

This code is only used for mining, both for tests (some Bitcoin Core tests will fail because they use hardcoded block and transaction hashes on regtest) and the Mining interface that's used by the Template Provider.

This should impact the block templates generated by the Template Provider. Once combined with Sjors/sv2-tp#10 such a change should not break anything.

[plebhash]

I applied this patch to Bitcoin Core and made some experiments:

using SRI as-is

if I used SRI as-is (building a Coinbase with 0x000...000 witness), as expected, TP peers reject the block with:

2025-09-01T16:06:03Z [error] AcceptBlock: bad-witness-merkle-match, CheckWitnessMalleatlon : witness merkle commitment mismatch
2025-09-01T16:06:03Z [error] ProcessNewBlock: AcceptBlock FAILED (bad-witness-merkle-match, CheckWitnessMalleatlon : witness merkle commitment mismatch)

using modified SRI

after modifying SRI to build a Coinbase with 0x0101...0101 witness, as expected, blocks are propagated without issues.