Skip to content

fix(sv1_api): roll only the negotiated version-rolling mask - #2485

Open
amartya1523 wants to merge 4 commits into
stratum-mining:mainfrom
amartya1523:fix/sv1-negotiated-version-mask
Open

amartya1523 wants to merge 4 commits into
stratum-mining:mainfrom
amartya1523:fix/sv1-negotiated-version-mask

Conversation

@amartya1523

@amartya1523 amartya1523 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Closes #2472.

Both sides of mining.configure acted on a mask other than the negotiated one:

  • Server. IsServer::handle_parsed_request stored the mask from the request before handle_configure decided what to grant, and mining.submit version bits were checked against that stored mask. A miner asking for ffffffff could then roll reserved bits, whatever the implementation granted.
  • Client. IsClient::handle_response stored the pool's mask as received, so a pool could hand the client reserved bits, or bits the client never asked for.

BIP 310 lets the miner roll only bits it requested and the server granted, and nothing outside VERSION_ROLLING_MASK (1fffffe0). Both paths now compute exactly that.

Commit 1: VersionRollingParams::negotiated_mask. One shared helper, requested & granted & VERSION_ROLLING_MASK. It returns None when version rolling was not requested or was refused.

Commit 2: server. handle_configure runs first, and only the negotiated mask (and min-bit-count) is stored. The grant in the response is narrowed to that same mask, so what the miner is told matches what submits are checked against. A session that did not request version rolling, or had it refused, stores no mask, so submits without version bits stay valid as before. The handle_configure docs now say the requested mask comes through request and the session mask is set after it returns. The example server reads it from there.

Commit 3: client. The response handler narrows the pool's grant to the mask IsClient::configure requested, rebuilt from the session state the same way configure builds the request.

Commit 4: sv1_api 7.0.0 → 7.1.0. Minor bump for the new public method. Nothing else calls it, so the ^7.0.0 requirements stay.

Behaviour change for implementors: set_version_rolling_mask is no longer called before handle_configure, so a handle_configure that read the session mask to learn the request should use request.version_rolling_mask() instead. In sv2-apps the translator already does that (downstream_message_handler.rs). It grants requested & VERSION_ROLLING_MASK, which the narrowing leaves unchanged, so no companion PR is needed.

Not in this PR: server_to_client::Configure::try_from still parses the pool's mask as is. The client no longer acts on it unnarrowed, and #2415 is changing that parser, so I left it alone to avoid a conflict.

Tests:

  • Server: a grant of ffffffff against a request for ffffffff answers and stores 1fffffe0, and a submit rolling bit 29 gets error 20. A request for 00ff0000 is not widened by a larger grant. A configure without version rolling keeps submits without version bits valid. A refused grant stores nothing.
  • Client: the same three cases.
  • Helper: a unit test for negotiated_mask.

All of them except the no-version-rolling server case, which guards against a regression, fail on main.

BIP 310 only lets a miner roll the version bits it asked for and the
server granted, and neither side may roll bits outside
VERSION_ROLLING_MASK. negotiated_mask computes that mask from a grant
and the requested mask, so the server and client paths can share it.
IsServer stored the mask from the mining.configure request before
handle_configure decided what to grant, and mining.submit version bits
were then checked against it, so a miner asking for ffffffff could roll
reserved bits.

Store only the negotiated mask once handle_configure returns, and narrow
the grant in the response to that same mask. A session that did not
request version rolling, or had it refused, keeps no mask, so submits
without version bits stay valid. The example server now reads the
requested mask from the request instead of the session state.
The mining.configure response handler stored the pool's mask as is, so
a pool could hand the client reserved bits or bits it never asked for.
Narrow the grant to the requested mask and to VERSION_ROLLING_MASK, and
keep no mask when version rolling was not requested.
sv1_api gains VersionRollingParams::negotiated_mask, so it takes a minor
bump. No other crate calls it, so their requirements stay at ^7.0.0.
@Jolah1

Jolah1 commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

tACK d6c0c53

Ran the sv1_api tests, and with main's configure logic put back the six new bug tests fail as described. Also threw random masks at both sides (500k configures and 2M submits on the server, 500k responses on the client):
stored mask is always requested & granted & 1fffffe0, the response carries the same one, and submits only pass inside it. A server that grants like the tproxy does behaves the same before and after.

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.

Submit version bits are checked against the requested mask instead of the negotiated one

2 participants