Skip to content

STR0_255: restrict to printable ASCII - #252

Merged
plebhash merged 2 commits into
stratum-mining:mainfrom
plebhash:2026-11-07-str0-255-ascii
Nov 12, 2026
Merged

plebhash merged 2 commits into
stratum-mining:mainfrom
plebhash:2026-11-07-str0-255-ascii

Conversation

@plebhash

@plebhash plebhash commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

closes #219

STR0_255 carried no character-set rule, so fields such as user_identity could hold any UTF-8 (control characters, invisible code points, emoji with hidden payloads), which invites validation and log-rendering edge cases without giving any functionality that ASCII does not already give.

This PR puts the rule on the type itself in 3.1, so it covers every STR0_255 field at once: every byte MUST be a printable ASCII character (0x20 to 0x7E), and a receiver MUST treat any other byte as a protocol error (same pattern as the F32 row).

With the rule on the type, the per-field statements it subsumes are dropped:

  • 3.5: "Error codes MUST consist only of printable ASCII characters." and the paragraph extending it to reason_code, plus the back-reference to it in 5.3.9
  • user_identity (5.3.2) and user_identifier (6.4.2): "UTF-8 encoding SHOULD be used."

A second commit covers the user_identity TLV value of extension 0x0002, which is a raw TLV value rather than a STR0_255 and so is not reached by the type rule: it now points at the same byte rule, and the examples that labelled the bytes UTF-8 (3.4 and the extension) say ASCII instead.

Note that error codes and reason_code previously had only a sender-side rule; they now get the receiver-side rejection as well.

This is a breaking change for any implementation currently sending non-ASCII bytes in those fields. Spec versioning is tracked separately in #218.

@plebhash
plebhash marked this pull request as ready for review November 7, 2026 23:01
@Sjors

Sjors commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

ACK d98bab7

Might be worth pointing out in the PR description that this doesn't impact the coinbase (scriptSig), which uses B0_255.

Maybe also mention that endpoint_host and Reconnect.new_host should use IDNA’s ASCII form, e.g. bücher.de -> xn--bcher-kva.de.

Theoretically this could break existing worker names (e.g. 矿工.worker1), so when this is applied to SRI it should have a release note.

Comment thread 03-Protocol-Overview.md Resolved
Comment thread 03-Protocol-Overview.md Resolved
Comment thread 05-Mining-Protocol.md Resolved
The type carried no character-set rule, so fields such as user_identity
could hold any UTF-8, with the validation and log-rendering edge cases
that invites (control characters, invisible code points) and no
functionality that ASCII does not already give. Put the rule on the type
so it covers every STR0_255 field at once, with a receiver-side rule
mirroring the F32 row, and drop the per-field statements it subsumes:
the printable-ASCII sentences for error codes and reason_code in 3.5,
the reason_code back-reference in 5.3.9, and the "UTF-8 encoding SHOULD
be used" on user_identity and user_identifier.

closes stratum-mining#219
The worker name in extension 0x0002 travels as a raw TLV value, not as
STR0_255, so the type-level byte rule does not reach it. It is the same
worker name that motivated the restriction, carried on every
SubmitSharesExtended. Point the value at the STR0_255 rule so it gets
the same byte range and receiver behaviour, and relabel the examples
that called the bytes UTF-8.
@plebhash
plebhash force-pushed the 2026-11-07-str0-255-ascii branch from d98bab7 to c3ebfde Compare November 11, 2026 18:43

@bit-aloo bit-aloo 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.

Once this is merged, we'll need to adapt the apps and core repos accordingly. We already have a method on Str0255 that converts the value to UTF-8 if possible, falling back to a hex string otherwise, we should hard error now

/// Returns the value as a UTF-8 string if possible, otherwise as a hex string prefixed with 0x.
pub fn as_utf8_or_hex(&self) -> String {
    match core::str::from_utf8(self.as_bytes()) {
        Ok(s) => alloc::string::String::from(s),
        Err(_) => format!("0x{}", bytes_to_hex(self.as_bytes())),
    }
}

Comment thread 03-Protocol-Overview.md
| U64 | 8 | Unsigned integer, 64-bit, little-endian |
| U256 | 32 | Unsigned integer, 256-bit, little-endian. Often the raw byte output of SHA-256 interpreted as an unsigned integer. |
| STR0_255 | 1 + LENGTH | String with 8-bit length prefix L. Unsigned integer, followed by L bytes. Allowed range of length is 0 to 255. The string is not null-terminated. |
| STR0_255 | 1 + LENGTH | String with 8-bit length prefix L. Unsigned integer, followed by L bytes. Allowed range of length is 0 to 255. The string is not null-terminated. Every byte MUST be a printable ASCII character (0x20 to 0x7E). A receiver MUST treat any other byte as a protocol error. |

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.

What does ‘protocol error’ mean here? We have something similar for f32. Is this left to implementers, or should we define it in the spec?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

yeah let's leave it here for consistency, and fix it everywhere via #256

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.

Sure!

@GitGab19 GitGab19 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.

ACK

@bit-aloo bit-aloo 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.

ACK

@plebhash
plebhash merged commit efade57 into stratum-mining:main Nov 12, 2026
1 check passed
@plebhash
plebhash deleted the 2026-11-07-str0-255-ascii branch November 12, 2026 12:53
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.

consider prohibiting non-ASCII characters on STR0_255

4 participants