← Back to Bitcoin Improvement Proposals
BIPinformationalscript

BIP93: Generalize codex32 format for any hrp and fix typos

**Summary of Changes:** Describe codex32 format for arbitrary human-readable parts not just "ms", specify master seed encoding standard, add new test vectors and enhance readability. This makes the document more like BIP-0173: proposing an encoding "codex32", then defining a standard for something using it. See discussion on https://github.com/bitcoin/bips/pull/2023#issuecomment-3538570493. **Spec:** - fixed the threshold mistake in the abstract - replaced "master seed" with "secret", prior to

No reviews
BenWestgate·Updated Mar 7, 2026·0 reviews·0 attestations·View source
Collections:BIPs — Open

Specification

Summary of Changes: Describe codex32 format for arbitrary human-readable parts not just "ms", specify master seed encoding standard, add new test vectors and enhance readability. This makes the document more like BIP-0173: proposing an encoding "codex32", then defining a standard for something using it.

See discussion on https://github.com/bitcoin/bips/pull/2023#issuecomment-3538570493.

Spec:

  • fixed the threshold mistake in the abstract
  • replaced "master seed" with "secret", prior to the "Master seed format" section and made descriptions hrp general
  • updated the checksum reference code to produce valid checksums for any hrp
  • change t to k to match the test vectors and book
  • defined "ms" codex32 secrets:
    • using terms "secret seed" (as the book does) and "codex32-encoded master seed" to refer to "ms" codex32 secrets
    • recommended using first 4 characters of the bech32-encoded fingerprint as the identifier
    • recommended the padding bits be set with a CRC code for extra error detection. Provided reference code for this checksum.

Test Vectors:

  • Fixed the cornucopia of naming conventions in the Test vectors
    • used mostly "secret seed", "codex32 secret", and "codex32-encoded X".
  • Fixed test vector 5 which did not actually append a long checksum to "random" data as the text said it would.
  • Added vector 6 encoding a "cl" prefix codex32-encoded HSM secret, then relabels the identifier (producing a new checksum and codex32-encoded HSM secret)
  • Added vector 7 which parses a "cl" prefix codex32 secret and decodes the HSM secret
  • Clarified why invalid prefix test vectors were bad (their checksum is for "ms" but their prefix is not "ms")
  • We might want to add one that uses "cl" with the old "ms" checksum code as that will now fail with the updated ms32_verify_checksum function

Discussion (0 threads)

Sign in to start a discussion on this spec.