[WIP] BIP93: Allow other human-readable parts #2320

BenWestgate commented at 7:45 PM on October 1, 2026: contributor

Summary

Generalize codex32 so that the human-readable part is not restricted to ms.

This PR is based on top of behavior neutral #2285.

BIP-32 master seeds and their shares continue to use ms, while other applications can use their own human-readable parts.

Changes

Specify the human-readable part as in BIP-173.
Include the human-readable part in checksum construction and verification.
Count its BIP-173 expansion toward the checksum length limits.
Rename the inline ms32 checksum and interpolation helpers to codex32.
Require all shares in a set to use the same human-readable part.
Clarify that the interpolation helpers operate on the data part and do not check the valid set conditions.
Limit fresh-secret generation to applications that accept every payload, or require rejection sampling otherwise.
Do not recommend correcting errors in the human-readable part unless the application specifies how.
Update the existing invalid vectors whose interpretation changes when other human-readable parts become valid.
Add test vectors covering:
- the registered cl human-readable part used by Core Lightning;
- checksum selection affected by human-readable-part length;
- an 83-character human-readable part containing 1;
- expanded lengths 94 and 95;
- a checksum computed over an uppercase human-readable part;
- a human-readable part longer than 83 characters.

Strings using ms are unchanged.

Testing

The codex32 checksum functions were checked against the previous ms32 functions for ms over random data parts of every length from 0 through 1029 symbols, including both checksum variants, the 94–95 expanded-length gap, and lengths beyond 1023.

The new vectors were checked with both the specification's Python code and an independent implementation, python-codex32. They agree except that python-codex32 does not yet enforce the 83-character human-readable-part limit.

Refs: #2040, #2258, #2285

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

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

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

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

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

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

bip93: Allow other human-readable parts

Specify the human-readable part as in BIP-0173 instead of requiring
"ms", so other applications, such as the registered "cl", can use the
codex32 format. Master seeds and their shares keep "ms".

Pass the human-readable part to the checksum functions and cover its
BIP-0173 expansion, which already counts toward the checksum length
limits. Rename the ms32 functions and constants that now serve every
human-readable part to codex32. Results for "ms" are unchanged.

Require every share in a set to have the same human-readable part, state
that the interpolation helpers do not check the set conditions, and limit
fresh-secret generation to applications that accept every payload, with
rejection sampling allowed for those that do not. Implementations should
not correct the human-readable part unless its application specifies how.

Update the existing invalid-vector classifications for generalized human-
readable parts. Add vectors for a Core Lightning "cl" secret, an
11-character human-readable part requiring the long checksum, the
83-character maximum, the 94-95 expanded-length gap, an uppercase human-
readable-part checksum, and an overlong human-readable part.

Checked the checksum functions against the previous ms32 functions for
"ms" across data-part lengths 0 through 1029, and checked interpolation
is unchanged. Checked every new vector with the specification's Python
code and python-codex32, and checked each invalid group fails for its
stated reason. Link-format, README table, and whitespace checks pass.

Refs: #2040, #2258, #2285

80a27cf13b

bip93: Clarify data-part error correction

State explicitly that the checksum's substitution and erasure correction
guarantees apply to errors in the data part. This avoids implying the same
correction guarantees for the human-readable part.

fb0b4f13b9

bip93: Record HRP generalization in changelog

Record the human-readable part generalization as version 0.3.0. It is a
backward-compatible extension, so BIP 3 calls for a minor version bump:
strings with the human-readable part "ms" are unchanged.

Preamble, README table, link-format, and whitespace checks pass.

Refs: #2320

0bfb24da6c

in bip-0093.mediawiki:71 in 80a27cf13b

  67 | @@ -68,24 +68,25 @@ efficient to read out loud, write, type or to put into QR codes.</ref> format ca
  68 |  A codex32 string is similar to a bech32 string defined in [https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki BIP-0173].
  69 |  It reuses the base-32 character set from BIP-0173, and consists of:
  70 |  
  71 | -* A human-readable part, which is the string "ms" (or "MS").
  72 | -* A separator, which is always "1".
  73 | +* A human-readable part, as specified in BIP-0173. It identifies the application, which can further restrict validity.

BenWestgate commented at 9:26 PM on October 1, 2026:

Delete the second sentence? Most specifically the application can further restrict payload validity. A BIP-0173 application HRP can define whatever it wants about the data part besides the checksum.

We additionally keep the codex32 header a normative requirement for all applications.

BenWestgate commented at 9:36 PM on October 1, 2026:

as per BIP-0173

is better than "as specified"

in bip-0093.mediawiki:72 in 80a27cf13b outdated

  67 | @@ -68,24 +68,25 @@ efficient to read out loud, write, type or to put into QR codes.</ref> format ca
  68 |  A codex32 string is similar to a bech32 string defined in [https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki BIP-0173].
  69 |  It reuses the base-32 character set from BIP-0173, and consists of:
  70 |  
  71 | -* A human-readable part, which is the string "ms" (or "MS").
  72 | -* A separator, which is always "1".
  73 | +* A human-readable part, as specified in BIP-0173. It identifies the application, which can further restrict validity.
  74 | +* A separator, which is always "1". If the human-readable part contains "1", the last one in the string is the separator.

BenWestgate commented at 9:28 PM on October 1, 2026:

We probably can remove this sentence since BIP-0173 covers it.

in bip-0093.mediawiki:83 in 80a27cf13b

  82 | +** A payload which is a sequence of up to 73 - 2''n'' bech32 characters, where ''n'' is the length of the human-readable part. (However, see [[#Long_Checksum|Long checksum]] below for an exception to this limit.)
  83 |  ** A checksum which consists of 13 or 15 bech32 characters as described below.
  84 |  
  85 | -See [[#Master_seed_format|Master seed format]] for the payload-length and payload-conversion requirements for BIP-0032 master seeds.
  86 | +BIP-0032 master seeds and their shares use the human-readable part "ms"; see [[#Master_seed_format|Master seed format]] for their other requirements.
  87 | +SatoshiLabs maintains a list of registered codex32 human-readable parts in [https://github.com/satoshilabs/slips/blob/master/slip-0173.md#uses-of-codex32 SLIP-0173].

BenWestgate commented at 9:32 PM on October 1, 2026:

This sentence feels out of place, it had it's own section right before the appendix in BIP-0173. I prefer it there than here. https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#registered-human-readable-prefixes

in bip-0093.mediawiki:163 in 80a27cf13b

 181 | -        return ms32_create_long_checksum(data)
 182 | -    return ms32_create_regular_checksum(data)
 183 | +def codex32_create_checksum(hrp, data):
 184 | +    if len(bech32_hrp_expand(hrp)) + len(data) + 13 > 93:  # See Long checksum
 185 | +        return codex32_create_long_checksum(hrp, data)
 186 | +    return codex32_create_regular_checksum(hrp, data)

BenWestgate commented at 9:50 PM on October 1, 2026:

codex32_verify_checksum(hrp, data) and codex32_create_checksum(hrp, data) should own the values = bech32_hrp_expand(hrp) + data expansion and the checksum selection. Repeating it within every primitive makes this code longer to read and harder to review. def codex32_regular_checksum(values): and similar for the other 3.

in bip-0093.mediawiki:200 in 80a27cf13b

 204 | -def ms32_create_long_checksum(data):
 205 | -    values = data
 206 | -    polymod = ms32_long_polymod(values + [0] * 15) ^ MS32_LONG_CONST
 207 | +def codex32_create_long_checksum(hrp, data):
 208 | +    values = bech32_hrp_expand(hrp) + data
 209 | +    polymod = codex32_long_polymod(values + [0] * 15) ^ CODEX32_LONG_CONST

BenWestgate commented at 9:53 PM on October 1, 2026:

similar, these primitives should accept (values) and not handle the HRP expansion and data.

in bip-0093.mediawiki:210 in 80a27cf13b

BenWestgate commented at 10:31 PM on October 1, 2026:

I dislike this formula representation of the maximum payload, if anyone has a better idea, please share.

Perhaps instead say the maximum string length is 1024 - len(hrp)?

I disliked it in the regular codex32 specification also.

BenWestgate commented at 10:31 PM on October 1, 2026:

I dislike the formula representation.

It may be cleaner to say maximum string length 1024 - len(hrp). any suggestions?

BenWestgate commented at 8:42 AM on October 5, 2026:

This remains unresolved: whether to switch to maximum string length accounting or continue saying the payload length which is mathematically messier but potentially more useful.

in bip-0093.mediawiki:304 in 80a27cf13b

 298 | @@ -291,19 +299,22 @@ There are two ways to create an initial set of ''k'' valid codex32 strings, depe
 299 |  <span id="For_a_fresh_secret"></span><span id="for-a-fresh-secret"></span>
 300 |  '''For a fresh secret'''
 301 |  
 302 | -In the case that the user wishes to generate a fresh secret, the user generates random initial shares, as follows:
 303 | +In the case that the user wishes to generate a fresh secret, the user generates random initial shares, as follows.
 304 | +This requires an application that accepts every payload of the chosen length as a secret, as the master seed format does.
 305 | +An application that does not MAY use rejection sampling instead: retry with a fresh set of shares until the resulting secret qualifies.

BenWestgate commented at 10:35 PM on October 1, 2026:

this might work better as a ref link to rationale, or placed after the fresh secret instructions so line 302 can remain unchanged.

in bip-0093.mediawiki:307 in 80a27cf13b

 304 | +This requires an application that accepts every payload of the chosen length as a secret, as the master seed format does.
 305 | +An application that does not MAY use rejection sampling instead: retry with a fresh set of shares until the resulting secret qualifies.
 306 |  
 307 | -# Choose a bit size from 128, 160, 192, 224, 256, or 512
 308 | +# Choose the human-readable part of the application and a payload length it accepts
 309 | +#* For a master seed, use <code>ms</code>, choose a bit size ''bitlength'' from 128, 160, 192, 224, 256, or 512, and use a payload of ceil(''bitlength / 5'') characters

BenWestgate commented at 10:37 PM on October 1, 2026:

nit: arguably doesn't need to be here.

in bip-0093.mediawiki:333 in 80a27cf13b outdated

 328 |  # Choose a threshold value ''k'' between 2 and 9, inclusive
 329 |  # Choose a 4 bech32 character identifier
 330 |  #* We do not define how to choose the identifier, beyond noting that it SHOULD be distinct for every set of shares the user may need to disambiguate
 331 |  # Set the share index to <code>s</code>
 332 |  # Set the payload to a bech32 encoding of the application-specified secret payload bits; for a master seed, follow [[#Master_seed_format|Master seed format]].
 333 |  # Generate a valid checksum in accordance with the Checksum section

BenWestgate commented at 10:40 PM on October 1, 2026:

This might belong better in "shared secret" we have an "unshared secret" section much earlier.

in bip-0093.mediawiki:408 in 80a27cf13b outdated

 416 | @@ -405,7 +417,11 @@ We define a long checksum to support the maximum seed size because its expanded
 417 |  While we could use the 15 character checksum for both cases, we prefer to keep the strings as short as possible for the more common cases of 128-bit and 256-bit master seeds.
 418 |  Longer strings mean more chances for transcription errors, so shorter strings are better.
 419 |  
 420 | -If the prefix is damaged and a user is guessing that the data might be using this scheme, then the user can enter the available data explicitly using the suspected <code>MS1</code> prefix.

BenWestgate commented at 10:44 PM on October 1, 2026:

I prefer to keep this sentence. It works for MS and it's harmless to try MS1, where as replacing a damaged private HRP (e.g. xprv) with a guessed public one (e.g. xpub) could broadcast it unintentionally.

BenWestgate commented at 10:46 PM on October 1, 2026: contributor

Reviewed all through Test vectors

BenWestgate renamed this:
~~BIP93: Allow other human-readable parts~~
[WIP] BIP93: Allow other human-readable parts
on Oct 5, 2026

bip93: Simplify checksum helper layering 9c5a8d3c11

bip93: Clarify application-specific HRP guidance 18919894e5

BenWestgate commented at 8:19 AM on October 5, 2026: contributor

9c5a8d3 LGTM, much better than expanding the hrp everywhere

in bip-0093.mediawiki:71 in 18919894e5

  67 | @@ -68,7 +68,7 @@ efficient to read out loud, write, type or to put into QR codes.</ref> format ca
  68 |  A codex32 string is similar to a bech32 string defined in [https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki BIP-0173].
  69 |  It reuses the base-32 character set from BIP-0173, and consists of:
  70 |  
  71 | -* A human-readable part, as specified in BIP-0173. It identifies the application, which can further restrict validity.
  72 | +* A human-readable part, as specified in BIP-0173. It identifies the application, which may impose additional validity requirements.

BenWestgate commented at 8:25 AM on October 5, 2026:

This second sentence should be removed. First it doesn't identify the application, it may identify a profile (of an application) but even then, some profiles like ln or the proposed <key origin>xpub use the HRP to show humans data. Removing it allows BIP-173 to remain authoritative here. We have no differences from bip173.

in bip-0093.mediawiki:300 in 18919894e5

 296 | @@ -298,10 +297,10 @@ There are two ways to create an initial set of ''k'' valid codex32 strings, depe
 297 |  
 298 |  In the case that the user wishes to generate a fresh secret, the user generates random initial shares, as follows.
 299 |  This requires an application that accepts every payload of the chosen length as a secret, as the master seed format does.
 300 | -An application that does not MAY use rejection sampling instead: retry with a fresh set of shares until the resulting secret qualifies.
 301 | +If the application does not accept every payload of the chosen length, it MAY use rejection sampling: retry with a fresh set of shares until the resulting secret is valid for the application.

BenWestgate commented at 8:30 AM on October 5, 2026:

nit: technically only the last share or even only the offending characters of the last share need to be retried with fresh randomness.

in bip-0093.mediawiki:420 in 18919894e5

 416 | @@ -418,7 +417,7 @@ The checksum covers the expanded human-readable part, as in BIP-0173, and the ex
 417 |  Beyond those limits, some errors in the human-readable part cannot be distinguished from errors elsewhere in the string, so counting the expansion keeps the error detection guarantees for the entire string.
 418 |  It also lets implementations select the checksum variant from the string alone, without knowing the application.
 419 |  
 420 | -If the human-readable part is damaged and a user is guessing that the data might be using this scheme, then the user can enter the available data explicitly using the suspected human-readable part.
 421 | +For master seeds, if the human-readable part is damaged, the user can enter the available data explicitly using the suspected <code>MS1</code> prefix.

BenWestgate commented at 8:38 AM on October 5, 2026:

Use the sentence:

For master seeds, if the human-readable part is damaged and a user is guessing that the data might be using this scheme, then the user can enter the available data explicitly using the suspected <code>MS1</code> prefix.

BenWestgate commented at 8:38 AM on October 5, 2026: contributor

Much improved, requesting a couple changes.