Skip to content

replace BIP320 with BIP323 for version rolling limitations #200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
plebhash wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

replace BIP320 with BIP323 for version rolling limitations #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions 02-Design-Goals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ As there are numerous changes from the original Stratum v1 to v2, it may be help
- Avoid introducing any additional risks to pool operators and miners since that would make adoption of v2 very improbable.

- Support version rolling natively.
Bitcoin block header contains a version field whose bits (determined by [BIP320](https://github.com/bitcoin/bips/blob/master/bip-0320.mediawiki)) can be freely used to extend the hashing space for a miner.
Bitcoin block header contains a version field whose bits (determined by [BIP323](https://github.com/bitcoin/bips/blob/master/bip-0323.mediawiki)) can be freely used to extend the hashing space for a miner.
It is already a common tech, we want to include it as a first class citizen in the new protocol.

- Support header-only mining (not touching the coinbase transaction) in as many situations as possible.
Expand All @@ -29,7 +29,7 @@ As there are numerous changes from the original Stratum v1 to v2, it may be help
- Dramatically reduce network traffic as well as client-side and server-side computational intensity, while still being able to send and receive hashing results rapidly for precise hash rate measurement (and therefore more precise mining reward distribution).

- Allow miners to (optionally) choose the transaction set they mine through work declaration on some independent communication channel.
At the same time, allow miners to choose how they utilize the available bits in the block header `nVersion` field, including both those bits which are used for mining (e.g. version-rolling AsicBoost) by [BIP320](https://github.com/bitcoin/bips/blob/master/bip-0320.mediawiki), and those bits used for [BIP8](https://github.com/bitcoin/bips/blob/master/bip-0008.mediawiki)/[BIP9](https://github.com/bitcoin/bips/tree/master/bip-0009) signaling.
At the same time, allow miners to choose how they utilize the available bits in the block header `nVersion` field, including both those bits which are used for mining (e.g. version-rolling AsicBoost) by [BIP323](https://github.com/bitcoin/bips/blob/master/bip-0323.mediawiki), and those bits used for [BIP8](https://github.com/bitcoin/bips/blob/master/bip-0008.mediawiki)/[BIP9](https://github.com/bitcoin/bips/tree/master/bip-0009) signaling.
This mechanism must not interfere with the efficiency or security of the main mining protocol.
- Use a separate communication channel for transaction selection so that it does not have a performance impact on the main mining/share communication, as well as can be run in three modes - disabled (i.e.pool does not yet support client work selection, to provide an easier transition from Stratum v1), client-push (to maximally utilize the client’s potential block-receive-latency differences from the pool), and client-declared (for pools worried about the potential of clients generating invalid block templates). The key issue to note is that both the client-push and client-declared approaches essentially function as client-push. The primary distinction between them lies in whether the pool validates the job proposed by the miner or not.

Expand Down
12 changes: 6 additions & 6 deletions 05-Mining-Protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Each Mining Device has to work on a unique part of the whole search space.
The full search space is defined in part by valid values in the following block header fields:

- `nonce` header field (32 bits)
- `version` header field (16 bits, as specified by [BIP 320](https://github.com/bitcoin/bips/blob/master/bip-0320.mediawiki))
- `version` header field (24 bits, as specified by [BIP 323](https://github.com/bitcoin/bips/blob/master/bip-0323.mediawiki))
- `nTime` header field (32 bits timestamp, limited under [`MAX_FUTURE_BLOCK_TIME`](https://github.com/bitcoin/bitcoin/blob/28ce159bc327e6dfec34077ff2e379b23a95db65/src/chain.h#L29))

The other portion of the block header that is used to define the full search space is the Merkle Root, which is deterministically computed from:
Expand All @@ -41,12 +41,12 @@ Standard Jobs are restricted to fixed Merkle Roots, where the only modifiable bi

We call this header-only mining (HOM), and it is the smallest assignable unit of search space by the protocol.

The size of the search space for one Standard Job, given a fixed `nTime` field, is `2^(NONCE_BITS + BIP320_VERSION_ROLLING_BITS) = ~280Th`, where `NONCE_BITS = 32` and `BIP320_VERSION_ROLLING_BITS = 16`.
The size of the search space for one Standard Job, given a fixed `nTime` field, is `2^(NONCE_BITS + BIP323_VERSION_ROLLING_BITS) = ~72PH/s`, where `NONCE_BITS = 32` and `BIP323_VERSION_ROLLING_BITS = 24`.
This is a guaranteed space before `nTime` rolling (or changing the Merkle Root by sending a new Job).

Standard Jobs are distributed via the [`NewMiningJob`](#5315-newminingjob-server---client) message, which can ONLY be sent via [Standard Channels](#521-standard-channels).

Note that Mining Devices with hashrate above 280 TH/s will outrun the true time when rolling the `nTime` field. This is not necessarily a problem, as long as the Job remains valid within the limits defined by the `MAX_FUTURE_BLOCK_TIME` constant of the Bitcoin protocol (2 hours).
Note that Mining Devices with hashrate above 72 PH/s will outrun the true time when rolling the `nTime` field. This is not necessarily a problem, as long as the Job remains valid within the limits defined by the `MAX_FUTURE_BLOCK_TIME` constant of the Bitcoin protocol (2 hours).

@Sjors Sjors Jun 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably worth highlighting this change in the PR description and/or making it a separate commit, including the calculation.

@plebhash plebhash Jun 16, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added to PR description


Depending on the hashrate of the Mining Device, it must receive new Standard Jobs (with a different Merkle Root) frequently enough in order to avoid rolling `nTime` too much ahead of the true time (which could result in rejected work).

Expand Down Expand Up @@ -407,7 +407,7 @@ If the `min_ntime` field is set, the client MUST start to mine on the new job im
| channel_id | U32 | Channel identifier, this must be a standard channel |
| job_id | U32 | Identifier of the job as provided by NewMiningJob or NewExtendedMiningJob message |
| min_ntime | OPTION[u32] | Smallest nTime value available for hashing for the new mining job. An empty value indicates this is a future job to be activated once a SetNewPrevHash message is received with a matching job_id. This SetNewPrevHash message provides the new prev_hash and min_ntime. If the min_ntime value is set, this mining job is active and miner must start mining on it immediately. In this case, the new mining job uses the prev_hash from the last received SetNewPrevHash message. |
| version | U32 | Valid 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. |
| version | U32 | Valid version field that reflects the current network consensus. The general purpose bits (as specified in BIP323) can be freely manipulated by the downstream node. The downstream node MUST NOT rely on the upstream node to set the BIP323 bits to any particular value. |
| merkle_root | U256 | Merkle root field as used in the bitcoin block header |

### 5.3.16 `NewExtendedMiningJob` (Server -> Client)
Expand All @@ -430,7 +430,7 @@ A proxy MUST translate the message into `NewMiningJob` for all downstream standa
| job_id | U32 | Server’s identification of the mining job |
| min_ntime | OPTION[u32] | Smallest nTime value available for hashing for the new mining job. An empty value indicates this is a future job to be activated once a SetNewPrevHash message is received with a matching job_id. This SetNewPrevHash message provides the new prev_hash and min_ntime. If the min_ntime value is set, this mining job is active and miner must start mining on it immediately. In this case, the new mining job uses the prev_hash from the last received SetNewPrevHash message. immediately. |
| version | U32 | Valid version field that reflects the current network consensus |
| version_rolling_allowed | BOOL | If set to True, the general purpose bits of version (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. If set to False, the downstream node MUST use version as it is defined by this message. |
| version_rolling_allowed | BOOL | If set to True, the general purpose bits of version (as specified in BIP323) can be freely manipulated by the downstream node. The downstream node MUST NOT rely on the upstream node to set the BIP323 bits to any particular value. If set to False, the downstream node MUST use version as it is defined by this message. |
| merkle_path | SEQ0_255[U256] | Merkle path hashes ordered from deepest |
| coinbase_tx_prefix | B0_64K | Prefix part of the coinbase transaction\* |
| coinbase_tx_suffix | B0_64K | Suffix part of the coinbase transaction |
Expand Down Expand Up @@ -498,7 +498,7 @@ This message signals that JDC expects to be rewarded for working on a Custom Job
| channel_id | U32 | Extended channel identifier |
| request_id | U32 | Client-specified identifier for pairing responses |
| mining_job_token | B0_255 | Token provided by JDS which uniquely identifies the Custom Job that JDC has declared. See the Job Declaration Protocol for more details. |
| version | U32 | Valid version field that reflects the current network consensus. The general purpose bits (as specified in BIP320) can be freely manipulated by the downstream node. |
| version | U32 | Valid version field that reflects the current network consensus. The general purpose bits (as specified in BIP323) can be freely manipulated by the downstream node. |
| prev_hash | U256 | Previous block’s hash, found in the block header field |
| min_ntime | U32 | Smallest nTime value available for hashing |
| nbits | U32 | Block header field |
Expand Down
2 changes: 1 addition & 1 deletion 06-Job-Declaration-Protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,7 @@ A request sent by JDC that proposes a selected set of transactions to JDS.
| --------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| request_id | U32 | Unique identifier for pairing the response |
| mining_job_token | B0_255 | Previously reserved mining job token received by AllocateMiningJobToken.Success |
| version | U32 | Version header field. To be later modified by BIP320-consistent changes. |
| version | U32 | Version header field. To be later modified by BIP323-consistent changes. |
| coinbase_tx_prefix | B0_64K | Serialized bytes representing the initial part of the coinbase transaction (not including extranonce) |
| coinbase_tx_suffix | B0_64K | Serialized bytes representing the final part of the coinbase transaction (after extranonce) |
| wtxid_list | SEQ0_64K[U256] | List of wtxids of the transaction set contained in the template. JDS checks the list against its mempool and requests missing txs via `ProvideMissingTransactions`. Does not include the coinbase transaction (as there is no corresponding full data for it yet). |
Expand Down
Loading
Loading