BIP93: Refactor format and seed sections #2285

pull BenWestgate wants to merge 6 commits into bitcoin:master from BenWestgate:bip93-master-seed-refactor changing 1 files +177 −173
  1. BenWestgate commented at 8:52 AM on September 12, 2026: contributor

    Motivation

    BIP 93 is easier to follow if the specification goes from the general format to its specific uses:

    1. codex32 format and checksums
    2. optional secret sharing
    3. BIP-0032 master seed encoding

    This PR reorganizes the specification in that order.

    It also removes duplicated explanations and redundant encoding/decoding helpers, makes the seed-size units consistent, and adds a retrospective changelog and Version: 0.2.1 preamble field.

    The final follow-up clarifies how codex32 strings are represented when passed to the interpolation functions and moves those helpers before generation and recovery use them.

    Behavior neutral changes only.

  2. BIP93: Separate format and seed sections
    Group the regular and long checksum definitions in the codex32 format
    section. Move the master-seed application profile to the end of the
    specification and keep seed-specific checksum motivation in the
    rationale.
    
    This is a behavior-neutral organization change on top of the #2258
    profile commit.
    eb7bb6c097
  3. BenWestgate commented at 9:15 AM on September 12, 2026: contributor

    eb7bb6c097fe9fc340ffa7f8b7cf8344b38fa84f is ready for review.

    Most of the PR description is extra seasoning or nice-to-have house-keeping before I rebase #2040 on this PR. @roconnor if you'd like you can propose a bits vs bytes consistency fixup commit and I will add it to this PR.

    I'll add commits for any cACK'd idea in the description

  4. apoelstra commented at 12:09 PM on September 12, 2026: contributor

    A bits vs bytes consistency fixup commit; and

    I wouldn't mind adding this here in a separate commit. Up to you.

    A cautionary warning to not convert bytes to shares.

    Let's defer to another PR. This might require some discussion about whether we should allow shares to bytes, whether we should allow bytes to shares if you're super careful, etc etc

    Optional: a changelog [for #2258]

    Yes please!

  5. apoelstra commented at 12:15 PM on September 12, 2026: contributor

    In the existing text we say "String validity may be further restricted by specific applications, see Master seed format below.". This is a run-on sentence. Can we change the "," to a "." and capitalize See?

    (This is unrelated to the current diff but this PR seems like we could fit it in here since you also fixed a couple other typos/formatting things.)

    Lol @ the old text saying overwhelming (1 - 2^65) probability. without a negative sign in front of 65. Negative 2^65 probability is overwhelming!

    Other than these nits eb7bb6c097fe9fc340ffa7f8b7cf8344b38fa84f looks good to me. This PR has no functional changes and is easy to review.

  6. BenWestgate commented at 4:10 PM on September 12, 2026: contributor

    bits vs bytes belongs here, anything non-functional, really.

    I will add a changelog and fix that run-on sentence. I dislike it too, too broad. As far as I know, different applications may only restrict validity by: HRP, payload_len and secret payload construction. We fixed, checksum selection and probably header so codex32_decode(codex) works well enough to say what the application even is.

    without a negative sign in front of 65.

    I added the correct number (but as base10 exponent) back in https://github.com/BenWestgate/bips/commit/98935ff1f903703db13a191262ce7e6dfe19938c we repeat numbers and phrases a lot in this standard. Should I add a de-duplication commit here? This probably comes before the bits vs bytes commit as I know some of those sentences are nearby duplicates.

    Did you ACK this TOC?

    ==Specification==
    ===codex32===
    ====Error Correction====
    ===SSSS-awareness===
    ====Generating Shares====
    ====Recovering Secret====
    ===Master seed format===
    

    Doc should start with shares if they want to do secret sharing (and read this section), as they are the most general codex32 string, they all have the same random payloads (unless we want to permit SLIP-0039 style constraints), while secrets are already application specific decoded/encoded.

  7. apoelstra commented at 3:48 PM on September 13, 2026: contributor

    Should I add a de-duplication commit here?

    Yeah, I think that's a good idea.

    Did you ACK this TOC?

    Yep.

  8. bip93: Deduplicate specification
    Keep the common format rules and checksum properties in one place, and replace the broad application-validity sentence with a concrete reference to the master seed requirements.
    
    Remove the redundant symbol encoder and decoder examples. Preserve their validation rules in the format and master seed text, including the encoded-length restriction for both secrets and shares. Retained checksum and interpolation code is unchanged.
    
    Checked retained Python ASTs against eb7bb6c, all 36 valid and 55 invalid vector occurrences, all six size mappings, legacy sizes, 1024 header combinations, checksum boundaries, share recovery, and nonzero padding. Link-format, README table, and whitespace checks pass.
    
    Refs: #2258, #2285
    9621d3fa06
  9. bip93: Reorganize specification
    Let readers implement unshared master seeds from the format and master
    seed sections without reading the secret sharing procedures. Keep the
    common header and unshared-secret rules under codex32, and group share
    generation and recovery under SSSS-awareness.
    
    Give checksum and error correction one TOC entry each. Use bold labels
    for the individual checksums and generation cases, and preserve both
    MediaWiki anchors and GitHub permalinks for demoted headings. Put the
    interpolation helpers with generation and its recovery wrapper afterward.
    Retained executable code is unchanged.
    
    Checked the retained Python ASTs, existing valid/invalid vectors, size
    mappings, header combinations, checksum boundaries, recovery, and padding.
    Inspected the rendered TOC and table and checked fragment targets.
    Link-format, README table, and whitespace checks pass.
    
    Refs: #2285
    1589133608
  10. bip93: Clarify seed-size units
    Describe seed sizes in bits in the encoding instructions, checksum
    rationale, and retained-size list, matching generation and the vectors.
    Keep bytes for decoded output and the historical contiguous byte-size
    range, and retain both units in the size table.
    
    The supported sizes and all numeric constraints are unchanged. The
    existing rationale already explains that BIP39 produces 512-bit seeds.
    
    Checked retained Python ASTs, all existing vector occurrences, size
    mappings, header combinations, checksum boundaries, recovery, padding,
    and rendered markup. Link-format, README table, and whitespace checks
    pass.
    
    Refs: #2258, #2285
    12a61ee567
  11. bip93: Add revision history
    Add a reverse-chronological draft changelog and matching Version header
    so readers can distinguish the earlier checksum-boundary and seed-size
    changes from this behavior-neutral reorganization.
    
    Assign retrospective versions to significant revisions and use their
    upstream integration dates, rather than individual patch author dates.
    Keep the Draft status and BSD-3-Clause license unchanged.
    
    Checked the historical entries against first-parent upstream history,
    the version and date ordering, and the metadata-only diff. Python ASTs,
    existing vectors, size and checksum boundaries, header combinations,
    recovery, padding, rendered markup, link formatting, README table, and
    whitespace checks pass.
    
    Refs: #2258, #2285
    54e0233ad7
  12. baslabofhd777-lab commented at 2:11 AM on September 14, 2026: none

    مرحبًا

  13. bip93: Explain secret-sharing data representation
    Define the integer-list representation once in the SSSS-awareness
    introduction, before either procedure needs it. Move the unchanged
    interpolation helpers there too, so recovery does not depend on code
    inside Generating shares. Describe interpolation's arguments and result
    beside its definition and refer to the shared representation from both
    generation and recovery.
    
    State that both checksum variants use the same procedures without an
    early reference to the interpolation function. Label the existing casing
    rules and remove the unnecessary word "workflows" from the rationale.
    No algorithms, validity conditions, version, or changelog entries change.
    
    Checked all Python blocks are byte-identical and that vectors, procedure
    conditions, casing rules, headings, anchors, and metadata are unchanged.
    Sixteen recovery cases pass using only the shared introduction and
    recovery snippets, covering regular and long checksums. Existing vector,
    size, header, checksum-boundary, recovery, and padding checks also pass.
    Local rendering, link formatting, README table, and whitespace checks
    pass; the casing label does not add a TOC entry.
    
    Refs: #2285
    1978ac253d
  14. BenWestgate commented at 3:35 AM on September 14, 2026: contributor

    @apoelstra could you rereview the current head 1978ac2 when you get a chance?

    eb7bb6c is preserved as reviewed. The follow-ups are:

    • 9621d3f: deduplicate specification
    • 1589133: reorganize sections/headings
    • 12a61ee: clarify seed-size units
    • 54e0233: add revision history/version
    • 1978ac2: introduce interpolation helpers before generation and recovery

    These implement the changes discussed above and are behavior-neutral. No further cleanup planned absent review.

  15. jonatack added the label Proposed BIP modification on Sep 14, 2026
  16. BenWestgate referenced this in commit dc1cb076c5 on Sep 22, 2026
  17. BenWestgate referenced this in commit 2dcf91310a on Sep 22, 2026
  18. BenWestgate commented at 5:53 AM on September 22, 2026: contributor

    I rebased #2040's branch on this PR's head. On top of this PR it's about half the size (+143/−59 vs +177/−173): https://github.com/BenWestgate/bips/compare/bip93-master-seed-refactor...bip93-fix-threshold

  19. BenWestgate referenced this in commit 922f64a0be on Sep 22, 2026
  20. BenWestgate referenced this in commit 8bfab11d27 on Sep 22, 2026
  21. bitcoin blocked a user on Sep 23, 2026

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bips. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-10-11 23:10 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me