Repository navigation
feat(job_source): prepare the extranonce types for Stratum V2 - #125
Conversation
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.
|
@jayrmotta, this is the prep PR from my #65 review. I'd welcome your review. |
| /// 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, | ||
| } | ||
| } |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| /// 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 | ||
| } |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
8d84f75 to
d8684ca
Compare
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.
d8684ca to
1a93043
Compare
|
I force-pushed again to 1a93043 so the iterator tests no longer assume a 64-bit |
|
Thanks for the review, @jayrmotta! |
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 checkson each commit, and withjust test-bitaxe-gamma baselineagainst 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.