Land verified mining and pool stack

Cargo.toml

@@ -58,6 +58,20 @@ bitcoin-rs-e2e        = { path = "e2e",               version = "0.14.0" }
 # Allocator. Defaults pull `secure` and `extended` overhead — disable for perf.
 mimalloc = { version = ">=0.1.50, <0.2", default-features = false }
 
+# --- Stratum V2 transport ------------------------------------------------------
+# Pinned SRI release family (v1.12.0): these crates are semver-major-coupled
+# and their wire layouts MUST move together. noise_sv2 2.0.0 is admitted with
+# the narrow duplicate-crypto exception documented in deny.toml.
+binary_sv2          = "=7.0.0"
+framing_sv2         = "=8.0.0"
+codec_sv2           = { version = "=7.0.0" }
+noise_sv2           = "=2.0.0"
+mining_sv2          = "=12.0.0"
+common_messages_sv2 = "=9.0.0"
+
+# Authority-key zeroization used by the SV2 Noise boundary.
+zeroize = { version = ">=1.8.2, <2", default-features = false, features = ["alloc"] }
+
 # --- Bitcoin ecosystem --------------------------------------------------------
 # bitcoin 0.32 line; 0.33 is still beta. `default = [std, secp-recovery]`.
 # Keep `bitcoinconsensus-std` out of the workspace-wide dependency: the

bin/bitcoin-rs/Cargo.toml

@@ -48,6 +48,8 @@ redb = ["bitcoin-rs-node/redb"]
 kernel = ["bitcoin-rs-node/kernel"]
 zmq = ["bitcoin-rs-node/zmq"]
 silent-payments = ["bitcoin-rs-node/silent-payments"]
+pool = ["bitcoin-rs-node/pool"]
+pool-sv2 = ["bitcoin-rs-node/pool-sv2"]
 
 [[test]]
 name = "g17_dependency_direction"

bin/bitcoin-rs/src/config.rs

@@ -11,7 +11,7 @@ use std::path::{Path, PathBuf};
 use anyhow::{Context as _, Result};
 use bitcoin_rs_chainstate::ValidationMode;
 use bitcoin_rs_node::options::{
-    parse_connect_endpoint, parse_network, parse_p2p_magic, parse_script_index,
+    PoolOverrides, parse_connect_endpoint, parse_network, parse_p2p_magic, parse_script_index,
     parse_storage_backend, parse_validation_engine, parse_validation_mode,
 };
 use bitcoin_rs_node::{

crates/chain/src/header_sync.rs

@@ -1,8 +1,8 @@
 use bitcoin_rs_consensus::MAX_TIMEWARP;
 use bitcoin_rs_primitives::{CompactTarget, Hash256, Network};
 
-pub use pow::compact_is_met_by;
-use pow::{compact_to_target, target_to_compact};
+pub use pow::{compact_is_met_by, compact_to_target};
+use pow::target_to_compact;
 
 use crate::{
     ChainError,
@@ -518,7 +518,7 @@ pub fn permitted_difficulty_transition(
 /// overflowing shift folds to `ChainWork::ZERO` instead of surfacing
 /// `pfOverflow`, and a sign-flagged encoding decodes to `ChainWork::ZERO`
 /// instead of being rejected by name.
-pub(crate) mod pow {
+pub mod pow {
     use bitcoin_rs_primitives::{CompactTarget, Hash256};
 
     use crate::node::ChainWork;
@@ -549,7 +549,7 @@ pub(crate) mod pow {
 
     /// Decodes a compact target, returning zero for negative encodings.
     #[must_use]
-    pub(crate) fn compact_to_target(bits: CompactTarget) -> ChainWork {
+    pub fn compact_to_target(bits: CompactTarget) -> ChainWork {
         let decoded = decode_compact(bits.to_consensus());
         if decoded.negative {
             ChainWork::ZERO

crates/chain/src/lib.rs

@@ -43,7 +43,7 @@ pub use deployment::{
 };
 pub use header_sync::{
     AcceptHeaders, HeaderAdmission, HeaderValidationMode, accept_headers, block_work,
-    compact_is_met_by, current_unix_seconds, permitted_difficulty_transition,
+    compact_is_met_by, compact_to_target, current_unix_seconds, permitted_difficulty_transition,
     validate_contextual_header, validate_pow,
 };
 pub use ibd::InitialBlockDownload;

crates/mining/Cargo.toml

@@ -22,10 +22,27 @@ compact_str.workspace = true
 parking_lot.workspace = true
 thiserror.workspace = true
 tracing.workspace = true
+bitcoin-rs-storage = { workspace = true, optional = true }
+ruint = { workspace = true, optional = true }
+sonic-rs = { workspace = true, optional = true }
+sha2 = { workspace = true, optional = true }
+# Pinned SRI release family; only the optional SV2 adapter uses Noise.
+binary_sv2 = { workspace = true, optional = true }
+framing_sv2 = { workspace = true, optional = true }
+codec_sv2 = { workspace = true, features = ["noise_sv2"], optional = true }
+noise_sv2 = { workspace = true, optional = true }
+mining_sv2 = { workspace = true, optional = true }
+common_messages_sv2 = { workspace = true, optional = true }
+zeroize = { workspace = true, optional = true }
 
 [features]
 default = []
 test-seam = []
+pool = ["dep:bitcoin-rs-storage", "dep:ruint", "dep:sonic-rs", "dep:sha2"]
+pool-sv2 = [
+    "pool", "dep:binary_sv2", "dep:framing_sv2", "dep:codec_sv2",
+    "dep:noise_sv2", "dep:mining_sv2", "dep:common_messages_sv2", "dep:zeroize",
+]
 
 
 [dev-dependencies]
@@ -37,6 +54,28 @@ criterion.workspace = true
 # gateway replacement seam must arrive through the test-seam feature, the same
 # way bitcoin-rs-p2p and bitcoin-rs-rpc opt in.
 bitcoin-rs-mempool = { workspace = true, features = ["test-seam"] }
+bitcoin-rs-mining = { workspace = true, features = ["test-seam"] }
+bitcoin-rs-storage = { workspace = true, features = ["test-seam", "redb", "fjall"] }
+tempfile.workspace = true
+# Miner-side key generation uses the same version as the optional Noise graph.
+secp256k1 = { version = "=0.28.2", default-features = false, features = ["std", "rand-std"] }
+rand = { version = "0.8.5", default-features = false, features = ["std", "std_rng"] }
+
+[[test]]
+name = "pool_jobs"
+required-features = ["pool"]
+
+[[test]]
+name = "pool_sv1"
+required-features = ["pool"]
+
+[[test]]
+name = "pool_sv2"
+required-features = ["pool-sv2"]
+
+[[test]]
+name = "pool_ledger"
+required-features = ["pool", "test-seam"]
 
 [[bench]]
 name = "candidate"

crates/mining/README.md

@@ -165,3 +165,13 @@ against live fixture pools. It is a measurement seam, not a budget.
 
 Part of [`bitcoin-rs`](../../README.md); see [`CONCEPTS.md`](../../CONCEPTS.md) for the
 project vocabulary.
+
+## Native pool
+
+The `pool` feature adds `pool::JobBook`, `pool::PoolCore`, the SV1 server
+in `pool::stratum::sv1`, and durable PPLNS accounting in `pool::ledger`.
+`pool-sv2` additionally enables the Noise transport and SV2 protocol session
+in `pool::stratum::sv2`. Both protocols use the same job/share owner and
+`MiningControl` submission boundary. The node owns listener composition,
+chain observations, storage construction, and shutdown. Neither feature
+enables the runtime by itself. See [pool operation](../../docs/pool.md).

crates/mining/src/bip22.rs

@@ -8,6 +8,11 @@ use crate::{MiningControlError, MiningError};
 
 const SIGOPS_LIMIT_REASON: &str = "bad-blk-sigops";
 
+/// BIP22 reason for a block whose parent is no longer the best tip. The node
+/// answers it for `ApplyError::PrevHashMismatch`; pool adapters read it as a
+/// stale sibling instead of a defective block.
+pub const STALE_PARENT_REASON: &str = "inconclusive-not-best-prevblk";
+
 /// Core `GetRejectReason` strings for consensus failures (API-19).
 pub fn consensus_reject_reason(error: &ConsensusError) -> CompactString {
     CompactString::from(match error {

crates/mining/src/coinbase.rs

@@ -4,7 +4,8 @@ use bitcoin_rs_primitives::{
 use bitcoin_rs_script::push_int;
 use thiserror::Error;
 
-const MIN_COINBASE_SCRIPT_SIG_LEN: usize = 2;
+use crate::template::CoinbaseBudget;
+
 /// BIP141 `OP_RETURN` `PUSH36` `aa21a9ed` prefix. Core `MINIMUM_WITNESS_COMMITMENT` is 38 bytes.
 const WITNESS_COMMITMENT_PREFIX: [u8; 6] = [0x6a, 0x24, 0xaa, 0x21, 0xa9, 0xed];
 
@@ -140,7 +141,7 @@ fn coinbase_script_sig(height: u32) -> Vec<u8> {
     // Consensus rejects coinbase scriptSigs shorter than two bytes
     // (`bad-cb-length`). Heights whose BIP34 prefix is a single opcode need a
     // trailing OP_0, matching Bitcoin Core's `CreateNewBlock`.
-    if script.len() < MIN_COINBASE_SCRIPT_SIG_LEN {
+    if script.len() < CoinbaseBudget::MIN_SCRIPT_SIG_LEN {
         script.push(0x00);
     }
     script

crates/mining/src/lib.rs

@@ -20,7 +20,9 @@ mod policy;
 /// Transport-neutral candidate assembly.
 mod template;
 
-pub use bip22::{chain_reject_reason, consensus_reject_reason, header_reject_reason};
+pub use bip22::{
+    STALE_PARENT_REASON, chain_reject_reason, consensus_reject_reason, header_reject_reason,
+};
 pub use coinbase::{
     MiningError, WITNESS_RESERVED_VALUE, needs_witness_reserved_value,
     update_uncommitted_block_structures, witness_commitment_script,
@@ -46,3 +48,7 @@ pub use template::{
     TemplateId, assemble_candidate, assemble_ordered_candidate, select_template_body,
     select_template_body_after, solve_block,
 };
+
+/// Optional native mining pool protocols and accounting.
+#[cfg(feature = "pool")]
+pub mod pool;

crates/mining/src/pool.rs

@@ -0,0 +1,21 @@
+//! Native mining pool jobs, protocols, and durable accounting.
+//!
+//! One JobBook owns job projection and share validation for both protocols.
+//! Node composition supplies mining control, storage, and chain observations.
+#![forbid(unsafe_code)]
+
+mod core;
+mod job;
+pub mod ledger;
+pub mod stratum;
+
+pub use core::{
+    BlockOutcome, LedgerUnavailable, PoolCore, RecordOutcome, RefreshError, Refreshed, ShareLedger,
+    WorkerIdentity,
+};
+pub use job::{
+    AcceptedShare, BIP320_VERSION_MASK, BlockReceipt, BlockStatus, Extranonce, ExtranonceLayout,
+    FoundBlock, Installed, Job, JobBook, JobBookConfig, JobError, JobId,
+    MAX_COINBASE_SCRIPT_SIG_LEN, MAX_NTIME_FORWARD_SECS, Session, SessionId, ShareClass,
+    ShareError, ShareOutcome, ShareSubmission, ShareTarget, ShareWork, StaleReason, fetch_template,
+};