b-open-io/stratum-v2

Stratum v2 Mining Protocol

Stratum v2 is the next-generation mining protocol developed by Braiins (Slush Pool), designed to address the limitations of Stratum v1. It introduces binary framing, end-to-end encryption, and decentralized job declaration.

When to Use

• Planning mining infrastructure upgrades
• Evaluating v1 to v2 migration
• Understanding modern mining security
• Implementing next-gen pool software
• Building decentralized mining solutions

Key Improvements Over v1

| Feature | Stratum v1 | Stratum v2 | |---------|------------|------------| | Format | JSON-RPC text | Binary framed | | Bandwidth | ~100% baseline | ~30% reduction | | Encryption | None (plaintext) | Noise Protocol (AEAD) | | Authentication | Password-based | Cryptographic | | Job Selection | Pool-controlled | Miner-declarable | | Efficiency | Higher latency | Lower latency |

Protocol Architecture

Stratum v2 consists of three subprotocols:

1. Mining Protocol

Core work distribution between pool and miners.

2. Job Declaration Protocol

Allows miners to construct their own block templates.

3. Template Distribution Protocol

Distributes block templates from Bitcoin nodes to pools/miners.

Binary Framing

Message Structure

+------------------+------------------+------------------+
| Extension Type   | Message Type     | Message Length   |
| (2 bytes)        | (1 byte)         | (3 bytes)        |
+------------------+------------------+------------------+
|                      Payload                           |
|                   (variable length)                    |
+--------------------------------------------------------+

Data Types

| Type | Description | Size | |------|-------------|------| | U8 | Unsigned 8-bit | 1 byte | | U16 | Unsigned 16-bit LE | 2 bytes | | U24 | Unsigned 24-bit LE | 3 bytes | | U32 | Unsigned 32-bit LE | 4 bytes | | U256 | 256-bit hash | 32 bytes | | STR0_255 | Length-prefixed string | 1 + n bytes | | B0_32 | Length-prefixed bytes | 1 + n bytes | | B0_64K | Length-prefixed bytes | 2 + n bytes | | SEQ0_64K | Sequence of items | 2 + items |

Channel Types

Standard Channel

• Basic mining operations
• Fixed extranonce size
• Pool-assigned difficulty

Extended Channel

• Larger extranonce support
• Custom coinbase prefix
• Header-only mining mode

Group Channel

• Aggregates multiple miners
• Proxy/farm configurations
• Efficient multiplexing

Encryption (Noise Protocol)

Stratum v2 uses the Noise Protocol Framework with:

• Handshake: Noise_NX_secp256k1_ChaChaPoly_SHA256
• Cipher: ChaCha20-Poly1305 (AEAD)
• Curve: secp256k1
• Hash: SHA-256

Connection Flow

1. Client initiates Noise handshake
2. Server provides certificate (signed by authority)
3. Encrypted channel established
4. All subsequent messages encrypted

Security Benefits

• Man-in-the-middle protection
• Hashrate hijacking prevention
• Pool impersonation prevention
• Privacy for miner operations

Mining Protocol Messages

Setup Messages

SetupConnection

{
  protocol: U32,
  min_version: U16,
  max_version: U16,
  flags: U32,
  endpoint_host: STR0_255,
  endpoint_port: U16,
  vendor: STR0_255,
  hardware_version: STR0_255,
  firmware: STR0_255,
  device_id: STR0_255
}

SetupConnection.Success

{
  used_version: U16,
  flags: U32
}

Channel Messages

OpenStandardMiningChannel

{
  request_id: U32,
  user_identity: STR0_255,
  nominal_hash_rate: F32,
  max_target: U256
}

OpenStandardMiningChannel.Success

{
  request_id: U32,
  channel_id: U32,
  target: U256,
  extranonce_prefix: B0_32,
  group_channel_id: U32
}

Job Messages

NewMiningJob

{
  channel_id: U32,
  job_id: U32,
  future_job: BOOL,
  version: U32,
  version_rolling_allowed: BOOL
}

SetNewPrevHash

{
  channel_id: U32,
  job_id: U32,
  prev_hash: U256,
  min_ntime: U32,
  nbits: U32
}

Share Submission

SubmitSharesStandard

{
  channel_id: U32,
  sequence_number: U32,
  job_id: U32,
  nonce: U32,
  ntime: U32,
  version: U32
}

SubmitShares.Success

{
  channel_id: U32,
  last_sequence_number: U32,
  new_submits_accepted_count: U32,
  new_shares_sum: U64
}

Job Declaration Protocol

Enables miners to select transactions for blocks:

Flow

1. Miner connects to Template Distribution node
2. Miner receives block template with transactions
3. Miner declares custom job to pool
4. Pool validates and accepts declaration
5. Miner works on self-constructed block

Messages

DeclareMiningJob

{
  request_id: U32,
  mining_job_token: B0_255,
  version: U32,
  coinbase_prefix: B0_64K,
  coinbase_suffix: B0_64K,
  tx_short_hash_nonce: U64,
  tx_short_hash_list: SEQ0_64K[U64],
  tx_hash_list_hash: U256,
  excess_data: B0_64K
}

Benefits

• Decentralizes transaction selection
• Reduces pool censorship risk
• Improves Bitcoin decentralization
• Miners control block content

Template Distribution Protocol

Distributes templates from Bitcoin node to pools/miners:

NewTemplate

{
  template_id: U64,
  future_template: BOOL,
  version: U32,
  coinbase_tx_version: U32,
  coinbase_prefix: B0_64K,
  coinbase_tx_input_sequence: U32,
  coinbase_tx_value_remaining: U64,
  coinbase_tx_outputs_count: U32,
  coinbase_tx_outputs: B0_64K,
  coinbase_tx_locktime: U32,
  merkle_path: SEQ0_255[U256]
}

Comparison: v1 vs v2 Session

Stratum v1 Session

Client: {"method":"mining.subscribe","params":["Agent/1.0"],"id":1}
Server: {"result":[[["mining.set_difficulty","1"],["mining.notify","1"]],"08000000",4],"id":1}
Client: {"method":"mining.authorize","params":["user.worker",""],"id":2}
Server: {"result":true,"id":2}
Server: {"method":"mining.set_difficulty","params":[1024]}
Server: {"method":"mining.notify","params":["job1","prev...","cb1","cb2",[],"ver","bits","time",true]}
Client: {"method":"mining.submit","params":["user.worker","job1","00000000","time","nonce"],"id":3}
Server: {"result":true,"id":3}

Stratum v2 Session

1. Noise handshake (encrypted channel established)
2. SetupConnection → SetupConnection.Success
3. OpenStandardMiningChannel → OpenStandardMiningChannel.Success
4. SetTarget (difficulty)
5. NewMiningJob + SetNewPrevHash (job assignment)
6. SubmitSharesStandard → SubmitShares.Success

Migration Considerations

When to Migrate

• Security is priority (MITM protection needed)
• Bandwidth costs significant
• Decentralization goals
• Modern infrastructure refresh

When to Stay on v1

• Legacy hardware compatibility
• Existing stable infrastructure
• Simple pool operations
• No security concerns

Hybrid Approach

Many pools run both:

• v1 on port 3333 (legacy compatibility)
• v2 on port 3334 (modern miners)

Translation proxies can bridge v1 miners to v2 pools.

BSV Considerations

Current State

• BSV pools primarily use Stratum v1
• GorillaPool uses optimized v1 implementation
• v2 adoption depends on ASIC firmware support

BSV-Specific Features

• Large block templates (transaction selection matters)
• getminingcandidate RPC (BSV-specific)
• submitminingsolution RPC (BSV-specific)
• Higher transaction throughput

Implementation Path

1. Start with Stratum v1 (proven, compatible)
2. Add v2 support when ASIC ecosystem ready
3. Maintain both for transition period

Reference Implementation

Stratum Reference Implementation (SRI):

• GitHub: stratum-mining/stratum
• Rust-based implementation
• Production-ready components

Components:

• roles/pool - Mining pool role
• roles/mining-proxy - Proxy/translator
• roles/jd-client - Job declaration client
• roles/jd-server - Job declaration server

Resources

• Official Stratum v2 Specification
• Stratum Protocol Website
• Noise Protocol Framework
• BIP Draft - Stratum v2
• Braiins Documentation

Implementation Status

| Component | Availability | |-----------|--------------| | Protocol Spec | Complete | | Reference Implementation | Production | | Pool Support | Growing | | ASIC Firmware | Limited | | BSV Support | Future |

Quick Reference

Stratum v2 Ports (typical):

• 3334 - Mining Protocol (encrypted)
• 8442 - Template Distribution
• 8443 - Job Declaration

Key Crates (Rust):

[dependencies]
binary_sv2 = "1.0"
codec_sv2 = "1.0"
framing_sv2 = "1.0"
noise_sv2 = "1.0"