BIP93: Refactor format and seed sections #2285

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, gives the encoding and decoding helpers their own heading after the checksums, makes the seed-size units consistent, and adds a retrospective changelog and Version: 0.2.1 preamble field.

Behavior neutral changes only. The inline Python is unchanged apart from where it sits.

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

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!

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.

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.

Should I add a de-duplication commit here?

Yeah, I think that's a good idea.

Did you ACK this TOC?

Yep.

مرحبًا

@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.

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

@apoelstra I force-pushed. eb7bb6c is unchanged and the follow-ups are now four commits:

• 732b0bf: deduplicate specification +16/-33
• 1af7a01: reorganize sections and headings
• 89b1630: clarify seed-size units +3/-3
• ecbed1c: add revision history and version +21

The Python, behavior and vectors are identical to master.