1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
//! # Stratum V2 Channels
//!
//! `channels_sv2` provides primitives and abstractions for Stratum V2 (Sv2) Channels.
//!
//! This crate implements the core channel management functionality for both mining clients and
//! servers, including standard, extended, and group channels, and share accounting mechanisms.
//!
//! ## Features
//!
//! - Channel primitives for SV2 mining protocol
//! - Channel management for mining servers and clients
//! - Standard, extended, and group channel support
//! - Share accounting
//! - Server-side job lifecycle management
//! - [`client`] module is `no_std` compatible. To enable it build the crate with `no_std` feature.
pub use MAX_EXTRANONCE_LEN;
/// Version rolling mask as per [BIP323](https://github.com/bitcoin/bips/blob/master/bip-0323.mediawiki):
/// only these general-purpose bits may differ between a job's advertised version and a share's
/// version. All other bits of a share's version must match the job's version exactly.
pub const VERSION_ROLLING_MASK: u32 = 0x1fffffe0;
/// Mirrors Bitcoin Core's `MAX_FUTURE_BLOCK_TIME` (`src/chain.h`): a block timestamp more than
/// 2 hours in the future is consensus-invalid.
///
/// Share validation enforces `share.ntime <= min_ntime + MAX_FUTURE_BLOCK_TIME`, where
/// `min_ntime` is the referenced job's (the chain tip's for jobs built or activated under it),
/// anchoring the consensus allowance at the receipt of the message that supplied it
/// (`min_ntime` ≈ wall time when that message arrived, since this crate is `no_std`-compatible
/// and has no clock). This is deliberately looser than the Sv2 spec's elapsed-time window
/// (`ntime <= min_ntime + seconds elapsed since receipt of the message that supplied it`, which
/// is stricter than consensus): embedding applications that have a time source can additionally
/// enforce the spec-exact window. The bound equals the consensus limit at receipt and becomes
/// conservative as the job ages; a false rejection would require a >2h-old job *and* a miner
/// stamping wall time instead of rolling from the job's `min_ntime` — a known, negligible edge.
pub const MAX_FUTURE_BLOCK_TIME: u32 = 2 * 60 * 60;
/// Worst-case chain-tip lifetime, in minutes, assumed when bounding the accepted-share dedup
/// cache (`seen_shares`).
///
/// `seen_shares` only needs to hold shares for the lifetime of one chain tip (it is flushed
/// whenever the tip's `prev_hash` changes), and 10 hours is far beyond any realistic block
/// interval, so the resulting cap is unreachable by a well-behaved channel.
pub const WORST_CASE_TIP_MINUTES: u64 = 600;
/// Safety margin applied on top of the expected share rate when bounding the accepted-share
/// dedup cache (`seen_shares`).
///
/// Poisson variance over thousands of expected shares is ~√N, so a 2× factor is already
/// generous; its real job is covering the window before vardiff converges.
pub const SEEN_SHARES_MARGIN: u64 = 2;
/// Lower clamp applied to the seen-shares budget derived by [`seen_shares_budget`].
///
/// Keeps duplicate detection meaningful when the configured expected rate is absurdly low:
/// 4 096 hashes ≈ 0.3 MB measured (the backing `HashSet` rounds up to 8 192 slots). Without
/// it, a tiny derived budget would close a legitimate server channel after a handful of
/// accepted shares.
pub const MIN_SEEN_SHARES_CAP: usize = 4_096;
/// Upper clamp on the seen-shares budget derived by [`seen_shares_budget`], in hashes.
///
/// Backstops absurd expected-rate configuration, so that no single server channel's dedup cache
/// can be sized past a few tens of MB. Client channels do not use this: they bound their cache
/// at the far smaller [`client::MAX_SEEN_SHARES`], see there for why.
pub const MAX_SEEN_SHARES_CAP: usize = 1 << 20;
/// Returns the maximum number of accepted-share hashes retained for duplicate detection, given
/// the channel's expected share rate:
///
/// ```text
/// budget = clamp(expected_shares_per_minute × WORST_CASE_TIP_MINUTES × SEEN_SHARES_MARGIN,
/// MIN_SEEN_SHARES_CAP, MAX_SEEN_SHARES_CAP)
/// ```
///
/// Sustaining more than [`SEEN_SHARES_MARGIN`]× the expected rate for
/// [`WORST_CASE_TIP_MINUTES`] straight means the share rate has far outrun the channel's
/// configured expectation with no tip transition in between — not a state to accommodate.
/// This assumes mainnet-like block cadence: on networks where a tip can stay pinned past ~20
/// hours (regtest, an idle CI chain), an honest channel can walk into the budget, so such
/// setups should raise the configured rate or treat the resulting channel closure as expected.
///
/// Worst-case per-channel memory (measured, not payload-only: the backing `HashSet` rounds its
/// capacity to a power of two at ~7/8 load and transiently doubles while rehashing): at the
/// default-ish 6 shares/min the budget is 7 200 hashes ≈ 0.5 MB per channel; at 100 shares/min,
/// 120 000 hashes ≈ 9 MB steady and ~15 MB peak through the last rehash. The result is clamped
/// into [[`MIN_SEEN_SHARES_CAP`], [`MAX_SEEN_SHARES_CAP`]] so that a degenerate expected rate
/// can neither disable dedup nor unbound memory.
///
/// Only server channels derive a budget: they have a pool-configured expected rate, and the
/// budget is load-bearing there (validation fails once it is hit, signalling the embedding
/// application to close the channel), so it must be unreachable for any honest rate. Client
/// channels bound `seen_shares` at the flat [`client::MAX_SEEN_SHARES`] and evict oldest-first;
/// see [`client::share_accounting::ShareAccounting`] for why they need no derivation.
pub use ;