From 1bd0189595ca7e42edb8f1039c85bfea223c1e0b Mon Sep 17 00:00:00 2001 From: plebhash Date: Tue, 9 Jun 2026 11:54:36 -0300 Subject: [PATCH] add coinbase_witness field to NewTemplate - add `NewTemplate.coinbase_witness` to TDP as `B0_32` - define conditional encoding: - empty when witness commitment output is omitted - exactly 32 bytes when witness commitment output is present - codify BIP141 empty-block behavior (witness commitment optional) - require clients to preserve TP-provided output ordering as ` || ` - clarify field purpose: serialize coinbase witness coherently with TP commitment output; no witness-commitment recomputation required - update Protocol Overview BIP141 text to match the new rules --- 03-Protocol-Overview.md | 7 ++++--- 07-Template-Distribution-Protocol.md | 13 ++++++++++++- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/03-Protocol-Overview.md b/03-Protocol-Overview.md index 62e1cbe..c38426c 100644 --- a/03-Protocol-Overview.md +++ b/03-Protocol-Overview.md @@ -318,7 +318,7 @@ This deserves some consideration in the Stratum V2 protocol design, mainly becau For a block that contains any SegWit transactions (in practice almost any non-empty block), the Coinbase transaction MUST have a witness as well as an `OP_RETURN` output carrying the witness commitment. For an empty block, the Coinbase transaction MAY have a witness and the `OP_RETURN` output with the witness commitment anyway. -The `OP_RETURN` output with the witness commitment is provided by Sv2 Template Providers in the `coinbase_tx_outputs` field of `NewTemplate` message. +The `OP_RETURN` output with the witness commitment is provided by Sv2 Template Providers in the `coinbase_tx_outputs` field of `NewTemplate` message. The corresponding Coinbase witness bytes are provided in `NewTemplate.coinbase_witness` (empty when no witness commitment output is present). On a serialized SegWit transaction, the BIP141 fields are: - marker @@ -367,7 +367,8 @@ That's because the Template Distribution Server would not be able to propagate a ### 3.7.4. BIP141 on `NewTemplate` -On the Template Distribution Protocol's `NewTemplate` there is one field affected by BIP141: +On the Template Distribution Protocol's `NewTemplate` there are two fields affected by BIP141: - `coinbase_tx_outputs` +- `coinbase_witness` -In case of blocks containing SegWit transactions (and optionally blocks that don't as well), this field carries the `OP_RETURN` output with the witness commitment. The `witness reserved value` (Coinbase witness) used for calculating this witness commitment is assumed to be 32 bytes of `0x00`, as it currently holds no consensus-critical meaning. This [may change in future soft-forks](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#extensible-commitment-structure). +In case a block contains any transactions with witness data, `coinbase_tx_outputs` carries the `OP_RETURN` output with the witness commitment, and `coinbase_witness` carries the exact 32-byte value used in that commitment pre-image. If all transactions in a block do not have witness data, the witness commitment is optional: if omitted, `coinbase_witness` is empty, and if included, `coinbase_witness` carries the exact 32-byte value used in that commitment pre-image. Clients MUST NOT assume `coinbase_witness` is `0x00...00`, as this [may change in future soft-forks](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#extensible-commitment-structure). This value is sent so clients can serialize the coinbase witness consistently with the provided commitment output. diff --git a/07-Template-Distribution-Protocol.md b/07-Template-Distribution-Protocol.md index 1469d38..7d1f2e1 100644 --- a/07-Template-Distribution-Protocol.md +++ b/07-Template-Distribution-Protocol.md @@ -104,12 +104,23 @@ The primary template-providing function. Note that the `coinbase_tx_outputs` byt | coinbase_tx_value_remaining | U64 | The value, in satoshis, available for spending in coinbase outputs added by the client. Includes both transaction fees and block subsidy. | | coinbase_tx_outputs_count | U32 | The number of transaction outputs included in coinbase_tx_outputs | | coinbase_tx_outputs | B0_64K | Bitcoin transaction outputs to be included as the last outputs in the coinbase transaction | +| coinbase_witness | B0_32 | Coinbase witness bytes. MUST be empty if no witness commitment output is present in `coinbase_tx_outputs`; otherwise MUST contain exactly 32 bytes | | coinbase_tx_locktime | U32 | The locktime field in the coinbase transaction | | merkle_path | SEQ0_255[U256] | Merkle path hashes ordered from deepest | Please note that differently from `SetCustomMiningJob.coinbase_tx_outputs` and `AllocateMiningJobToken.Success.coinbase_tx_outputs`, `NewTemplate.coinbase_tx_outputs` MUST NOT be serialized as a CompactSize-prefixed array. This field must simply carry the ordered sequence of consensus‑serialized outputs, but the number of outputs MUST be inferred from `NewTemplate.coinbase_tx_outputs_count`. This is the equivalent of taking a CompactSize-prefixed array and dropping its (outer) prefix. -Please also note that in case the block contains SegWit transactions (and optionally blocks that don't as well), `NewTemplate.coinbase_tx_outputs` MUST carry the witness commitment. The `witness reserved value` (Coinbase witness) used for calculating this witness commitment is assumed to be 32 bytes of `0x00`, as it currently holds no consensus-critical meaning. This [may change in future soft-forks](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#extensible-commitment-structure). +The full ordered list of coinbase outputs is constructed as ` || `. Clients MUST NOT reorder or modify outputs from `NewTemplate.coinbase_tx_outputs`. + +Please also note that if the block contains any transactions with witness data, `NewTemplate.coinbase_tx_outputs` MUST carry the witness commitment, and `NewTemplate.coinbase_witness` MUST contain exactly 32 bytes equal to the value used in the witness commitment pre-image. + +If all transactions in a block do not have witness data, the witness commitment is optional. In this case, the server MAY omit the witness commitment output from `NewTemplate.coinbase_tx_outputs`, and then `NewTemplate.coinbase_witness` MUST be empty. If the server includes a witness commitment output anyway, `NewTemplate.coinbase_witness` MUST contain exactly 32 bytes equal to the value used in the witness commitment pre-image. + +Clients MUST NOT assume `NewTemplate.coinbase_witness` is `0x00...00`, as this [may change in future soft-forks](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#extensible-commitment-structure). + +`NewTemplate.coinbase_witness` exists so clients can serialize the coinbase input witness in a way that is coherent with the witness commitment output already provided by the server. Clients are not required to recalculate the witness commitment hash. + +If `NewTemplate.coinbase_witness` contains 32 bytes, the client MUST serialize the coinbase transaction as SegWit and the coinbase input witness MUST contain exactly one stack element whose bytes are equal to `NewTemplate.coinbase_witness`. If `NewTemplate.coinbase_witness` is empty, the client MUST serialize the coinbase transaction without BIP141 witness fields. ## 7.3 `SetNewPrevHash` (Server -> Client)