From fc60d01688e11299f9429da8e775bde61431a3e8 Mon Sep 17 00:00:00 2001 From: jolah1 Date: Tue, 13 Oct 2026 17:21:42 +0100 Subject: [PATCH 1/2] fix(channels_sv2)!: keep seen shares when the tip returns to a prev_hash Channels cleared seen_shares on every prev_hash change. When the tip went A to B and back to A with the same coinbase and merkle root, a proof accepted under A was not seen any more and was credited again under the returning job ID. Client channels now keep seen_shares across tip changes. The queue is already capped at MAX_SEEN_SHARES and evicts oldest-first, so clearing it was never needed to bound memory. flush_seen_shares is removed. Server channels cannot do the same, since their set is a hard budget sized for one prev_hash. ShareAccounting::on_prev_hash_change replaces flush_seen_shares: it keeps the set of the prev_hash being left, tagged with that prev_hash, and makes it current again if the next change returns to it. Keeping that set without the tag is not enough: on the way back to A it would be replaced by B's set and A's hashes would be dropped anyway. The budget still applies to the current set, so a server channel holds at most twice its budget. A revisit across more than one tip (A to B to C to A) is not covered. https://github.com/stratum-mining/stratum/issues/2396 --- sv2/channels-sv2/src/client/extended.rs | 73 ++++---- sv2/channels-sv2/src/client/mod.rs | 7 +- .../src/client/share_accounting.rs | 31 +--- sv2/channels-sv2/src/client/standard.rs | 132 +++++++++++--- sv2/channels-sv2/src/lib.rs | 11 +- sv2/channels-sv2/src/server/extended.rs | 172 +++++++++++++++--- .../src/server/share_accounting.rs | 83 +++++++-- sv2/channels-sv2/src/server/standard.rs | 97 +++++++--- 8 files changed, 449 insertions(+), 157 deletions(-) diff --git a/sv2/channels-sv2/src/client/extended.rs b/sv2/channels-sv2/src/client/extended.rs index 367ca742f3..797ef22d3d 100644 --- a/sv2/channels-sv2/src/client/extended.rs +++ b/sv2/channels-sv2/src/client/extended.rs @@ -692,22 +692,15 @@ impl ExtendedChannel { /// - Retires the previously active job as stale, leaving the channel with no active job until /// the next job message arrives. /// - Marks all past jobs as stale and clears them. - /// - Clears all seen shares if `prev_hash` changed, as shares for the previous chain tip will - /// be rejected as stale; a repeated `prev_hash` keeps them, see - /// [`ShareAccounting::flush_seen_shares`]. + /// - Keeps seen shares, see [`ShareAccounting::is_share_seen`]. pub fn on_chain_tip_update(&mut self, chain_tip: ChainTip) -> Result<(), ExtendedChannelError> { self.update_chain_tip(chain_tip); Ok(()) } // Moves the channel onto `chain_tip`: future jobs are dropped, the active and past jobs go - // stale, retired extranonce prefixes are pruned and seen shares are flushed if `prev_hash` - // changed. + // stale and retired extranonce prefixes are pruned. fn update_chain_tip(&mut self, chain_tip: ChainTip) { - let is_new_prev_hash = self - .chain_tip - .as_ref() - .is_some_and(|previous| previous.prev_hash() != chain_tip.prev_hash()); self.chain_tip = Some(chain_tip); // all other future jobs are now useless @@ -732,11 +725,6 @@ impl ExtendedChannel { // the jobs that just went stale can no longer accept shares, so any retired extranonce // prefix they were the last reference to is now releasable self.prune_retired_extranonce_prefixes(); - - // hashes are retained while prev_hash is unchanged, see ShareAccounting::flush_seen_shares - if is_new_prev_hash { - self.share_accounting.flush_seen_shares(); - } } /// Handles a [`SetNewPrevHash`](SetNewPrevHashMp) message from upstream. @@ -747,9 +735,7 @@ impl ExtendedChannel { /// untouched. /// - If it is a future job, activates it as the current job. /// - Marks the previously active job and all past jobs as stale, and clears past jobs. - /// - Clears all seen shares if `prev_hash` changed, as shares for the previous chain tip will - /// be rejected as stale; a repeated `prev_hash` keeps them, see - /// [`ShareAccounting::flush_seen_shares`]. + /// - Keeps seen shares, see [`ShareAccounting::is_share_seen`]. /// - Updates the chain tip for the channel. pub fn on_set_new_prev_hash( &mut self, @@ -795,15 +781,6 @@ impl ExtendedChannel { // prefix they were the last reference to is now releasable self.prune_retired_extranonce_prefixes(); - // hashes are retained while prev_hash is unchanged, see ShareAccounting::flush_seen_shares - if self - .chain_tip - .as_ref() - .is_some_and(|chain_tip| chain_tip.prev_hash() != set_new_prev_hash.prev_hash) - { - self.share_accounting.flush_seen_shares(); - } - self.chain_tip = Some(set_new_prev_hash.into()); Ok(()) @@ -3336,14 +3313,14 @@ mod tests { }; // network target: 000000000000d7c0... (hard, so no accidental BlockFound) - let set_new_prev_hash = |job_id: u32| SetNewPrevHashMp { + let prev_hash = [ + 200, 53, 253, 129, 214, 31, 43, 84, 179, 58, 58, 76, 128, 213, 24, 53, 38, 144, 205, + 88, 172, 20, 251, 22, 217, 141, 21, 221, 21, 0, 0, 0, + ]; + let set_new_prev_hash = |job_id: u32, prev_hash: [u8; 32]| SetNewPrevHashMp { channel_id, job_id, - prev_hash: [ - 200, 53, 253, 129, 214, 31, 43, 84, 179, 58, 58, 76, 128, 213, 24, 53, 38, 144, - 205, 88, 172, 20, 251, 22, 217, 141, 21, 221, 21, 0, 0, 0, - ] - .into(), + prev_hash: prev_hash.into(), nbits: 453040064, ntime_start: 1745596970, }; @@ -3359,7 +3336,9 @@ mod tests { }; channel.on_new_extended_mining_job(future_job(1)).unwrap(); - channel.on_set_new_prev_hash(set_new_prev_hash(1)).unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(1, prev_hash)) + .unwrap(); assert!(matches!( channel.validate_share(share(0, 1)), Ok(ShareValidationResult::Valid(_)) @@ -3367,7 +3346,9 @@ mod tests { // the upstream repeats the tip under a new job_id: same header space, new job channel.on_new_extended_mining_job(future_job(2)).unwrap(); - channel.on_set_new_prev_hash(set_new_prev_hash(2)).unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(2, prev_hash)) + .unwrap(); // the identical proof under the new job_id is a duplicate, not a second validation assert!(matches!( @@ -3375,6 +3356,30 @@ mod tests { Err(ShareValidationError::DuplicateShare(_)) )); assert_eq!(channel.get_share_accounting().get_validated_shares(), 1); + + // the tip moves to another prev_hash, where the same nonce makes a different header + let mut other_prev_hash = prev_hash; + other_prev_hash[0] ^= 1; + channel.on_new_extended_mining_job(future_job(3)).unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(3, other_prev_hash)) + .unwrap(); + assert!(matches!( + channel.validate_share(share(2, 3)), + Ok(ShareValidationResult::Valid(_)) + )); + + // and returns to the first one with the same job again (A→B→A): the proof validated + // under the first tip is still a duplicate + channel.on_new_extended_mining_job(future_job(4)).unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(4, prev_hash)) + .unwrap(); + assert!(matches!( + channel.validate_share(share(3, 4)), + Err(ShareValidationError::DuplicateShare(_)) + )); + assert_eq!(channel.get_share_accounting().get_validated_shares(), 2); } // An immediately-active job whose coinbase carries a 32-byte extranonce. diff --git a/sv2/channels-sv2/src/client/mod.rs b/sv2/channels-sv2/src/client/mod.rs index d478b3c612..ac815828c1 100644 --- a/sv2/channels-sv2/src/client/mod.rs +++ b/sv2/channels-sv2/src/client/mod.rs @@ -50,9 +50,10 @@ pub const MAX_PAST_JOBS: usize = 16; /// /// A client cache does not need to hold a whole chain tip's worth of shares. It exists to catch /// a share source re-submitting work it already sent — a retransmit or a buggy loop, which -/// arrives within seconds — not to reconcile a tip. 4 096 covers ~11 hours of history for a -/// typical 6 shares/min channel and ~7 minutes for a very busy 600 shares/min proxy channel, -/// far beyond any realistic duplicate window in both cases. Overflow evicts oldest-first, and +/// arrives within seconds, or a replay once the tip returns to a `prev_hash` it just left, which +/// follows a short reorg. The cache is kept across tip changes for the latter. 4 096 covers +/// ~11 hours of history for a typical 6 shares/min channel and ~7 minutes for a very busy +/// 600 shares/min proxy channel, far beyond any realistic duplicate window in both cases. Overflow evicts oldest-first, and /// an evicted-then-replayed hash costs one double-counted local statistic: an accepted replay /// window, see [`ShareAccounting`](share_accounting::ShareAccounting) for why clients do not /// fail hard at the bound. diff --git a/sv2/channels-sv2/src/client/share_accounting.rs b/sv2/channels-sv2/src/client/share_accounting.rs index d2479fde61..ae8863a09e 100644 --- a/sv2/channels-sv2/src/client/share_accounting.rs +++ b/sv2/channels-sv2/src/client/share_accounting.rs @@ -99,10 +99,9 @@ pub enum ShareValidationError { /// /// # Duplicate detection is bounded, and its overflow is an accepted replay window /// -/// `seen_shares` holds at most [`MAX_SEEN_SHARES`] validated hashes per `prev_hash`, evicting -/// oldest-first. After that many validated shares under one still-current `prev_hash`, a replay -/// of an evicted share passes [`is_share_seen`](Self::is_share_seen) again and is validated (and -/// forwarded) a second time. This is deliberate: clients do not fail hard at the bound the way +/// `seen_shares` holds at most [`MAX_SEEN_SHARES`] validated hashes, evicting oldest-first. +/// After that many validated shares, a replay of an evicted share passes +/// [`is_share_seen`](Self::is_share_seen) again and is validated (and forwarded) a second time. This is deliberate: clients do not fail hard at the bound the way /// server channels do, because /// /// - the target is upstream-controlled, so no bound derived from an expected share rate can @@ -243,19 +242,6 @@ impl ShareAccounting { } } - /// Clears the set of seen share hashes. - /// - /// Must be called whenever the chain tip's `prev_hash` changes, and only then. Validated - /// hashes are retained for as long as `prev_hash` is unchanged: job IDs are not committed - /// into the block header, so a job replaced under the same `prev_hash` commits to the same - /// header space as its predecessor, and flushing then would let a proof that was already - /// validated (and forwarded) be validated again under the new job ID. This is also what - /// makes the seen-shares cap per-`prev_hash`: the queue only ever holds the shares validated - /// while one `prev_hash` was current. - pub fn flush_seen_shares(&mut self) { - self.seen_shares.clear(); - } - /// Returns the sequence number of the last share received. pub fn get_last_share_sequence_number(&self) -> u32 { self.last_share_sequence_number @@ -315,7 +301,12 @@ impl ShareAccounting { /// Checks if the given share hash has already been seen (duplicate detection). /// /// The underlying queue holds at most [`MAX_SEEN_SHARES`] hashes (oldest evicted first) and - /// is flushed whenever the chain tip's `prev_hash` changes. + /// is kept across chain tip changes. Job IDs are not committed into the block header, so a + /// job under a `prev_hash` the tip has already had, whether it stayed (a repeated + /// `SetNewPrevHash`) or came back to it (A→B→A), can commit to the same header space as an + /// earlier one, and forgetting its hashes would let a proof that was already validated (and + /// forwarded) be validated again under the new job ID. Header hashes commit to `prev_hash`, + /// so hashes from different tips never compare equal. pub fn is_share_seen(&self, share_hash: Hash) -> bool { self.seen_shares.contains(&share_hash) } @@ -448,9 +439,5 @@ mod tests { for i in overflow..cap + overflow { assert!(accounting.is_share_seen(hash(i))); } - - // a chain-tip transition clears both the set and the eviction order - accounting.flush_seen_shares(); - assert_eq!(accounting.seen_shares.len(), 0); } } diff --git a/sv2/channels-sv2/src/client/standard.rs b/sv2/channels-sv2/src/client/standard.rs index a4f5688ddd..adf6aa45b8 100644 --- a/sv2/channels-sv2/src/client/standard.rs +++ b/sv2/channels-sv2/src/client/standard.rs @@ -157,9 +157,9 @@ impl StandardChannel { /// /// A first tip only initializes the channel, and setting the current tip again changes /// nothing. Replacing the tip with a different one is a chain-tip transition: future jobs are - /// cleared, the active and past jobs go stale rather than stay validatable against a header - /// the miner was never assigned, and seen shares are flushed if `prev_hash` changed (a - /// repeated `prev_hash` keeps them, see [`ShareAccounting::flush_seen_shares`]). + /// cleared, and the active and past jobs go stale rather than stay validatable against a + /// header the miner was never assigned. Seen shares are kept, see + /// [`ShareAccounting::is_share_seen`]. pub fn set_chain_tip(&mut self, chain_tip: ChainTip) { match &self.chain_tip { None => self.chain_tip = Some(chain_tip), @@ -169,13 +169,8 @@ impl StandardChannel { } // Moves the channel onto `chain_tip`: future jobs are dropped, the active and past jobs go - // stale, retired extranonce prefixes are pruned and seen shares are flushed if `prev_hash` - // changed. + // stale and retired extranonce prefixes are pruned. fn update_chain_tip(&mut self, chain_tip: ChainTip) { - let is_new_prev_hash = self - .chain_tip - .as_ref() - .is_some_and(|previous| previous.prev_hash() != chain_tip.prev_hash()); self.chain_tip = Some(chain_tip); // all other future jobs are now useless @@ -198,11 +193,6 @@ impl StandardChannel { // the jobs that just went stale can no longer accept shares, so any retired extranonce // prefix they were the last reference to is now releasable self.prune_retired_extranonce_prefixes(); - - // hashes are retained while prev_hash is unchanged, see ShareAccounting::flush_seen_shares - if is_new_prev_hash { - self.share_accounting.flush_seen_shares(); - } } /// Sets the extranonce prefix for the channel. @@ -554,8 +544,7 @@ impl StandardChannel { /// - Clears all future jobs. /// - Marks the previously active job and all past jobs as stale (they are no longer valid for /// share propagation). - /// - Clears past jobs, and the set of seen shares if `prev_hash` changed (a repeated - /// `prev_hash` keeps them, see [`ShareAccounting::flush_seen_shares`]). + /// - Clears past jobs. Seen shares are kept, see [`ShareAccounting::is_share_seen`]. /// - Updates chain tip information. Returns error if no matching future job found, leaving /// channel state untouched. pub fn on_set_new_prev_hash( @@ -600,15 +589,6 @@ impl StandardChannel { // prefix they were the last reference to is now releasable self.prune_retired_extranonce_prefixes(); - // hashes are retained while prev_hash is unchanged, see ShareAccounting::flush_seen_shares - if self - .chain_tip - .as_ref() - .is_some_and(|chain_tip| chain_tip.prev_hash() != set_new_prev_hash.prev_hash) - { - self.share_accounting.flush_seen_shares(); - } - self.chain_tip = Some(set_new_prev_hash.into()); Ok(()) @@ -1981,6 +1961,108 @@ mod tests { assert_eq!(channel.get_past_jobs_count(), 0); } + #[test] + fn test_repeated_prev_hash_keeps_seen_shares() { + // Job IDs are not committed into the block header, so a job under a prev_hash the + // channel has already had, whether the upstream repeats the tip or returns to it after + // moving away (A→B→A), commits to the same headers as the earlier job with the same + // merkle root. The validated-share hashes must survive both, or the same proof is + // validated (and forwarded) again under the new job_id. + let channel_id = 1; + let extranonce_prefix = [ + 83, 116, 114, 97, 116, 117, 109, 32, 86, 50, 32, 83, 82, 73, 32, 80, 111, 111, 108, 0, + 0, 0, 0, 0, 0, 0, 1, + ] + .to_vec(); + + let mut channel = StandardChannel::new( + channel_id, + "user_identity".to_string(), + ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(), + Target::from_le_bytes([0xff; 32]), + 1.0, + None, + ) + .unwrap(); + + let future_job = |job_id: u32| NewMiningJob { + channel_id, + job_id, + merkle_root: [ + 189, 200, 25, 246, 119, 73, 34, 42, 209, 112, 237, 50, 169, 71, 163, 192, 24, 84, + 56, 86, 147, 71, 243, 44, 18, 107, 167, 169, 169, 66, 186, 98, + ] + .into(), + version: 536870912, + ntime_start: Sv2Option::new(None), + }; + + // network target: 000000000000d7c0... (hard, so no accidental BlockFound) + let prev_hash = [ + 200, 53, 253, 129, 214, 31, 43, 84, 179, 58, 58, 76, 128, 213, 24, 53, 38, 144, 205, + 88, 172, 20, 251, 22, 217, 141, 21, 221, 21, 0, 0, 0, + ]; + let mut other_prev_hash = prev_hash; + other_prev_hash[0] ^= 1; + let set_new_prev_hash = |job_id: u32, prev_hash: [u8; 32]| SetNewPrevHashMp { + channel_id, + job_id, + prev_hash: prev_hash.into(), + nbits: 453040064, + ntime_start: 1745596970, + }; + + let share = |sequence_number: u32, job_id: u32| SubmitSharesStandardOwned { + channel_id, + sequence_number, + job_id, + nonce: 0, + ntime: 1745596971, + version: 536870912, + }; + + channel.on_new_mining_job(future_job(1)).unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(1, prev_hash)) + .unwrap(); + assert!(matches!( + channel.validate_share(share(0, 1)), + Ok(ShareValidationResult::Valid(_)) + )); + + // the upstream repeats the tip under a new job_id: same header space, new job + channel.on_new_mining_job(future_job(2)).unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(2, prev_hash)) + .unwrap(); + assert!(matches!( + channel.validate_share(share(1, 2)), + Err(ShareValidationError::DuplicateShare(_)) + )); + + // the tip moves to another prev_hash, where the same nonce makes a different header + channel.on_new_mining_job(future_job(3)).unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(3, other_prev_hash)) + .unwrap(); + assert!(matches!( + channel.validate_share(share(2, 3)), + Ok(ShareValidationResult::Valid(_)) + )); + + // and returns to the first one with the same job again: the proof validated under the + // first tip is still a duplicate + channel.on_new_mining_job(future_job(4)).unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(4, prev_hash)) + .unwrap(); + assert!(matches!( + channel.validate_share(share(3, 4)), + Err(ShareValidationError::DuplicateShare(_)) + )); + assert_eq!(channel.get_share_accounting().get_validated_shares(), 2); + } + #[test] fn test_set_new_prev_hash_keeps_all_past_jobs_in_stale_set() { // Regression test: with past jobs at the MAX_PAST_JOBS cap, retiring the displaced diff --git a/sv2/channels-sv2/src/lib.rs b/sv2/channels-sv2/src/lib.rs index d8290f2117..4d458414f2 100644 --- a/sv2/channels-sv2/src/lib.rs +++ b/sv2/channels-sv2/src/lib.rs @@ -45,9 +45,9 @@ 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. +/// The budget only needs to cover the shares accepted under one `prev_hash` (a server channel +/// starts a new set 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 @@ -90,7 +90,10 @@ pub const MAX_SEEN_SHARES_CAP: usize = 1 << 20; /// 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 +/// 120 000 hashes ≈ 9 MB steady and ~15 MB peak through the last rehash. These figures double +/// when the set of the previous `prev_hash` is still kept aside, which a server channel does so +/// that a tip returning to it keeps rejecting proofs already credited there (see +/// `server::share_accounting::ShareAccounting::on_prev_hash_change`). 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. /// diff --git a/sv2/channels-sv2/src/server/extended.rs b/sv2/channels-sv2/src/server/extended.rs index 61d88b64b3..a76d58a6cf 100644 --- a/sv2/channels-sv2/src/server/extended.rs +++ b/sv2/channels-sv2/src/server/extended.rs @@ -802,8 +802,8 @@ impl ExtendedChannel { /// it, as no Template Distribution message refers to it. /// /// The previously active job and all past jobs go stale, the other future jobs are dropped, - /// the chain tip is updated and accepted-share hashes are flushed if `prev_hash` changed, see - /// [`ShareAccounting::flush_seen_shares`]. Returns [`ExtendedChannelError::JobIdNotFound`] if + /// the chain tip is updated and accepted-share hashes are kept per `prev_hash`, see + /// [`ShareAccounting::on_prev_hash_change`]. Returns [`ExtendedChannelError::JobIdNotFound`] if /// no future job carries `job_id`, leaving the channel unchanged. pub fn activate_future_job( &mut self, @@ -827,16 +827,13 @@ impl ExtendedChannel { Ok(()) } - /// Updates the chain tip, flushing accepted-share hashes only if `prev_hash` changed: a - /// repeated tip commits to the same header space, see - /// [`ShareAccounting::flush_seen_shares`]. + /// Updates the chain tip. Accepted-share hashes are kept per `prev_hash`, so a repeated tip, + /// or a return to the `prev_hash` just left, still rejects proofs already credited under it, + /// see [`ShareAccounting::on_prev_hash_change`]. fn update_chain_tip(&mut self, chain_tip: ChainTip) { - if self - .chain_tip - .as_ref() - .is_some_and(|current| current.prev_hash() != chain_tip.prev_hash()) - { - self.share_accounting.flush_seen_shares(); + if let Some(current) = &self.chain_tip { + self.share_accounting + .on_prev_hash_change(current.prev_hash(), chain_tip.prev_hash()); } self.chain_tip = Some(chain_tip); } @@ -853,8 +850,9 @@ impl ExtendedChannel { /// /// All past jobs are cleared. /// - /// Accepted-share hashes are flushed only if `prev_hash` actually changed: a repeated tip - /// commits to the same header space, see [`ShareAccounting::flush_seen_shares`]. + /// Accepted-share hashes are kept per `prev_hash`, so a repeated tip, or a return to the + /// `prev_hash` just left, still rejects proofs already credited under it, see + /// [`ShareAccounting::on_prev_hash_change`]. pub fn on_set_new_prev_hash( &mut self, set_new_prev_hash: SetNewPrevHashTdp, @@ -894,9 +892,9 @@ impl ExtendedChannel { /// instead. The new custom mining job is then set as the active job. /// /// Assumes SetCustomMiningJob.{prev_hash, nbits, ntime_start} have already been validated. - /// Updates the channel's `ChainTip`. Accepted-share hashes are flushed only if `prev_hash` - /// changed: a custom job that keeps it and only advances `ntime_start` (or `nbits`) commits to - /// the same header space as its predecessor, see [`ShareAccounting::flush_seen_shares`]. + /// Updates the channel's `ChainTip`. Accepted-share hashes are kept per `prev_hash`: a custom + /// job that keeps it and only advances `ntime_start` (or `nbits`) commits to the same header + /// space as its predecessor, see [`ShareAccounting::on_prev_hash_change`]. /// /// Returns the job id of the new custom mining job. /// @@ -943,9 +941,10 @@ impl ExtendedChannel { } // only a prev_hash change opens a new header space; nbits or ntime_start alone do not, - // see ShareAccounting::flush_seen_shares - if is_new_prev_hash { - self.share_accounting.flush_seen_shares(); + // see ShareAccounting::on_prev_hash_change + if let Some(chain_tip) = &self.chain_tip { + self.share_accounting + .on_prev_hash_change(chain_tip.prev_hash(), new_chain_tip.prev_hash()); } // dropping the evicted past job's target mapping (its shares degrade to InvalidJobId) @@ -4549,6 +4548,82 @@ mod tests { assert_eq!(channel.get_share_accounting().get_shares_accepted(), 1); } + #[test] + fn test_custom_job_returning_to_previous_prev_hash_keeps_seen_shares() { + // A custom job that returns to the prev_hash the channel just left (A→B→A), with the + // same coinbase, commits to the same header space as the job accepted under A before. + // The hashes accepted under A must survive the round trip, or the same proof becomes + // creditable again under the returning job ID. + let channel_id = 1; + let max_target = Target::from_le_bytes([0xff; 32]); + let mut channel = ExtendedChannel::new( + channel_id, + "user_identity".to_string(), + ExtranoncePrefix::from_wire(vec![1, 2, 3, 4]).unwrap(), + max_target, + 100.0, + true, + 8u16, + 100, + 1.0, + None, + None, + None, + ) + .unwrap(); + // permissive channel target, so that the share is accepted under every job + channel.set_target(max_target).unwrap(); + + let prev_hash = [ + 154, 124, 239, 231, 221, 122, 160, 173, 164, 175, 87, 33, 74, 214, 191, 107, 73, 34, 0, + 162, 227, 16, 44, 40, 33, 73, 0, 0, 0, 0, 0, 0, + ]; + let mut other_prev_hash = prev_hash; + other_prev_hash[0] ^= 1; + let ntime_start = 1745596910; + + let share = |sequence_number: u32, job_id: u32| SubmitSharesExtended { + channel_id, + sequence_number, + job_id, + nonce: 0, + ntime: ntime_start + 1, + version: 536870912, + extranonce: vec![0; 8].try_into().unwrap(), + }; + + let first_job_id = channel + .on_set_custom_mining_job(custom_mining_job(channel_id, 1, prev_hash, ntime_start)) + .unwrap(); + assert!(matches!( + channel.validate_share(share(0, first_job_id)), + Ok(ShareValidationResult::Valid(_)) + )); + + // under another prev_hash the same nonce makes a different header + let second_job_id = channel + .on_set_custom_mining_job(custom_mining_job( + channel_id, + 2, + other_prev_hash, + ntime_start, + )) + .unwrap(); + assert!(matches!( + channel.validate_share(share(1, second_job_id)), + Ok(ShareValidationResult::Valid(_)) + )); + + let third_job_id = channel + .on_set_custom_mining_job(custom_mining_job(channel_id, 3, prev_hash, ntime_start)) + .unwrap(); + assert!(matches!( + channel.validate_share(share(2, third_job_id)), + Err(ShareValidationError::DuplicateShare(_)) + )); + assert_eq!(channel.get_share_accounting().get_shares_accepted(), 2); + } + #[test] fn test_zero_max_target_is_rejected() { // a zero max_target is refused at open, on update and on set_target, leaving the @@ -5077,7 +5152,7 @@ mod tests { 162, 227, 16, 44, 40, 33, 73, 0, 0, 0, 0, 0, 0, ] .into(); - let set_new_prev_hash = |template_id: u64| SetNewPrevHash { + let set_new_prev_hash = |template_id: u64, prev_hash: &U256| SetNewPrevHash { template_id, prev_hash: prev_hash.clone(), ntime_start: 1745596910, @@ -5088,7 +5163,9 @@ mod tests { channel .on_new_template(template(1), coinbase_reward_outputs.clone()) .unwrap(); - channel.on_set_new_prev_hash(set_new_prev_hash(1)).unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(1, &prev_hash)) + .unwrap(); let first_job_id = channel.get_active_job().unwrap().get_job_id(); let share = |sequence_number: u32, job_id: u32| SubmitSharesExtended { @@ -5100,16 +5177,18 @@ mod tests { version: 536870912, extranonce: vec![1, 0, 0, 0, 0, 0, 0, 0].try_into().unwrap(), }; - assert!(matches!( - channel.validate_share(share(0, first_job_id)), - Ok(ShareValidationResult::Valid(_)) - )); + let first_share_hash = match channel.validate_share(share(0, first_job_id)) { + Ok(ShareValidationResult::Valid(share_hash)) => share_hash, + _ => panic!("the first share must be valid"), + }; // the peer repeats the tip under a new template_id: same header space, new job_id channel - .on_new_template(template(2), coinbase_reward_outputs) + .on_new_template(template(2), coinbase_reward_outputs.clone()) + .unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(2, &prev_hash)) .unwrap(); - channel.on_set_new_prev_hash(set_new_prev_hash(2)).unwrap(); let second_job_id = channel.get_active_job().unwrap().get_job_id(); assert_ne!(first_job_id, second_job_id); @@ -5119,6 +5198,45 @@ mod tests { Err(ShareValidationError::DuplicateShare(_)) )); assert_eq!(channel.get_share_accounting().get_shares_accepted(), 1); + + // the tip moves to another prev_hash, where the same nonce makes a different header + let mut other_prev_hash = prev_hash.to_array(); + other_prev_hash[0] ^= 1; + let other_prev_hash: U256 = other_prev_hash.into(); + channel + .on_new_template(template(3), coinbase_reward_outputs.clone()) + .unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(3, &other_prev_hash)) + .unwrap(); + let third_job_id = channel.get_active_job().unwrap().get_job_id(); + assert!(matches!( + channel.validate_share(share(2, third_job_id)), + Ok(ShareValidationResult::Valid(_)) + )); + // the hashes accepted under the first tip are set aside, so they don't count towards + // this tip's budget + assert!(!channel + .get_share_accounting() + .is_share_seen(first_share_hash)); + + // and returns to the first one with the same template again (A→B→A): the proof + // credited under the first tip is still a duplicate + channel + .on_new_template(template(4), coinbase_reward_outputs) + .unwrap(); + channel + .on_set_new_prev_hash(set_new_prev_hash(4, &prev_hash)) + .unwrap(); + let fourth_job_id = channel.get_active_job().unwrap().get_job_id(); + assert!(channel + .get_share_accounting() + .is_share_seen(first_share_hash)); + assert!(matches!( + channel.validate_share(share(3, fourth_job_id)), + Err(ShareValidationError::DuplicateShare(_)) + )); + assert_eq!(channel.get_share_accounting().get_shares_accepted(), 2); } #[test] diff --git a/sv2/channels-sv2/src/server/share_accounting.rs b/sv2/channels-sv2/src/server/share_accounting.rs index 92fee64a7a..f19b3788ee 100644 --- a/sv2/channels-sv2/src/server/share_accounting.rs +++ b/sv2/channels-sv2/src/server/share_accounting.rs @@ -19,6 +19,7 @@ //! issue `SubmitShares.Success` or `SubmitShares.Error` messages. Not intended for use by mining //! clients. +use binary_sv2::U256Owned; use bitcoin::hashes::sha256d::Hash; use std::collections::{HashMap, HashSet}; @@ -99,6 +100,8 @@ pub struct ShareAccounting { batch_acknowledged: bool, share_batch_size: usize, seen_shares: HashSet, + // the hashes accepted under the previous prev_hash, put back if the tip returns to it + previous_seen_shares: Option<(U256Owned, HashSet)>, seen_shares_budget: usize, best_diff: f64, blocks_found: u32, @@ -124,6 +127,7 @@ impl ShareAccounting { batch_acknowledged: false, share_batch_size, seen_shares: HashSet::new(), + previous_seen_shares: None, seen_shares_budget, best_diff: 0.0, blocks_found: 0, @@ -173,17 +177,33 @@ impl ShareAccounting { } } - /// Clears the set of seen share hashes. + /// Moves duplicate detection from the chain tip's `prev_hash` to `new_prev_hash`. /// - /// Must be called whenever the chain tip's `prev_hash` changes, and only then. Accepted - /// hashes are retained for as long as `prev_hash` is unchanged: job and template IDs are not - /// committed into the block header, so a job replaced under the same `prev_hash` commits to - /// the same header space as its predecessor, and flushing then would let a proof that was - /// already credited be credited again under the new job ID. This is also what makes the - /// seen-shares budget per-`prev_hash`: the set only ever holds the shares accepted while one - /// `prev_hash` was current. - pub fn flush_seen_shares(&mut self) { - self.seen_shares.clear(); + /// Must be called whenever the chain tip's `prev_hash` changes; an unchanged `prev_hash` is a + /// no-op. Job and template IDs are not committed into the block header, so any job under a + /// given `prev_hash` can commit to the same header space as an earlier one, and forgetting + /// the hashes accepted under that `prev_hash` would let a proof that was already credited be + /// credited again under a new job ID. That holds while `prev_hash` is unchanged, and also + /// when the tip returns to the `prev_hash` it just left (A→B→A): the hashes of the + /// `prev_hash` being left are kept aside and become current again if the next change + /// returns to it. Hashes kept for an older `prev_hash` are dropped. + /// + /// Header hashes commit to `prev_hash`, so hashes accepted under different tips never + /// compare equal and only the current set needs checking. The seen-shares budget applies to + /// that set alone, so it stays per-`prev_hash`, and the cache holds at most twice + /// `seen_shares_budget` hashes. + pub fn on_prev_hash_change(&mut self, prev_hash: U256Owned, new_prev_hash: U256Owned) { + if prev_hash == new_prev_hash { + return; + } + let restored = match self.previous_seen_shares.take() { + Some((previous_prev_hash, seen_shares)) if previous_prev_hash == new_prev_hash => { + seen_shares + } + _ => HashSet::new(), + }; + let left = std::mem::replace(&mut self.seen_shares, restored); + self.previous_seen_shares = Some((prev_hash, left)); } /// Returns `true` once the accepted-share dedup cache has reached its budget. @@ -265,9 +285,9 @@ impl ShareAccounting { /// Checks if the share hash has already been accepted (duplicate detection). /// - /// The underlying set holds at most `seen_shares_budget` hashes (see - /// [`is_seen_shares_budget_exhausted`](Self::is_seen_shares_budget_exhausted)) and is flushed - /// whenever the chain tip's `prev_hash` changes. + /// Only the hashes accepted under the current `prev_hash` are checked, see + /// [`on_prev_hash_change`](Self::on_prev_hash_change). They are at most `seen_shares_budget` + /// (see [`is_seen_shares_budget_exhausted`](Self::is_seen_shares_budget_exhausted)). pub fn is_share_seen(&self, share_hash: Hash) -> bool { self.seen_shares.contains(&share_hash) } @@ -397,9 +417,42 @@ mod tests { assert!(accounting.is_share_seen(hash(i))); } - // a chain-tip transition resets the budget - accounting.flush_seen_shares(); + // a prev_hash change resets the budget + accounting.on_prev_hash_change([1; 32].into(), [2; 32].into()); assert!(!accounting.is_seen_shares_budget_exhausted()); assert!(!accounting.is_share_seen(hash(0))); } + + #[test] + fn seen_shares_are_kept_for_the_previous_prev_hash() { + fn hash(i: u32) -> bitcoin::hashes::sha256d::Hash { + let mut bytes = [0u8; 32]; + bytes[..4].copy_from_slice(&i.to_le_bytes()); + ::from_slice(&bytes).unwrap() + } + let (a, b, c) = ([1; 32], [2; 32], [3; 32]); + let mut accounting = ShareAccounting::new(10, 100); + + accounting.update_share_accounting(1.0, 0, hash(0)); + accounting.on_prev_hash_change(a.into(), b.into()); + accounting.update_share_accounting(1.0, 1, hash(1)); + assert!(!accounting.is_share_seen(hash(0))); + + // A→B→A puts A's hashes back, and keeps B's aside + accounting.on_prev_hash_change(b.into(), a.into()); + assert!(accounting.is_share_seen(hash(0))); + assert!(!accounting.is_share_seen(hash(1))); + accounting.on_prev_hash_change(a.into(), b.into()); + assert!(accounting.is_share_seen(hash(1))); + + // an unchanged prev_hash keeps the current hashes + accounting.on_prev_hash_change(b.into(), b.into()); + assert!(accounting.is_share_seen(hash(1))); + + // B→C→A: only B's hashes were kept aside, so A starts empty + accounting.on_prev_hash_change(b.into(), c.into()); + accounting.on_prev_hash_change(c.into(), a.into()); + assert!(!accounting.is_share_seen(hash(0))); + assert!(!accounting.is_share_seen(hash(1))); + } } diff --git a/sv2/channels-sv2/src/server/standard.rs b/sv2/channels-sv2/src/server/standard.rs index eadc95a8d0..86cbc41560 100644 --- a/sv2/channels-sv2/src/server/standard.rs +++ b/sv2/channels-sv2/src/server/standard.rs @@ -747,8 +747,8 @@ impl StandardChannel { /// it, as no Template Distribution message refers to it. /// /// The previously active job and all past jobs go stale, the other future jobs are dropped, - /// the chain tip is updated and accepted-share hashes are flushed if `prev_hash` changed, see - /// [`ShareAccounting::flush_seen_shares`]. Returns [`StandardChannelError::JobIdNotFound`] if + /// the chain tip is updated and accepted-share hashes are kept per `prev_hash`, see + /// [`ShareAccounting::on_prev_hash_change`]. Returns [`StandardChannelError::JobIdNotFound`] if /// no future job carries `job_id`, leaving the channel unchanged. pub fn activate_future_job( &mut self, @@ -774,16 +774,13 @@ impl StandardChannel { Ok(()) } - /// Updates the chain tip, flushing accepted-share hashes only if `prev_hash` changed: a - /// repeated tip commits to the same header space, see - /// [`ShareAccounting::flush_seen_shares`]. + /// Updates the chain tip. Accepted-share hashes are kept per `prev_hash`, so a repeated tip, + /// or a return to the `prev_hash` just left, still rejects proofs already credited under it, + /// see [`ShareAccounting::on_prev_hash_change`]. fn update_chain_tip(&mut self, chain_tip: ChainTip) { - if self - .chain_tip - .as_ref() - .is_some_and(|current| current.prev_hash() != chain_tip.prev_hash()) - { - self.share_accounting.flush_seen_shares(); + if let Some(current) = &self.chain_tip { + self.share_accounting + .on_prev_hash_change(current.prev_hash(), chain_tip.prev_hash()); } self.chain_tip = Some(chain_tip); } @@ -803,8 +800,9 @@ impl StandardChannel { /// /// All past jobs are cleared. /// - /// Accepted-share hashes are flushed only if `prev_hash` actually changed: a repeated tip - /// commits to the same header space, see [`ShareAccounting::flush_seen_shares`]. + /// Accepted-share hashes are kept per `prev_hash`, so a repeated tip, or a return to the + /// `prev_hash` just left, still rejects proofs already credited under it, see + /// [`ShareAccounting::on_prev_hash_change`]. pub fn on_set_new_prev_hash( &mut self, set_new_prev_hash: SetNewPrevHash, @@ -3655,19 +3653,20 @@ mod tests { 162, 227, 16, 44, 40, 33, 73, 0, 0, 0, 0, 0, 0, ] .into(); - let set_new_prev_hash = |template_id: u64| SetNewPrevHashTdp { - template_id, - prev_hash: prev_hash.clone(), - ntime_start: 1745596910, - n_bits: 453040064, - target: [0xff; 32].into(), - }; + let set_new_prev_hash = + |template_id: u64, prev_hash: &binary_sv2::U256Owned| SetNewPrevHashTdp { + template_id, + prev_hash: prev_hash.clone(), + ntime_start: 1745596910, + n_bits: 453040064, + target: [0xff; 32].into(), + }; standard_channel .on_new_template(template(1), coinbase_reward_outputs.clone()) .unwrap(); standard_channel - .on_set_new_prev_hash(set_new_prev_hash(1)) + .on_set_new_prev_hash(set_new_prev_hash(1, &prev_hash)) .unwrap(); let first_job_id = standard_channel.get_active_job().unwrap().get_job_id(); @@ -3679,17 +3678,17 @@ mod tests { ntime: 1745596910, version: 536870912, }; - assert!(matches!( - standard_channel.validate_share(share(0, first_job_id)), - Ok(ShareValidationResult::Valid(_)) - )); + let first_share_hash = match standard_channel.validate_share(share(0, first_job_id)) { + Ok(ShareValidationResult::Valid(share_hash)) => share_hash, + _ => panic!("the first share must be valid"), + }; // the peer repeats the tip under a new template_id: same header space, new job_id standard_channel - .on_new_template(template(2), coinbase_reward_outputs) + .on_new_template(template(2), coinbase_reward_outputs.clone()) .unwrap(); standard_channel - .on_set_new_prev_hash(set_new_prev_hash(2)) + .on_set_new_prev_hash(set_new_prev_hash(2, &prev_hash)) .unwrap(); let second_job_id = standard_channel.get_active_job().unwrap().get_job_id(); assert_ne!(first_job_id, second_job_id); @@ -3712,6 +3711,50 @@ mod tests { .get_shares_accepted(), 1 ); + + // the tip moves to another prev_hash, where the same nonce makes a different header + let mut other_prev_hash = prev_hash.to_array(); + other_prev_hash[0] ^= 1; + let other_prev_hash: binary_sv2::U256Owned = other_prev_hash.into(); + standard_channel + .on_new_template(template(3), coinbase_reward_outputs.clone()) + .unwrap(); + standard_channel + .on_set_new_prev_hash(set_new_prev_hash(3, &other_prev_hash)) + .unwrap(); + let third_job_id = standard_channel.get_active_job().unwrap().get_job_id(); + assert!(matches!( + standard_channel.validate_share(share(2, third_job_id)), + Ok(ShareValidationResult::Valid(_)) + )); + // the hashes accepted under the first tip are set aside, so they don't count towards + // this tip's budget + assert!(!standard_channel + .get_share_accounting() + .is_share_seen(first_share_hash)); + + // and returns to the first one with the same template again (A→B→A): the proof + // credited under the first tip is still a duplicate + standard_channel + .on_new_template(template(4), coinbase_reward_outputs) + .unwrap(); + standard_channel + .on_set_new_prev_hash(set_new_prev_hash(4, &prev_hash)) + .unwrap(); + let fourth_job_id = standard_channel.get_active_job().unwrap().get_job_id(); + assert!(standard_channel + .get_share_accounting() + .is_share_seen(first_share_hash)); + assert!(matches!( + standard_channel.validate_share(share(3, fourth_job_id)), + Err(ShareValidationError::DuplicateShare(_)) + )); + assert_eq!( + standard_channel + .get_share_accounting() + .get_shares_accepted(), + 2 + ); } #[test] From b0fbd3883cbcc90d1ebe70e9bb91115c47245162 Mon Sep 17 00:00:00 2001 From: jolah1 Date: Mon, 9 Nov 2026 12:22:02 +0100 Subject: [PATCH 2/2] bump channels_sv2 and the crates that expose it channels_sv2 breaks its API, so it takes a major bump. stratum_translation exposes channels_sv2::bip141::StripBip141Error in StratumTranslationError, and stratum-core re-exports both, so taking channels_sv2 10 breaks them too. --- Cargo.lock | 6 +++--- stratum-core/Cargo.toml | 6 +++--- stratum-core/stratum-translation/Cargo.toml | 4 ++-- sv2/channels-sv2/Cargo.toml | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 58a34da8dd..5e9c64cb60 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -250,7 +250,7 @@ dependencies = [ [[package]] name = "channels_sv2" -version = "9.0.0" +version = "10.0.0" dependencies = [ "binary_sv2", "bitcoin", @@ -1162,7 +1162,7 @@ checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f" [[package]] name = "stratum-core" -version = "0.7.0" +version = "0.8.0" dependencies = [ "binary_sv2", "bitcoin", @@ -1184,7 +1184,7 @@ dependencies = [ [[package]] name = "stratum_translation" -version = "0.6.0" +version = "0.7.0" dependencies = [ "binary_sv2", "bitcoin", diff --git a/stratum-core/Cargo.toml b/stratum-core/Cargo.toml index a04da46d3b..657dbb8854 100644 --- a/stratum-core/Cargo.toml +++ b/stratum-core/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "stratum-core" -version = "0.7.0" +version = "0.8.0" authors = ["The Stratum V2 Developers"] edition = "2021" readme = "README.md" @@ -20,13 +20,13 @@ framing_sv2 = { path = "../sv2/framing-sv2", version = "^9.0.0" } noise_sv2 = { path = "../sv2/noise-sv2", version = "^2.1.0" } parsers_sv2 = { path = "../sv2/parsers-sv2", version = "^0.7.0" } handlers_sv2 = { path = "../sv2/handlers-sv2", version = "^0.7.0" } -channels_sv2 = { path = "../sv2/channels-sv2", version = "^9.0.0" } +channels_sv2 = { path = "../sv2/channels-sv2", version = "^10.0.0" } common_messages_sv2 = { path = "../sv2/subprotocols/common-messages", version = "^10.0.0" } mining_sv2 = { path = "../sv2/subprotocols/mining", version = "^13.0.0" } template_distribution_sv2 = { path = "../sv2/subprotocols/template-distribution", version = "^8.0.0" } job_declaration_sv2 = { path = "../sv2/subprotocols/job-declaration", version = "^11.0.0" } sv1_api = { path = "../sv1", version = "^7.0.0", optional = true } -stratum_translation = { path = "stratum-translation", version = "^0.6.0", optional = true } +stratum_translation = { path = "stratum-translation", version = "^0.7.0", optional = true } bitcoin = { workspace = true } [features] diff --git a/stratum-core/stratum-translation/Cargo.toml b/stratum-core/stratum-translation/Cargo.toml index eb3f1644b4..c5e635f9d7 100644 --- a/stratum-core/stratum-translation/Cargo.toml +++ b/stratum-core/stratum-translation/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "stratum_translation" -version = "0.6.0" +version = "0.7.0" edition = "2021" license = "MIT OR Apache-2.0" description = "Stratum V1 ↔ Stratum V2 translation utilities for reuse across proxies, apps, and firmware" @@ -12,7 +12,7 @@ path = "src/lib.rs" [dependencies] binary_sv2 = { path = "../../sv2/binary-sv2", version = "^8.0.0" } mining_sv2 = { path = "../../sv2/subprotocols/mining", version = "^13.0.0" } -channels_sv2 = { path = "../../sv2/channels-sv2", version = "^9.0.0" } +channels_sv2 = { path = "../../sv2/channels-sv2", version = "^10.0.0" } v1 = { path = "../../sv1", package = "sv1_api", version = "^7.0.0" } tracing = { workspace = true } bitcoin = { workspace = true } diff --git a/sv2/channels-sv2/Cargo.toml b/sv2/channels-sv2/Cargo.toml index 6aa2b4e73f..9719d5298f 100644 --- a/sv2/channels-sv2/Cargo.toml +++ b/sv2/channels-sv2/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "channels_sv2" -version = "9.0.0" +version = "10.0.0" authors = ["The Stratum V2 Developers"] edition = "2021" readme = "README.md"