Skip to content

Comments

Implement Stratum V2 protocol support#111

Open
warioishere wants to merge 3 commits intoblitzpool-masterfrom
feature/stratum-v2-support
Open

Implement Stratum V2 protocol support#111
warioishere wants to merge 3 commits intoblitzpool-masterfrom
feature/stratum-v2-support

Conversation

@warioishere
Copy link
Owner

@warioishere warioishere commented Feb 9, 2026

Summary

Complete implementation of the Stratum V2 mining protocol with full specification coverage (51/51 spec items). This adds support for modern, efficient mining with improved security and flexibility.

Key Features

Core Protocol Stack

  • Noise NX handshake with EllSwift key encoding for secure connections
  • ChaCha20-Poly1305 AEAD encryption for all protocol messages
  • Binary framing with extension support and channel routing

Mining Protocols

  • Standard mining channels - traditional pool-provided work
  • Extended mining channels - custom coinbase construction with extranonce management
  • Multi-channel support - multiple channels per connection
  • Group channels - shared difficulty across channels

Advanced Features

  • Template Distribution Protocol (TDP) - pool provides block templates, miners construct blocks
  • Job Declaration Protocol (JDP) - miners declare custom jobs to the pool
  • Protocol auto-detection - V1 and V2 can coexist on same ports
  • Reconnect support - server-initiated load balancing

Implementation Details

  • Pure TypeScript implementation with zero native dependencies
  • 235 unit tests across 13 test suites (100% passing)
  • Multi-channel architecture with per-channel state tracking
  • SipHash-2-4 for transaction ID compression
  • Merkle root reconstruction for extended channel shares

Testing

  • ✅ All 13 SV2 test suites passing (235 tests)
  • ✅ No regressions in existing tests
  • ✅ Type-safe with TypeScript strict mode
  • ✅ Fixed pre-existing client controller test failures

Configuration

New environment variables:

  • `SV2_AUTHORITY_PRIVKEY` - Authority key for signing certificates (optional, auto-generated if not set)
  • `SV2_JDP_PORT` - Job Declaration Protocol port (default: 3337)
  • `SV2_JDP_ENABLED` - Enable JDP server (default: false)

Compatibility

  • Backward compatible - V1 clients continue to work unchanged
  • Protocol detection allows gradual migration
  • No database schema changes required

@warioishere warioishere force-pushed the feature/stratum-v2-support branch from 4f15445 to 559c4a6 Compare February 11, 2026 22:50
@warioishere warioishere mentioned this pull request Feb 14, 2026
Draft
7 tasks
@warioishere warioishere force-pushed the feature/stratum-v2-support branch 2 times, most recently from 9384412 to f74d703 Compare February 21, 2026 08:21
@warioishere
v2.0.0 — Add full Stratum V2 protocol support
2f36455 
Implement the complete Stratum V2 mining protocol stack alongside the
existing Stratum V1 infrastructure, enabling miners to connect via
either protocol on configurable ports.

## Core SV2 Protocol Layer
- Binary codec (sv2-binary-codec.ts): U8/U16/U24/U32/U64, BOOL,
  STR0_32/STR0_255, B0_32/B0_64/B0_16M, SEQ0_255/SEQ0_64K
- Frame reader/writer (sv2-frame.ts): 6-byte header framing with
  extension_type, msg_type, msg_length, channel_msg bit flag
- Constants (sv2-constants.ts): all message types, setup flags,
  channel message flag, Noise protocol constants
- Message serializers/deserializers (sv2-messages.ts): SetupConnection,
  OpenStandardMiningChannel, NewMiningJob, SetNewPrevHash,
  SubmitSharesStandard/Success/Error, SetTarget, UpdateChannel,
  CloseChannel, Reconnect, OpenMiningChannelError

## Noise NX Encrypted Transport
- Full Noise_NX_EllSwift+ChaChaPoly handshake (sv2-noise.ts)
- EllSwift key encoding via @scure/btc-signer for BIP-324 compatible ECDH
- ChaCha20-Poly1305 AEAD encryption with nonce rotation
- Certificate signing with Schnorr signatures (tiny-secp256k1)
- Authority key pair management from SV2_CERT_AUTHORITY_SECRET_KEY env var

## Extended Channel Support
- Extended channel messages (sv2-extended-messages.ts):
  OpenExtendedMiningChannel, NewExtendedMiningJob,
  SubmitSharesExtended, SetExtranoncePrefix, SetGroupChannel
- Extranonce manager (sv2-extranonce-manager.ts): unique prefix
  allocation per channel with configurable prefix size
- Variable extranonce sizes with scriptSig varint patching for
  coinbase prefix when channel extranonce != MiningJob's 8-byte slot
- Block reconstruction from extended shares: coinbase from
  prefix+extranonce+suffix, merkle root from path, 80-byte header

## Template Distribution Protocol (TDP)
- TDP messages (sv2-tdp-messages.ts): NewTemplate, SetNewPrevHash,
  SubmitSolution, CoinbaseOutputConstraints, RequestTransactionData
- Template distribution service bridging Bitcoin Core templates to
  SV2 format with coinbase output constraints and merkle paths
- PM2-aware logging: routine TDP logs emitted only from primary worker

## Job Declaration Protocol (JDP)
- JDP messages (sv2-jdp-messages.ts): AllocateMiningJobToken,
  DeclareMiningJob, IdentifyTransactions, ProvideMissingTransactions,
  SubmitSolutionJd
- SipHash-2-4 (sv2-siphash.ts): pure TS implementation for short
  transaction ID computation, verified against official test vectors
- Job declaration service and client for custom block template
  negotiation between miners and pool
- SetCustomMiningJob bridge: declared jobs forwarded to extended
  channel clients for mining
- Transaction validation against mempool wtxids per spec

## SV2 Client (StratumV2Client.ts)
- Full connection lifecycle: Noise handshake → SetupConnection →
  channel open → job distribution → share validation → block submission
- Multi-channel support per connection (standard + extended)
- Version rolling support via SetupConnection flags
- Job-specific difficulty tracking per SV2 spec
- Vardiff with initial target from miner's nominal hash rate
- Share duplicate detection via SHA-256 submission hashing
- Block submission with DB persistence and notifications for all paths
  (standard, extended, TDP SubmitSolution, JDP SubmitSolutionJd)

## Spec Compliance
- SubmitShares.Success sends per-batch values (not cumulative)
- OpenMiningChannel.Error uses proper serializer with request_id
- Wire error codes: stale-share, invalid-job-id, difficulty-too-low
- Block submission checks result === 'SUCCESS!' consistently across
  SV1, SV2 standard, SV2 extended, and TDP paths
- JDP transaction validation uses wtxids (not txids)
- channel_msg bit set correctly on all channel-bound message types

## Infrastructure
- PM2 cluster-safe extranonce prefix allocation (worker ID offset)
- SV2 pool fee discovery API endpoint
- Downstream miner reporting for JDC proxy visibility
- Regtest and testnet4 Docker Compose stacks
- 391 tests across 45 suites (224 SV2-specific unit tests)

## Configuration
- SV2_PORT: SV2 listening port (default 3336)
- SV2_JDP_PORT: JDP listening port (default 3337)
- SV2_JDP_ENABLED: enable JDP server (default false)
- SV2_CERT_AUTHORITY_SECRET_KEY: Noise authority key (hex)
@warioishere warioishere force-pushed the feature/stratum-v2-support branch from f74d703 to 2f36455 Compare February 21, 2026 08:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@warioishere