diff --git a/COVERAGE.md b/COVERAGE.md index 8b9e4d0..1cc8732 100644 --- a/COVERAGE.md +++ b/COVERAGE.md @@ -65,16 +65,17 @@ Cross-cutting invariants with no single home message. |---|---|---|---|---|---|---| | GEN-1 | Ω1 | Θ1 | `channel_msg` bit wrong per message type (e.g. `NewMiningJob` 0x15 sent with bit unset, `OpenStandardMiningChannel.Success` 0x11 with bit set) | [§3.2.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#321-routing-frames-over-channels) "when set, indicates a message which is specific to a channel, whereas if it is unset, the message is to be interpreted by the immediate receiving device", [§8](https://github.com/stratum-mining/sv2-spec/blob/main/08-Message-Types.md#8-message-types) | Assert bit on every received frame | all messages | | GEN-2 | Ω1 | Θ1 | Core messages sent with non-zero `extension_type` | [§3.4.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#341-extension-type-field-usage) "MUST have `extension_type` set to `0x0000`" | Assert `extension_type & 0x7FFF == 0x0000` (mask `channel_msg` bit first) | all messages | -| GEN-3 | Ω1 | Θ1 | Error codes containing bytes outside printable ASCII (control characters or non-printable bytes) | [§3.5](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#35-error-codes) "Error codes MUST consist only of printable ASCII characters" | Validate every `error_code` string; assert printable ASCII only | all `*.Error` messages | +| GEN-3 | Ω1 | Θ1 | Server-sent error codes containing bytes outside printable ASCII (control characters or non-printable bytes) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `STR0_255` "Every byte MUST be a printable ASCII character (0x20 to 0x7E). A receiver MUST treat any other byte as a protocol error." | Validate every `error_code` string; assert printable ASCII only | all `*.Error` messages | | GEN-4 | Ω2 | Θ1 | Server sends messages for a `channel_id` never opened on this connection | [§5.2](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#52-channel) (channel ID consistency) (derived) | Track open channel set; assert all inbound channel messages reference it | all channel messages | | GEN-5 | Ω2 | Θ1 | Job starvation: Mining Protocol Server never sends fresh jobs after the first, stranding miners on an exhausted search space | [§5.1](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#51-job) (server must manage hashing space and "provide new and unique Jobs quickly enough") (derived) | Soft liveness/timing metric | `NewMiningJob`, `NewExtendedMiningJob` | | GEN-6 | Ω1 | Θ1 | Message with unknown `extension_type` that terminates locally is not discarded and ignored (server errors, hangs up, or crashes) | [§3.4.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#341-extension-type-field-usage) "Messages with an unknown `extension_type` which are to be processed locally (as defined above) MUST be discarded and ignored" | Send a frame with an unallocated `extension_type`; assert the session continues unaffected | all messages | | GEN-7 | Ω2 | Θ2 | Server chokes on unnegotiated/unknown TLV fields appended to a core message | [§3.4.3](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#343-stratum-v2-tlv-encoding-model) ("unknown fields can be safely ignored") (derived) | Grind a valid share; append an unknown TLV to its `SubmitSharesExtended`; assert the share is processed normally | `SubmitSharesExtended`, `SubmitShares.Success` | | GEN-8 | Ω1 | Θ1 | Server-generated TLV fields violate placement/ordering rules (not at end of payload, not ordered by `extension_type`) | [§3.4.3](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#343-stratum-v2-tlv-encoding-model) "TLV fields MUST be placed at the end of the message payload" and "TLV fields MUST be ordered by `extension_type`" | Parse TLV region on server messages (only if the server negotiates a TLV extension) | all TLV-extended messages | -| GEN-9 | Ω1 | Θ2 | TLV field exceeding its extension's maximum length is accepted | [§3.4.3](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#343-stratum-v2-tlv-encoding-model) "the recipient MUST reject the message" | Negotiate ext `0x0002`; submit an otherwise-valid share (meets the channel target) carrying a 33-byte `user_identity`; assert `SubmitShares.Error` (only if the server supports extension `0x0002`) | `RequestExtensions`, `SubmitSharesExtended`, `SubmitShares.Error` | -| GEN-10 | Ω1 | Θ1 | Proxy drops or modifies an unknown-extension channel message instead of forwarding it unmodified to the channel endpoint | [§3.4.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#341-extension-type-field-usage) "MUST forward that message... MUST NOT be otherwise modified" | Inject an unknown-`extension_type` channel message on one side of the proxy; assert byte-identical forwarding on the other (only if the target is a proxy, with the harness on both sides of it) | all channel messages | -| GEN-11 | Ω1 | Θ1 | Server sends extension-specific messages for an extension that was never negotiated | [§3.4.2](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#342-implementing-extensions-support) "Extensions MUST require negotiation... before sending" | Assert no extension-typed frames arrive without a prior `RequestExtensions.Success` | `RequestExtensions.Success` | -| GEN-12 | Ω2 | Θ1 | Server sends contradictory responses to a single request (e.g. both `.Success` and `.Error` for the same `request_id`) | `request_id` definitions in [§5.3.3](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#533-openstandardminingchannelsuccess-server---client), [§5.3.5](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#535-openextendedminingchannelsuccess-server---client), [§5.3.6](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#536-openminingchannelerror-server---client), ext `0x0001` [§2](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#2-messages-defined-by-this-extension) (derived) | Assert exactly one response per `request_id` | `OpenMiningChannel.Error`, `RequestExtensions.Error` | +| GEN-9 | Ω1 | Θ2 | TLV field exceeding its extension's maximum length is accepted | [§3.4.3](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#343-stratum-v2-tlv-encoding-model) "the recipient MUST reject the message" | Negotiate ext `0x0002`; submit an otherwise-valid share (meets the channel target) carrying a 33-byte printable `user_identity`; assert `SubmitShares.Error` (only if the server supports extension `0x0002`) | `RequestExtensions`, `SubmitSharesExtended`, `SubmitShares.Error` | +| GEN-10 | Ω1 | Θ1 | Proxy drops an unknown-extension channel message, or modifies any byte other than the permitted `channel_id` remap, instead of forwarding it to the channel endpoint | [§3.4.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#341-extension-type-field-usage) "MUST forward that message... Any `channel_id` mapping/conversion required for other channel messages MUST be done on the `channel_id` in the first four bytes of the message payload, but the message MUST NOT be otherwise modified" | Inject an unknown-`extension_type` channel message on one side of the proxy; assert it is forwarded with only the first four payload bytes allowed to differ (only if the target is a proxy, with the harness on both sides of it) | all channel messages | +| GEN-11 | Ω1 | Θ1 | Server sends extension-specific messages for an extension that was never negotiated | [§3.4.2](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#342-implementing-extensions-support) "Extensions MUST require negotiation... before sending" | Assert no extension-typed frames other than `RequestExtensions.*` arrive without a prior `RequestExtensions.Success` | `RequestExtensions.Success` | +| GEN-12 | Ω2 | Θ1 | Server sends contradictory responses to a single request (e.g. both `.Success` and `.Error` for the same `request_id`) | `request_id` definitions in [§5.3.3](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#533-openstandardminingchannelsuccess-server---client), [§5.3.5](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#535-openextendedminingchannelsuccess-server---client), [§5.3.6](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#536-openminingchannelerror-server---client), ext `0x0001` [§2](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#2-messages-defined-by-this-extension) (derived) | Assert at most one response per `request_id`; zero responses are handled by the message-specific silence scenarios and are compliant for `RequestExtensions` when the server does not engage | `OpenMiningChannel.Error`, `RequestExtensions.Error` | +| GEN-15 | Ω2 | Θ1 | Server sends a `B0_32` field longer than 32 bytes | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `B0_32` "Allowed range of length is 0 to 32" (derived: field type range) | Validate the length prefix on every received `B0_32` field (notably `extranonce_prefix` in `OpenStandardMiningChannel.Success`, `OpenExtendedMiningChannel.Success`, and `SetExtranoncePrefix`); assert ≤ 32 | `OpenStandardMiningChannel.Success`, `OpenExtendedMiningChannel.Success`, `SetExtranoncePrefix` | ### Common Protocol Messages @@ -90,8 +91,10 @@ Cross-cutting invariants with no single home message. | C-SC-6 | Ω1 | Θ1 | Server sets `REQUIRES_FIXED_VERSION` but later sends `NewExtendedMiningJob` with `version_rolling_allowed = True` | [§5.3.1](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#531-setupconnection-flags-for-mining-protocol) "if this bit is set, extended jobs MUST NOT indicate support for version rolling" | Cross-message consistency (only if the server sets `REQUIRES_FIXED_VERSION`) | `NewExtendedMiningJob` | | C-SC-7 | Ω1 | Θ1 | Server accepts `SetupConnection` with a `protocol` it does not serve | [§3.6.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#361-setupconnection-client---server) "If the server does not support the requested `protocol`, it MUST respond with `SetupConnection.Error`" | Send `SetupConnection` with a valid `protocol` the suite's target does not serve (e.g. `protocol=1`, Job Declaration, against a Mining Protocol Server); assert `SetupConnection.Error` | `SetupConnection.Error` | | C-SC-8 | Ω1 | Θ1 | Server accepts `SetupConnection` with no supported version in the offered range (e.g. `(3,3)`, `(3,2)`, `(1,1)`) or closes without first sending `SetupConnection.Error` | [§3.6.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#361-setupconnection-client---server) "If the server supports no protocol version between `min_version` and `max_version` inclusive, it MUST respond with `SetupConnection.Error`" | Send version ranges with no overlap with 2; assert framed `SetupConnection.Error` before TCP close | `SetupConnection.Error` | -| C-SC-9 | Ω2 | Θ1 | Server crashes or drops the connection on 255-byte device-info strings (`vendor`, `hardware_version`, `firmware`, `device_id`) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `STR0_255` "Allowed range of length is 0 to 255" (derived) | Send `SetupConnection` with 255-byte strings; assert a framed `.Success` or `.Error` | `SetupConnection.Success`, `SetupConnection.Error` | +| C-SC-9 | Ω2 | Θ1 | Server crashes or drops the connection on 255-byte device-info strings (`vendor`, `hardware_version`, `firmware`, `device_id`) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `STR0_255` "Allowed range of length is 0 to 255" (derived) | Send `SetupConnection` with 255-byte printable-ASCII strings (so the probe exercises only the length bound); assert a framed `.Success` or `.Error` | `SetupConnection.Success`, `SetupConnection.Error` | | C-SC-10 | Ω1 | Θ1 | Server accepts `SetupConnection` with a `protocol` value outside the ones the spec defines | [§3.6.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#361-setupconnection-client---server) "If the server does not support the requested `protocol`, it MUST respond with `SetupConnection.Error`" (`protocol` defines only 0, 1 and 2, so a server cannot support any other value) | Send `SetupConnection` with `protocol=3`; assert `SetupConnection.Error`. Needs a hand-built frame, since a typed client cannot encode an undefined `protocol` | `SetupConnection.Error` | +| C-SC-11 | Ω1 | Θ1 | Server accepts `SetupConnection` with `REQUIRES_STANDARD_JOBS` but sets `REQUIRES_EXTENDED_CHANNELS` in `.Success.flags` (an unsatisfiable feature set) | [§5.3.1](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#531-setupconnection-flags-for-mining-protocol) "`REQUIRES_EXTENDED_CHANNELS` cannot be honored for a client that set `REQUIRES_STANDARD_JOBS` in `SetupConnection.flags`" | Send `SetupConnection` with `REQUIRES_STANDARD_JOBS`; if `.Success`, assert `REQUIRES_EXTENDED_CHANNELS` is unset; if `.Error`, C-SCE-3 covers the flags | `SetupConnection.Success`, `SetupConnection.Error` | +| C-SC-12 | Ω1 | Θ1 | Server does not treat a non-printable byte in a `SetupConnection` `STR0_255` field (`endpoint_host`, `vendor`, `hardware_version`, `firmware`, `device_id`) as a protocol error (accepts the message or silently ignores the bad field) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `STR0_255` "Every byte MUST be a printable ASCII character (0x20 to 0x7E). A receiver MUST treat any other byte as a protocol error." | Send a byte-level `SetupConnection` with one `STR0_255` field at a time set to a control byte or a byte > 0x7E (all other fields valid); assert `SetupConnection.Error` or disconnect | `SetupConnection.Success`, `SetupConnection.Error` | #### `SetupConnection.Success` ([§3.6.2](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#362-setupconnectionsuccess-server---client)) @@ -126,6 +129,8 @@ No scenarios yet. | M-OSMC-2 | Ω2 | Θ1 | Client completes `SetupConnection.Success` on a Mining Protocol connection, then opens no channels — server fails to close the idle connection within a reasonable period | [§5.3.2](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#532-openstandardminingchannel-client---server) (server SHOULD close idle connections) | Connect, handshake, wait; assert connection timeout + disconnect | — | | M-OSMC-3 | Ω1 | Θ1 | A valid `OpenStandardMiningChannel` receives neither `.Success` nor `.Error` | [§5.3.2](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#532-openstandardminingchannel-client---server) "Server MUST accept the target or respond by sending OpenMiningChannel.Error" | Send a satisfiable request; assert a terminal `.Success` or `.Error` within timeout; silence violates the exhaustive accept-or-error MUST | — | | M-OSMC-4 | Ω1 | Θ1 | Server that did not set `REQUIRES_EXTENDED_CHANNELS` rejects a satisfiable `OpenStandardMiningChannel` | [§5.2.2](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#522-extended-channel) "MUST also accept Standard Channels unless they set `REQUIRES_EXTENDED_CHANNELS`" | After a `.Success` without `REQUIRES_EXTENDED_CHANNELS`, send a satisfiable `OpenStandardMiningChannel`; assert `.Success` | `SetupConnection.Success`, `OpenStandardMiningChannel.Success`, `OpenMiningChannel.Error` | +| M-OSMC-5 | Ω1 | Θ1 | Server does not treat a non-printable byte in `OpenStandardMiningChannel.user_identity` as a protocol error (accepts the channel open) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `STR0_255` "Every byte MUST be a printable ASCII character (0x20 to 0x7E). A receiver MUST treat any other byte as a protocol error.", [§5.3.2](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#532-openstandardminingchannel-client---server) `user_identity` is `STR0_255` | Send a byte-level `OpenStandardMiningChannel` with `user_identity` containing a control byte or a byte > 0x7E; assert `OpenMiningChannel.Error` or disconnect | `OpenStandardMiningChannel.Success`, `OpenMiningChannel.Error` | +| M-OSMC-6 | Ω1 | Θ1 | Server does not treat a non-finite or negative `nominal_hash_rate` in `OpenStandardMiningChannel` as a protocol error (accepts the channel open) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `F32` "A receiver MUST treat NaN, ±Infinity, and negative values (including -0.0) as protocol errors.", [§5.3.2](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#532-openstandardminingchannel-client---server) `nominal_hash_rate` is `F32` | Send `OpenStandardMiningChannel` with each invalid `F32` bit pattern (`NaN`, `+Infinity`, `-Infinity`, `-0.0`, negative); assert `OpenMiningChannel.Error` or disconnect | `OpenStandardMiningChannel.Success`, `OpenMiningChannel.Error` | #### `OpenStandardMiningChannel.Success` ([§5.3.3](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#533-openstandardminingchannelsuccess-server---client)) @@ -141,6 +146,8 @@ No scenarios yet. |---|---|---|---|---|---|---| | M-OEMC-1 | Ω1 | Θ1 | Server doesn't support Extended channels at all | [§5.2.2](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#522-extended-channel) "Upstream servers which accept connections and provide work MUST support Extended Channels" | `OpenExtendedMiningChannel` must not error | `OpenMiningChannel.Error` | | M-OEMC-2 | Ω1 | Θ1 | A valid `OpenExtendedMiningChannel` receives neither `.Success` nor `.Error` | [§5.3.4](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#534-openextendedminingchannel-client---server) "Server MUST satisfy the `min_extranonce_size` or respond with `OpenMiningChannel.Error`" | Send a satisfiable request; assert a terminal `.Success` or `.Error` within timeout; silence violates the exhaustive accept-or-error MUST | — | +| M-OEMC-3 | Ω1 | Θ1 | Server does not treat a non-printable byte in `OpenExtendedMiningChannel.user_identity` as a protocol error (accepts the channel open) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `STR0_255` "Every byte MUST be a printable ASCII character (0x20 to 0x7E). A receiver MUST treat any other byte as a protocol error.", [§5.3.4](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#534-openextendedminingchannel-client---server) inherits `user_identity` as `STR0_255` from `OpenStandardMiningChannel` | Send a byte-level `OpenExtendedMiningChannel` with `user_identity` containing a control byte or a byte > 0x7E; assert `OpenMiningChannel.Error` or disconnect | `OpenExtendedMiningChannel.Success`, `OpenMiningChannel.Error` | +| M-OEMC-4 | Ω1 | Θ1 | Server does not treat a non-finite or negative `nominal_hash_rate` in `OpenExtendedMiningChannel` as a protocol error (accepts the channel open) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `F32` "A receiver MUST treat NaN, ±Infinity, and negative values (including -0.0) as protocol errors.", [§5.3.4](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#534-openextendedminingchannel-client---server) inherits `nominal_hash_rate` as `F32` from `OpenStandardMiningChannel` | Send `OpenExtendedMiningChannel` with each invalid `F32` bit pattern (`NaN`, `+Infinity`, `-Infinity`, `-0.0`, negative); assert `OpenMiningChannel.Error` or disconnect | `OpenExtendedMiningChannel.Success`, `OpenMiningChannel.Error` | #### `OpenExtendedMiningChannel.Success` ([§5.3.5](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#535-openextendedminingchannelsuccess-server---client)) @@ -165,6 +172,7 @@ No scenarios yet. | Scenario IDs | Compliance tier | Testability tier | Failure mode | Spec basis | Detection | Involves | |---|---|---|---|---|---|---| | M-UC-1 | Ω1 | Θ1 | `UpdateChannel` with a `max_target` *smaller than the channel's current target* is ignored (no `SetTarget` within the new bound follows) | [§5.3.7](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#537-updatechannel-client---server) "When `max_target` is smaller than the channel’s current target, the upstream node MUST reflect the client’s request (and send an appropriate `SetTarget` message)" | Send `UpdateChannel` with `max_target` below the current target; await a `SetTarget` with `target <= max_target` (or `UpdateChannel.Error`) within the grace period; see M-ST-1 for crossing | `SetTarget`, `UpdateChannel.Error` | +| M-UC-2 | Ω1 | Θ1 | Server does not treat a non-finite or negative `nominal_hash_rate` in `UpdateChannel` as a protocol error (accepts the update or silently ignores the value) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `F32` "A receiver MUST treat NaN, ±Infinity, and negative values (including -0.0) as protocol errors.", [§5.3.7](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#537-updatechannel-client---server) `nominal_hash_rate` is `F32` | After opening a channel, send `UpdateChannel` with each invalid `F32` bit pattern (`NaN`, `+Infinity`, `-Infinity`, `-0.0`, negative); assert `UpdateChannel.Error` or disconnect | `UpdateChannel.Error` | #### `UpdateChannel.Error` ([§5.3.8](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#538-updatechannelerror-server---client)) @@ -180,7 +188,7 @@ No scenarios yet. | M-CC-1 | Ω1 | Θ1 | Server sends any message for a channel after the client's `CloseChannel` (jobs, `SetTarget`, or anything else channel-scoped) | [§5.3.9](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#539-closechannel-client---server-server---client) "The server MUST stop sending messages for the channel" | Close channel; after a short grace period for messages already in flight, assert no further message for that `channel_id` for the rest of the session | `NewMiningJob`, `NewExtendedMiningJob`, `SetTarget` | | M-CC-2 | Ω3 | Θ1 | Server-initiated `CloseChannel` mid-session without `reason_code`; client cannot re-open cleanly | [§5.3.9](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#539-closechannel-client---server-server---client) | Resilience test (only if the server closes a channel on its own) | — | | M-CC-3 | Ω1 | Θ1 | `CloseChannel` addressing a group channel doesn't close member channels (or closes unrelated ones) | [§5.3.9](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#539-closechannel-client---server-server---client) "all channels belonging to such group MUST be closed" | Group topology probe (only if the server uses groups) | `SetGroupChannel` | -| M-CC-4 | Ω1 | Θ1 | `CloseChannel` `reason_code` contains bytes outside printable ASCII (control characters or non-printable bytes) | [§5.3.9](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#539-closechannel-client---server-server---client) "subject to the same character restrictions as error codes", [§3.5](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#35-error-codes) "Error codes MUST consist only of printable ASCII characters" | Validate `reason_code` string; assert printable ASCII only (only if the server closes a channel on its own) | — | +| M-CC-4 | Ω1 | Θ1 | `CloseChannel` `reason_code` contains bytes outside printable ASCII (control characters or non-printable bytes) | [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) `STR0_255` "Every byte MUST be a printable ASCII character (0x20 to 0x7E). A receiver MUST treat any other byte as a protocol error." ([§5.3.9](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#539-closechannel-client---server-server---client) defines `reason_code` as `STR0_255`) | Validate `reason_code` string; assert printable ASCII only (only if the server closes a channel on its own) | — | | M-CC-5 | Ω1 | Θ2 | Closing one channel (individual, not group) accidentally closes or rejects valid work on another channel on the same connection | [§5.2](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#52-channel) "All Channels are independent of each other" | Open channels A and B, close A, submit a valid share on B; assert `SubmitShares.Success` | `SubmitSharesStandard`, `SubmitSharesExtended`, `SubmitShares.Success` | #### `SetExtranoncePrefix` ([§5.3.10](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#5310-setextranonceprefix-server---client)) @@ -276,6 +284,7 @@ Deferred until a Job Declarator Server suite exists: exercising these messages r | M-ST-2 | Ω1 | Θ2 | Mining Protocol Server applies new target retroactively to active jobs that had `ntime_start` set | [§5.3.21](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#5321-settarget-server---client) "not applicable for already received jobs with `ntime_start=nTime`" | Grind a share valid under the old target on a pre-`SetTarget` job; assert old target applies | `NewMiningJob`, `SubmitSharesStandard` | | M-ST-3 | Ω1 | Θ2 | A `SetTarget` update for one channel (individual, not group) changes validation on another independent channel | [§5.2](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#52-channel) "All Channels are independent of each other" | Open channels A and B, reduce A's target via `UpdateChannel`; grind and submit a share on B valid under B's unchanged target; assert `SubmitShares.Success` | `UpdateChannel`, `SubmitSharesStandard`, `SubmitSharesExtended`, `SubmitShares.Success` | | M-ST-4 | Ω1 | Θ1 | `SetTarget` addressed to a group channel carries a `target` above the most recently accepted `max_target` of at least one member channel | [§5.3.21](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#5321-settarget-server---client) "When `SetTarget` is sent to a group channel, the target is applicable to all channels in the group, and the bound above applies to each of them" | Open channels with different `max_target`s that the server groups; on every group-addressed `SetTarget` assert the M-ST-1 bound against each member (only if the server uses groups) | `SetGroupChannel`, `OpenStandardMiningChannel`, `OpenExtendedMiningChannel`, `UpdateChannel` | +| M-ST-5 | Ω1 | Θ2 | `SetTarget` is not applied to a future job already received with an empty `ntime_start`; after activation the old target still governs | [§5.3.21](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#5321-settarget-server---client) "The target is valid until the next `SetTarget` message is sent and is applicable for all jobs received on the channel in the future or already received with an empty `ntime_start`." | Receive a future job, provoke a `SetTarget` via `UpdateChannel`, activate that job with a `SetNewPrevHash` referencing its `job_id`, then submit a share that discriminates between the old and new targets; assert the new target governs (only if `SetTarget` and `SetNewPrevHash` are observed) | `NewMiningJob`, `NewExtendedMiningJob`, `SetNewPrevHash`, `SetTarget`, `UpdateChannel`, `SubmitSharesStandard`, `SubmitSharesExtended`, `SubmitShares.Error` | #### `SetGroupChannel` ([§5.3.22](https://github.com/stratum-mining/sv2-spec/blob/main/05-Mining-Protocol.md#5322-setgroupchannel-server---client)) @@ -303,7 +312,7 @@ One subsection per registered extension; future registrations append new subsect | Scenario IDs | Compliance tier | Testability tier | Failure mode | Spec basis | Detection | Involves | |---|---|---|---|---|---|---| | X0001-REQS-1 | Ω1 | Θ1 | `request_id` doesn't echo the request | ext `0x0001` [§2](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#2-messages-defined-by-this-extension) `request_id` "Unique identifier for pairing the response" | Random `request_id`s; assert pairing | — | -| X0001-REQS-2 | Ω1 | Θ1 | Extension-defined message framed with the wrong `extension_type` (must be `0x0001`, not `0x0000`) | [§3.4.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#341-extension-type-field-usage) "MUST have `extension_type` set to the identifier of the extension that introduced them", ext `0x0001` [§3](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#3-message-types) | Assert `extension_type == 0x0001` (after masking `channel_msg` bit) on every negotiation frame | `RequestExtensions.Error` | +| X0001-REQS-2 | Ω1 | Θ1 | Extension-defined message framed with the wrong `extension_type` (must be `0x0001`, not `0x0000` or `0x8001`) | [§3.4.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#341-extension-type-field-usage) "MUST have `extension_type` set to the identifier of the extension that introduced them", ext `0x0001` [§3](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#3-message-types) | Assert raw `extension_type == 0x0001` (the extension's message table sets `channel_msg = 0`) on every negotiation frame | `RequestExtensions.Error` | | X0001-REQS-3 | Ω2 | Θ1 | `RequestExtensions.Success.supported_extensions` contains extension IDs that were not in the client's request | ext `0x0001` [§1](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#1-overview) (derived — negotiation semantics: Success confirms which of the requested extensions are supported) | Request a known set of extensions; assert `supported_extensions` ⊆ requested set | — | ##### `RequestExtensions.Error` @@ -311,14 +320,27 @@ One subsection per registered extension; future registrations append new subsect | Scenario IDs | Compliance tier | Testability tier | Failure mode | Spec basis | Detection | Involves | |---|---|---|---|---|---|---| | X0001-REQE-1 | Ω1 | Θ1 | None of the requested extensions are supported, but server doesn't respond with `RequestExtensions.Error` | ext `0x0001` [§4](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#4-implementation-notes) ("MUST respond with `RequestExtensions.Error` if none of the requested extensions are supported") | Request only unallocated extension IDs; assert `Error` | — | -| X0001-REQE-2 | Ω1 | Θ1 | `Error` contents wrong: `unsupported_extensions` ≠ the requested-but-unsupported set | ext `0x0001` [§1.1](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#11-negotiating-extensions) "identifying unsupported extensions and required extensions from the responder", [§4](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#4-implementation-notes) | Request a mix of supported and bogus IDs; assert exact unsupported set | — | +| X0001-REQE-2 | Ω1 | Θ1 | `Error` contents wrong: `unsupported_extensions` ≠ the requested-but-unsupported set | ext `0x0001` [§1.1](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#11-negotiating-extensions) "identifying unsupported extensions and required extensions from the responder", [§4](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#4-implementation-notes) | Force an `Error` response (request only unallocated IDs, or omit a server-required extension); assert `unsupported_extensions` equals the requested-but-unsupported set. A `Success` listing a supported subset is compliant for a partial request (ext `0x0001` §4 example 4) | — | | X0001-REQE-3 | Ω1 | Θ1 | `request_id` doesn't echo the request | ext `0x0001` [§2](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#2-messages-defined-by-this-extension) `request_id` "Unique identifier for pairing the response" | Random `request_id`s; assert pairing | — | | X0001-REQE-4 | Ω1 | Θ1 | `Error.required_extensions` omits an extension the server requires but the client did not request | ext `0x0001` [§4](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0001-extensions-negotiation.md#4-implementation-notes) "MUST list every omitted required extension in `required_extensions`" | Request without a server-required extension; assert `required_extensions` contains it (only if the server requires an extension) | — | +#### Extension `0x0002` — [Worker-Specific Hashrate Tracking](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0002-worker-specific-hashrate-tracking.md) + +This extension defines no new messages; it extends `SubmitSharesExtended` with a `user_identity` TLV field. Generic TLV machinery lives in the [General](#general-3135-5152-8) table as GEN-7…GEN-9. + +##### `SubmitSharesExtended` (TLV-extended) + +| Scenario IDs | Compliance tier | Testability tier | Failure mode | Spec basis | Detection | Involves | +|---|---|---|---|---|---|---| +| X0002-SSE-1 | Ω1 | Θ2 | Server accepts a `SubmitSharesExtended` whose negotiated `0x0002` TLV carries a non-printable `user_identity` value | ext `0x0002` [§1.1](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0002-worker-specific-hashrate-tracking.md#11-tlv-format-for-user_identity) "Subject to the same byte rule as `STR0_255`", [§3.1](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#31-data-types-mapping) "Every byte MUST be a printable ASCII character ... A receiver MUST treat any other byte as a protocol error" | Negotiate `0x0002`; submit an otherwise-valid share (meets the channel target) with a within-32-byte TLV containing a control byte; assert the share is rejected (`SubmitShares.Error` or disconnect) (only if the server supports extension `0x0002`) | `RequestExtensions`, `SubmitSharesExtended`, `SubmitShares.Error` | +| X0002-SSE-2 | Ω1 | Θ2 | Server rejects or chokes on an otherwise-valid share carrying a valid `0x0002` `user_identity` TLV | ext `0x0002` [§1.3](https://github.com/stratum-mining/sv2-spec/blob/main/extensions/0x0002-worker-specific-hashrate-tracking.md#13-behavior-based-on-negotiation) "The `user_identity` field MUST be included in `SubmitSharesExtended` as a TLV with Type `0x0002`", [§3.4.3](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#343-stratum-v2-tlv-encoding-model) "A device processing `SubmitSharesExtended` MUST scan for TLV fields matching any negotiated extensions" | Negotiate `0x0002`; submit an otherwise-valid share (meets the channel target) with a printable `user_identity` TLV; assert `SubmitShares.Success` (only if the server supports extension `0x0002`) | `RequestExtensions`, `SubmitSharesExtended`, `SubmitShares.Success` | + ### Job Declaration Protocol Messages ([§6](https://github.com/stratum-mining/sv2-spec/blob/main/06-Job-Declaration-Protocol.md)) Reserved for a future Job Declarator Server suite. No scenarios yet. +The current spec also includes a `DeclareMiningJob.wtxid_list` block-order MUST ([§6.4.4](https://github.com/stratum-mining/sv2-spec/blob/main/06-Job-Declaration-Protocol.md#644-declareminingjob-client---server)) and the BIP141 rules for `DeclareMiningJob` ([§3.7.2](https://github.com/stratum-mining/sv2-spec/blob/main/03-Protocol-Overview.md#372-bip141-on-declareminingjob)); add `JD-*` scenarios when this suite is implemented. + ### Template Distribution Protocol Messages ([§7](https://github.com/stratum-mining/sv2-spec/blob/main/07-Template-Distribution-Protocol.md)) Reserved for a future Template Distribution Server suite. No scenarios yet. @@ -333,16 +355,17 @@ Reserved for a future Template Distribution Server suite. No scenarios yet. |---|---| | GEN-1 — `channel_msg` bit correctness | ❌ | | GEN-2 — `extension_type` on core messages | ❌ | -| GEN-3 — error code printable ASCII only | ❌ | +| GEN-3 — server error codes printable ASCII only | ❌ | | GEN-4 — `channel_id` never opened | ❌ | | GEN-5 — job starvation (liveness) | ❌ | | GEN-6 — unknown `extension_type` discarded | ❌ | | GEN-7 — unexpected TLV fields ignored | ❌ | | GEN-8 — server TLV placement/ordering | ❌ | | GEN-9 — over-length TLV rejected | ❌ | -| GEN-10 — proxy forwards unknown-extension frames unmodified | ❌ | +| GEN-10 — proxy forwards unknown-extension frames (channel_id remap only) | ❌ | | GEN-11 — no extension messages without negotiation | ❌ | | GEN-12 — contradictory double response | ❌ | +| GEN-15 — oversized `B0_32` field | ❌ | | C-SC-1 — no messages before `SetupConnection` response | ❌ | | C-SC-2 — rejects empty `device_id` | ❌ | | C-SC-3 — `REQUIRES_FIXED_VERSION` vs `REQUIRES_VERSION_ROLLING` | ❌ | @@ -351,8 +374,10 @@ Reserved for a future Template Distribution Server suite. No scenarios yet. | C-SC-6 — `REQUIRES_FIXED_VERSION` + `version_rolling_allowed` consistency | ❌ | | C-SC-7 — unsupported `protocol` value | ✅ | | C-SC-8 — version range with no supported version | ✅ | -| C-SC-9 — 255-byte device-info strings | ❌ | +| C-SC-9 — 255-byte printable device-info strings | ❌ | | C-SC-10 — undefined `protocol` value | ❌ | +| C-SC-11 — `REQUIRES_EXTENDED_CHANNELS` on a `REQUIRES_STANDARD_JOBS` connection | ❌ | +| C-SC-12 — non-printable `STR0_255` in `SetupConnection` | ❌ | | C-SCS-1 — `SetupConnection` response type / TCP close vs framed error | ✅ | | C-SCS-2 — `used_version` within negotiated range | ✅ | | C-SCE-1 — feature-probing missing/mismatched error flags | ❌ | @@ -362,11 +387,15 @@ Reserved for a future Template Distribution Server suite. No scenarios yet. | M-OSMC-2 — inactivity timeout on idle mining connection | ❌ | | M-OSMC-3 — no response to standard channel open | ❌ | | M-OSMC-4 — standard channel rejected without `REQUIRES_EXTENDED_CHANNELS` | ❌ | +| M-OSMC-5 — non-printable `user_identity` (standard) | ❌ | +| M-OSMC-6 — invalid `F32` `nominal_hash_rate` (standard) | ❌ | | M-OSMCS-1 — `request_id` echo in channel open success | ✅ | | M-OSMCS-2 — `channel_id` uniqueness | ❌ | | M-OSMCS-3 — `extranonce_prefix` uniqueness | ❌ | | M-OEMC-1 — Extended channel support | ❌ | | M-OEMC-2 — no response to extended channel open | ❌ | +| M-OEMC-3 — non-printable `user_identity` (extended) | ❌ | +| M-OEMC-4 — invalid `F32` `nominal_hash_rate` (extended) | ❌ | | M-OEMCS-1 — `request_id` echo in extended open success | ✅ | | M-OEMCS-2 — `channel_id` uniqueness (extended) | ❌ | | M-OEMCS-3 — `extranonce_size` vs `min_extranonce_size` | ✅ | @@ -376,6 +405,7 @@ Reserved for a future Template Distribution Server suite. No scenarios yet. | M-OEMCS-7 — target vs `max_target` on extended open | ❌ | | M-OMCE-1 — `request_id` echo on open error | ❌ | | M-UC-1 — `UpdateChannel` target reduction honored | ❌ | +| M-UC-2 — invalid `F32` `nominal_hash_rate` in `UpdateChannel` | ❌ | | M-UCE-1 — `UpdateChannel.Error` for invalid channel | ❌ | | M-UCE-2 — no `UpdateChannel.Error` on valid update | ❌ | | M-CC-1 — silence after `CloseChannel` | ❌ | @@ -428,6 +458,7 @@ Reserved for a future Template Distribution Server suite. No scenarios yet. | M-ST-2 — `SetTarget` non-retroactivity | ❌ | | M-ST-3 — target update leaks to another independent channel | ❌ | | M-ST-4 — group `SetTarget` bound vs each member's `max_target` | ❌ | +| M-ST-5 — `SetTarget` applied to already-received future job | ❌ | | M-SGC-1 — `SetGroupChannel` vs `REQUIRES_STANDARD_JOBS` | ❌ | | M-SGC-2 — group/channel ID namespace separation | ❌ | | X0001-REQ-1 — disconnect when required extensions ignored | ❌ | @@ -438,6 +469,8 @@ Reserved for a future Template Distribution Server suite. No scenarios yet. | X0001-REQE-2 — `Error` unsupported set exact | ❌ | | X0001-REQE-3 — `request_id` echo on negotiation error | ❌ | | X0001-REQE-4 — `required_extensions` completeness | ❌ | +| X0002-SSE-1 — non-printable `user_identity` TLV rejected | ❌ | +| X0002-SSE-2 — valid `user_identity` TLV accepted | ❌ | Note: more columns will be added as the project matures (Job Declarator Server, Template Distribution Server suites).