The Template Distribution protocol is used to receive updates of the block template to use in mining the next block.
It effectively replaces BIP 22 (opens new window) and BIP 23 (opens new window) (getblocktemplate
) and provides a much more efficient API which allows Bitcoin Core (or some other full node software) to push template updates at more appropriate times as well as provide a template which may be mined on quickly for the block-after-next.
While not recommended, the template update protocol can be a remote server, and is thus authenticated and signed in the same way as all other protocols (using the same SetupConnection handshake).
Like the Job Declaration and Job Distribution protocols, all Template Distribution messages have the channel_msg
bit unset, and there is no concept of channels.
After the initial common handshake, the client MUST immediately send a CoinbaseOutputDataSize
message to indicate the space it requires for coinbase output addition, to which the server MUST immediately reply with the current best block template it has available to the client.
Thereafter, the server SHOULD push new block templates to the client whenever the total fee in the current block template increases materially, and MUST send updated block templates whenever it learns of a new block.
Template Providers MUST attempt to broadcast blocks which are mined using work they provided, and thus MUST track the work which they provided to clients.
CoinbaseOutputDataSize
(Client -> Server)Ultimately, the pool is responsible for adding coinbase transaction outputs for payouts and other uses, and thus the Template Provider will need to consider this additional block size when selecting transactions for inclusion in a block (to not create an invalid, oversized block). Thus, this message is used to indicate that some additional space in the block/coinbase transaction be reserved for the pool’s use (while always assuming the pool will use the entirety of available coinbase space).
The Job Declarator MUST discover the maximum serialized size of the additional outputs which will be added by the pool(s) it intends to use this work.
It then MUST communicate the maximum such size to the Template Provider via this message.
The Template Provider MUST NOT provide NewMiningJob
messages which would represent consensus-invalid blocks once this additional size — along with a maximally-sized (100 byte) coinbase field — is added.
Further, the Template Provider MUST consider the maximum additional bytes required in the output count variable-length integer in the coinbase transaction when complying with the size limits.
Field Name | Data Type | Description |
---|---|---|
coinbase_output_max_additional_size | U32 | The maximum additional serialized bytes which the pool will add in coinbase transaction outputs |
NewTemplate
(Server -> Client)The primary template-providing function. Note that the coinbase_tx_outputs
bytes will appear as is at the end of the coinbase transaction.
Field Name | Data Type | Description |
---|---|---|
template_id | U64 | Server’s identification of the template. Strictly increasing, the current UNIX time may be used in place of an ID |
future_template | BOOL | True if the template is intended for future SetNewPrevHash message sent on the channel. If False, the job relates to the last sent SetNewPrevHash message on the channel and the miner should start to work on the job immediately. |
version | U32 | Valid header version field that reflects the current network consensus. The general purpose bits (as specified in BIP320) can be freely manipulated by the downstream node. The downstream node MUST NOT rely on the upstream node to set the BIP320 bits to any particular value. |
coinbase_tx_version | U32 | The coinbase transaction nVersion field |
coinbase_prefix | B0_255 | Up to 8 bytes (not including the length byte) which are to be placed at the beginning of the coinbase field in the coinbase transaction |
coinbase_tx_input_sequence | U32 | The coinbase transaction input's nSequence field |
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_tx_locktime | U32 | The locktime field in the coinbase transaction |
merkle_path | SEQ0_255[U256] | Merkle path hashes ordered from deepest |
SetNewPrevHash
(Server -> Client)Upon successful validation of a new best block, the server MUST immediately provide a SetNewPrevHash
message.
If a NewMiningJob
message has previously been sent with an empty min_ntime
, which is valid work based on the prev_hash
contained in this message, the template_id
field SHOULD be set to the job_id
present in that NewTemplate
message indicating the client MUST begin mining on that template as soon as possible.
TODO: Define how many previous works the client has to track (2? 3?), and require that the server reference one of those in SetNewPrevHash
.
Field Name | Data Type | Description |
---|---|---|
template_id | U64 | template_id referenced in a previous NewTemplate message |
prev_hash | U256 | Previous block’s hash, as it must appear in the next block's header |
header_timestamp | U32 | The nTime field in the block header at which the client should start (usually current time). This is NOT the minimum valid nTime value. |
nBits | U32 | Block header field |
target | U256 | The maximum double-SHA256 hash value which would represent a valid block. Note that this may be lower than the target implied by nBits in several cases, including weak-block based block propagation. |
RequestTransactionData
(Client -> Server)A request sent by the Job Declarator to the Template Provider which requests the set of transaction data for all transactions (excluding the coinbase transaction) included in a block, as well as any additional data which may be required by the Pool to validate the work.
Field Name | Data Type | Description |
---|---|---|
template_id | U64 | The template_id corresponding to a NewTemplate message |
RequestTransactionData.Success
(Server->Client)A response to RequestTransactionData
which contains the set of full transaction data and excess data required for validation.
For practical purposes, the excess data is usually the SegWit commitment, however the Job Declarator MUST NOT parse or interpret the excess data in any way.
Note that the transaction data MUST be treated as opaque blobs and MUST include any SegWit or other data which the Pool may require to verify the transaction.
For practical purposes, the transaction data is likely the witness-encoded transaction today.
However, to ensure backward compatibility, the transaction data MAY be encoded in a way that is different from the consensus serialization of Bitcoin transactions.
Ultimately, having some method of negotiating the specific format of transactions between the Template Provider and the Pool’s Template verification node would be overly burdensome, thus the following requirements are made explicit.
The RequestTransactionData.Success
sender MUST ensure that the data is provided in a forwards- and backwards-compatible way to ensure the end receiver of the data can interpret it, even in the face of new, consensus-optional data.
This allows significantly more flexibility on both the RequestTransactionData.Success
-generating and -interpreting sides during upgrades, at the cost of breaking some potential optimizations which would require version negotiation to provide support for previous versions.
For practical purposes, and as a non-normative suggested implementation for Bitcoin Core, this implies that additional consensus-optional data be appended at the end of transaction data.
It will simply be ignored by versions which do not understand it.
To work around the limitation of not being able to negotiate e.g. a transaction compression scheme, the format of the opaque data in RequestTransactionData.Success
messages MAY be changed in non-compatible ways at the time a fork activates, given sufficient time from code-release to activation (as any sane fork would have to have) and there being some in-Template Negotiation Protocol signaling of support for the new fork (e.g. for soft-forks activated using BIP 9 (opens new window)).
Field Name | Data Type | Description |
---|---|---|
template_id | U64 | The template_id corresponding to a NewTemplate/RequestTransactionData message |
excess_data | B0_64K | Extra data which the Pool may require to validate the work |
transaction_list | SEQ0_64K[B0_16M] | List of full transactions as requested by ProvideMissingTransactions, in the order they were requested in ProvideMissingTransactions |
RequestTransactionData.Error
(Server->Client)Field Name | Data Type | Description |
---|---|---|
template_id | U64 | The template_id corresponding to a NewTemplate/RequestTransactionData message |
error_code | STR0_255 | Reason why no transaction data has been provided |
Possible error codes:
template-id-not-found
- used when the template being referenced is too old and no longer stored in the memory of the Template Providerstale-template-id
- used when the prev_hash of the corresponding template is still in the Template Provider's memory, but it no longer points to the latest tipSubmitSolution
(Client -> Server)Upon finding a coinbase transaction/nonce pair which double-SHA256 hashes at or below SetNewPrevHash::target
, the client MUST immediately send this message, and the server MUST then immediately construct the corresponding full block and attempt to propagate it to the Bitcoin network.
Field Name | Data Type | Description |
---|---|---|
template_id | U64 | The template_id field as it appeared in NewTemplate |
version | U32 | The version field in the block header. Bits not defined by BIP320 as additional nonce MUST be the same as they appear in the NewMiningJob message, other bits may be set to any value. |
header_timestamp | U32 | The nTime field in the block header. This MUST be greater than or equal to the header_timestamp field in the latest SetNewPrevHash message and lower than or equal to that value plus the number of seconds since the receipt of that message. |
header_nonce | U32 | The nonce field in the header |
coinbase_tx | B0_64K | The full serialized coinbase transaction, meeting all the requirements of the NewMiningJob message, above |