Skip to content

feat(job_source): prepare the extranonce types for Stratum V2 - #125

Merged
rkuester merged 7 commits into
256foundation:mainfrom
rkuester:refactor-job-source-for-sv2
Oct 19, 2026
Merged

rkuester merged 7 commits into
256foundation:mainfrom
rkuester:refactor-job-source-for-sv2

Conversation

@rkuester

Copy link
Copy Markdown
Collaborator

Prepare the shared job source code for Stratum V2 support, so #65 can build on it. Code inside the SV2 modules stays with #65; this PR changes only the types they share with the rest of Mujina.

Rename the coinbase and extranonce types and fields from Stratum V1's terms to the terms Stratum V2 uses: the coinbase prefix, the extranonce prefix, the extranonce, and the coinbase suffix. V1's names stay in the V1 client and its wire types, and the V1 source maps one set to the other.

Write the extranonce counter most significant byte first, so rolling changes the bytes at the right of the slot and splitting a range fixes the bytes at the left, the way SV2 divides an extranonce between an upstream and its downstreams. This changes the extranonce bytes sent to V1 pools; a pool accepts any value, so shares stay valid.

Let an extranonce fill a slot of 1--32 bytes, the range SV2 allows. The counter stays 64 bits wide at the right end of the slot, with zeros to its left. The types become opaque: code outside the module builds values from wire bytes and divides a range by splitting, and never reads the counter as a number. This replaces the second template field and the padding at submit in #65.

Along the way, fix the extranonce iterator overflowing at the end of a full 8-byte range, answer its position queries without stepping through 2^64 values, and print wide extranonces and ranges compactly.

Tested with just checks on each commit, and with just test-bitaxe-gamma baseline against pool.256foundation.org and solo.ckpool.org (no rejected shares in either). #65 rebased onto this branch builds and passes its tests at each commit.

Rename the shared extranonce and coinbase types and fields from Stratum
V1's terms to the terms Stratum V2 uses. V1 numbers the pieces in wire
order (coinbase1, extranonce1, extranonce2, coinbase2), so the names say
where a piece sits in a message but not what it is. V2 names them by
role: the coinbase prefix, the extranonce prefix the upstream fixes, the
extranonce the miner rolls, and the coinbase suffix. With V2 support
coming, the shared code should use names that fit both protocols.

Keep V1's names in the V1 client and its wire types, since there they
name what is on the wire. The V1 source maps one set of names to the
other where it builds a job template and where it submits a share.
Write the extranonce counter into the coinbase most significant byte
first, so the bytes the miner rolls sit at the right end of the slot
and a split of the range fixes the bytes at the left.

Stratum V2 lays out an extranonce the same way. Each layer between the
pool and the miner (a proxy, a job declarator) narrows the space by
appending bytes to the prefix it received, and the miner rolls what
remains at the right. With the counter big-endian, the scheduler's
split among hash threads becomes one more such layer, and wider slots
pad with zeros at the left, where an unused prefix sits.

The order also makes the hex form of a value match its bytes on the
wire. A value of 0x1234 in a 4-byte slot was sent as 34120000 and is
now sent as 00001234, the way it already prints.

This changes the extranonce bytes Mujina submits to Stratum V1 pools.
A pool accepts any value in the slot, so shares stay valid.
Mark the extranonce iterator exhausted after it yields the last value of
its range, instead of stepping one past the end. A range that ends at
the counter's largest value, as a full 8-byte range does, overflowed
the counter there: a debug build panicked, and a release build wrapped
to zero and began the range again.

Compute the remaining count in a wider integer as well. A full 8-byte
range holds 2^64 values, one more than the counter can count, so the
size hint overflowed in the same way. Report no upper bound when the
count exceeds what a usize holds.
@rkuester

Copy link
Copy Markdown
Collaborator Author

@jayrmotta, this is the prep PR from my #65 review. I'd welcome your review.

@jayrmotta jayrmotta left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tACK 8d84f75 with two nits

Comment on lines +254 to +261
/// Returns an iterator over the extranonces in the range, in order.
pub fn iter(&self) -> ExtranonceIter {
ExtranonceIter {
next: Some(self.first),
last: self.last,
width: self.width,
}
}

@jayrmotta jayrmotta Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: This iterator isn't being used in any production code, to confirm it I've added #[cfg(test)] to it and it still builds as expected. That also means the hash threads are only using the start value, meaning if a mining device exceeds the BIP-320 theoretical ceiling of 281TH/s it would start repeating the extranonce and potentially producing duplicate shares.

For the devices we currently support and the ones we've been building towards this won't be a problem, but when we get to the last generation devices like the S23 hydro it could lead to the issue described.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When support for BIP-323 lands this also ceases to be an issue as the theoretical ceiling raises to 72PH/s in header-only mining, so "fixing" is probably low priority.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, neither the scheduler nor any current thread rolls extranonce yet. None has needed to, so there's no issue there. I'd still like to keep this interface as the common way for them to do it when they need to. A thread must know what its hardware can do, and either roll whatever it must to avoid duplicate work or tell the scheduler it has exhausted the job.

BIP-323 doesn't fix anything on its own. It gives a thread and its hardware more space to roll, but using that space is still up to the thread.

Comment on lines +189 to +199
/// Returns the number of extranonces in the range.
///
/// The count is a `u128` because the full range of a slot of 8 bytes or
/// more holds 2^64 extranonces.
#[expect(
clippy::len_without_is_empty,
reason = "a range holds at least one extranonce"
)]
pub fn len(&self) -> u128 {
u128::from(self.last - self.first) + 1
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: doesn't u128 conflicts with the WorkExhausted::extranonce_searched which is u64? Since the comment says a slot of 8 bytes or more holds 2^64 extranonces a future code assessing the number of extranonces searched would truncate it and report an incorrect number.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. Nothing creates WorkExhausted yet, so I'll drop extranonce_searched in a follow-up that cleans up the scheduler-to-thread interface.

I've also made len() private and removed split_at(), since callers are meant to split and roll ranges, not do math on them. For planning, the iterator's new remaining() gives the exact count left. While there, I fixed iterator queries like count() and nth_back() that could hang on a full range.

@rkuester
rkuester force-pushed the refactor-job-source-for-sv2 branch from 8d84f75 to d8684ca Compare October 19, 2026 17:04
Let an extranonce fill a slot of 1--32 bytes, the range Stratum V2
allows, instead of 1--8. The counter stays 64 bits wide and sits at the
right end of the slot. In a slot wider than 8 bytes, the bytes left of
the counter are zero, the same as a prefix that an upstream left
unused. A V2 pool can give a channel 16 or 32 bytes, and the coinbase
must hold all of them.

Make the extranonce opaque. Code outside the module no longer reads or
sets the counter as a number. It gets bytes and a width, and builds a
value from wire bytes. A range comes from the full slot and is divided
into nearly equal parts by splitting. The dummy source's range now runs
from the winning block's extranonce to the end of the slot, instead of a
fixed 101 values that the scheduler could not split among more threads.

Print a value as its wire bytes in hex at any width, which matches the
hex a pool logs.

Accept the Stratum V1 extranonce2 size the pool sends without narrowing
it to a byte first, which let a size of 257 pass as 1.
Answer the extranonce iterator's queries, such as counting, skipping
ahead, or taking the last value, from the range's bounds. The standard
versions step through the range one value at a time, and a full 8-byte
range holds 2^64 values, so they never finished. Let the iterator run
from either end.

Make the count panic at once when the range holds more extranonces than
a usize can hold, as the standard library's ranges do. Because Rust
gives all iterators a count that must return a usize, hide it behind a
deprecated inherent method of the same name to discourage users from
calling it.
Print an extranonce in a slot wider than 8 bytes with its longest run of
zero bytes compressed to "::", the way IPv6 addresses do, and add the
width in bytes, which the digits no longer show. A 32-byte slot holds
at most 8 nonzero bytes, so the full form is mostly zeros. Slots of up
to 8 bytes still print in full, so a log line can be matched against
the hex a pool logs:

    00001234
    ::1234/32

Print a range as its first value and its length, in the shape of a Rust
struct, instead of its raw counter bounds. Large powers of two print as
such:

    { start: 40000000, len: 2^30 }
    { start: 220cf1ad, len: 101 }

Print the debug form of each type as its display form with the type
name in front, so a hash task's debug output shows wire bytes rather
than the counter as a decimal number.
Let callers ask the extranonce iterator how many extranonces are left,
as a 128-bit count that holds the 2^64 of a full 8-byte range. Point
the deprecated count at it, so a caller who reaches for the standard
count learns of a count that cannot panic.

A thread that plans its work, for example to warn the scheduler before
its range runs out, needs this count.
@rkuester
rkuester force-pushed the refactor-job-source-for-sv2 branch from d8684ca to 1a93043 Compare October 19, 2026 19:16
@rkuester

Copy link
Copy Markdown
Collaborator Author

I force-pushed again to 1a93043 so the iterator tests no longer assume a 64-bit usize. They now build ranges from usize::MAX, so they test the same limits on any pointer width. Only tests changed.

@rkuester
rkuester added this pull request to the merge queue Oct 19, 2026
@rkuester

Copy link
Copy Markdown
Collaborator Author

Thanks for the review, @jayrmotta!

Merged via the queue into 256foundation:main with commit 1179e0b Oct 19, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants