BIP93: Refactor format and seed sections

[BenWestgate]

Motivation: the Specification should move from most general to specific cases.

Group the regular and long checksum definitions together in the codex32 format section. Move Master seed format application to after of the codex32 format specification and keep seed-specific checksum motivation in the rationale.

Deduplicate repeated explanations and redundant inline encoding/decoding helpers: 9621d3f

This is a behavior-neutral organization change on top of #2258, progressing from codex32 format → optional secret sharing → master seed encoding.

This PR retains the required ms HRP,

There is also:

• a bits vs bytes consistency fixup: 12a61ee,
• a retrospective changelog history: 54e0233, and lastly
• TOC simplification and casing fixup: 1589133

Discussion:
bits vs bytes
https://github.com/bitcoin/bips/pull/2258/changes#r3894597745
https://github.com/bitcoin/bips/pull/2258/changes#r3894609812
https://github.com/bitcoin/bips/pull/2258/changes#r3894685643
Optional: a changelog.
#2258 (comment)

A cautionary warning to not convert bytes to shares.
#2258 (comment)

Rationale

====Long Checksum==== seems like it belongs in ===codex32=== with bold, like it is in BIP173 and BIP350.

We first describe the general checksummed base32 format called codex32 and then define a secret sharing scheme and BIP-0032 master seed encoding using it.

The final part of ==Specification== should be ===Master seed format===.

I'm undecided if every application must use the codex32 header, I think they can be free to choose and they may use it even if they do not support SSS, like CL1 rejected threshold != 0 invalidating shared secrets even if another application did the secret recovery.

It's most flexible and Bech32-like to not require it. OTOH, every application has used it thus far so making codex32_decode(hrp, data) continue to require:

    if codex[pos+1].isalpha() or codex[pos+1] == "0" and codex[pos+6] != "s":
        return None

improves the certainty damaged base32 data is codex32. If saving 6 characters were top priority, they'd Bech32-encode anyhow.

Nevertheless, ===SSSS-awareness=== feels like it belongs as the only === section between ===codex32=== and ===Master seed format===. That way it can be skipped over by readers who do not need sharing.

Future work

Generalized HRPs, optional headers, new helper APIs, and bytes-to-shares guidance/warning remain deferred.

[BenWestgate]

eb7bb6c 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

[apoelstra]

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!

[apoelstra]

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 eb7bb6c looks good to me. This PR has no functional changes and is easy to review.

[BenWestgate]

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 BenWestgate@98935ff 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.

[apoelstra]

Should I add a de-duplication commit here?

Yeah, I think that's a good idea.

Did you ACK this TOC?

Yep.

[BenWestgate]

I preserved reviewed commit eb7bb6c and appended four commits. I saw BIP-0380 did put Checksum in the TOC and since our Error Correction is not an after thought or warning like BIP-0173 decided both Checksum and Error Correct deserved a seat in the TOC. I put regular and long checksums as bold headings inside Checksum section.

• 9621d3f: deduplication, including replacing the run-on validity sentence with a master-seed cross-reference.
• 1589133: section organization and heading cleanup.
• 12a61ee: seed-size units as requested by @roconnor.
• 54e0233: revision history changelog.
• Bytes-to-shares warning deferred as requested.

[baslabofhd777-lab]

مرحبًا

[BenWestgate]

I added one more 1978ac2 after re-reviewing the stacked changes.

When I first tried to implement BIP93 it took me a moment because ms32_interpolate was described as taking "codex32 shares/strings" but it really needs u5 data parts I clarified that.

I also missed that when Generate and Recover were swapped, the definition of how to use the function was missing from it's first reference, so I put the functions in the ===SSSS-Awareness=== introduction. Maybe that title is better as ===Secret Sharing Scheme=== but not worth another commit.

Hopefully this is still easy to review, the Changelog and bits/bytes commits are tiny and this final one is small also.

I recommend reviewers view each individual commit, the whole stacked diff is hard to follow due to the movement of many blocks.

File looks great on my last proof-read. Ready for review and rereview at 1978ac2.