Skip to content

docs: Say what correct can and can't repair #102

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

Open
BenWestgate wants to merge 1 commit into
base: reviewability-v1
Choose a base branch
from
+33 −0
Open

docs: Say what correct can and can't repair #102

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
33 changes: 33 additions & 0 deletions docs/user/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,6 +279,39 @@ follow Bitcoin Core v32's maintained
confirmed.” `--plain` skips card confirmation. Redirected damaged input can
still require an interactive correction confirmation.

### What `correct` can repair

`correct` repairs one string at a time. Type each unreadable character as `?`.
It can fix:

- up to 8 unreadable characters or up to 4 wrong ones. One wrong character
uses up the room of two unreadable ones, so 6 unreadable and 1 wrong, or 4
unreadable and 2 wrong, also work;
- 13 unreadable characters in a row, or 15 in a long codex32 string (127
characters);
- up to 4 missing characters, up to 4 extra ones, or one of each;
Comment thread
BenWestgate marked this conversation as resolved.
- one swap of two characters anywhere in the string along with up to 2 wrong
ones, or up to 3 swaps of neighboring characters;
- one missing, extra or swapped character along with up to 3 wrong ones;
Comment thread
BenWestgate marked this conversation as resolved.
- one or two whole four-character groups missing, extra or swapped, or one
group with every character wrong.
Comment on lines +296 to +297

@BenWestgate BenWestgate Oct 22, 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.

wasn't it:
one or two whole four-character groups, missing, extra, wrong or swapped?

the one group wrong seems wrong since we can correct 8 arbitrary erasures which is how these are solved.

@BenWestgate BenWestgate Oct 22, 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.

Missing, extra and swapped groups all work for two groups. Wrong groups only work for one, because the search never treats a whole group as unreadable. A wrong character counts as an error at an unknown position, and the checksum can locate about 4 of those. One fully wrong group is 4 errors, which is fixed. Two fully wrong groups are 8, which timed out in every trial. The 8-erasure capacity only applies if the user marks those characters as ?. So 0bf2587 adds: "If you know which groups are wrong, type their characters as ?: two groups are then 8 unreadable characters, which it can fix."

The search could also try each pair of groups as erasures. With 10 groups that is 45 cases of an 8-erasure fill, which is cheap, but it changes correction, so it would be a separate follow-up.

Generated by Claude Code

@BenWestgate BenWestgate Oct 22, 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.

"the search never treats a whole group as unreadable" it is supposed to and it used to correct any two groups where every character or more than most were errors provided there were no other errors in the string.

@BenWestgate BenWestgate Oct 22, 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.

The search could also try each pair of groups as erasures. With 10 groups that is 45 cases of an 8-erasure fill, which is cheap, but it changes correction, so it would be a separate follow-up.

The search absolutely used to do this and it still should since it's cheap and useful to try any 2 groups as 4 erasures each. I want that reverted or back in before v1, while this user document can be deferred.


It can't fix 9 or more scattered unreadable characters, 5 or more missing
characters outside whole missing groups, more than 13 unreadable characters in a
row (15 in a long codex32 string), or two groups that are both wrong. If you
know which groups are wrong, type their characters as `?`: two groups are then 8
unreadable characters, which it can fix. Some repairs take the full ten seconds,
so a slower computer may not finish them, and past this list the search rarely
succeeds.

If whole groups are missing, give the seed's size with `--bytes`, such as
`--bytes 32` for a 74-character string. Specifying the size narrows the search
and can let repairs finish before the deadline.

Filling 13 unreadable characters in a row (15 in a long codex32 string) always
produces a valid string, but if any other character was mistyped, that string is
wrong. This is why `correct` asks you to type `YES` before showing it.

### Advanced: completing missing trailing characters

The correction command can fill trailing erasures when the final characters
Expand Down
Loading