Skip to content

docs: Rework the recovery cards #88

Open

Description

@BenWestgate

docs/user/recovery-card.html has 32 blank four-character boxes, four per row, which is enough for the 127-character long form. Most backups are 48 characters (12 groups), and the codex32 book only has worksheets for that length.

  • Make the standard card exactly 12 groups, for 128-bit seeds and shares.
  • Add a second template for 256-bit seeds and shares: 74 characters, 19 groups.
  • Each card fits a single length, so neither needs a length field.
  • Consider a landscape layout so all 12 groups fit on one line. The first entry prompt doesn't know the length yet and accepts one long line, so a one-line card matches how the first string is typed.
  • For grouping, the preferred layout is the CLI's: blocks of four groups with a wider gap between blocks. Weigh it against the alternatives in the PR.
  • Optional: number the boxes with tiny, light numbers in the upper corner, like the checksum worksheets on secretcodex32.com.

Whether the rarer lengths (54, 61, 67 and 127 characters) need a card is still open. #72 covers the GUI's written-card view, not the printed card.

Tester feedback (2026-10-08)

A tester sent card mockups through Ben.

  • Number every character, 1–48, like the codex32 booklet. One box per character, two blocks of four per row. The numbers let someone who is interrupted find their place again, so make them required, not optional. A 74-character card numbers 1–74. If the boxes stay four characters wide, as in docs: Size recovery cards to the backup length #96, label them 1–4, 5–8 and so on, not by group.
  • Pre-print MS1 in boxes 1–3.
  • Shade alternate rows so the eye keeps its row.
  • Ben is prototyping 8-character rows in landscape, with the instructions in a second column, so 48 or 74 large characters fit on one page. Settle the layout in docs: Size recovery cards to the backup length #96.
  • Offline recovery steps. Step 2 is too technical. Say to keep copies of Bitcoin Core, python-codex32 and Tails with the backup, and to check that the computer is disconnected. Step 4 implies Bitcoin Core has a codex32 recovery flow, but it doesn't. Name ms32 wallet instead.
  • Fingerprint field. The mockups add a master fingerprint field. Share cards still leave it off (docs: Answer first-time questions in the user guide #90). Settle it in the cards' security design review before docs: Size recovery cards to the backup length #96 merges. Draft tradeoffs:
    • Someone with k−1 shares and part of the last share still has to search every candidate. The fingerprint only spares them a few address checks per candidate.
    • It does confirm a seed for an unfunded wallet, and it links a card to the wallet's descriptors and PSBTs.
    • On an unshared S card it costs nothing, because whoever holds the card can compute it.

Activity

  1. changed the title [-]docs: Size recovery cards to the backup length[/-] [+]docs: Rework the recovery cards[/+] on Oct 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions