One of three mutually exclusive options for the same problem — see the table at the bottom. This is the one I'd recommend merging.
BIP 21's example address 175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W has a deliberately broken checksum (the final character was replaced, per @TheBlueMatt in #119), and #1861 documented that intent with a note. BIP 321 inherited the address but not the note, and the addresses added to BIP 321 after the fork from BIP 21 do not follow the convention — their checksums are valid:
| Address | Status on master |
|---|---|
175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W |
invalid checksum (intentional) |
bc1qufgy354j3kmvuch987xe4s40836x3h0lg8f5n2 |
valid bech32, witness v0, mainnet |
bc1p5swkugezn97763tl0yty6556856uug0q6jflljvep9m4p7339x5qzyrh4g |
valid bech32m, witness v1, mainnet |
tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg |
valid bech32, witness v0, testnet |
So the document currently ships two spendable mainnet addresses in its examples — exactly the accident #119 and #1861 were about.
This PR
Applies the existing convention to the remaining addresses by altering the final checksum character of each, then adds BIP 21's note verbatim, which is now accurate for every address in the document:
Note: The addresses used in these examples are intentionally invalid to prevent accidental transactions.
Properties preserved:
- Bech32 detects any single-character substitution, so the modified strings cannot be valid addresses under either the bech32 or bech32m constant. I verified all of them against a reference implementation of both.
- Human-readable part, charset and length are unchanged (42 and 62 characters), so the examples stay structurally representative of P2WPKH and P2TR and remain usable as negative test vectors.
- The uppercase QR-code variants are updated to match.
- The changed testnet address in the "Invalid URIs" section still demonstrates its point, which is the HRP/parameter-key mismatch (a
tbaddress in thebcparameter), not the checksum.
The three options
| PR | Approach | Diff | |
|---|---|---|---|
| #2228 | keep the addresses, word the note to match reality | +2 | |
| #2229 | invalidate every address, add BIP 21's note verbatim | +7 / -5 | this PR, my preference |
| #2230 | make every address valid, warn against paying them | +18 / -16 |
Only one should be merged; I'll close the other two.
My preference is this PR. It is the only one of the three that leaves no spendable address anywhere in the document, it makes BIP 21's existing wording literally true here so the two documents stay in sync, and the whole cost is four characters. #2228 is the minimal-diff fallback if maintainers would rather not touch strings that downstream implementations may already be using as test vectors. #2230 is on the table because #119 was closed for lack of author consensus rather than on the merits, so the option deserves to be stated explicitly rather than assumed dead — but it is the one I would close first.
