Skip to content

feat(stratum_v2): add SV2 support - #65

Open
jayrmotta wants to merge 8 commits into
256foundation:mainfrom
jayrmotta:feature/sv2-support
Open

jayrmotta wants to merge 8 commits into
256foundation:mainfrom
jayrmotta:feature/sv2-support

Conversation

@jayrmotta

@jayrmotta jayrmotta commented Jun 5, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This pull request introduces Stratum V2 support to Mujina, it's the result of #54 with guidance from Ryan and Plebhash.

The SV2 team has great crates like channels_sv2, sv2-apps, and so on, which made possible for Mujina to reuse the same APIs, behaviors, and patterns used to build their proxies, pools, and so on which will be Mujina's counterparties. In other words, we abstract away a big part of the stratum-related code like the Noise handshake, frame processing, state machine, and so on.

We ended up with a lot less domain-specific protocol code, and more dealing with the intricacies of a firmware like being shutdown-safe, having safe defaults and checks, interfacing and providing feedback to the user.

This pull request is in draft and open for comments, suggestions, etc. I will continue to edit it as I prepare it for a final review.

Steps to try it out

Assuming you have Mujina cloned and checked out this pull request's branch.

Export the variables as we normally do for SV1 servers, but using the stratum2+tcp:// scheme and suffixing it with the authority key 9auqWEzQDVyd2oe1JVGFLMLHZtCo2FFqZwtKA5gd9xbuEu7PH72 as described in SV2 spec.

$ export MUJINA_POOL_URL="stratum2+tcp://75.119.150.111:3333/9auqWEzQDVyd2oe1JVGFLMLHZtCo2FFqZwtKA5gd9xbuEu7PH72"
$ export MUJINA_POOL_USER="<bitcoin payout address>.<worker name>"

Then you can try with regular log level or run it with debug, that would help if you see any problems as you test.

$ RUST_LOG=mujina_miner=debug cargo run

Features

  • Support for SV2 extended channels. There is a theoretical limit of 280TH/s for standard channels HOM (header only mining), and given that Mujina intends on powering high hashrate devices it seemed reasonable to start supporting extended channels, but remaining open to adding standard channels later if a good reasoning/argument is presented.
  • Adapted the exponential backoff reconnect strategy to be used both by SV1 and SV2. It was also introduced a distinction of errors that might be temporary and can be retried like reconnections in contrast to errors that are fatal and require intervention.
  • Introduces a set of integration tests using integration_tests_sv2 harness and its sniffer for assertions in behavior focused tests meant to enforce protocol compliance.
  • Made several improvements to accomodate a second protocol and the "wiring" required to switch depending on the protocol scheme in the provided URL.

Notes

  1. I had a challenge around building a merkle root as the terminology currently used is SV1-specific but the data structure is/should be generic/agnostic. For example SV2 doesn't use the term extranonce2 anymore, which conflicts with MerkleRootTemplate and Extranonce2, both important to keep SV1 and SV2 functionality.
  2. If you run long enough with debug logs enabled, you'll see reports of duplicate shares found and dropped by the client. I elaborated more on this below as a comment, I think this should be handled in its own pull request, which I'm happy to work next if nobody else does.

@jayrmotta

jayrmotta commented Jun 5, 2026 •

Copy link
Copy Markdown
Contributor Author

My recent test session pointing to the SRI pool had 100% shares accepted, and that's expected as we use the same validate_share function used by the pool (tested against the SRI pool). Some shares do however fail the validation and report errors, as far as I could observe all related to duplicate shares.

I did some investigations and I suspect we suffer from the same issues that led to bitaxeorg/ESP-Miner#420 which was also triggered by esp-miner's implementation of SV2 support. Something for a separate discussion and implementation, but I believe has to happen given that allowing for higher hashrate is something that matters more for Mujina then it does for ESP-Miner.

I was wondering if a share that fails validate_share should be accounted as rejected, even if the rejection came from the client itself and not the upstream server. Right now it's not being accounted, hence the 100% success.

@adammwest

adammwest commented Jun 11, 2026 •

Copy link
Copy Markdown

Another Relavent PR shufps/ESP-Miner-NerdQAxePlus#546

I did some investigations and I suspect we suffer from the same issues that led to bitaxeorg/ESP-Miner#420

I am the author of that PR,
If you use sniffed Antminer register values, the space is smaller than the 280Th theoretical limit for header only mining.
I think first ill try to make an issue then this topic can be discussed in more detail.
#72

Comment thread mujina-miner/src/daemon.rs Outdated
Box::new(TcpConnector::new(pool_url.clone())),
);
let stratum_name = stratum_source.name();
if endpoint.protocol == PoolProtocol::StratumV2 {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Does it make more sense to match here? AFAIK there is also stratum+ssl which some pools use as a protocol, and there may be other protocols implemented in the future, so matching makes it clear at compile-time if this check is missing any variants.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

That's an interesting shout, will do some research and experiment to see how different approaches to adding new/variant protocols would look like.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Hey @b-rowan, I've made some changes to how we match against different protocols, added some no-ops for SV1 SSL/TLS as an example.

I think however we could have a wider refactor so transport and protocol aren't handled together.

Please take a look if you have some time 😉

Comment thread mujina-miner/src/stratum_v2/client.rs Outdated
Comment on lines +241 to +244
let addr = tokio::time::timeout(
Duration::from_secs(DNS_TIMEOUT_SECS),
resolve_host_port(&self.config.socket_addr()),
)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Do we need this since Mujina always runs on a full fledged linux?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I've learned SocketAddr can't hold unresolved addresses (domain names), there is also a chance DNS resolution will hang forever if the name server pointed to isn't responding.

I've made a change to use resolve_host from the network_helpers module, it already has its own timeout and handles formatting the host and port (important for ipv6).

Comment thread mujina-miner/src/stratum_v2/client.rs Outdated
Comment on lines +133 to +141
fn socket_addr(&self) -> String {
// IPv6 literals must be bracketed in a host:port string (RFC 3986 §3.2.2).
if self.host.contains(':') {
format!("[{}]:{}", self.host, self.port)
} else {
format!("{}:{}", self.host, self.port)
}
}
}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Perhaps we could store it as a SocketAddr instead?

https://doc.rust-lang.org/std/net/enum.SocketAddr.html

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I ended up getting rid of this and only using resolve_host, but I couldn't hold a SocketAddr as I would need to access individual properties at different moments down the line.

Comment thread mujina-miner/src/stratum_v2/client.rs Resolved
Comment thread mujina-miner/src/stratum_v2/client.rs Resolved
@jayrmotta
jayrmotta force-pushed the feature/sv2-support branch 2 times, most recently from 91b1242 to 5b8d78a Compare June 30, 2026 19:41
@jayrmotta
jayrmotta requested a review from b-rowan June 30, 2026 20:21
@jayrmotta
jayrmotta marked this pull request as ready for review June 30, 2026 20:21

@b-rowan b-rowan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Couple small nits, seems solid to me overall. Definitely should have a secondary review since I am not very familiar with the internals though.

Comment thread mujina-miner/src/config.rs Resolved

use std::env;

use anyhow::Context as _;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This might be worth commenting or removing, not sure what this is for?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

It's meant to load the function context added to Result/Option, this pattern is used in many places in this code base. When the Context object itself is used we name it properly, but other places we import it only for the context function.

@jayrmotta
jayrmotta force-pushed the feature/sv2-support branch from 5b8d78a to 8b1350c Compare July 1, 2026 23:45
@rkuester
rkuester force-pushed the feature/sv2-support branch from 8b1350c to e757847 Compare July 4, 2026 03:24
@rkuester

rkuester commented Jul 4, 2026

Copy link
Copy Markdown
Collaborator

Rebased this atop 2f6efca, which now ensures that each commit in a multi-commit PR passes CI.

@rkuester

rkuester commented Jul 6, 2026

Copy link
Copy Markdown
Collaborator

I did some investigations and I suspect we suffer from the same issues that led to bitaxeorg/ESP-Miner#420

I am the author of that PR, If you use sniffed Antminer register values, the space is smaller than the 280Th theoretical limit for header only mining. I think first ill try to make an issue then this topic can be discussed in more detail. #72

In the course of reviewing this PR, I've gone down the search space partitioning rabbit hole (which if done incorrectly can lead to duplicate shares) and have posted a link to a draft write-up over in discussion #72. It's still a work in progress as I wrap my brain around all the work esp-miner and its derivatives have done to reverse engineer this behavior. Thanks again, @adammwest!

@jayrmotta
jayrmotta force-pushed the feature/sv2-support branch 2 times, most recently from f7d3ef3 to 679608d Compare July 9, 2026 18:12
jayrmotta added a commit to jayrmotta/mujina that referenced this pull request Jul 29, 2026
Config's pool list assumed every job source is a pool. That does
not hold: 256foundation#60 prototypes mining directly
against a Bitcoin Core node instead of a Stratum pool, and
256foundation#65 adds Stratum V2 support, whose terminology
(channels, proxies, job declaration) doesn't map onto "pool"
either.

Rename Config.pools to Config.sources and change its type from
Vec<PoolConfig> to Vec<SourceConfig>, an enum tagged by `kind`
with a single Pool(PoolConfig) variant today. The tag lets
/config and /sources respond additively as source kinds are
added, instead of needing a breaking shape change later.
jayrmotta added a commit to jayrmotta/mujina that referenced this pull request Jul 29, 2026
Config's pool list assumed every job source is a pool. That does
not hold: 256foundation#60 prototypes mining directly
against a Bitcoin Core node instead of a Stratum pool, and
256foundation#65 adds Stratum V2 support, whose terminology
(channels, proxies, job declaration) doesn't map onto "pool"
either.

Rename Config.pools to Config.sources and change its type from
Vec<PoolConfig> to Vec<SourceKind>, an enum tagged by `kind` with
a single Pool(PoolConfig) variant today. The tag lets a future
consumer of the tree respond additively as source kinds are
added, instead of needing a breaking shape change later.
jayrmotta added a commit to jayrmotta/mujina that referenced this pull request Aug 5, 2026
Config's pool list assumed every job source is a pool. That does
not hold: 256foundation#60 prototypes mining directly
against a Bitcoin Core node instead of a Stratum pool, and
256foundation#65 adds Stratum V2 support, whose terminology
(channels, proxies, job declaration) doesn't map onto "pool"
either.

Rename Config.pools to Config.sources and change its type from
Vec<PoolConfig> to Vec<SourceKind>, an enum tagged by `kind` with
a single Pool(PoolConfig) variant today. The tag lets a future
consumer of the tree respond additively as source kinds are
added, instead of needing a breaking shape change later.
@jayrmotta
jayrmotta force-pushed the feature/sv2-support branch from 679608d to a9cefda Compare August 14, 2026 20:40
@jayrmotta

Copy link
Copy Markdown
Contributor Author

Hey @rkuester, I just rebased main onto this branch to keep it fresh and ready for reviews, but the CI failed because the stratum-apps transitively brings json5 which uses this ISC license.

I'm sending this message so you can help me assess if we could accept dependencies with this license or if I have to consider alternatives so we don't depend on that.

@rkuester

rkuester commented Aug 15, 2026 •

Copy link
Copy Markdown
Collaborator

Hey @rkuester, I just rebased main onto this branch to keep it fresh and ready for reviews [...]

I owe you several beers already for your patience.

[...] but the CI failed because the stratum-apps transitively brings json5 which uses this ISC license.

ISC is acceptable. The initial addition missed it because it wasn't in any of our existing dependencies. For the record, it's widely used and essentially MIT, and GPL-compatible per the FSF's guidelines.

Would you please add it to the allow list in the relevant commit?

Thank you for testing the new license check machinery! 😂

@rkuester

Copy link
Copy Markdown
Collaborator

Would you please add it to the allow list in the relevant commit?

@jayrmotta in order for the series to pass CI on each commit individually, that needs to get either amended into the commit that adds the dependency or reordered as its own commit before the commit that adds the dependency.

(just ci locally should give you the same result, hopefully. If not, please let me know, because it would be a subtle bug with just ci on updates to PR branches.)

@jayrmotta
jayrmotta force-pushed the feature/sv2-support branch from e4f6312 to 4c19a49 Compare August 17, 2026 12:05
Comment thread mujina-miner/src/stratum_v2/client.rs Outdated
Comment on lines +144 to +147
/// Pool requested a reconnect.
Reconnect(Reconnect<'static>),
/// Pool reassigned the channel to a different endpoint.
ChannelEndpointChanged(ChannelEndpointChanged),

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Hey @plebhash, I remember from our deep dive you saying these two messages might not be necessary. Can you please help me understand?

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

what I meant to say there is that SRI currently does not implement these, and I haven't seen any other implementations that do

so it should be relatively safe to skip them on an MVP

@jayrmotta

Copy link
Copy Markdown
Contributor Author

Hey @rkuester, I might just go ahead and cut the integration_tests_sv2 dependency along the tests I had written.

Perhaps in the future we can have something like that as a separate repo, but for now I think the gain we get by simplifying the changeset just seems worth.

I might also move this back to draft to invite more reviews and comments until I have finished rebasing and removing this dep.

@jayrmotta
jayrmotta marked this pull request as draft September 1, 2026 15:47
@jayrmotta
jayrmotta force-pushed the feature/sv2-support branch 2 times, most recently from 783e69f to 28caccb Compare September 14, 2026 20:26
@jayrmotta

Copy link
Copy Markdown
Contributor Author

Summary of my recent changes:

  • The tests that relied on integration_tests_sv2 were dropped as they brought many transient dependencies and added a significant number of lines. Perhaps we can think of a fuzzing approach external to the main repo;
  • Implemented SetupConnectionSuccess.flags version rolling enforcement, a pool answering REQUIRES_FIXED_VERSION now causes a fatal FixedVersionRequired error;
  • Added support for the missing SetExtranoncePrefix message;
  • A few other minor improvements and simplifications.

I would love if you could run this branch pointing to an SV2 pool (perhaps your own if you are using SV2-ui) and then share logs, any observed behavior that seemed odd, all feedback is welcome.

let extranonce_counter_size =
Self::derive_extranonce_counter_size(msg.extranonce_size)
.context("OpenExtendedMiningChannelSuccess: invalid extranonce params")?;
let extranonce_size = (msg.extranonce_size as usize).min(u8::MAX as usize) as u8;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggested change
let extranonce_size = (msg.extranonce_size as usize).min(u8::MAX as usize) as u8;
let extranonce_size = u8::try_from(msg.extranonce_size).context("OpenExtendedMiningChannelSuccess: invalid extranonce params")?;

It's better to fail early and load than silently truncate. Also in client.rs you already reject extranonce_size > 32 so this wouldn't be hit anyways. So you could just do extranonce_size = msg.extranonce_size as u8.

Why the SV2 spec specifies a u16 for extranonce_size in the first place is another question (it makes no sense).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Agreed. It's the client layer's job to check wire values and convert them to Mujina's own types. The source layer should never see a raw wire value.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The clamp is gone, the source builds ExtranonceRange::full(extranonce_size), which fails the session instead of truncating.

Comment on lines +426 to +427
let initial_target = target_from_le_bytes(msg.target.inner_as_ref())
.context("OpenExtendedMiningChannelSuccess: invalid target")?;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Following on from the clamp comment. The deeper issue is where validation lives. client.rs is the protocol boundary: it already rejects bad extranonce_size and wrong request_id at channel open, but then forwards the raw wire message in ClientEvent. So every consumer downstream re-parses (inner_as_ref()) and re-validates (prefix length, target length, size clamps) things the client already vetted, hence the conversion ceremony in this arm, and the duplicated prefix parsing in SetExtranoncePrefix.

Suggestion: convert once at the boundary. The events mujina actually reads, channel open, SetTarget, SetExtranoncePrefix, should carry validated domain values (Target, ExtranoncePrefix, extranonce_size: u8, counter size) computed where the message is decoded, so malformed values fail connection setup where they belong. NewExtendedMiningJob/SetNewPrevHash stay as wire messages since they're passed whole into channels_sv2's ExtendedChannel. The rule becomes: wire types stop at client.rs; everything past it is domain data, and this arm shrinks to its core logic: building the channel and session.

Same pattern repeats in SetTarget, SetExtranoncePrefix, and the B032 guard in handle_share_submission. This part of the code is just best example of this.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

The rule becomes: wire types stop at client.rs; everything past it is domain data

Again, strongly agree.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I have refactored the code using hexagonal architecture ideas, so now the types and dependencies are not leaking into higher level abstractions.

@rkuester rkuester left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I've reviewed this PR in two parts. The SV2 client and source stand on their own and only run when Mujina connects to an SV2 pool, so they can keep improving in the tree without affecting anything else. I haven't gone through them with a fine-tooth comb. For that I'm trusting the other reviewers here, and I know you've worked with the SRI team on this code, which is great. I've looked hardest at the shared code, which other modules build on, so that's where most of my comments are.

Some of the shared changes were easier for me to make than to describe, so I've made them myself in #125 (with a request for your review), which prepares the shared job source layer a bit. It renames the merkle root template and extranonce types to protocol-neutral terms, which you asked about in your description. Those happen to be SV2's terms, since SV2 named the pieces for what they are. It also gives the extranonce type its slot width, which replaces your commit "carry the full extranonce2 allocation". Please rebase this PR onto #125 and build on those types.

Thanks for your patience! This review is long overdue.

Comment thread mujina-miner/Cargo.toml Outdated
slotmap = { workspace = true }
num-traits = { workspace = true }
ruint = "1.17.0"
stratum-apps = { version = "0.4", default-features = false, features = ["network", "core", "config"] }

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Please update to stratum-apps 0.8 or later. The 0.4 version here pulls in channels_sv2 5.0.0, where ExtendedChannel remembers the hash of every valid share in an unbounded set until the next SetNewPrevHash, to catch duplicates. SRI bounded it in stratum-mining/stratum#2297, and the fix shipped in channels_sv2 8.0.0, which stratum-apps 0.8 uses.

0.8 also lets you drop the config feature from this list. In 0.4 the crate fails to compile without it, because tp_type.rs imports config_helpers outside the feature gate. I checked that 0.8 builds with only network and core.

Unfortunately, stratum-apps 0.8 still depends on the config crate unconditionally. That's about 45 crates (json5, ron, yaml-rust2, rust-ini, toml, pest, and their dependencies) for a configuration-file parser Mujina never calls. Nothing to do about it in this PR. I've opened stratum-mining/sv2-apps#922 to make the dependency optional, and once a stratum-apps release includes it, those crates leave Mujina's build. @plebhash, I'd welcome your review there.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

merged!

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Updated to stratum-apps 0.8 with only network and core enabled

Comment thread mujina-miner/src/stratum_v2/client.rs Outdated
/// # Errors
///
/// Returns [`StratumV2Error::Protocol`] if `bytes` is not exactly 32 bytes.
pub(crate) fn target_from_le_bytes(bytes: &[u8]) -> StratumV2Result<Target> {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Conversions like this belong to the client and shouldn't be exported. Right now this function is pub(crate) and re-exported from stratum_v2, allowing a layering inversion where the source reaches into the client to decode a target.

In any event, the function itself also seems unnecessary. It takes &[u8] and then checks that there are 32 bytes. If it took [u8; 32], the type would hold the length and the error case would go away, but then it would only be calling Target::from_le_bytes, which already takes [u8; 32]. So I'd drop this function and just call that directly.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Dropped, along with its re-export. The client converts SetTarget and the channel-open target to Target itself, with Target::from_le_bytes on the fixed-size array, so the source never decodes a target.

@@ -0,0 +1,144 @@
//! Shared connection-lifecycle utilities for pool job sources.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Please rename this file reconnect.rs. It holds no connection, only the logic for when and how to retry one, and connection is already the name of the V1 socket module.

In this commit, please also move the rest of the shared reconnect code into this file. Move the three backoff tests out of stratum_v1.rs, rather than copying them later in the SV2 source commit. Move the shared backoff_wait from that commit to this one too, and switch V1 to it, replacing V1's own copy.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done and got rid of the duplicate code.

Comment thread mujina-miner/src/config.rs Outdated
use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};
use std::str::FromStr;
use stratum_apps::key_utils::Secp256k1PublicKey;

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

The parsing is good work, but it doesn't belong in config.rs, which describes what goes in a config file. Nothing saves a PoolEndpoint, and only the code that builds sources reads it. It also makes the config module import a Stratum V2 library. I'd move it to job_source/upstream.rs as upstream::Endpoint and upstream::Protocol, since the far end can be a pool, a proxy, or a job declarator, and the SV2 spec calls it the upstream.

Please also drop PoolConfig::endpoint(). Only its own test calls it, and after the move it would make config.rs import from job_source.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done as suggested

Comment thread mujina-miner/src/config.rs Outdated
///
/// Private to enforce the invariant that V2 endpoints always carry a key
/// and V1 endpoints never do. Use [`PoolEndpoint::authority_pubkey`] to read it.
authority_pubkey: Option<Secp256k1PublicKey>,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Please put the key in the V2 variant, so the type guarantees that V2 has a key and V1 doesn't:

pub enum Protocol {
    StratumV1,
    StratumV2 { authority_key: Secp256k1PublicKey },
}

The private field checks this only when an endpoint is built, so the daemon still handles a missing key that can't happen, with a comment to explain why. With the key in the variant, the daemon takes the key from the match arm, and the private field, the accessor, and that error path all go away. Please also drop the Serialize and Deserialize derives on the enum. Nothing serializes it.

One question could change this. The spec seems to allow leaving out the authority key for a trusted local proxy, and connect_with_noise already accepts None, which encrypts the connection but doesn't authenticate the far end. Do you intend to support that? If so, the variant should probably hold an Option.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done as suggested

Comment thread mujina-miner/src/daemon.rs Outdated
"Using Stratum V2 source"
);

let sv2_config = Sv2PoolConfig::new(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

The daemon imports the SV2 client's PoolConfig here, so it has to supply everything the client needs, through a nine-argument constructor, and some of that doesn't belong in the daemon lyaer. For example, it passes a placeholder hash rate, though the scheduler sends the real one before this source connects, as in V1. I'd rather the daemon not know the client exists. Could the source take its own plain struct instead, with only what the daemon knows (the host, port, authority key, user, and device strings), filled in by name? The source would add the hash rate, and stratum_v2::client would convert to Str0255 where it builds SetupConnection and OpenExtendedMiningChannel. If the source validated its config when it starts, a bad value could still fail at startup.

V1 has the same problem with its PoolConfig, but that's a separate fix.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed

)
.context("Failed to build Stratum V2 pool config")?;

let sv2_source = StratumV2Source::new(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

The SV2 arm should share more of the daemon's setup with V1, so that adding a protocol changes only how the source gets built. Read the user and the user agent above the match, set up the forced-rate wrapper and the registration once, and have each arm build only its own source. As it stands, the SV2 arm duplicates that setup and leaves out the wrapper, so MUJINA_POOL_FORCED_RATE is silently ignored for SV2.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed

Comment thread mujina-miner/src/config.rs Outdated
/// Stratum V1 over plain TCP, spelled `stratum+tcp://`.
StratumV1,
/// Stratum V1 over TLS, spelled `stratum+ssl://`.
StratumV1Ssl,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Please drop StratumV1Ssl and StratumV1Tls and let those schemes fail as UnsupportedScheme. Whoever adds TLS support later can add the variants it needs.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Dropped.

/// path component. V1 pool URLs often carry the worker name in that path;
/// the miner reads the worker from its own config, so the path is dropped
/// before resolving the address.
pub async fn connect(url: &str) -> StratumResult<Self> {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Now that you've added the match on endpoint.protocol, its two arms should work at the same level of abstraction. The V2 arm builds its config from the parsed endpoint, but the V1 arm passes the raw URL to TcpConnector, so this function parses it a second time and now has to strip paths to match the parser. Please change the V1 code to fit. Have TcpConnector and Connection::connect take a host and port, have the V1 arm pass the endpoint's, and drop the string handling here.

This commit also drops support for tcp:// URLs, which work on main. Please say the tcp:// scheme was dropped in the commit message, in case anybody was using it.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yep, it's done.

/// sending a FIN — produces no reader error and no EOF, so without a deadline
/// both the source and the client wait forever and the reconnect back-off is
/// never reached. The V1 source bounds the same gap with the same limit.
const MAX_JOB_GAP: Duration = Duration::from_secs(2 * 60);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

The SV2 spec doesn't require jobs at any rate. An upstream must send a new job when a new block arrives, and the spec says nothing about timing in between. SRI's pool sends a new job only when its template provider sends a new template, which happens on a new block or when fees rise past a threshold, so on a quiet mempool it can send nothing for a whole block interval. SRI's own translator sends its SV1 miners a keepalive mining.notify every 60 seconds to cover that gap.

With that in mind, this two-minute limit on jobs looks like it would recycle healthy connections. Could the source use a different sign of life, or drop the check entirely?

@plebhash, have you thought about how a downstream should detect a dead upstream in SV2?

@plebhash plebhash Oct 13, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

indeed I don't think what's being done here is a good idea

SRI's own translator sends its SV1 miners a keepalive mining.notify every 60 seconds to cover that gap.

Sv1 firmware is a bit naive with regards to this, which forced SRI translator to implement this workaround... but we should take this opportunity to do something a bit more clever, because it's not realistic to expect jobs to come in every X seconds "just because Sv1 pools used to do it this way"

if the mempool is empty and there's no point in sending a new job, we should assume the server simply won't send any job!

as long as we're smart about managing our search space, a good firmware implementation should be able to keep hashing indefinetely


a more reliable sign of a dead Sv2 server is the fact that shares are being sent but no SubmitShares.Success acknowledgement ever arrives (or .Error, in case something is wrong on client side)

but it's also important to keep in mind that Sv2 allows batched acknowledgements on SubmitShares.Success, and there's nothing on spec dictating what the batching logic must be based on (e.g.: number of successful shares vs some fixed time window)

so it's hard to come up with generalized rule of thumb... but there's definitely plenty room for heuristics that would be way more reliable than the current approach

@plebhash plebhash Oct 13, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

but TBH this is the first time I'm really thinking about this problem

we haven't really implemented anything like this on SRI, and I wonder if an MVP really needs it?

this feels like a nice-to-have UX optimization to be added some time in the future, once the more foundational stuff is already validated?

unless ofc the Sv1 implementation is already establishing this as a first-class Mujina functionality


edit:

The V1 source bounds the same gap with the same limit.

well, maybe that is indeed the case...

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Mujina only recently gained this nice-to-have feature for SV1 because the Red Team^TM identified it as a vulnerability to malicious pools or MITMs. It's debatable how serious to take such a threat is—the pool already has your money and can do far worse—but it seemed like a reasonable add for robustness.

Having a liveliness check for SV2 certainly shouldn't hold up adding this PR's client to Mujina. Simply dropping this is a good fix for now.

Seems like "we" should consider the issue of liveliness at the SV2 spec level though. Your idea of using share acknowledgments sounds reasonable, as does using submissions themselves on the upstream side. Despite the batching, maybe there could be a limit on how long an upstream can leave share unacknowledged, and some corresponding minimum for how often the downstream must send a share or renegotiate difficulty or whatever.

It may be worth defining something if for no other reason than to prevent implementations from inventing limits of their own and creating a de facto specification.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Seems like "we" should consider the issue of liveliness at the SV2 spec level though.

at a gut level this feels like a great idea, and the first half is already addressed:

how often the downstream must send a share or renegotiate difficulty or whatever

a client can never promise a share by a deadline, but server knows nominal_hash_rate and is free to send SetTarget based on its vardiff and expected share rate, so it already has enough information to determine what it deems to be a dead client


for the other half, I'm afraid the protocol lacks primitives to make this a low-hanging fruit

sure, there is always the possibility of adding some new sentence along the lines of a server MUST NOT leave a share unacknowledged for more than T seconds

but whatever value T we choose will inevitably be arbitrary and subject to potential blindspots around viable use-cases... so while this approach is tempting, it also makes me hesitant

the alternative is for the server to declare its own batching criteria, but there's no way for it to communicate them

is it a time window of T seconds? is it every X successful shares?

the client needs to know the criteria beforehand, otherwise it cannot assert liveliness

and in order for the client to be notified about this criteria, we need a new field on Open*MiningChannel.Success, which can be achieved via either:

  • breaking change in Mining Protocol (which is likely to face resistance in the community)
  • protocol extension

personally, after deep consideration of the options listed above, I would leave this to a potential protocol extension, to be implemented on SRI in case there's meaningful demand to justify the efforts

@plebhash plebhash Oct 13, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

btw when it comes to attack vectors, I'm afraid none of this will really mitigate a sufficiently sophisticated attacker

like you said, a malicious pool is already a non-starter, and whether they acknowledge shares or not is kind of a meaningless detail

a MITM should be addressed with proper authentication, which is what Sv2 noise solves... if the attacker is sophisticated enough to have compromised the authority private key, they can also simply implement share acknowledgement and remain undetected

so a potential extension for server liveliness guarantee is more like a nice-to-have safeguard against faulty servers, but nothing more than that

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

more like a nice-to-have safeguard against faulty servers

And that's the real use case: robustness, not countering maliciousness.

Server liveliness, judged by whether shares get acknowledged, is one case of a broader issue, now that I look at this harder. In several places the spec allows or expects one side to wait for the other, or to give up after "a reasonable period," without saying how long. For example, how long:

  • A server may hold acknowledgements while it aggregates them, and so how long a client might wait before it calls the server dead (section 5.3.13)
  • A client has to open a channel after setup (section 5.3.2)
  • A pool has to answer SetCustomMiningJob before the miner falls back to another pool (section 5.3.19)

Sections 5.3.21 and 6.2 have more.

The problem is, each of these SHOULDs, timeouts, and reasonables has to turn into a concrete number in code, and if the spec doesn't pick it, each implementation will. Mujina will ship its own guesses, other clients will ship theirs, and upstreams might have to satisfy whichever guess is strictest. Something like this happened with SV1. Cgminer picked 90 seconds for liveliness, and over a decade later, SRI's translator has to send a keepalive mining.notify to clients once a minute to stay under that number.

whatever value T we choose will inevitably be arbitrary and subject to potential blindspots around viable use-cases

True, any value will be somewhat arbitrary. But leaving it out of the spec doesn't avoid an arbitrary value. It moves the choice into each implementation, where nobody weighs the use cases at all. SRI's own translator is such a use case. It opens its first channel only when an SV1 miner arrives, which may be hours after it connects, and a pool that reads section 5.3.2's "reasonable period" as 30 seconds would drop it. A value in the spec at least gets debated in the open, and it can be generous.

The IETF specifies values like these all the time. Where no single value fits, the side that needs more time advertises its own, as a QUIC endpoint does with max_ack_delay (RFC 9000). IKEv2 leaves out its retry timeouts "because they do not affect interoperability" (RFC 7296), but the SV2 waits above do affect it.

I think the spec authors should take a pass through the spec for waits like these and decide, for each one, whether to give it a value, let a peer advertise one, or leave it to implementations on purpose. For server liveliness, a bound on share acknowledgement might be enough. A server that batches by share count can still meet it by sending whatever it has batched before the bound runs out. A server with a real reason to hold acks longer could advertise its own bound in an optional TLV, the way QUIC does.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

stratum-mining/sv2-spec#245 is now tracking this.

@plebhash plebhash Oct 21, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

stratum-mining/sv2-spec#246 is proposing 60s as deadline for SubmitShares.Success

not sure when it will be merged, and whether there will be pushback that forces us to pick a different number

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Dropped, as discussed. Liveness for SV2 can wait for sv2-spec#245 / #246.

@rkuester

Copy link
Copy Markdown
Collaborator

I was wondering if a share that fails validate_share should be accounted as rejected, even if the rejection came from the client itself and not the upstream server.

No, I'd leave them out of the rejected count. The pool never saw those shares, so the count should only include shares the pool itself rejected. Most of these failures are expected, such as a stale share after a new block, or a duplicate from overlapping nonce ranges (see discussion #72). Logging those at debug is enough. A few can only happen when Mujina builds a share wrong, for example with a bad extranonce size. Those should log at warn so somebody notices.

@jayrmotta

jayrmotta commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor Author

Thank you for the thorough review @rkuester, will jump on it right away.

A share whose hash meets its job's network target is a valid block,
whichever protocol the source speaks. The scheduler holds both the
job template and the share hash, so it reports the find once, at
info, for every source.

The dummy source re-mines block 881,423, so its shares log a block
found too. That is real proof of work for that block, and the log
shows the hardware and the stack can find one.
Add a Stratum V2 client that connects to a pool over Noise_NX, sets
up the connection, opens one extended mining channel, and then relays
pool messages to its consumer as events and the consumer's commands
to the pool. Build on stratum-apps 0.8, with only its network and
core features, for the transport and the message types. deny.toml
allows ISC for json5, which it pulls in through the config crate.

Keep wire types inside the client. It checks each value it receives
and converts it to Mujina's types, and it numbers and encodes shares
itself. Only jobs and prev hashes pass through as wire messages,
since the consumer hands them whole to channels_sv2's ExtendedChannel.

Bound the connect, the handshake, each setup response and each frame
write, so a pool that stalls during setup or stops reading its socket
ends the attempt with a retryable error instead of hanging the client.
Move the wait for a first hash rate, the back-off, and the handling of
a lost connection out of stratum_v1.rs into job_source/reconnect.rs,
along with the back-off tests, so the V1 and V2 sources share one
implementation. A source keeps only what is its own: the state it
resets per connection and how it connects. The reconnect log leaves
naming the pool to the connect log that follows it.
Parse the URL naming a job source's upstream into an
upstream::Endpoint: the host, the port, and the protocol the scheme
implies. stratum+tcp:// or a bare host:port means Stratum V1.
stratum2+tcp://host:port/key means Stratum V2, and the key lives in
the V2 variant, so V2 always has one and V1 never does. Any other
scheme fails with UnsupportedScheme instead of reaching DNS as a
garbled host.

The upstream can be a pool, a proxy or a job declarator, and only the
code that builds sources reads one, so the parser lives in job_source.
Add a job source that runs the SV2 client, turns its jobs into job
templates, and hands the scheduler's shares to it, reconnecting with
back-off when the connection drops. It takes only what the daemon
knows and adds the hash rate the scheduler reports.

A job activated by SetNewPrevHash reaches the scheduler as
ReplaceJob, so late shares from the old block are dropped. Any other
job arrives as UpdateJob, so late shares on the same block still go
out. Shares are not checked locally; the pool judges them.

Never wait on the client. A share that finds the client behind is
dropped with a warning, so a stuck connection cannot stop the source
reading the scheduler's commands. A Reconnect redirects only the next
attempt and keeps the configured authority key, so a pool can move
the miner between its own servers but cannot strand it on one.
Build the source that MUJINA_POOL_URL's protocol names: a
StratumV2Source for stratum2+tcp://, the Stratum V1 source otherwise.
Read the user, apply the forced-rate wrapper and register the source
once, outside the match, so a protocol only decides how its source is
built and MUJINA_POOL_FORCED_RATE works for both.

Give the V1 source the endpoint's host and port in place of the URL,
so the parser is the only code that reads one. This drops the tcp://
scheme, which the V1 connection accepted; such a URL stops the daemon
at startup with the parse error.
Pools size a channel's target from its nominal hash rate. The
scheduler reports a new aggregate rate whenever boards come and go or
their telemetry changes, so a rate fixed at channel-open time drifts
from what the miner delivers.

Add ClientCommand::UpdateChannel, carrying the channel and its hash
rate, and have the SV2 source send it with the current rate on every
hash rate update while a channel is open. The client builds the
UpdateChannel message, leaving maximum_target at the maximum so the
pool stays free to choose the target.

A pool answers only an UpdateChannel it cannot accept, with
UpdateChannel.Error; the client logs its error code and the channel
stays open.
A pool can replace a channel's extranonce prefix at any time with
SetExtranoncePrefix. It builds every job sent after that message on
the new prefix, so a miner that keeps the old one computes a
different coinbase and every later share is rejected.

Emit SetExtranoncePrefix from the client and apply it to the
ExtendedChannel. Jobs received afterwards carry the new prefix into
their templates, while jobs already received keep the prefix they
were built on, which is the scope the spec gives the message. A
message addressed to another channel, a group channel included, is
ignored, since the prefix belongs to a single channel.
@jayrmotta
jayrmotta force-pushed the feature/sv2-support branch from adc9643 to 15d38b5 Compare October 30, 2026 18:41
@jayrmotta

jayrmotta commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor Author

Hey @rkuester, I'm done with the changes requested but still didn't reply to each of the comments to provide context. Also, next week I'm planning a deep testing session both on SV1 and SV2 pools to make sure the expected behaviors are according to plan.

So, you can review if you want but I will still do some live end to end testing.

@jayrmotta

Copy link
Copy Markdown
Contributor Author

Hey @rkuester @b-rowan @paratoxicdev, if you have the time please review it, I have applied changes/fixed to all comments and suggestions. Thank you for the contributions!

@b-rowan b-rowan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I don't see anything major, although I am probably not qualified for a full content review, I'll leave that to the people more embedded in the project.

I haven't marked all the log locations that would need to be changed per my first few comments (find host = self. should work to find them), but curious for internal comment on those if it makes sense to change them. I feel it makes sense to have some consistency there, so feel free to resolve or suggest something if you have an opinion (CC @rkuester).

} => {
info!(
pool = %self.config.url,
host = %self.config.host,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Does it make sense to use self.name here instead? Some pools might have backups running on a different port, so showing the port seems useful in the logs, and it only adds 6 characters max.

self.first_share_logged = false;

info!(pool = %self.config.url, "Connecting to pool");
info!(host = %self.config.host, port = self.config.port, "Connecting to pool");

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This is using both host and port, could probably replace with self.name and just make that consistent across the the logging, as with the comment above, OR include both if there is some benefit to having them logged this way.

Either way I think it makes sense to standardize this on one of the 2 options.

if e.is_fatal() {
ConnectOutcome::Fatal(e.into())
} else {
warn!(error = %e, "Disconnected from pool");

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Another situation where you may want to include the self.name information, always better to be more verbose here, especially with a warning log. End users may want to do log parsing or show it on a centralized dashboard, and more information here is definitely useful.

dummy::DummySource,
forced_rate::{ForcedRateConfig, ForcedRateSource},
stratum_v1::StratumV1Source,
stratum_v2::{SourceConfig as Sv2SourceConfig, StratumV2Source},

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Nit, but I think this is better named StratumV2SourceConfig, it keeps the naming consistent.

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.

6 participants