From e1f9f1c819aea7414e5b7ea58e16bc00e0a66532 Mon Sep 17 00:00:00 2001 From: fi3 Date: Sun, 16 Jun 2024 14:23:48 +0200 Subject: [PATCH 1/5] Add max coinbase out sigops to CoinbaseOutputDataSize in TP protocol The template provide need a way to know how many sigops the pool want to include in the coinbase outupts, otherwise is not able to create a template that if mined will result in a valid block. --- 07-Template-Distribution-Protocol.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/07-Template-Distribution-Protocol.md b/07-Template-Distribution-Protocol.md index df45796..26b22db 100644 --- a/07-Template-Distribution-Protocol.md +++ b/07-Template-Distribution-Protocol.md @@ -12,17 +12,18 @@ Template Providers MUST attempt to broadcast blocks which are mined using work t ## 7.1 `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). +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, and sigops 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 and sigops 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 and sigops). -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. +The Job Declarator MUST discover the maximum serialized size of the additional outputs and sigops which will be added by the pool(s) it intends to use this work. +It then MUST communicate it 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 and sigops — along with a maximally-sized (100 byte) coinbase script 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 | +| coinbase_output_max_sigops | U16 | The maximum additional sigops which the pool will add in coinbase transaction outputs | ## 7.2 `NewTemplate` (Server -> Client) From b694882d831282600e893ffd1cc6aaa19333eb44 Mon Sep 17 00:00:00 2001 From: fi3 Date: Tue, 18 Jun 2024 10:49:42 +0200 Subject: [PATCH 2/5] Rename CoinbaseOutputDataSize to CoinbaseOutputConstraints --- 06-Job-Declaration-Protocol.md | 2 +- 07-Template-Distribution-Protocol.md | 4 ++-- 08-Message-Types.md | 2 +- README.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/06-Job-Declaration-Protocol.md b/06-Job-Declaration-Protocol.md index 127a440..374e282 100644 --- a/06-Job-Declaration-Protocol.md +++ b/06-Job-Declaration-Protocol.md @@ -38,7 +38,7 @@ Notably, if the pool intends to change the space it requires for coinbase transa | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | request_id | U32 | Unique identifier for pairing the response | | mining_job_token | B0_255 | Token that makes the client eligible for committing a mining job for approval/transaction declaration or for identifying custom mining job on mining connection. | -| coinbase_output_max_additional_size | U32 | The maximum additional serialized bytes which the pool will add in coinbase transaction outputs. See discussion in the Template Distribution Protocol's CoinbaseOutputDataSize message for more details. | +| coinbase_output_max_additional_size | U32 | The maximum additional serialized bytes which the pool will add in coinbase transaction outputs. See discussion in the Template Distribution Protocol's CoinbaseOutputConstraints message for more details. | | async_mining_allowed | BOOL | If true, the mining_job_token can be used immediately on a mining connection in the SetCustomMiningJob message, even before DeclareMiningJob and DeclareMiningJob.Success messages have been sent and received. If false, Job Declarator MUST use this token for DeclareMiningJob only.
This MUST be true when SetupConnection.flags had REQUIRES_ASYNC_JOB_MINING set. | | coinbase_tx_outputs | B0_64K | Bitcoin transaction outputs added by the pool | diff --git a/07-Template-Distribution-Protocol.md b/07-Template-Distribution-Protocol.md index 26b22db..6310915 100644 --- a/07-Template-Distribution-Protocol.md +++ b/07-Template-Distribution-Protocol.md @@ -5,12 +5,12 @@ It effectively replaces [BIP 22](https://github.com/bitcoin/bips/blob/master/bip 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. +After the initial common handshake, the client MUST immediately send a `CoinbaseOutputConstraints` 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. -## 7.1 `CoinbaseOutputDataSize` (Client -> Server) +## 7.1 `CoinbaseOutputConstraints` (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, and sigops 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 and sigops 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 and sigops). diff --git a/08-Message-Types.md b/08-Message-Types.md index 1a9290e..993a86a 100644 --- a/08-Message-Types.md +++ b/08-Message-Types.md @@ -42,7 +42,7 @@ | 0x59 | 0 | DeclareMiningJob.Error | | 0x60 | 1 | SubmitSolution | | Template Distribution Protocol | | | -| 0x70 | 0 | CoinbaseOutputDataSize | +| 0x70 | 0 | CoinbaseOutputConstraint | | 0x71 | 0 | NewTemplate | | 0x72 | 0 | SetNewPrevHash | | 0x73 | 0 | RequestTransactionData | diff --git a/README.md b/README.md index 245c6fc..5074c01 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ This repository contains the Stratum V2 protocol specification. - [6.1.9 ProvideMissingTransactions (Server->Client)](./06-Job-Declaration-Protocol.md#619-providemissingtransactions-server-client) - [6.1.10 ProvideMissingTransactions.Success (Client->Server)](./06-Job-Declaration-Protocol.md#6110-providemissingtransactionssuccess-client-server) - [7. Template Distribution Protocol](./07-Template-Distribution-Protocol.md) - - [7.1 CoinbaseOutputDataSize (Client -> Server)](./07-Template-Distribution-Protocol.md#71-coinbaseoutputdatasize-client---server) + - [7.1 CoinbaseOutputConstraints (Client -> Server)](./07-Template-Distribution-Protocol.md#71-coinbaseoutputdatasize-client---server) - [7.2 NewTemplate (Server -> Client)](./07-Template-Distribution-Protocol.md#72-newtemplate-server---client) - [7.3 SetNewPrevHash (Server -> Client)](./07-Template-Distribution-Protocol.md#73-setnewprevhash-server---client) - [7.4 RequestTransactionData (Client -> Server)](./07-Template-Distribution-Protocol.md#74-requesttransactiondata-client---server) From 501466693a362be653714cc1fa9046ca64f89e93 Mon Sep 17 00:00:00 2001 From: fi3 Date: Tue, 18 Jun 2024 10:55:08 +0200 Subject: [PATCH 3/5] Explain why coinbase_output_max_sigops is an U16 --- 07-Template-Distribution-Protocol.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/07-Template-Distribution-Protocol.md b/07-Template-Distribution-Protocol.md index 6310915..bc10800 100644 --- a/07-Template-Distribution-Protocol.md +++ b/07-Template-Distribution-Protocol.md @@ -19,6 +19,8 @@ The Job Declarator MUST discover the maximum serialized size of the additional o It then MUST communicate it 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 and sigops — along with a maximally-sized (100 byte) coinbase script 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. +Current sigops limit per block in bitcoin is 80_000. We are not aware of any use cases where +coinbase have more the 65_535 so coinbase_output_max_sigops is an U16. Note that taproot outputs consume 0 sigops. | Field Name | Data Type | Description | | ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------- | From 26981fe2a56899f3f69e24a16428ba7447355bc3 Mon Sep 17 00:00:00 2001 From: Fi3 Date: Wed, 22 Jan 2025 19:34:16 +0100 Subject: [PATCH 4/5] Update 06-Job-Declaration-Protocol.md Co-authored-by: plebhash <147345153+plebhash@users.noreply.github.com> --- 06-Job-Declaration-Protocol.md | 1 + 1 file changed, 1 insertion(+) diff --git a/06-Job-Declaration-Protocol.md b/06-Job-Declaration-Protocol.md index 374e282..634a431 100644 --- a/06-Job-Declaration-Protocol.md +++ b/06-Job-Declaration-Protocol.md @@ -39,6 +39,7 @@ Notably, if the pool intends to change the space it requires for coinbase transa | request_id | U32 | Unique identifier for pairing the response | | mining_job_token | B0_255 | Token that makes the client eligible for committing a mining job for approval/transaction declaration or for identifying custom mining job on mining connection. | | coinbase_output_max_additional_size | U32 | The maximum additional serialized bytes which the pool will add in coinbase transaction outputs. See discussion in the Template Distribution Protocol's CoinbaseOutputConstraints message for more details. | +| coinbase_output_max_additional_sigops | U16 | The maximum additional sigops which the pool will add in coinbase transaction outputs. See discussion in the Template Distribution Protocol's CoinbaseOutputConstraints message for more details. | | async_mining_allowed | BOOL | If true, the mining_job_token can be used immediately on a mining connection in the SetCustomMiningJob message, even before DeclareMiningJob and DeclareMiningJob.Success messages have been sent and received. If false, Job Declarator MUST use this token for DeclareMiningJob only.
This MUST be true when SetupConnection.flags had REQUIRES_ASYNC_JOB_MINING set. | | coinbase_tx_outputs | B0_64K | Bitcoin transaction outputs added by the pool | From 7e10ddc4817a8f8b2f96cd4e91ab7b9ad033ea20 Mon Sep 17 00:00:00 2001 From: Fi3 Date: Wed, 22 Jan 2025 19:34:25 +0100 Subject: [PATCH 5/5] Update 07-Template-Distribution-Protocol.md Co-authored-by: plebhash <147345153+plebhash@users.noreply.github.com> --- 07-Template-Distribution-Protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/07-Template-Distribution-Protocol.md b/07-Template-Distribution-Protocol.md index bc10800..aa121ba 100644 --- a/07-Template-Distribution-Protocol.md +++ b/07-Template-Distribution-Protocol.md @@ -25,7 +25,7 @@ coinbase have more the 65_535 so coinbase_output_max_sigops is an U16. Note that | 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 | -| coinbase_output_max_sigops | U16 | The maximum additional sigops which the pool will add in coinbase transaction outputs | +| coinbase_output_max_additional_sigops | U16 | The maximum additional sigops which the pool will add in coinbase transaction outputs | ## 7.2 `NewTemplate` (Server -> Client)