Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions stratum-core/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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]
Expand Down
4 changes: 2 additions & 2 deletions stratum-core/stratum-translation/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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 }
Expand Down
2 changes: 1 addition & 1 deletion sv2/channels-sv2/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
73 changes: 39 additions & 34 deletions sv2/channels-sv2/src/client/extended.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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,
Expand Down Expand Up @@ -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(())
Expand Down Expand Up @@ -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,
};
Expand All @@ -3359,22 +3336,50 @@ 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(_))
));

// 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!(
channel.validate_share(share(1, 2)),
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.
Expand Down
7 changes: 4 additions & 3 deletions sv2/channels-sv2/src/client/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
31 changes: 9 additions & 22 deletions sv2/channels-sv2/src/client/share_accounting.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
}
Expand Down Expand Up @@ -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);
}
}
Loading
Loading