Stratum V2 mining protocol module for blvm-node.
This module implements a complete Stratum V2 mining protocol server for blvm-node. It provides:
- Stratum V2 Server: Full protocol implementation for miner connections
- Mining Pool Management: Miner registration, channel management, and job distribution
- Share Validation: Proof-of-work validation using the consensus layer
- Block Template Generation: Integration with node's block template generation
- Automatic Block Submission: Submits valid blocks to the node when found
The module integrates with blvm-node through the NodeAPI interface:
┌─────────────────┐
│ blvm-node │
│ (Core Node) │
└────────┬────────┘
│ NodeAPI
│ (get_block_template, submit_block)
│
▼
┌─────────────────┐
│ blvm-stratum-v2 │
│ (Module) │
│ │
│ ┌─────────────┐ │
│ │ SV2 Server │ │◄─── Stratum V2 Miners
│ └─────────────┘ │ (Encrypted Protocol)
└─────────────────┘
- Message Format: Binary encoding (bincode) with TLV framing (tag + length + payload)
- Setup Connection: Protocol version negotiation and capability exchange
- Mining Channels: Multiple channels per miner with configurable difficulty
- Job Distribution: Automatic job distribution to all active channels
- Share Submission: Share validation with PoW checking
- Error Handling: Comprehensive error responses with proper error codes
- Block Template Generation: Uses node's consensus-verified template generation
- Merkle Path Calculation: Proper Stratum V2 merkle path from coinbase to root
- Coinbase Splitting: Splits coinbase at correct point for miner customization
- Share Validation: Validates shares against channel targets and network difficulty
- Block Detection: Automatically detects and submits valid blocks
- Miner Registration: Tracks connected miners and their channels
- Job Management: Maintains job history with automatic cleanup
- Connection Management: Automatic cleanup of disconnected miners
- Statistics: Tracks shares, acceptance rates, and miner activity
The module is part of the blvm-node module system. It is loaded automatically when configured in the node's module configuration.
Configure the module in the node's configuration:
[modules.blvm-stratum-v2]
enabled = true
listen_addr = "0.0.0.0:3333"enabled: Enable or disable the module (default:false)listen_addr: Address to listen for Stratum V2 connections (default:0.0.0.0:3333)
The node does not bind a dedicated Stratum miner port; listen_addr there is informational / merge-mining related. Miners connect to this module’s listen_addr. Optional P2P Stratum TLV demux is controlled on the node by [stratum_v2].p2p_stratum_demux (default true). Outbound Stratum-shaped bytes to P2P peers use NodeAPI::send_peer_transport_payload. See blvm/CONFIGURATION.md and the blvm-docs Stratum V2 + Merge Mining page.
The module manifest (module.toml) defines:
name = "blvm-stratum-v2"
version = "0.1"
description = "Stratum V2 mining protocol module"
entry_point = "blvm-stratum-v2"
capabilities = [
"read_blockchain",
"subscribe_events",
]- SetupConnection: Initial connection setup with protocol version and capabilities
- OpenMiningChannel: Request to open a mining channel with minimum difficulty
- SubmitShares: Submit mining shares for validation
- SetupConnectionSuccess: Connection established successfully
- SetupConnectionError: Connection failed with error code and message
- OpenMiningChannelSuccess: Channel opened with target and max jobs
- OpenMiningChannelError: Channel open failed with error details
- NewMiningJob: New mining job with coinbase parts and merkle path
- SetNewPrevHash: Previous block hash update (chain reorganization)
- SubmitSharesSuccess: Shares accepted with last job ID
- SubmitSharesError: Shares rejected with error code and message
The module subscribes to these node events:
- BlockMined: Block successfully mined - updates pool and notifies miners
- BlockTemplateUpdated: New block template available - generates and distributes jobs
- MiningDifficultyChanged: Mining difficulty changed - updates pool settings
- StratumV2MessageReceived: Stratum TLV from P2P (or historical paths) — processes protocol messages
The module publishes these events:
- MiningJobCreated: New mining job created and distributed
- ShareSubmitted: Mining share submitted and validated
Shares are validated using a two-stage process:
- Channel Target Validation: Checks if share meets the channel's target difficulty (easier than network difficulty)
- Network Difficulty Validation: Checks if share meets network difficulty (valid block)
Shares that pass channel validation are accepted. Shares that also pass network validation trigger automatic block submission.
- Each channel maintains a history of active jobs (configurable
max_jobs, default: 10) - Old jobs are automatically cleaned up when the limit is exceeded
- Jobs are distributed to all active channels when a new block template is available
- Miners are automatically registered on successful connection setup
- Channels are opened per miner request with configurable difficulty
- Disconnected miners (no activity for 5+ minutes) are automatically removed
- Periodic cleanup runs every 5 minutes
All protocol errors return appropriate error messages:
- Error Code 1: Setup connection failed (unsupported protocol version, etc.)
- Error Code 2: Channel open failed (miner not registered, invalid parameters)
- Error Code 3: Share submission failed (invalid job, channel not found, etc.)
blvm-node: Module system and NodeAPI integrationblvm-consensus: Proof-of-work validationblvm-protocol: Protocol types and structurestokio: Async runtimeserde: Message serializationsha2: Cryptographic hashing
The module includes comprehensive test coverage:
- Unit tests for all core components
- Integration tests for protocol flows
- Concurrent operation tests for thread safety
- Error handling tests for edge cases
See TEST_COVERAGE.md for detailed test coverage information.
MIT License - see LICENSE file for details.