BIP93: correct threshold range

Lil-Duckling-22 commented at 11:50 am on October 29, 2025: none

Update Abstract to align with specification: threshold can be 0 for unshared secret or 2-9 for shares.

Apparently previous “between 1 and 9” range appears inconsistent with the detailed spec (threshold=1 isn’t valid in codex32).

Update bip-0093.mediawiki 91bbe04242

jonatack renamed this:
~~fix: correct threshold range in Abstract section~~
BIP93: correct threshold range
on Oct 29, 2025

in bip-0093.mediawiki:23 in 91bbe04242

19@@ -20,7 +20,7 @@ This document describes a standard for backing up and restoring the master seed
20 [https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki BIP-0032] hierarchical deterministic wallet, using Shamir's secret sharing.
21 It includes an encoding format, a BCH error-correcting checksum, and algorithms for share generation and secret recovery.
22 Secret data can be split into up to 31 shares.
23-A minimum threshold of shares, which can be between 1 and 9, is needed to recover the secret, whereas without sufficient shares, no information about the secret is recoverable.
24+A minimum threshold of shares, which can be 0 (for unshared secret) or between 2 and 9 (for shares), is needed to recover the secret, whereas without sufficient shares, no information about the secret is recoverable.

jonatack commented at 7:59 pm on November 4, 2025:

Not sure about this change.

The current abstract states “between 1 and 9” for what “is needed to recover the secret”.

And the Recovering Master Seed section stipulates: “The first character of the data part indicates the threshold of the share, and it is required to be a non-“0” digit.”

So these two excerpts seem to concur? Perhaps it could be clearer.

cc @apoelstra for feedback

BenWestgate commented at 12:37 pm on November 6, 2025:

It’s correct as it is.

Threshold is a value 1 through 9 and refers to the number of strings needed to recover the seed.

k is the literal first numeric character of the bech32 data so it cannot be “1” even if the threshold is 1. “0” is recommended for unshared secrets (threshold 1) although any numeric value is allowed as it is ignored when share_idx = "s".

Whether it is clear or not is another matter. You’d have to read the body to know these details so I think the abstract is fine. There may be some conflation of “threshold” with “threshold digit” which is called k in the codex book and many reference implementations, which is what lead you to opening this PR.

jonatack added the label Proposed BIP modification on Nov 4, 2025

jonatack added the label Pending acceptance on Nov 4, 2025

BenWestgate commented at 12:48 pm on November 6, 2025: none

They call the threshold parameter k in the codex book but used t or threshold in this BIP.

I can see how this might be confusing.

jonatack added the label PR Author action required on Nov 6, 2025

Update bip-0093.mediawiki affbe854f3

Lil-Duckling-22 requested review from BenWestgate on Nov 6, 2025

Lil-Duckling-22 commented at 7:42 pm on November 6, 2025: none

Thanks for the review and giving a justified correction!

Is this closer to what you suggested?

in bip-0093.mediawiki:70 in affbe854f3

66@@ -67,8 +67,8 @@ It reuses the base-32 character set from BIP-0173, and consists of:
67 * A human-readable part, which is the string "ms" (or "MS").
68 * A separator, which is always "1".
69 * A data part which is in turn subdivided into:
70-** A threshold parameter, which MUST be a single digit between "2" and "9", or the digit "0".
71-*** If the threshold parameter is "0" then the share index, defined below, MUST have a value of "s" (or "S").
72+** A threshold digit (also called ''k'' in the codex book), which MUST be a single digit between "2" and "9", or the digit "0". This digit encodes the threshold (the number of shares required for recovery), where threshold 1 is encoded as "0" for unshared secrets, and thresholds 2-9 are encoded as digits "2"-"9" for shared secrets.

BenWestgate commented at 8:05 pm on November 6, 2025:

I don’t know if we need to mention what the digit is called in the Codex32 book.

This digit does not always directly encode the threshold number of strings required for recovery.

Threshold 1 is denoted by share index “s” NOT the first data character being “0”. “0” is merely a recommendation, and if used, forces the share index to “s”.

Lil-Duckling-22 commented at 4:49 am on November 14, 2025:

Resolved

in bip-0093.mediawiki:71 in affbe854f3 outdated

66@@ -67,8 +67,8 @@ It reuses the base-32 character set from BIP-0173, and consists of:
67 * A human-readable part, which is the string "ms" (or "MS").
68 * A separator, which is always "1".
69 * A data part which is in turn subdivided into:
70-** A threshold parameter, which MUST be a single digit between "2" and "9", or the digit "0".
71-*** If the threshold parameter is "0" then the share index, defined below, MUST have a value of "s" (or "S").
72+** A threshold digit (also called ''k'' in the codex book), which MUST be a single digit between "2" and "9", or the digit "0". This digit encodes the threshold (the number of shares required for recovery), where threshold 1 is encoded as "0" for unshared secrets, and thresholds 2-9 are encoded as digits "2"-"9" for shared secrets.
73+*** If the threshold digit is "0" then the share index, defined below, MUST have a value of "s" (or "S").

BenWestgate commented at 8:08 pm on November 6, 2025:

Digit vs parameter is probably bikeshedding

apoelstra commented at 6:48 pm on November 14, 2025:

Agreed. And I don’t think “digit” is the right term for a bech32 character anyway.

in bip-0093.mediawiki:149 in affbe854f3

145@@ -146,14 +146,14 @@ The master seed is decoded by converting the payload to bytes:
146 
147 Note that unlike the decoding process in BIP-0173, we do NOT require that the incomplete group be all zeros.
148 
149-For an unshared secret, the threshold parameter (the first character of the data part) is ignored (beyond the fact it must be a digit for the codex32 string to be valid).
150-We recommend using the digit "0" for the threshold parameter in this case.
151+For an unshared secret, the threshold digit (the first character of the data part, also called ''k'') is ignored (beyond the fact it must be a digit for the codex32 string to be valid).

BenWestgate commented at 8:11 pm on November 6, 2025:

Even if @apoelstra believes BIP93 should clarify the Codex32 book uses a different term k for the threshold parameter. We definitely should not keep repeating both nomenclatures.

in bip-0093.mediawiki:150 in affbe854f3

145@@ -146,14 +146,14 @@ The master seed is decoded by converting the payload to bytes:
146 
147 Note that unlike the decoding process in BIP-0173, we do NOT require that the incomplete group be all zeros.
148 
149-For an unshared secret, the threshold parameter (the first character of the data part) is ignored (beyond the fact it must be a digit for the codex32 string to be valid).
150-We recommend using the digit "0" for the threshold parameter in this case.
151+For an unshared secret, the threshold digit (the first character of the data part, also called ''k'') is ignored (beyond the fact it must be a digit for the codex32 string to be valid).
152+We recommend using the digit "0" for the threshold digit in this case, which encodes a threshold of 1 (no sharing).

BenWestgate commented at 8:15 pm on November 6, 2025:

Technically share index “s” denotes a threshold 1unshared secret as the threshold parameter is ignored in this case and it should stay that way for interoperability.

in bip-0093.mediawiki:156 in affbe854f3 outdated

153 The 4 character identifier also has no effect beyond aiding users in distinguishing between multiple different master seeds in cases where they have more than one.
154 
155 ===Recovering Master Seed===
156 
157 When the share index of a valid codex32 string (converted to lowercase) is not the letter "s", we call the string an codex32 share.
158-The first character of the data part indicates the threshold of the share, and it is required to be a non-"0" digit.

BenWestgate commented at 8:19 pm on November 6, 2025:

This line is correct. Read the line above: when the share index is not “s”. The threshold parameter cannot be “0” in that case, so we know that for a codex32 share, the threshold parameter is required to be 2-9.

murchandamus commented at 4:30 pm on November 10, 2025: contributor

It sounds like it is contested that this is an improvement, even if there may be some need for clarification here. Please update the PR and mark any review comments as resolved as you address them.

Update bip-0093.mediawiki 3ee54134bd

apoelstra commented at 6:50 pm on November 14, 2025: contributor

Please remove the digit vs parameter changes, or at least move them to their own commit so they are easy to ignore. I agree with your PR summary, that “between 1 and 9” is wrong, but I can’t find the text “between 1 and 9” anywhere in the document or in your diff. This feels to me like LLM slop. At the very least I cannot review this PR in this state.

murchandamus commented at 11:14 pm on November 14, 2025: contributor

@apoelstra: The last sentence of the Abstract of the currently published version of BIP 93 reads:

A minimum threshold of shares, which can be between 1 and 9, is needed to recover the secret, whereas without sufficient shares, no information about the secret is recoverable. @Lil-Duckling-22: Please incorporate the requested changes.

Update bip-0093.mediawiki f3ba8174a9

BenWestgate commented at 11:33 am on November 16, 2025: none

Apparently previous “A minimum threshold of shares, which can be between 1 and 9, is needed to recover the secret” range appears inconsistent with the detailed spec (threshold=1 isn’t valid in codex32).

One string with share index “s” can recover the secret but it is the secret. Further the term “threshold” (not “threshold parameter”) always refers to shares:

The relevant definitions proving this text is wrong:

secrets:

Note that a share index value of “s” (or “S”) is special and denotes the unshared secret (see section “Unshared Secret”). When the share index of a valid codex32 string (converted to lowercase) is the letter “s”, we call the string a codex32 secret. For an unshared secret, the threshold parameter (the first character of the data part) is ignored (beyond the fact it must be a digit for the codex32 string to be valid).

shares:

When the share index of a valid codex32 string (converted to lowercase) is not the letter “s”, we call the string an codex32 share. The first character of the data part indicates the threshold of the share, and it is required to be a non-“0” digit.

recover:

In order to recover a master seed, one needs a set of valid codex32 shares such that:

All shares have the same threshold value, the same identifier, and the same length. @apoelstra: Based on these details, the correct abstract text would be:

Secret data can be directly encoded 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.

Further our test vectors use the oxymoron term “secret share” it should probably be replaced with “codex32 secret”:

Derived share with index D: MS12NAMEDLL4F8JLH4E5VDVULDLFXU2JHDNLSM97XVENRXEG

Secret share with index S: MS12NAMES6XQGUZTTXKEQNJSJZV4JV3NZ5K3KWGSPHUH6EVW

Recovered secret with share index S:
Recovered codex32 secret:

Secret share with index s: ms13cashsllhdmn9m42vcsamx24zrxgs3qqjzqud4m0d6nln

Secret with share index s: codex32 secret: codex32 secret with k value 3:

Note that the choice to append two zero bits was arbitrary, and any of the following four secret shares would have been valid choices.

copy the choice above (minus any “with”)

Secret share with index S: MS100C8VSM32ZXFGUHPCHTLUPZRY9X8GF2TVDW0S3JN54KHCE6MUA7LQPZYGSFJD6AN074RXVCEMLH8WU3TK925ACDEFGHJKLMNPQRSTUVWXY06FHPV80UNDVARHRAK

*Secret with share index S: *codex32 secret:

Vector 5 even has the recommended secret threshold parameter "0". I’m not sure what was going on here, t becomes k in this part of the spec, without ever introducing k although it’s standard SSS term and doesn’t need introduction. Why did it change for no reason? It seems the vector texts were for an earlier draft of the spec. Perhaps ones where uppercase and non-zero threshold parameter codex32 strings were not called codex32 secrets even with share index “S” or “s”.

If you want my opinion, BIP93 should use k everywhere as that’s what your book uses (and the wikipedia article on SSS). It also looks less like other lowercase characters. But that’s a bigger diff than just changing the test vector k’s.

BIP93: correct threshold range #2023