From 0fa4d9d56eb72176e4cf4079ecb820705c3c70a9 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 1 Oct 2026 05:01:04 +0000 Subject: [PATCH 1/4] docs: Answer first-time questions in the user guide A tester asked why the fingerprint stays off the cards, why restore asks for it, how long a string is, which share indices create uses, and whether letter case matters. Answer each in a short section. The restore answer describes the typed-fingerprint step from #57, so this sits on that branch. Closes #90 Claude-Session: https://claude.ai/code/session_015CuLXqAvAovfoVcUmmogwa --- docs/user/guide.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/user/guide.md b/docs/user/guide.md index 332d77a..c39bcd7 100644 --- a/docs/user/guide.md +++ b/docs/user/guide.md @@ -314,6 +314,37 @@ Maximize the terminal and reduce its font size if a QR does not fit. Keep `qr` connected to the terminal; redirecting its output creates an image file. Only public descriptors, xpubs, and PSBTs may cross the offline boundary by QR. +## Common questions + +**Why is the master fingerprint on the wallet record and not on the cards?** +On a card, it would let anyone holding one card fewer than the threshold test +guesses for the seed. Without it, those cards reveal nothing about the seed. +Shared cards use a random identifier for the same reason. A record stored apart +from the cards is also an independent check when you restore. + +**Why does restore ask me to type the fingerprint?** +A mistaken correction, a card from another backup, or a typo in a hex seed each +produce a valid wallet that your cards can't recover. Typing the fingerprint +from the record makes codex32 compare all eight characters before Bitcoin Core +is changed, and that needs the record in hand. With no record, press Enter: +codex32 shows the fingerprint with a warning and asks before restoring. + +**How do I know how long a string is while typing it?** +Neither `ms1` nor the header says. A Bitcoin master seed is 48, 54, 61, 67, 74 +or 127 characters. Most are 48, which is 12 groups of four; 256-bit seeds are +74, which is 19 groups with two characters in the last. The first string you +enter sets the length for the rest. + +**Which share indices do I get, and what is `S`?** +`ms32 create 2` and the other thresholds write shares at random indices and +never show `S`, the secret itself. `ms32 create` with no threshold writes one +unshared secret card, and `ms32 secret` rebuilds the secret from shares. Each +run without `--existing` makes a new seed and identifier. + +**Does letter case matter?** +A codex32 string is all uppercase or all lowercase, and mixing them makes it +invalid. Either case gives the same seed and fingerprint. + ## Technical references Automation, low-level private exports, parser behavior, correction mathematics, From bdd4a2bab38d807d6910bdcb61394b2b3e16f4e0 Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Thu, 1 Oct 2026 01:42:42 -0500 Subject: [PATCH 2/4] docs: Qualify share and identifier defaults The FAQ treated random indices and identifiers as unconditional even though the CLI accepts chosen share indices and an explicit set identifier. State the default behavior and the available choices accurately. Refs #90. --- docs/user/guide.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/user/guide.md b/docs/user/guide.md index c39bcd7..c01984c 100644 --- a/docs/user/guide.md +++ b/docs/user/guide.md @@ -336,10 +336,11 @@ or 127 characters. Most are 48, which is 12 groups of four; 256-bit seeds are enter sets the length for the rest. **Which share indices do I get, and what is `S`?** -`ms32 create 2` and the other thresholds write shares at random indices and -never show `S`, the secret itself. `ms32 create` with no threshold writes one -unshared secret card, and `ms32 secret` rebuilds the secret from shares. Each -run without `--existing` makes a new seed and identifier. +`ms32 create 2` chooses random share indices by default; use `--indices` to +choose specific ones. Shared creation never shows `S`, the secret itself. +`ms32 create` with no threshold writes one unshared secret card, and +`ms32 secret` rebuilds the secret from shares. Each run without `--existing` +makes a new seed; its identifier is random unless you specify one. **Does letter case matter?** A codex32 string is all uppercase or all lowercase, and mixing them makes it From aafb7167dbd945d3ea7d607dd3e6a1877483485e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 3 Oct 2026 15:41:21 +0000 Subject: [PATCH 3/4] docs: Link the recovery cards from the length answer The 48-character answer points to the standard card and the 74-character answer to the 256-bit card from #96. The other lengths have no card yet. Claude-Session: https://claude.ai/code/session_015CuLXqAvAovfoVcUmmogwa --- docs/user/guide.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/user/guide.md b/docs/user/guide.md index c01984c..404b6ba 100644 --- a/docs/user/guide.md +++ b/docs/user/guide.md @@ -331,9 +331,11 @@ codex32 shows the fingerprint with a warning and asks before restoring. **How do I know how long a string is while typing it?** Neither `ms1` nor the header says. A Bitcoin master seed is 48, 54, 61, 67, 74 -or 127 characters. Most are 48, which is 12 groups of four; 256-bit seeds are -74, which is 19 groups with two characters in the last. The first string you -enter sets the length for the rest. +or 127 characters. Most are 48, which is 12 groups of four and fits the +[standard card](recovery-card.html). 256-bit seeds are 74, which is 19 groups +with two characters in the last and fits the [256-bit card](recovery-card-256.html). +54, 61, 67 and 127-character backups have no printable card yet. The first +string you enter sets the length for the rest. **Which share indices do I get, and what is `S`?** `ms32 create 2` chooses random share indices by default; use `--indices` to From 1cf1a17793652ced53a7e5416ccb29d506782d60 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Sun, 4 Oct 2026 17:59:58 -0500 Subject: [PATCH 4/4] docs: Correct backup identifier defaults Distinguish random shared-backup identifiers from the fingerprint-derived unshared default. Include the exact reviewed 256-bit recovery card from PR #96 so the new FAQ link resolves on this branch as well as the final integration. Address the two current PR #97 review findings. The card blob is identical to the independently print-previewed PR #96 artifact, and git diff --check passes. AI-assisted follow-up requested by the maintainer; refs #90. --- docs/user/guide.md | 4 +- docs/user/recovery-card-256.html | 72 ++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 docs/user/recovery-card-256.html diff --git a/docs/user/guide.md b/docs/user/guide.md index 404b6ba..320ef98 100644 --- a/docs/user/guide.md +++ b/docs/user/guide.md @@ -342,7 +342,9 @@ string you enter sets the length for the rest. choose specific ones. Shared creation never shows `S`, the secret itself. `ms32 create` with no threshold writes one unshared secret card, and `ms32 secret` rebuilds the secret from shares. Each run without `--existing` -makes a new seed; its identifier is random unless you specify one. +makes a new seed. Shared backups use a random identifier unless you specify +one. For an unshared backup, the default identifier comes from the first 20 +bits of the BIP32 master fingerprint. **Does letter case matter?** A codex32 string is all uppercase or all lowercase, and mixing them makes it diff --git a/docs/user/recovery-card-256.html b/docs/user/recovery-card-256.html new file mode 100644 index 0000000..5b73eee --- /dev/null +++ b/docs/user/recovery-card-256.html @@ -0,0 +1,72 @@ + + + + + codex32 recovery card: 74 characters + + + +

codex32 recovery card: 74 characters (256-bit)

+

+ PROTECTED RECOVERY MATERIAL — keep offline. Do not photograph, upload, or enter this + text into a website, chat, or network-connected device. +

+ +

Backup details

+
+
Threshold (shares needed):
+
Four-character identifier:
+
This share index:
+
Wallet policy: single-key / multisig / other:
+
Separate wallet record location(s):
+
+ +

Protected codex32 text — copy exactly, four characters per box

+
+ + + + + +
+

The last box holds two characters. For 128-bit seeds and shares (48 characters), + use the standard card.

+ +

Offline recovery

+
    +
  1. Collect the stated threshold of cards with the same identifier and text length.
    2. +
  2. On a reviewed offline computer, install the owner’s archived codex32 release.
    3. +
  3. Run codex32 check. It validates but does not suggest corrections.
    4. +
  4. Restore the wallet using its documented Bitcoin Core recovery workflow.
    5. +
  5. Use the separate wallet record to verify the restored wallet before signing.
    6. +
+ +

Manual fallback

+

+ Keep a versioned offline copy of the Codex32 Book Recovery Wheel and Translation + Worksheet, file 2023-03-07--bw.pdf, with the owner’s recovery kit. + Expected SHA-256: 0370ea863d2eae692408aeefa9b13c14283e520f45a00f7373ad933ccf418f2e. + Follow that archived document if compatible software is unavailable. +

+

Card revision 2 — BIP93/codex32 — one card per share or secret.

+ +