Skip to content

sv1 api hardening - #2498

Open
bit-aloo wants to merge 9 commits into
stratum-mining:mainfrom
bit-aloo:2026-11-10-sv1-api-redesign
Open

bit-aloo wants to merge 9 commits into
stratum-mining:mainfrom
bit-aloo:2026-11-10-sv1-api-redesign

Conversation

@bit-aloo

@bit-aloo bit-aloo commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

closes: #2462
closes: #2464
closes: #2469
closes: #2472
closes: #2473
closes: #2474
closes: #2475
closes: #2476
closes: #2477
closes: #2478
closes: #2479
closes: #2480
closes: #2481
closes: #2482
closes: #2487
closes: #2488
closes: #2489
closes: #2490
closes: #2491
closes: #2492
closes: #2493
closes: #2494
ref: #2412
closes: project-loupe/audit-stratum#6
closes: project-loupe/audit-stratum#43
closes: project-loupe/audit-stratum#85
closes: project-loupe/audit-stratum#102
closes: project-loupe/audit-stratum#103
closes: project-loupe/audit-stratum#104
closes: project-loupe/audit-stratum#105
closes: project-loupe/audit-stratum#106
closes: project-loupe/audit-stratum#107
closes: project-loupe/audit-stratum#161
closes: project-loupe/audit-stratum#163
closes: project-loupe/audit-stratum#205
closes: project-loupe/audit-stratum#206
closes: project-loupe/audit-stratum#207
closes: project-loupe/audit-stratum#209
closes: project-loupe/audit-stratum#210
closes: project-loupe/audit-stratum#236
closes: project-loupe/audit-stratum#261
closes: project-loupe/audit-stratum#262
closes: project-loupe/audit-stratum#269
closes: project-loupe/audit-stratum#275
closes: project-loupe/audit-stratum#280

companion stratum-mining/sv2-apps#996

@Christopherdominic

Copy link
Copy Markdown
Contributor

Pinning the wire forms first is great, but b9c71e27 both rewrites the API and changes accepted and emitted wire forms (string IDs, optional password, opaque resume IDs, 32-bit ntime/nonce, set_version_mask name), and rewrites ~300 lines of wire_compat.rs in the same commit. Could the behaviour changes move into their own commits after the refactor, so the refactor commit only touches wire_compat.rs for API renames? That would make it reviewable that the redesign itself preserves the wire.

@Christopherdominic

Copy link
Copy Markdown
Contributor

This closes #2473, #2478 and #2490, which #2486, #2495 and #2496 already target. Could we agree an order, so those PRs either land first or are explicitly closed in favour of this one?

Covers the envelope forms, every request and notification parser, client-side
results, and the JSON emitted for replies and notifications, so the redesign
that follows shows each behaviour change as a fixture diff.
Replaces the four-variant message enum, the Method layer and the direction
enums with a two-variant envelope, where a notification is a request without
an ID. Typed messages are grouped by operation: ClientToServer and
ServerToClient carry them in Request and Response envelopes, and a reply is
typed by the method of the request it answers.

IsServer and IsClient, each with an Async variant, become routers with one
entry point and required handlers. They keep no session state and check none:
a handler acts on its message and sends the reply, and callers match replies
to their requests.

Also accepts string IDs, an omitted authorize password and opaque subscribe
resume IDs, rejects ntime and nonce above 32 bits, reads short min-bit-count
strings as decimal, and sends mining.set_version_mask under its BIP 310 name.
stratum-translation, the example and the fuzz targets move to the new API.
…culty

A zero target gives an infinite difficulty, which SetDifficulty cannot encode.
Return InvalidSv1Difficulty instead.
Checks hex lengths before decoding, limits notify merkle branches to 32
entries, extranonce2 sizes to what a submit can carry and string IDs to 64
bytes, keeps decode errors bounded whatever the message size, escapes peer
strings in Display, and redacts the configure connection URL from raw
requests.
Clamps the mask in configure results to VERSION_ROLLING_MASK when decoding and
when encoding, so neither side acts on reserved bits whatever the peer or the
implementor provides.
Encoding panics on a difficulty that is not finite and positive, so decoding
now rejects such values too and any decoded notification can be sent again.
The fuzz target asserts that round trip.
serde_json's default float parser can be off by one ulp, so a message
re-encoded from an exact float failed the equality assertion. Enable
float_roundtrip for the fuzz build only.
sv1_api 8.0.0 breaks its public API, and stratum_translation and stratum-core
expose its types.
@bit-aloo
bit-aloo force-pushed the 2026-11-10-sv1-api-redesign branch from 46445c8 to 49e2010 Compare November 16, 2026 13:46
The sv1 wire target builds messages with arbitrary string IDs and asserted
that every serialized message decodes. Decoding now rejects a string ID longer
than 64 bytes, so the target asserts that rejection and keeps the round trip
for every other message.
@bit-aloo
bit-aloo marked this pull request as ready for review November 16, 2026 13:58
@bit-aloo

Copy link
Copy Markdown
Member Author

I am opening this for review. This changes sv1_api quite a bit. The traits are now very similar to those in handlers, with similar async variants. The typed messages should no longer be ambiguous either.

I am also working on sv2-apps to see if we can improve the existing APIs or add new ones to make them easier to use.

@bit-aloo
bit-aloo requested a review from GitGab19 November 16, 2026 14:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment