Protocol V2 and Word Lists#26
Merged
Merged
Conversation
eljojo
force-pushed
the
protocol-v2
branch
4 times, most recently
from
fec61d5 to
25d1340
Compare
Encode each share as 25 human-readable words using the BIP39 English word list. The first 24 words encode the share data (33 bytes), and the 25th word encodes the share index — so recovering via words requires no extra input from the user. Words appear in README.txt, PDF, and can be typed or pasted directly into the recovery tool's paste area. The paste area auto-detects all formats: PEM blocks, compact strings, plain word lists, and numbered two-column grids.
This was referenced Feb 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fix #23. also fix #5.
The PDF now contains a list of 25 words that can be input in the paste box.
The goal is to make it possible for someone to share their key over the telephone.
Details
Golden tests
This commit adds deterministic test fixtures for the v1 share format. Shares, PEM files, compact encoding, and encrypted manifest are generated once and verified on every test run. Covers parsing, re-encoding, combining all valid subsets, and full decrypt-and-extract. This is to ensure backwards compatibility with V1 bundles.
Protocol V2
v1 shares contain the base64 string directly (44 bytes → 45-byte shares). v2 shares contain raw bytes (32 bytes → 33-byte shares); we use base64url-encode on the raw bytes to get the age passphrase.
We use the last byte to store the index of the share and a checksum.
BIP39 word encoding
Uses the standard BIP39 English word list (2048 words, 11 bits each).
24 words to store the share, 25th word stores metadata.
The 25th word encodes the share index, so the recovery tool can identify shares without asking the user for a number. The first 4 bits are used for an index, the last 7 are used for the checksum (to catch typing the wrong word). The first 15 shares have a nicer UX, after 15 shares the index doesn't fit in the 4 bits, so the UI can't mark the checkbox that shows the share has been imported, but the process still works.
The paste area auto-detects all input formats: PEM blocks, compact strings, plain word lists, and numbered two-column grids copied from the PDF/README.
Note for recoveries done using only word lists and the generic recover.html (hosted on github pages): for this to work, it's important to write down the total number of shares required as well as the threshold it was configured with. These values are included in the PDF. The app has a button to try bruteforcing these values, but it's better to write them down initially. This is not necessary when using the share either in full PEM format or short format or QR. this is also not a problem with the bundled recover.html
SHA-256 signatures are used to verify the BIP39 list of words is correct against https://github.com/bitcoin/bips/blob/ed7af6ae7e80c90bcfc69b3936073505e2fc2503/bip-0039/english.txt