Skip to content

docs: Answer first-time questions in the user guide #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
BenWestgate wants to merge 1 commit into
base: claude/new-issue-fixes-fvhbl3-88
Choose a base branch
from
Draft

docs: Answer first-time questions in the user guide #97

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/user/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,42 @@ 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

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A typo in a hex seed is a total loss. They get a backup that cannot recover their intended master seed. I've asked elsewhere (other PRs) that we might want to take steps to prevent typos here, using an existing codex32 secret has error detection and is much safer to type. A hex seed has none besides being too short too long or a non hex char.

I think remove this sentence since you never type hex seeds anyway to restore a wallet.

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI-assisted triage requested by the maintainer.

Agreed to remove the hex-seed sentence. Hex input lacks checksum protection; a syntactically valid typo can back up a different seed and lose access to the intended funds. New cards can still recover that wrong seed, so the original blanket claim was also misleading. The prepared replacement explains that a valid checksum does not establish wallet identity without suggesting hex entry as a restore step.

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:
Comment on lines +315 to +316

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer before restoring a Bitcoin Core wallet or similar. "changed" feels vague.

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI-assisted triage requested by the maintainer.

Agreed that “Bitcoin Core is changed” is vague. “Before restoring a Bitcoin Core wallet” would still promise a gate that this base lacks. The prepared answer instead says when to compare the displayed fingerprint after restoration. Once the pre-import gate tracked by #26/#91 is present, describe its actual behavior before restoration.

codex32 shows the fingerprint with a warning and asks before restoring.
Comment on lines +315 to +317

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Describe the fingerprint checks restore actually performs

When restoring with ms32 wallet, there is no prompt for the recorded fingerprint or missing-record warning: _bitcoin_core() in src/codex32/cli.py passes the recovered seed directly to _initialize_wallet(), and BitcoinCore.initialize() selects the destination wallet and imports the key without comparing a supplied fingerprint. The fingerprint is printed afterward. This FAQ therefore promises a safety check that does not exist, potentially leading users restoring the wrong backup to rely on automatic verification instead of checking the record themselves. Describe the current manual verification procedure, or implement the promised check before documenting it.

Useful? React with 👍 / 👎.

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI-assisted triage requested by the maintainer. The maintainer previously directed this task to follow the merged tool-neutral AI policy; this topic stack carries an older policy.

Confirmed on 3260b44: _bitcoin_core() calls _initialize_wallet(), which imports before printing the fingerprint. There is no typed-record or no-record gate on this base. This blocks the FAQ as written. A documentation-only replacement is prepared describing manual post-restore comparison and the missing-record stop condition. The required pre-import gate remains tracked by #26/#91. This is triage, not an ACK of the current wording.


**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 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).
Comment thread
BenWestgate marked this conversation as resolved.
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
choose specific ones. Shared creation never shows `S`, the secret itself.
Comment on lines +328 to +329

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with allowing 'S' to be passed via --indices if someone wants a backup that includes the shared secret and shares. create 0 shows the secret after all. We may want to use some RED somewhere warning that it's the secret or maybe not, i've seen good arguments either way so I don't care, no difference would be less code but it is important if they do pass S that they know this is the SECRET and CAN SPEND with this card ALONE, security review this and decide what to do about showing and confirming "S" and any necessary safe guards.

This is a separate issue so open an issue about it. And it's probably not v1 urgent so it may not need a closing PR unless you think it does before v1

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--indices also should allow duplicates, in which case the user writes and confirms the share indices in the order they gave them, except the duplicates are moved to the end to maximize the spaced repetition and minimize the chance the user has them in their mental memory (or confirms off the already written card and not a new card.

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ex: `--indices aaacccxxxddd would have them acxdacxdacxd. Unique initial indices are required anyway for the basis generation.

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI-assisted triage requested by the maintainer.

Tracked explicit S and repeated secret cards in #173; #87 remains the repeated-index tracker. The issue records aaacccxxxddd → acxdacxdacxd, copies of the same confirmed artifact, distinct basis indices, and explicit understanding that S can spend alone. Proposed post-v1: current rejection fails closed, so this enhancement need not block truthful FAQ wording. Security review is required before enabling it; no implementation/security ACK is claimed here.

`ms32 create` with no threshold writes one unshared secret card, and

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with --indices they should be able to confirm multiple unshared secret cards, each containing the exact same data. It's good to make more than one backup, so the guide should mention this somewhere, although unshared secrets are not a primary value proposition of codex32 so it's more intermediate or advanced use.

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI-assisted triage requested by the maintainer.

Included in #173: explicit repeated S output should confirm multiple cards with exactly the same secret and header. The guide already says redundant unshared copies are possible and each copy can recover the seed. Document the --indices workflow after implementation; on this head the threshold-0 path does not use those indices.

`ms32 secret` rebuilds the secret from shares. Each run without `--existing`
makes a new seed. Shared backups use a random identifier unless you specify

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

have we said by now the entropy comes from Bitcoin Core?

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI-assisted triage requested by the maintainer.

Not on this base. generation.py uses Python secrets.token_bytes() for fresh seed/share randomness; connecting to Core does not mean Core supplies it. #145 adds the Core+OS entropy source and is still open. Keep that explanation with #145 and update the guide when it lands, rather than claim Core entropy here now.

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
invalid. Either case gives the same seed and fingerprint.
Comment on lines +337 to +338

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:
either all...

mixed case is invalid

if you agree

@BenWestgate BenWestgate Oct 24, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI-assisted triage requested by the maintainer.

Agreed. Prepared wording: “A codex32 string must be either all uppercase or all lowercase. Mixed case is invalid. Either case gives the same seed and fingerprint.”


## Technical references

Automation, low-level private exports, parser behavior, correction mathematics,
Expand Down
Loading