From 9424889f2a60409437f79c23de56302016e95947 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Thu, 22 Oct 2026 20:33:07 +0000 Subject: [PATCH] docs: Say what correct can and can't repair A tester called correction a black box: the user guide gave it one paragraph and the limits were only in the developer API guide. List what one string can survive and what it can't, how --bytes narrows the search, and the 13-fill case that the YES prompt guards. Each limit was checked by damaging BIP-93 test vectors and running the correction search one trial at a time, 3 to 4 trials per case. Closes #89 Claude-Session: https://claude.ai/code/session_015CuLXqAvAovfoVcUmmogwa Claude-Session: https://claude.ai/code/session_01Q1TNm1YeYW8K9W2eBvxmCD --- docs/user/guide.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/user/guide.md b/docs/user/guide.md index b875ab04..16ee5ac3 100644 --- a/docs/user/guide.md +++ b/docs/user/guide.md @@ -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; +- 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; +- one or two whole four-character groups missing, extra or swapped, or one + group with every character wrong. + +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