Skip to content

Conversation

@BenWestgate
Copy link
Contributor

@BenWestgate BenWestgate commented Jan 8, 2026

codex32 string length limited to always cover HRP characters, master seed bit lengths limited to multiples of 32-bits, updated master seed encoding/decoding processes.

Rationale

PR helper for #2040: prepares text for general HRP lengths by defining limits based on string length not data part length and deprecating master seed lengths that violate the new codex32 length rule.

Why
Restricting seeds to 32-bit multiples makes valid secret seed lengths differ by at least 6-7 characters reducing ambiguity to two valid lengths for insert/delete-correcting error correcting wallets. Restricting to 64-bit multiples has one valid length within correctable distance but @roconnor-blockstream wants 160-bit seeds.

Key changes c286c2c

  • Overall string max length for regular codex32 now limited to 94 chars. Payload changed from “up to 74” → up to 72 bech32 characters.
  • Long codex32: new length window (97–1024 characters) and payload allowance relaxed (up to 1001 bech32 chars).
  • Explain the checksum covers low HRP+data per BIP-0173.

Other changes:

  • Remove "decode" from Unshared Secret as this process should be application specific once HRP is generalized.
  • Master seed format changes:
    • Add "decode" section.
    • Restrict seed lengths to 32-bit multiples (128-512) to avoid an "ms" exception for switching between regular and long format. Leaves our desired 128-, 160-, 192-, 224-, 256-bitlengths as well as many others.
    • Recommend how to derive unspecified identifiers for fresh and reshared secret seeds.
    • Recommend deterministic implementations derive padding using a defined CRC code.
  • Defined a "shared string" as a non-"0" threshold parameter codex32 string.
    • Defined how to "decode" these as implementers have been surprised naked share payload bytes are insufficient to recover the secret.
  • Defined a "master share set" as a k shared strings valid set generated with exactly k-1 fresh shares in accordance with that section. (needed for deriving reshare identifiers.)
  • Added a couple <ref> notes for the less obvious changes.
  • Fixed missing /ref so Footnotes now appear at the end of Rationale (they're invisible in master)
  • Bolded all section references.

Backward-compatibility and migration

  • Existing codex32 strings that encode typical data lengths remain valid; however implementations may need to be adjusted that:
    • Accepted codex32 strings 95 and 96 characters long.
    • Rejected Long codex32 data-parts below 81 characters as the new HRP coverage allows them.
    • Rejected codex32 string lengths below 48, equal to 97 or 98 and above 127 characters as codex32 now allows lengths 21 to 94 and 97 to 1024.

Test Vectors
I have a reference implementation with test vectors according to this spec update, as well as #2040, so I will add these if reviewers agree about the text changes.

Clarified codex32 string specifications, including character limits and decoding processes. Updated references to BIP-0173 and adjusted payload character limits.
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.

1 participant