[Research] Script to randomly test SeedQR resiliency against different transcription errors

[kdmukai]

see: https://x.com/KeithMukai/status/2021947006193901939

A few key questions are worth getting answers to:

• SeedQRs use the "L" QR code error correction level. How many blocks can be incorrectly transcribed but still result in a readable SeedQR?
• Does it differ for Compact SeedQR vs Standard SeedQR?
• Is there a difference between marking the wrong block vs simply omitting a block?
• Are specific regions less tolerant to errors (e.g. the "fixed patterns" or "format info" areas)?

Based on these findings, any recommendations for improving our SeedQR templates?

I'd suggest writing a script that randomly generates new SeedQRs and intentionally applies the above errors. The script can then feed the resulting SeedQR back into a QR decoder to see if it's still readable.

[SeedSigner]

This seems like a good idea, though I would also point out that a lot of error issues arise out of inconsistent / partial marking of the QR grid. How much of an individual grid space needs to be marked for it to "count", and how do environmental factors affect scanning as well -- lighting, reflectivity, ink color contrast to background color, etc. etc. Maybe some of this can be accounted for in software, but just want to point on these other variables.

[kdmukai]

a lot of error issues arise out of inconsistent / partial marking of the QR grid. How much of an individual grid space needs to be marked for it to "count", and how do environmental factors affect scanning as well -- lighting, reflectivity, ink color contrast to background color, etc. etc.

I would pull that out into its own separate research endeavor. Those aren't transcription errors in the sense that I'm talking about, they're physical readability questions. Whatever those physical findings end up being can be documented like the old scantron instructions:

What I want to stay focused on here is the digital basics of the QR format itself with respect to error tolerance and how that might guide us to improve the templates. This is a perfectly rendered QR code... but is it valid?

[rx18-eng]

Was looking into the codebase to map this out :

SeedQR is hardcoded to ERROR_CORRECT_L (lowest level, ~7% recovery) in helpers/qr.py:17. At L level, Reed-Solomon gives you floor(EC_codewords / 2) correctable symbol errors, where one symbol is one 8-bit codeword:

• Compact 12-word (21x21, V1): 7 EC codewords, 3 correctable
  symbol errors
• Standard 12-word (25x25, V2): 10 EC codewords, 5 correctable
  symbol errors
• Compact 24-word (25x25, V2): 10 EC codewords, 5 correctable
  symbol errors
• Standard 24-word (29x29, V3): 15 EC codewords, 7 correctable
  symbol errors

A "symbol error" is a corrupted codeword, not a single wrong module. Multiple wrong modules within the same codeword only count as one symbol error. So the actual number of tolerable wrong modules could be way higher depending on where errors land. That's exactly what the script needs to quantify.

Compact vs Standard: Compact 12-word is the most fragile (3 correctable errors across 249 user blocks). Standard 24-word is the most resilient (7 across 624 blocks). Standard also uses QR Numeric mode (3 digits into 10 bits) while Compact uses Binary mode (raw bytes), giving Standard slight extra redundancy per module.

Wrong block vs omission: at the data level both are bit flips, but omissions (forgot to fill a black module) tend to cluster in
dense black regions, hitting the same codeword multiple times(costs you only one symbol error). Random flips spread across
codewords and are worst case. Worth testing random, omission only, and commission only separately.

Regional sensitivity: corrupting a finder pattern (three big corner squares) means pyzbar won't detect the QR at all. Timing
patterns cause global grid misalignment. Format info is stored twice with its own BCH correction so it's surprisingly tough. Data
modules degrade gracefully up to the EC limit. A heatmap of "flip this module, does it still decode" would be useful output from the script.

One thing worth flagging: Standard SeedQR decoding(decode_qr.py:841-860) does not validate the BIP-39 checksum
after parsing, it just checks word count is 12 or 24. Compact is fine because bip39.mnemonic_from_bytes() recomputes checksum by construction. This means for Standard SeedQR there's a silent corruption window where errors stay within EC capacity and decode "successfully" but to a wrong mnemonic. The script should always compare decoded result against the original seed, not just check whether pyzbar returned data.

Script approach:
tests/test_seedqr.py:run_encode_decode_test() is almost the right
scaffold. Generate seed, encode via
SeedQrEncoder/CompactSeedQrEncoder, render via
QR().qrimage(), map pixel coords to module positions (accounting
for border=3, box_size=5, fit=True), flip N modules per error
pattern, feed to DecodeQR().add_image(), compare decoded mnemonic
against original. Binary search for the failure threshold,
aggregate across many seeds. Could live in tools/ next to
seed_phrase_to_qr.py.

Happy to write the script if there's interest.