Zcash mining infrastructure monorepo: a Stratum V2 pool server, Job Declaration protocol for miner-controlled transaction selection, Noise Protocol encryption, compact block relay with forward error correction, and production observability.
This repository merges previously separate projects into a single workspace, including native relay support (sovright-relay) and the standalone relay-sidecar binary.
Built for Zcash's Equihash (200,9) consensus -- 140-byte headers, 1,344-byte solutions, and 32-byte nonces.
The workspace includes the merged Stratum/JD infrastructure crates plus relay components in one repo (crates/*).
zcash-pool-server (main orchestrator)
|-- zcash-template-provider Fetches templates from Zebra RPC
|-- zcash-mining-protocol Binary message codec (NewEquihashJob, SubmitEquihashShare)
|-- zcash-equihash-validator Share validation + adaptive difficulty (vardiff)
|-- zcash-pool-common Shared types (PayoutTracker, CompactSize)
|-- zcash-jd-server Job Declaration Server (miner-controlled templates)
|-- sovright-noise Noise_NK encryption (X25519 + ChaCha20-Poly1305)
|-- sovright-telemetry Prometheus metrics, structured logging, OpenTelemetry
`-- sovright-relay Compact block relay with Reed-Solomon FEC
zcash-jd-client (standalone binary)
|-- zcash-template-provider
|-- zcash-mining-protocol
`-- local Zebra node
sovright-relay-sidecar (builds binary: relay-sidecar)
|-- sovright-relay
`-- Zebra RPC polling
- TemplateProvider polls Zebra's
getblocktemplateRPC - JobDistributor creates
NewEquihashJobmessages from templates - Miners receive jobs, compute Equihash solutions, submit shares
- ShareProcessor validates solutions via EquihashValidator
- VardiffController adjusts per-miner difficulty targeting ~5 shares/min
- PayoutTracker records PPS contributions
- Found blocks are announced to the relay network then submitted to Zebra
| Crate | Description |
|---|---|
zcash-pool-server |
Pool server: accepts miner connections, distributes jobs, validates shares, tracks payouts |
zcash-template-provider |
Fetches block templates from Zebra via JSON-RPC with longpoll caching |
zcash-mining-protocol |
Zcash Stratum V2 binary message types and codec with frame validation |
zcash-equihash-validator |
Equihash solution validation and adaptive difficulty controller |
zcash-pool-common |
Shared types: PPS payout tracker, CompactSize encoding |
zcash-jd-server |
Job Declaration Server; Full-Template mode is unavailable pending payout authorization |
zcash-jd-client |
Job Declaration Client binary for decentralized template construction |
sovright-noise |
Noise_NK encryption with X25519 key exchange and zeroized key material |
sovright-telemetry |
Prometheus metrics, JSON logging, OpenTelemetry tracing |
sovright-relay |
Low-latency compact block relay (BIP 152 adapted) with Reed-Solomon FEC |
relay-sidecar |
Sidecar binary for integrating the relay network into existing pools |
cargo build --release # Build all crates
cargo build -p zcash-pool-server # Build specific crate
cargo check # Fast type checking
cargo clippy # Lint checkscargo test # Run all tests
cargo test -p sovright-relay # Test specific crateRequires a running Zebra node with RPC enabled on port 8232.
cargo run --example run_pool -p zcash-pool-serverAllows miners to construct their own block templates for decentralized transaction selection.
cargo run -p zcash-jd-client -- \
--zebra-url http://127.0.0.1:8232 \
--pool-jd-addr 127.0.0.1:3334Bridges existing pools to the compact block relay network.
cp crates/sovright-relay-sidecar/config.example.toml config.toml
# Edit config.toml with your relay peers and auth key
cargo run -p sovright-relay-sidecar --bin relay-sidecar -- --config config.tomlcargo run --example fetch_template -p zcash-template-provider # Fetch template from Zebra
cargo run --example validate_share -p zcash-equihash-validator # Share validation demoPool server configuration (see crates/zcash-pool-server/src/config.rs):
| Setting | Default | Description |
|---|---|---|
listen_addr |
0.0.0.0:3333 |
TCP bind address for miner connections |
zebra_url |
http://127.0.0.1:8232 |
Zebra RPC endpoint |
nonce_1_len |
4 | Pool nonce prefix length (bytes) |
initial_difficulty |
1.0 | Starting share difficulty |
target_shares_per_minute |
5.0 | Vardiff target rate |
payout_state_path |
payout-state.json |
Durable PPS payout state file |
noise_enabled |
false | Enable Noise_NK encryption |
jd_listen_addr |
None | Job Declaration port (e.g. 0.0.0.0:3334) |
relay_enabled |
false | Enable compact block relay |
metrics_addr |
None | Prometheus metrics endpoint |
The JD protocol defines two modes for miner-controlled block construction:
- Coinbase-Only: Miner customizes the coinbase transaction output; pool provides the transaction list. Lower overhead, compatible with most setups.
- Full-Template (unavailable): Miner-selected transaction sets are rejected until current-version consensus parsing, selected-fee payout authorization, and commitment validation are implemented. Enabling
jd_full_template_enabledfails configuration validation; a static payout threshold cannot make this mode safe.
- Noise_NK encryption prevents StraTap, BiteCoin, and ISP Log attacks
- Replay protection via per-channel sequence validation
- EROSION attack detection through short-lived connection tracking
- Timing attack mitigation with configurable response jitter
- Key material zeroized on drop
See docs/security/stratum-v2-attack-analysis.md for the full threat model.
docs/stratum-v2-planning.md-- Technical design and rationaledocs/plans/-- Implementation phase plansdocs/integration/pool-operator-guide.md-- Setting up a pooldocs/integration/miner-quickstart.md-- Connect to a pool in 5 minutesdocs/integration/jd-client-guide.md-- Running the JD Clientdocs/integration/full-template-mode.md-- Transaction selection guidedocs/integration/protocol-reference.md-- Message format referencedocs/integration/migration-from-v1.md-- Upgrading from Stratum V1
- Zebra -- Zcash node providing
getblocktemplateRPC (port 8232) - equihash -- Core Equihash algorithm implementation
MIT OR Apache-2.0