Stratum V2

https://stratumprotocol.org/specification
Admin
Stratum V2 is the next-generation communication protocol for cryptocurrency mining that enhances...
Tokens:14,365
Snippets:184
Trust Score:8.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### TLV Field Representation

Source: https://stratumprotocol.org/specification/03-protocol-overview

Example of a TLV field structure for extension 0x0002 appended to a message.

```text
[TYPE: 0x0002 0x01] [LENGTH: 0x000A] [VALUE: "Worker_001"]
```

--------------------------------

### Stratum V2 URL with Embedded Authority Key

Source: https://stratumprotocol.org/specification/04-protocol-security

Example of a mining URL containing a base58-check encoded authority public key in the path.

```text
stratum2+tcp://thepool.com:34254/9bXiEd8boQVhq7WddEcERUL5tyyJVFYdU8th3HfbNXK3Yw6GRXh
```

--------------------------------

### PushSolution (Client -> Server)

Source: https://stratumprotocol.org/specification/06-job-declaration-protocol

The PushSolution message is used in Full-Template mode to propagate a found block solution to the JDS.

```APIDOC
## PushSolution

### Description
Sent by JDC as soon as a valid block is found, so that it can be propagated also by JDS. This message is only guaranteed to be valid for the most recent DeclareMiningJob.Success sent on the same connection.

### Parameters
- **extranonce** (B0_32) - Extranonce bytes which need to be added to coinbase to form a fully valid submission.
- **prev hash** (U256) - Hash of the last block.
- **nonce** (U32) - Nonce leading to the hash being submitted.
- **ntime** (U32) - The nTime field in the block header.
- **nbits** (U32) - The nBits field in the block header.
- **version** (U32) - Version header field.
```

--------------------------------

### OpenStandardMiningChannel.Success

Source: https://stratumprotocol.org/specification/05-mining-protocol

The server response confirming the successful opening of a standard mining channel.

```APIDOC
## OpenStandardMiningChannel.Success (Server -> Client)

### Description
Sent as a response for opening a standard channel, if successful.

### Parameters
- **request_id** (U32) - Required - Client-specified request ID from OpenStandardMiningChannel message.
- **channel_id** (U32) - Required - Newly assigned identifier of the channel.
- **target** (U256) - Required - Initial target for the mining channel.
- **extranonce_prefix** (B0_32) - Required - Bytes used as implicit first part of extranonce.
- **group_channel_id** (U32) - Required - Group channel into which the new channel belongs.
```

--------------------------------

### NewTemplate (Server -> Client)

Source: https://stratumprotocol.org/specification/07-template-distribution-protocol

The primary template-providing function sent from the server to the client. It contains all necessary information to construct a coinbase transaction and begin mining.

```APIDOC
## NewTemplate (Server -> Client)

### Description
The primary template-providing function. The coinbase_tx_outputs bytes will appear as is at the end of the coinbase transaction.

### Parameters
- **template_id** (U64) - Server’s identification of the template. Strictly increasing.
- **future_template** (BOOL) - True if the template is intended for future SetNewPrevHash message; if False, the miner should start work immediately.
- **version** (U32) - Valid header version field reflecting current network consensus.
- **coinbase_tx_version** (U32) - The coinbase transaction nVersion field.
- **coinbase_prefix** (B0_255) - Up to 8 bytes to be placed at the beginning of the coinbase field.
- **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.
- **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.
```

--------------------------------

### Key Generation Algorithm

Source: https://stratumprotocol.org/specification/04-protocol-security

The procedure for generating a 32-byte secret key and the corresponding 64-byte ElligatorSwift public key.

```text
1. generate random 32-byte secret key `sk`
2. let `d' = int(sk)`
3. fail if `d = 0` or `d' > n` where `n` is group order of secp256k1 curve
4. compute `P` as `d'⋅G`
5. drop the Y coordinate and compute (u, t) = XElligatorSwift(P.x)
6. ellswift_pub = bytes(u) || bytes(t)
7. output keypair `(sk, ellswift_pub)`
```

--------------------------------

### SubmitSharesExtended

Source: https://stratumprotocol.org/specification/05-mining-protocol

Submits mining shares for extended channels, including the extranonce required for coinbase construction.

```APIDOC
## SubmitSharesExtended

### Description
Submits mining shares for extended channels. This message extends the standard share submission by including the extranonce bytes needed to form a valid coinbase transaction.

### Parameters
- **extranonce** (B0_32) - Required - Extranonce bytes to be added to the coinbase. The size must match the negotiated extranonce size from channel opening.
```

--------------------------------

### OpenStandardMiningChannel

Source: https://stratumprotocol.org/specification/05-mining-protocol

Requests to open a standard mining channel to the upstream node. This is a necessary step for communication and job assignment.

```APIDOC
## OpenStandardMiningChannel (Client -> Server)

### Description
Requests to open a standard channel to the upstream node. Clients should initiate communication by opening a channel to receive job assignments.

### Parameters
- **request_id** (U32) - Required - Client-specified identifier for matching responses.
- **user_identity** (STR0_255) - Required - Sequence of bytes used to identify/authenticate the client.
- **nominal_hash_rate** (F32) - Required - Expected hashrate of the device in h/s.
- **max_target** (U256) - Required - Maximum target which can be accepted by the connected device.
```

--------------------------------

### Calculate Merkle Root for Coinbase Transaction

Source: https://stratumprotocol.org/specification/05-mining-protocol

Logic for constructing the coinbase transaction and computing the Merkle root using the provided path and transaction components.

```python
# Build the coinbase transaction
coinbase_tx = concatenate(
    coinbase_tx_prefix,
    extranonce_prefix,
    extranonce, # null if standard channel
    coinbase_tx_suffix
)

# txid of the coinbase transaction (not wtxid, as coinbase_tx_prefix and coinbase_tx_suffix were stripped of BIP141)
coinbase_txid = SHA256(SHA256(coinbase_tx))

# Compute the Merkle root by folding over the Merkle path
raw_merkle_root = coinbase_txid
for each merkle_leaf in merkle_path:
    data = concatenate(raw_merkle_root, merkle_leaf as little_endian_bytes)
    raw_merkle_root = SHA256(SHA256(data))

# Interpret the final 32-byte hash as a 256-bit integer in little-endian form
merkle_root = Uint256(little_endian_bytes = raw_merkle_root)
```

--------------------------------

### SubmitSolution

Source: https://stratumprotocol.org/specification/07-template-distribution-protocol

The SubmitSolution message is sent by the client to the server when a valid coinbase transaction and nonce pair is found that meets the target difficulty.

```APIDOC
## SubmitSolution (Client -> Server)

### Description
Upon finding a coinbase transaction/nonce pair which double-SHA256 hashes at or below the target, the client sends this message to the server to construct and propagate the full block.

### Parameters
- **template_id** (U64) - The template_id field as it appeared in NewTemplate.
- **version** (U32) - The version field in the block header.
- **header_timestamp** (U32) - The nTime field in the block header.
- **header_nonce** (U32) - The nonce field in the header.
- **coinbase_tx** (B0_64K) - The full serialized coinbase transaction.
```

--------------------------------

### NewExtendedMiningJob

Source: https://stratumprotocol.org/specification/05-mining-protocol

Distributes a new mining job to extended or group channels, providing the necessary data to construct the coinbase transaction and compute the Merkle root.

```APIDOC
## NewExtendedMiningJob

### Description
This message provides a new mining job to an extended or group channel. It includes the job ID, versioning information, Merkle path, and coinbase transaction components required for mining.

### Parameters
- **channel_id** (U32) - Required - Identifier for the group or extended channel.
- **job_id** (U32) - Required - Server’s identification of the mining job.
- **min_ntime** (OPTION[u32]) - Optional - Smallest nTime value available for hashing.
- **version** (U32) - Required - Valid version field reflecting network consensus.
- **version_rolling_allowed** (BOOL) - Required - Indicates if version bits can be manipulated by the downstream node.
- **merkle_path** (SEQ0_255[U256]) - Required - Merkle path hashes ordered from deepest.
- **coinbase_tx_prefix** (B0_64K) - Required - Prefix part of the coinbase transaction.
- **coinbase_tx_suffix** (B0_64K) - Required - Suffix part of the coinbase transaction.
```

--------------------------------

### SetTarget

Source: https://stratumprotocol.org/specification/05-mining-protocol

The server controls the submission rate by adjusting the difficulty target on a specified channel.

```APIDOC
## SetTarget

### Description
The server controls the submission rate by adjusting the difficulty target on a specified channel. All submits leading to hashes higher than the specified target will be rejected by the server.

### Parameters
- **channel_id** (U32) - Channel identifier
- **maximum_target** (U256) - Maximum value of produced hash that will be accepted by a server to accept shares
```

--------------------------------

### OpenExtendedMiningChannel

Source: https://stratumprotocol.org/specification/05-mining-protocol

Requests to open an extended mining channel, similar to standard channel opening but with additional extranonce requirements.

```APIDOC
## OpenExtendedMiningChannel (Client -> Server)

### Description
Requests to open an extended channel instead of a standard channel. Includes all fields from OpenStandardMiningChannel plus specific extranonce requirements.

### Parameters
- **request_id** (U32) - Required - Client-specified identifier.
- **user_identity** (STR0_255) - Required - Client identification string.
- **nominal_hash_rate** (F32) - Required - Expected hashrate in h/s.
- **max_target** (U256) - Required - Maximum target accepted by the device.
- **min_extranonce_size** (U16) - Required - Minimum size of extranonce needed by the device/node.
```

--------------------------------

### SubmitSharesStandard

Source: https://stratumprotocol.org/specification/05-mining-protocol

Submits the result of hashing work from the client to the server.

```APIDOC
## SubmitSharesStandard

### Description
Client sends the result of its hashing work to the server for validation.

### Parameters
- **channel_id** (U32) - Channel identification
- **sequence_number** (U32) - Unique sequential identifier of the submit
- **job_id** (U32) - Identifier of the job
- **nonce** (U32) - Nonce leading to the hash
- **ntime** (U32) - The nTime field in the block header
- **version** (U32) - Full nVersion field
```

--------------------------------

### AllocateMiningJobToken

Source: https://stratumprotocol.org/specification/06-job-declaration-protocol

A request from the JDC to the JDS to obtain an identifier for a future-submitted mining job. This is rate-limited and requires prior negotiation.

```APIDOC
## AllocateMiningJobToken (JDC -> JDS)

### Description
A request to get an identifier for a future-submitted mining job. Rate limited to a rather slow rate and only available on connections where this has been negotiated.

### Parameters
- **user_identifier** (STR0_255) - Required - Unconstrained sequence of bytes used by the pool to identify/authenticate the client.
- **request_id** (U32) - Required - Unique identifier for pairing the response.
```

--------------------------------

### SubmitShares.Error

Source: https://stratumprotocol.org/specification/05-mining-protocol

Reports an error for an incorrect share submission attempt.

```APIDOC
## SubmitShares.Error

### Description
Sent by the server when a share submission is incorrect or fails validation.

### Parameters
- **channel_id** (U32) - Required - Channel identifier
- **sequence_number** (U32) - Required - Submission sequence number for which this error is returned
- **error_code** (STR0_255) - Required - Human-readable error code
```

--------------------------------

### NewMiningJob

Source: https://stratumprotocol.org/specification/05-mining-protocol

Provides an updated mining job to the client through a standard channel.

```APIDOC
## NewMiningJob

### Description
Provides an updated mining job to the client. This is the first message sent after a channel is opened.

### Parameters
- **channel_id** (U32) - Required - Channel identifier
- **job_id** (U32) - Required - Identifier of the job
- **min_ntime** (OPTION[u32]) - Optional - Smallest nTime value available for hashing
- **version** (U32) - Required - Valid version field reflecting network consensus
- **merkle_root** (U256) - Required - Merkle root field for the block header
```

--------------------------------

### DeclareMiningJob.Error

Source: https://stratumprotocol.org/specification/06-job-declaration-protocol

A response sent by JDS rejecting a Custom Job declaration.

```APIDOC
## DeclareMiningJob.Error

### Description
Rejects a Custom Job declaration, triggering a fallback mechanism.

### Parameters
- **request_id** (U32) - Required - Identifier of the original request
- **error_code** (STR0_255) - Required - Human-readable error code
- **error_details** (B0_64K) - Optional - Further details regarding the error
```

--------------------------------

### ProvideMissingTransactions.Success

Source: https://stratumprotocol.org/specification/06-job-declaration-protocol

A response sent by JDC to JDS containing the requested missing transactions.

```APIDOC
## ProvideMissingTransactions.Success

### Description
Supplies the full transaction data requested by the JDS.

### Parameters
- **request_id** (U32) - Required - Identifier of the original DeclareMiningJob request
- **transaction_list** (SEQ0_64K[B0_16M]) - Required - List of full transactions
```

--------------------------------

### Authenticated Encryption Methods

Source: https://stratumprotocol.org/specification/04-protocol-security

The required interface for the AEAD cipher implementation used in the protocol.

```text
ENCRYPT(k, n, ad, pt)
DECRYPT(k, n, ad, ct)
```

--------------------------------

### DeclareMiningJob.Success

Source: https://stratumprotocol.org/specification/06-job-declaration-protocol

A response sent by JDS acknowledging a successful Custom Job declaration.

```APIDOC
## DeclareMiningJob.Success

### Description
Acknowledges that the template declared is valid and provides a new mining job token.

### Parameters
- **request_id** (U32) - Required - Identifier of the original request
- **new_mining_job_token** (B0_255) - Required - Unique custom work identifier
```

--------------------------------

### SubmitShares.Success

Source: https://stratumprotocol.org/specification/05-mining-protocol

Acknowledges successful share submissions from the miner.

```APIDOC
## SubmitShares.Success

### Description
Response sent by the server to acknowledge successful share submissions. This can aggregate multiple successful submissions into a single response.

### Parameters
- **channel_id** (U32) - Required - Channel identification
- **last_sequence_number** (U32) - Required - Most recent sequence number with a correct result
- **new_submits_accepted_count** (U32) - Required - Count of new submits acknowledged within this batch
- **new_shares_sum** (U64) - Required - Sum of difficulty of shares acknowledged within this batch
```

--------------------------------

### SetNewPrevHash

Source: https://stratumprotocol.org/specification/05-mining-protocol

Broadcasts a new previous block hash to clients, signaling an update to the block header and invalidating previous jobs.

```APIDOC
## SetNewPrevHash

### Description
This message is broadcast when a new block is detected. It provides the new previous block hash and associated header fields, requiring clients to switch to the specified job ID immediately.

### Parameters
- **channel_id** (U32) - Required - Group channel or channel that this prevhash is valid for.
- **job_id** (U32) - Required - ID of the job to be used for mining with this prevhash.
- **prev_hash** (U256) - Required - Previous block’s hash.
- **min_ntime** (U32) - Required - Smallest nTime value available for hashing.
- **nbits** (U32) - Required - Block header nbits field.
```

--------------------------------

### SetNewPrevHash

Source: https://stratumprotocol.org/specification/07-template-distribution-protocol

The SetNewPrevHash message is sent by the server to the client upon successful validation of a new best block. It provides the template_id, prev_hash, header_timestamp, nBits, and target to facilitate the transition to a new mining job.

```APIDOC
## SetNewPrevHash

### Description
Sent by the server to the client to indicate a new best block and provide updated mining parameters.

### Parameters
- **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
- **nBits** (U32) - Block header field
- **target** (U256) - The maximum double-SHA256 hash value which would represent a valid block
```

--------------------------------

### UpdateChannel

Source: https://stratumprotocol.org/specification/05-mining-protocol

Client notifies the server about changes on the specified channel, such as nominal hash rate or maximum target adjustments.

```APIDOC
## UpdateChannel

### Description
Client notifies the server about changes on the specified channel. This is used by proxies to report downstream channel changes.

### Parameters
- **channel_id** (U32) - Channel identification
- **nominal_hash_rate** (F32) - Nominal hash rate of the device
- **maximum_target** (U256) - Requested maximum target for the device
```

--------------------------------

### Authority Public Key Test Vector

Source: https://stratumprotocol.org/specification/04-protocol-security

Raw byte representation and corresponding base58-check encoded string for a pool authority public key.

```python
raw_ca_public_key = [118, 99, 112, 0, 151, 156, 28, 17, 175, 12, 48, 11, 205, 140, 127, 228, 134, 16, 252, 233, 185, 193, 30, 61, 174, 227, 90, 224, 176, 138, 116, 85]
prefixed_base58check = "9bXiEd8boQVhq7WddEcERUL5tyyJVFYdU8th3HfbNXK3Yw6GRXh"
```

--------------------------------

### SetCustomMiningJob

Source: https://stratumprotocol.org/specification/05-mining-protocol

Signals that the JDC expects to be rewarded for working on a Custom Job. This message must be sent on an extended or group channel and requires the REQUIRES_WORK_SELECTION flag.

```APIDOC
## SetCustomMiningJob

### Description
Signals that the JDC expects to be rewarded for working on a Custom Job. This message must be sent on an extended or group channel and requires the REQUIRES_WORK_SELECTION flag.

### Parameters
- **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
- **version** (U32) - Valid version field that reflects the current network consensus
- **prev_hash** (U256) - Previous block’s hash
- **min_ntime** (U32) - Smallest nTime value available for hashing
- **nbits** (U32) - Block header field
- **coinbase_tx_version** (U32) - The coinbase transaction nVersion field
- **coinbase_prefix** (B0_255) - Up to 8 bytes to be placed at the beginning of the coinbase field
- **coinbase_tx_input_nSequence** (U32) - The coinbase transaction input's nSequence field
- **coinbase_tx_outputs** (B0_64K) - Outputs of 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
```

--------------------------------

### Calculate ciphertext length from plaintext length

Source: https://stratumprotocol.org/specification/04-protocol-security

Converts a plaintext payload length to the corresponding ciphertext length, accounting for MAC overhead and maximum block sizes.

```c
#define MAX_CT_LEN 65535
#define MAC_LEN 16
#define MAX_PT_LEN (MAX_CT_LEN - MAC_LEN)

uint pt_len_to_ct_len(uint pt_len) {
        uint remainder;
        remainder = pt_len % MAX_PT_LEN;
        if (remainder > 0) {
                remainder += MAC_LEN;
        }
        return pt_len / MAX_PT_LEN * MAX_CT_LEN + remainder;
}
```

--------------------------------

### ProvideMissingTransactions

Source: https://stratumprotocol.org/specification/06-job-declaration-protocol

A request sent by JDS to JDC to provide transactions missing from the JDS mempool.

```APIDOC
## ProvideMissingTransactions

### Description
Requests that the JDC provides full transaction data for transactions not recognized by the JDS.

### Parameters
- **request_id** (U32) - Required - Identifier of the original DeclareMiningJob request
- **unknown_tx_position_list** (SEQ0_64K[U16]) - Required - List of positions of unrecognized transactions
```

--------------------------------

### DeclareMiningJob

Source: https://stratumprotocol.org/specification/06-job-declaration-protocol

A request sent by JDC to JDS to propose a selected set of transactions for a mining job.

```APIDOC
## DeclareMiningJob

### Description
Proposes a selected set of transactions to the JDS for mining in Full-Template mode.

### Parameters
- **request_id** (U32) - Required - Unique identifier for pairing the response
- **mining_job_token** (B0_255) - Required - Previously reserved mining job token
- **version** (U32) - Required - Version header field
- **coinbase_tx_prefix** (B0_64K) - Required - Initial part of the coinbase transaction
- **coinbase_tx_suffix** (B0_64K) - Required - Final part of the coinbase transaction
- **wtxid_list** (SEQ0_64K[U256]) - Required - List of wtxids of the transaction set
- **excess_data** (B0_64K) - Optional - Extra data required to validate the work
```

--------------------------------

### RequestTransactionData.Success

Source: https://stratumprotocol.org/specification/07-template-distribution-protocol

A response to RequestTransactionData containing the set of full transaction data and excess data required for validation.

```APIDOC
## RequestTransactionData.Success

### Description
A response to RequestTransactionData which contains the set of full transaction data and excess data required for validation.

### Parameters
- **template_id** (U64) - Required - The template_id corresponding to a NewTemplate/RequestTransactionData message
- **excess_data** (B0_64K) - Required - Extra data which the Pool may require to validate the work
- **transaction_list** (SEQ0_64K[B0_16M]) - Required - List of full transactions as requested by ProvideMissingTransactions, in the order they were requested in ProvideMissingTransactions
```

--------------------------------

### CloseChannel

Source: https://stratumprotocol.org/specification/05-mining-protocol

Closes a mining channel, signaling the end of operations for that channel.

```APIDOC
## CloseChannel

### Description
Client or server sends this message to end operations for a specific channel. If a group channel is addressed, all channels in that group are closed.

### Parameters
- **channel_id** (U32) - Channel identification
- **reason_code** (STR0_255) - Reason for closing the channel
```

--------------------------------

### RequestTransactionData

Source: https://stratumprotocol.org/specification/07-template-distribution-protocol

A request sent by the Job Declarator to the Template Provider to retrieve transaction data for a specific template.

```APIDOC
## RequestTransactionData

### Description
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.

### Parameters
- **template_id** (U64) - Required - The template_id corresponding to a NewTemplate message
```

--------------------------------

### TLV Encoded Byte Sequence

Source: https://stratumprotocol.org/specification/03-protocol-overview

Hexadecimal representation of the TLV field for extension 0x0002.

```text
00 02 01 00 0A 57 6F 72 6B 65 72 5F 30 30 31
```
Tokens:
Raw