BIP93: terminology, typo, and phrasing fixups #2052

BenWestgate · 2025-12-10T02:37:25Z

Various terminology fixes, typo fixes and phrase fixups from #2040 and #2023.

In the interest of moving forward I would kinda like Ben to make a new PR with the non-HRP changes, which it seems like everyone agrees with and would reduce the size of the diff of this one.

#2040 (comment)

This is that PR.

… term fixes

BenWestgate

Short rationale for changes that may not be immediately obvious.

BenWestgate · 2025-12-10T13:42:20Z

bip-0093.mediawiki

+It includes an encoding format, a BCH error-correcting checksum, and optional Shamir's secret sharing algorithms for share generation and secret recovery.
+Secret data can be encoded directly, or split into up to 31 shares.


I moved SSS down a sentence and called it optional so users don't assume it's required.

Yeah, this made me double-take but we were already trying to do that with our misleading "threshold from 1 to 9" description. Your text is better.

BenWestgate · 2025-12-10T13:42:54Z

bip-0093.mediawiki

+[https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki BIP-0032] hierarchical deterministic wallet using it.
+It includes an encoding format, a BCH error-correcting checksum, and optional Shamir's secret sharing algorithms for share generation and secret recovery.
+Secret data can be encoded directly, or split into up to 31 shares.
+A minimum threshold of shares, which can be between 2 and 9, is needed to recover the secret, whereas without sufficient shares, no information about the secret is recoverable.


closes #2023

BenWestgate · 2025-12-10T13:43:55Z

bip-0093.mediawiki

+Note that per BIP-0173, the lowercase form is used when determining a character's value for checksum purposes.
+In particular, given an all uppercase codex32 string, we still use lowercase <code>ms</code> as the human-readable part during checksum construction.


moved these sentences from test vectors to definition

BenWestgate · 2025-12-10T13:45:52Z

bip-0093.mediawiki

+    combined = data + ms32_create_checksum(data)
+    return "ms" + "1" + ''.join([CHARSET[d] for d in combined])
+
+def ms32_decode(codex):


this is a function that would save a few minutes for implementers, summarizes the validity rules (except for incomplete group) in code form.

Where did it come from? It looks correct to me but I didn't look too carefully at it.

Me. It's from my local copy of my python-codex32 package. It passes the test vectors. I'll send CI when I publish it.
We could reject incomplete groups here rather than wait for convertbits or your sanity_check.
Lib code will have slight diff to raise descriptive error classes like your rust does instead of return None though.

In my view it's okay for the reference code to be more accepting than a production implementation.

But I'd also be happy tightening it up. Let's defer to a later PR though since there's enough happening here as-is.

yes, we never know if a base32 native secret wants to use this specification in which case incomplete groups would not apply to it.

It looks correct to me but I didn't look too carefully at it.

6763349

Fixed a bug and made the validity condition cleaner.

BenWestgate · 2025-12-10T13:47:57Z

bip-0093.mediawiki

-* The number of codex32 shares is exactly equal to the (common) threshold value.
-
-If all the above conditions are satisfied, the <code>ms32_recover</code> function will return a codex32 secret when its argument is the list of codex32 shares with each share represented as a list of integers representing the characters converted using the bech32 character table from BIP-0173.
+* The number of shares is exactly equal to the (common) threshold value.


throughout the text I reduced the use of "codex32" as an adjective to reduce jargon and avoid UI designers assuming they can't just say "share" or "secret".

BenWestgate · 2025-12-10T13:49:48Z

bip-0093.mediawiki

 ===Generating Shares===

-If we already have ''t'' valid codex32 strings such that:
+If we already have ''k'' valid codex32 strings such that:


I prefer k and that's what the SSS wikipedia article uses but t is also correct. The codex32 book and test vectors used k so that's why I got rid of t for consistency.

BenWestgate · 2025-12-10T13:51:48Z

bip-0093.mediawiki

+The codex32 secret and the ''k''-1 codex32 shares form a set of ''k'' valid initial codex32 strings from which additional shares can be derived as described above.

-===Long codex32 Strings===
+===Long codex32===


I renamed the format "Long codex32" to match "codex32" it felt weird to make "strings" part of the proper noun. also updated test vector 5 to match.

BenWestgate · 2025-12-10T13:55:05Z

bip-0093.mediawiki

+A secret seed is a codex32 encoding of:
+
+* The human-readable part "ms" for master seed.
+* The data-part values:
+** A threshold parameter, which MUST be a single digit between "2" and "9", or the digit "0".
+** An identifier consisting of 4 bech32 characters.
+*** We do not define how to choose the identifier, beyond noting that it SHOULD be distinct for every master seed and share set the user may need to disambiguate.
+** The share index "s".
+** A conversion of the 16-to-64-byte BIP-0032 HD master seed to bech32:
+*** Start with the bits of the master seed, most significant bit per byte first.
+*** Re-arrange those bits into groups of 5, and pad with arbitrary bits at the end if needed.
+*** Translate those bits to characters using the bech32 character table from BIP-0173.


This duplicates L281-285 in "For an Existing Secret" we might want to cite this section and delete lines up there or vice versa.

Also looks like I forgot the checksum here?

Yeah, I vote we delete the above section and link down here. In "for an existing secret" I think we want to add a line about length. Specifically, if your seed data is 46 bytes or fewer, use codex32; otherwise use long codex32 (ref).

We could also move this section after the Unshared Secret section.

Everyone needs the master seed standard to import/export seeds but not all users want the SSS stuff. So "Existing secret" is lower priority. If we define master seed encoding first L281-285 can be replaced with a link.

There's a lot of overlap between "Fresh" and "Existing" and it risks reader auto-pilot.

For example my reviewer on BIP85 app completely missed that initial share indices were supposed to be chosen alphabetically. (There is not supposed to be a "z" initial share for example.)

A refactor to de-duplicate is possible but I haven't thought about it.

I'm fine with the existing duplicated text. We can refactor in a followup if you want. Especially if the goal is to rearrange text in order of priority.

I moved the new "Master seed format" to be below "Unshared Secret". The "direct encoding of ... master seed" sentence could hop down from "Unshared" leaving it HRP pure (no diff when #2040 is rebased on this.)

Looks better to me. I left "existing secret" as in aa06616.

In "for an existing secret" I think we want to add a line about length. Specifically, if your seed data is 46 bytes or fewer, use codex32; otherwise use long codex32 (ref).

It says:

Generate a valid checksum in accordance with the Checksum section

And the Checksum section says:

def ms32_create_checksum(data): if len(data) > 80: # See Long codex32 Strings return ms32_create_long_checksum(data)

BenWestgate · 2025-12-10T14:04:36Z

bip-0093.mediawiki

 * Derived share with index <code>D</code>: <code>MS12NAMEDLL4F8JLH4E5VDVULDLFXU2JHDNLSM97XVENRXEG</code>
-* Secret share with index <code>S</code>: <code>MS12NAMES6XQGUZTTXKEQNJSJZV4JV3NZ5K3KWGSPHUH6EVW</code>
-* Master secret (hex): <code>d1808e096b35b209ca12132b264662a5</code>
+* Recovered secret seed with index <code>S</code>: <code>MS12NAMES6XQGUZTTXKEQNJSJZV4JV3NZ5K3KWGSPHUH6EVW</code>


If the book does away with "secret seed" we may drop it here and stick to "secret" or "codex32 secret". See: BlockstreamResearch/codex32#72
This is the best terminology for now, plus "secret seed" books are in print. I'm fine with using this term in BIP93.

For distinction, I'm deliberately not calling interpolated secrets "codex32-encoded master seeds" because they aren't encoded from seeds, they're decoded into seeds.

This seems reasonable to me.

BenWestgate · 2025-12-10T14:13:03Z

bip-0093.mediawiki

 This example shows generating a new 512-bit master seed using "random" codex32 characters and appending a checksum.
 The payload contains 103 bech32 characters, which corresponds to 515 bits. The last three bits are discarded when converting to a 512-bit master seed.

-This is an example of a '''Long codex32 String'''.
+This is an example of a '''Long codex32''' string.
+
+k value (bech32): <code>0</code>
+
+identifier (bech32): <code>0C8V</code>
+
+payload (bech32): <code>M32ZXFGUHPCHTLUPZRY9X8GF2TVDW0S3JN54KHCE6MUA7LQPZYGSFJD6AN074RXVCEMLH8WU3TK925ACDEFGHJKLMNPQRSTUVWXY06F</code>

-* Secret share with index <code>S</code>: <code>MS100C8VSM32ZXFGUHPCHTLUPZRY9X8GF2TVDW0S3JN54KHCE6MUA7LQPZYGSFJD6AN074RXVCEMLH8WU3TK925ACDEFGHJKLMNPQRSTUVWXY06FHPV80UNDVARHRAK</code>
-* Master secret (hex): <code>dc5423251cb87175ff8110c8531d0952d8d73e1194e95b5f19d6f9df7c01111104c9baecdfea8cccc677fb9ddc8aec5553b86e528bcadfdcc201c17c638c47e9</code>


The example text did not fit what the data showed, assembled from random characters and appending a checksum. So I did this piecewise assembly to match the text exactly as per the discussion in #2040 (comment)

This looks fine to me. I don't want to hang up this PR on terminology but I find it a little bit confusing that we use the terms "master seed" and "secret seed" to refer to the same data with different encodings. I wonder if we should change "Master seed (hex)" to "Secret seed (hex)" and change "Secret seed" to "Secret seed (codex32)".

Master seeds aren't bijective with their codex32-encodings due to threshold, identifier and arbitrary padding so I wouldn't use the same word.

As with up here I'm okay with just calling it "secret" or "codex32 secret", this case is not a "codex32-encoded" existing seed:

This example shows generating a new 512-bit master seed using "random" codex32 characters and appending a checksum.

And codex32 characters should be bech32 characters?

I see you've put (codex32) in parenthesis is that the preference when giving data as opposed to (bech32) as master vector 1 used:

codex32 secret (bech32):

"codex32 secret (bech32)" or "Secret (bech32)" looks better than "Secret seed (codex32)"

I'm happy with "codex32 secret (bech32)". It maaybe implies that the checksum is the bech32 checksum but I think it's clear from context what's meant. And it captures both that the character set is bech32 vs hex, and that the "codex32 secret" has more data than the bare seed.

Nowhere do we label a result string (bech32). (hex) seems to be used everywhere because it looks more like bech32 than the reverse.

Checksum is 150% too long to be Bech32.

So I have Vector 5 like this:

k value (bech32): 0

identifier (bech32): 0C8V

payload (bech32): M32ZXFGUHPCHTLUPZRY9X8GF2TVDW0S3JN54KHCE6MUA7LQPZYGSFJD6AN074RXVCEMLH8WU3TK925ACDEFGHJKLMNPQRSTUVWXY06F

checksum: HPV80UNDVARHRAK

codex32 secret: MS100C8VSM32ZXFGUHPCHTLUPZRY9X8GF2TVDW0S3JN54KHCE6MUA7LQPZYGSFJD6AN074RXVCEMLH8WU3TK925ACDEFGHJKLMNPQRSTUVWXY06FHPV80UNDVARHRAK

Master seed (hex): dc5423251cb87175ff8110c8531d0952d8d73e1194e95b5f19d6f9df7c01111104c9baecdfea8cccc677fb9ddc8aec5553b86e528bcadfdcc201c17c638c47e9

master node xprv: xprv9s21ZrQH143K4UYT4rP3TZVKKbmRVmfRqTx9mG2xCy2JYipZbkLV8rwvBXsUbEv9KQiUD7oED1Wyi9evZzUn2rqK9skRgPkNaAzyw3YrpJN

Do we need to change Vector 2 as well or are you okay there:

Derived share with index D: MS12NAMEDLL4F8JLH4E5VDVULDLFXU2JHDNLSM97XVENRXEG

Recovered secret seed with index S: MS12NAMES6XQGUZTTXKEQNJSJZV4JV3NZ5K3KWGSPHUH6EVW

Master seed (hex): d1808e096b35b209ca12132b264662a5

Vector 2 seems fine to me.

bip-0093.mediawiki

apoelstra · 2025-12-10T15:45:26Z

Done reviewing aa06616. Looks great, thanks! My comments are all just nits (except the "random errors" thing which I think is important).

…cret reduced the heading level of checksum and error correction to make the table of contents easier to parse. Moved Master seed Encoding to be below Unshared Secret.

BenWestgate · 2025-12-10T19:47:01Z

bip-0093.mediawiki

 If a codex32 string is encoded in a QR code, it SHOULD use the uppercase form, as this is encoded more compactly.

-===Checksum===
+====Checksum====


ToC was getting hard on my eyes with so many H3 so I indented Checksum and Error Correction so there's only 4 H3 in a row afterwards: Unshared Secret, Master seed format, Recover Secret, Generate Shares.

BenWestgate · 2025-12-10T19:48:14Z

bip-0093.mediawiki

+When the human-readable part of a valid codex32 secret (converted to lowercase) is the string "ms", we call it a codex32-encoded master seed or secret seed. The payload in this case is a direct encoding of a BIP-0032 HD master seed.
+
+A secret seed is a codex32 encoding of:
+
+* The human-readable part "ms" for master seed.
+* The data-part values:
+** A threshold parameter, which MUST be a single digit between "2" and "9", or the digit "0".
+** An identifier consisting of 4 bech32 characters.
+*** We do not define how to choose the identifier, beyond noting that it SHOULD be distinct for every master seed and share set the user may need to disambiguate.
+** The share index "s".
+** A conversion of the 16-to-64-byte BIP-0032 HD master seed to bech32:
+*** Start with the bits of the master seed, most significant bit per byte first.
+*** Re-arrange those bits into groups of 5, and pad with arbitrary bits at the end if needed.
+*** Translate those bits to characters using the bech32 character table from BIP-0173.
+** A valid checksum in accordance with the Checksum section.


Checksum was added. Rest is unchanged from it's old location.

BenWestgate · 2025-12-10T19:58:18Z

bip-0093.mediawiki

 ===Test vector 5===

-This example shows generating a new 512-bit master seed using "random" codex32 characters and appending a checksum.
+This example shows generating a new 512-bit master seed using "random" bech32 characters and appending a checksum.


caught this. There's no such thing as "codex32" characters because we use the bech32 character set.

BenWestgate · 2025-12-12T07:11:08Z

bip-0093.mediawiki

+    combined = data + ms32_create_checksum(data)
+    return "ms" + "1" + ''.join([CHARSET[d] for d in combined])
+
+def ms32_decode(codex):


It looks correct to me but I didn't look too carefully at it.

6763349

Fixed a bug and made the validity condition cleaner.

BenWestgate · 2025-12-12T07:18:19Z

bip-0093.mediawiki

+    if pos < 2 or not (48 <= len(codex) <= 127):
        return None
    if not all(x in CHARSET for x in codex[pos+1:]):
        return None
-    hrp = codex[:pos]
-    if not (hrp == "ms" and codex[pos+1].isdigit()) or codex[pos+1] == "0" and codex[pos+6] != "s":


Easier to read without parentheses.

apoelstra · 2025-12-15T13:11:06Z

ACK 6763349

jonatack

Good improvements, with some follow-ups (IIUC, not sure) for a new PR.

jonatack · 2025-12-15T17:18:23Z

bip-0093.mediawiki

+
+def ms32_encode(data):
+    combined = data + ms32_create_checksum(data)
+    return "ms" + "1" + ''.join([CHARSET[d] for d in combined])


Possible follow-up: "ms" is ~defined further below, line 193 and 197, after its use throughout the code -- maybe define it before the code?

True. In the spec definition we say it's always "ms" but not why until the master seed format standard.

If #2040 is cleaned up to avoid making contentious statements about length, BIP93 will be human-readable part agonistic like BIP-0173. And this would renamed def codex32_encode(hrp, data) similar for verify_checksum and create_checksum.

Half the purpose of this PR was to rebase #2040 on it for a simpler diff to review.

murchandamus · 2025-12-15T17:36:15Z

Thanks @BenWestgate, @apoelstra, and @jonatack.

BenWestgate added 2 commits December 9, 2025 20:30

Change master seed to secret in most places, ''t'' to ''k'' and other…

4b6ffb5

… term fixes

Replace deleted linebreak, delete vestigal oxford commas

aa06616

BenWestgate mentioned this pull request Dec 10, 2025

BIP93: correct threshold range #2023

Closed

BenWestgate commented Dec 10, 2025

View reviewed changes

apoelstra reviewed Dec 10, 2025

View reviewed changes

bip-0093.mediawiki Show resolved Hide resolved

apoelstra reviewed Dec 10, 2025

View reviewed changes

bip-0093.mediawiki Outdated Show resolved Hide resolved

apoelstra reviewed Dec 10, 2025

View reviewed changes

bip-0093.mediawiki Outdated Show resolved Hide resolved

apoelstra reviewed Dec 10, 2025

View reviewed changes

bip-0093.mediawiki Outdated Show resolved Hide resolved

BenWestgate mentioned this pull request Dec 10, 2025

Change "secret seed" to "secret". BlockstreamResearch/codex32#72

Open

jonatack added Proposed BIP modification Pending acceptance This BIP modification requires sign-off by the champion of the BIP being modified labels Dec 10, 2025

errors->random errors, fix newlines, vector5: secret seed->codex32 se…

7b83e6f

…cret reduced the heading level of checksum and error correction to make the table of contents easier to parse. Moved Master seed Encoding to be below Unshared Secret.

BenWestgate commented Dec 10, 2025

View reviewed changes

BIP93: change codex32 characters to bech32 characters

d926cc9

BenWestgate commented Dec 10, 2025

View reviewed changes

Fix hrp length off by 1 bug. Refactor validity condition to read easier.

6763349

BenWestgate commented Dec 12, 2025

View reviewed changes

jonatack removed the Pending acceptance This BIP modification requires sign-off by the champion of the BIP being modified label Dec 15, 2025

jonatack reviewed Dec 15, 2025

View reviewed changes

jonatack merged commit 98935ff into bitcoin:master Dec 15, 2025
4 checks passed

jonatack mentioned this pull request Dec 15, 2025

BIP93: Generalize codex32 format for any hrp and fix typos #2040

Open

		It includes an encoding format, a BCH error-correcting checksum, and optional Shamir's secret sharing algorithms for share generation and secret recovery.
		Secret data can be encoded directly, or split into up to 31 shares.

		Note that per BIP-0173, the lowercase form is used when determining a character's value for checksum purposes.
		In particular, given an all uppercase codex32 string, we still use lowercase <code>ms</code> as the human-readable part during checksum construction.

BIP93: terminology, typo, and phrasing fixups #2052

BIP93: terminology, typo, and phrasing fixups #2052

Uh oh!

Conversation

BenWestgate commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BenWestgate left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BenWestgate Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BenWestgate Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BenWestgate Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BenWestgate Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

apoelstra commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BenWestgate commented Dec 10, 2025 •

edited

Loading

BenWestgate left a comment •

edited

Loading

BenWestgate Dec 10, 2025 •

edited

Loading

BenWestgate Dec 10, 2025 •

edited

Loading

BenWestgate Dec 10, 2025 •

edited

Loading

BenWestgate Dec 10, 2025 •

edited

Loading

apoelstra commented Dec 10, 2025 •

edited

Loading

jonatack left a comment •

edited

Loading