Skip to content

Add extranonce_manager module in channels_sv2 #2098

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
plebhash merged 4 commits into from
Apr 24, 2026
Merged

Add extranonce_manager module in channels_sv2 #2098

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a8a949d
implement ExtranonceAllocator for efficient extranonce prefix managem…
GitGab19 Mar 2, 2026
5ce25ec
remove legacy extranonce from `mining_sv2`
GitGab19 Mar 2, 2026
a4a234c
add `from_arbitrary_vec_to_array` in two tests (after removing it fro…
GitGab19 Mar 2, 2026
fd67587
bump MAJOR of `mining_sv2`
GitGab19 Apr 16, 2026
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
View file
Open in desktop

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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,11 @@ codec_sv2 = { path = "../sv2/codec-sv2", version = "^5.0.0", features = ["noise_
extensions_sv2 = { path = "../sv2/extensions-sv2", version = "^0.1.0" }
framing_sv2 = { path = "../sv2/framing-sv2", version = "^6.0.0" }
noise_sv2 = { path = "../sv2/noise-sv2", version = "^1.0.0" }
parsers_sv2 = { path = "../sv2/parsers-sv2", version = "^0.2.0" }
handlers_sv2 = { path = "../sv2/handlers-sv2", version = "^0.2.0" }
parsers_sv2 = { path = "../sv2/parsers-sv2", version = "^0.3.0" }
handlers_sv2 = { path = "../sv2/handlers-sv2", version = "^0.3.0" }
channels_sv2 = { path = "../sv2/channels-sv2", version = "^5.0.0" }
common_messages_sv2 = { path = "../sv2/subprotocols/common-messages", version = "^7.0.0" }
mining_sv2 = { path = "../sv2/subprotocols/mining", version = "^8.0.0" }
mining_sv2 = { path = "../sv2/subprotocols/mining", version = "^9.0.0" }
template_distribution_sv2 = { path = "../sv2/subprotocols/template-distribution", version = "^5.0.0" }
job_declaration_sv2 = { path = "../sv2/subprotocols/job-declaration", version = "^7.0.0" }
sv1_api = { path = "../sv1", version = "^4.0.0", optional = true }
Expand Down
2 changes: 1 addition & 1 deletion stratum-core/stratum-translation/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ path = "src/lib.rs"

[dependencies]
binary_sv2 = { path = "../../sv2/binary-sv2", version = "^5.0.0" }
mining_sv2 = { path = "../../sv2/subprotocols/mining", version = "^8.0.0" }
mining_sv2 = { path = "../../sv2/subprotocols/mining", version = "^9.0.0" }
channels_sv2 = { path = "../../sv2/channels-sv2", version = "^5.0.0" }
v1 = { path = "../../sv1", package = "sv1_api", version = "^4.0.0" }
tracing = { workspace = true }
Expand Down
2 changes: 1 addition & 1 deletion sv2/channels-sv2/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ keywords = ["stratum", "mining", "bitcoin", "protocol"]

[dependencies]
binary_sv2 = { path = "../binary-sv2", version = "^5.0.0" }
mining_sv2 = { path = "../subprotocols/mining", version = "^8.0.0" }
mining_sv2 = { path = "../subprotocols/mining", version = "^9.0.0" }
template_distribution_sv2 = { path = "../subprotocols/template-distribution", version = "^5.0.0" }
tracing = { workspace = true }
bitcoin = { workspace = true }
Expand Down
56 changes: 37 additions & 19 deletions sv2/channels-sv2/src/client/extended.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,10 @@ use crate::{
error::ExtendedChannelError,
share_accounting::{ShareAccounting, ShareValidationError, ShareValidationResult},
},
extranonce_manager::ExtranoncePrefix,
merkle_root::merkle_root_from_path,
target::{bytes_to_hex, u256_to_block_hash},
MAX_EXTRANONCE_PREFIX_LEN,
MAX_EXTRANONCE_LEN,
};
use alloc::{format, string::String, vec, vec::Vec};
use binary_sv2::{self, Sv2Option};
Expand Down Expand Up @@ -59,11 +60,11 @@ pub type ExtendedJob<'a> = (NewExtendedMiningJob<'a>, Vec<u8>, Target);
/// `job_id`).
/// - Share accounting for the channel (as tracked by the client).
/// - The channel's current chain tip.
#[derive(Clone, Debug)]
#[derive(Debug)]
pub struct ExtendedChannel<'a> {
channel_id: u32,
user_identity: String,
extranonce_prefix: Vec<u8>,
extranonce_prefix: ExtranoncePrefix,
rollable_extranonce_size: u16,
target: Target,
nominal_hashrate: f32,
Expand All @@ -84,7 +85,7 @@ impl<'a> ExtendedChannel<'a> {
pub fn new(
channel_id: u32,
user_identity: String,
extranonce_prefix: Vec<u8>,
extranonce_prefix: ExtranoncePrefix,
target: Target,
nominal_hashrate: f32,
version_rolling: bool,
Expand Down Expand Up @@ -118,8 +119,22 @@ impl<'a> ExtendedChannel<'a> {
}

/// Returns the bytes representing the first part of the `extranonce`.
pub fn get_extranonce_prefix(&self) -> &Vec<u8> {
&self.extranonce_prefix
pub fn get_extranonce_prefix(&self) -> &[u8] {
self.extranonce_prefix.as_bytes()
}

/// Returns the length of the `upstream_prefix` region of this channel's
/// extranonce prefix, if known.
///
/// See [`ExtranoncePrefix::upstream_prefix_len`](crate::extranonce_manager::ExtranoncePrefix::upstream_prefix_len)
/// for the full semantics. In particular, this is `None` for channels
/// opened from a wire-sourced prefix (the common case on a client),
/// and `Some(n)` when the application minted the prefix locally from
/// an [`ExtranonceAllocator`](crate::extranonce_manager::ExtranonceAllocator) — e.g. a proxy that
/// sub-allocates an upstream-assigned extranonce space and hands one
/// slot to each downstream channel.
pub fn upstream_prefix_len(&self) -> Option<u8> {
self.extranonce_prefix.upstream_prefix_len()
}

/// Returns `true` if the channel supports version rolling as per [BIP 320](https://github.com/bitcoin/bips/blob/master/bip-0320.mediawiki).
Expand All @@ -146,9 +161,9 @@ impl<'a> ExtendedChannel<'a> {
/// Returns an error if the new extranonce prefix is too large.
pub fn set_extranonce_prefix(
&mut self,
new_extranonce_prefix: Vec<u8>,
new_extranonce_prefix: ExtranoncePrefix,
) -> Result<(), ExtendedChannelError> {
if new_extranonce_prefix.len() > MAX_EXTRANONCE_PREFIX_LEN {
if new_extranonce_prefix.len() > MAX_EXTRANONCE_LEN as usize {
return Err(ExtendedChannelError::NewExtranoncePrefixTooLarge);
}

Expand Down Expand Up @@ -267,7 +282,7 @@ impl<'a> ExtendedChannel<'a> {
}
self.active_job = Some((
new_extended_mining_job,
self.extranonce_prefix.clone(),
self.extranonce_prefix.as_bytes().to_vec(),
self.target,
));
}
Expand All @@ -276,7 +291,7 @@ impl<'a> ExtendedChannel<'a> {
new_extended_mining_job.job_id,
(
new_extended_mining_job,
self.extranonce_prefix.clone(),
self.extranonce_prefix.as_bytes().to_vec(),
self.target,
),
);
Expand Down Expand Up @@ -389,7 +404,7 @@ impl<'a> ExtendedChannel<'a> {
}
self.active_job = Some((
new_extended_mining_job,
self.extranonce_prefix.clone(),
self.extranonce_prefix.as_bytes().to_vec(),
self.target,
));

Expand Down Expand Up @@ -608,9 +623,12 @@ impl<'a> ExtendedChannel<'a> {

#[cfg(test)]
mod tests {
use crate::client::{
extended::ExtendedChannel,
share_accounting::{ShareValidationError, ShareValidationResult},
use crate::{
client::{
extended::ExtendedChannel,
share_accounting::{ShareValidationError, ShareValidationResult},
},
extranonce_manager::ExtranoncePrefix,
};
use binary_sv2::Sv2Option;
use bitcoin::Target;
Expand All @@ -636,7 +654,7 @@ mod tests {
let mut channel = ExtendedChannel::new(
channel_id,
user_identity,
extranonce_prefix.clone(),
ExtranoncePrefix::from_wire(extranonce_prefix.clone()).unwrap(),
target,
nominal_hashrate,
version_rolling,
Expand Down Expand Up @@ -722,7 +740,7 @@ mod tests {
let mut channel = ExtendedChannel::new(
channel_id,
user_identity,
extranonce_prefix.clone(),
ExtranoncePrefix::from_wire(extranonce_prefix.clone()).unwrap(),
target,
nominal_hashrate,
version_rolling,
Expand Down Expand Up @@ -803,7 +821,7 @@ mod tests {
let mut channel = ExtendedChannel::new(
channel_id,
user_identity,
extranonce_prefix.clone(),
ExtranoncePrefix::from_wire(extranonce_prefix.clone()).unwrap(),
target,
nominal_hashrate,
version_rolling,
Expand Down Expand Up @@ -904,7 +922,7 @@ mod tests {
let mut channel = ExtendedChannel::new(
channel_id,
user_identity,
extranonce_prefix.clone(),
ExtranoncePrefix::from_wire(extranonce_prefix.clone()).unwrap(),
target,
nominal_hashrate,
version_rolling,
Expand Down Expand Up @@ -999,7 +1017,7 @@ mod tests {
let mut channel = ExtendedChannel::new(
channel_id,
user_identity,
extranonce_prefix.clone(),
ExtranoncePrefix::from_wire(extranonce_prefix.clone()).unwrap(),
target,
nominal_hashrate,
version_rolling,
Expand Down
54 changes: 36 additions & 18 deletions sv2/channels-sv2/src/client/standard.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,12 @@ use crate::{
error::StandardChannelError,
share_accounting::{ShareAccounting, ShareValidationError, ShareValidationResult},
},
extranonce_manager::ExtranoncePrefix,
merkle_root::merkle_root_from_path,
target::{bytes_to_hex, u256_to_block_hash},
MAX_EXTRANONCE_PREFIX_LEN,
MAX_EXTRANONCE_LEN,
};
use alloc::{format, string::String, vec::Vec};
use alloc::{format, string::String};
use binary_sv2::{self, Sv2Option};
use bitcoin::{
blockdata::block::{Header, Version},
Expand Down Expand Up @@ -45,11 +46,11 @@ pub type StandardJob<'a> = (NewMiningJob<'a>, Target);
/// - stale jobs (jobs from previous chain tip, indexed by job_id)
/// - share accounting state
/// - chain tip state
#[derive(Debug, Clone)]
#[derive(Debug)]
pub struct StandardChannel<'a> {
channel_id: u32,
user_identity: String,
extranonce_prefix: Vec<u8>,
extranonce_prefix: ExtranoncePrefix,
target: Target,
nominal_hashrate: f32,
future_jobs: HashMap<u32, StandardJob<'a>>,
Expand All @@ -65,7 +66,7 @@ impl<'a> StandardChannel<'a> {
pub fn new(
channel_id: u32,
user_identity: String,
extranonce_prefix: Vec<u8>,
extranonce_prefix: ExtranoncePrefix,
target: Target,
nominal_hashrate: f32,
) -> Self {
Expand Down Expand Up @@ -111,9 +112,9 @@ impl<'a> StandardChannel<'a> {
/// Returns an error if the prefix is too large.
pub fn set_extranonce_prefix(
&mut self,
extranonce_prefix: Vec<u8>,
extranonce_prefix: ExtranoncePrefix,
) -> Result<(), StandardChannelError> {
if extranonce_prefix.len() > MAX_EXTRANONCE_PREFIX_LEN {
if extranonce_prefix.len() > MAX_EXTRANONCE_LEN as usize {
return Err(StandardChannelError::NewExtranoncePrefixTooLarge);
}

Expand All @@ -122,8 +123,22 @@ impl<'a> StandardChannel<'a> {
}

/// Returns the bytes representing the first part of the extranonce.
pub fn get_extranonce_prefix(&self) -> &Vec<u8> {
&self.extranonce_prefix
pub fn get_extranonce_prefix(&self) -> &[u8] {
self.extranonce_prefix.as_bytes()
}

/// Returns the length of the `upstream_prefix` region of this channel's
/// extranonce prefix, if known.
///
/// See [`ExtranoncePrefix::upstream_prefix_len`](crate::extranonce_manager::ExtranoncePrefix::upstream_prefix_len)
/// for the full semantics. In particular, this is `None` for channels
/// opened from a wire-sourced prefix (the common case on a client),
/// and `Some(n)` when the application minted the prefix locally from
/// an [`ExtranonceAllocator`](crate::extranonce_manager::ExtranonceAllocator) — e.g. a proxy that
/// sub-allocates an upstream-assigned extranonce space and hands one
/// slot to each downstream channel.
pub fn upstream_prefix_len(&self) -> Option<u8> {
self.extranonce_prefix.upstream_prefix_len()
}

/// Returns the current target for the channel.
Expand Down Expand Up @@ -193,7 +208,7 @@ impl<'a> StandardChannel<'a> {
let merkle_root = merkle_root_from_path(
new_extended_mining_job.coinbase_tx_prefix.inner_as_ref(),
new_extended_mining_job.coinbase_tx_suffix.inner_as_ref(),
&self.extranonce_prefix,
self.extranonce_prefix.as_bytes(),
&new_extended_mining_job.merkle_path.inner_as_ref(),
)
.expect("merkle root must be valid")
Expand Down Expand Up @@ -389,9 +404,12 @@ impl<'a> StandardChannel<'a> {

#[cfg(test)]
mod tests {
use crate::client::{
share_accounting::{ShareValidationError, ShareValidationResult},
standard::StandardChannel,
use crate::{
client::{
share_accounting::{ShareValidationError, ShareValidationResult},
standard::StandardChannel,
},
extranonce_manager::ExtranoncePrefix,
};
use binary_sv2::Sv2Option;
use bitcoin::Target;
Expand All @@ -412,7 +430,7 @@ mod tests {
let mut channel = StandardChannel::new(
channel_id,
user_identity,
extranonce_prefix,
ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
target,
nominal_hashrate,
);
Expand Down Expand Up @@ -475,7 +493,7 @@ mod tests {
let mut channel = StandardChannel::new(
channel_id,
user_identity,
extranonce_prefix,
ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
target,
nominal_hashrate,
);
Expand Down Expand Up @@ -529,7 +547,7 @@ mod tests {
let mut channel = StandardChannel::new(
channel_id,
user_identity,
extranonce_prefix,
ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
target,
nominal_hashrate,
);
Expand Down Expand Up @@ -611,7 +629,7 @@ mod tests {
let mut channel = StandardChannel::new(
channel_id,
user_identity,
extranonce_prefix,
ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
target,
nominal_hashrate,
);
Expand Down Expand Up @@ -687,7 +705,7 @@ mod tests {
let mut channel = StandardChannel::new(
channel_id,
user_identity,
extranonce_prefix,
ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
target,
nominal_hashrate,
);
Expand Down
Loading
Loading