BIP 321 started as a verbatim copy of BIP 21 (7e6a583) and has diverged since, but it never picked up the note about example addresses that was added to BIP 21 in #1861. This adds it.
One of three mutually exclusive options for the same problem — see the table at the bottom. My preference is #2229, not this PR.
Background
#119 (2015) proposed replacing the base58 example address 175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W, whose checksum is intentionally invalid, with a valid one. It was closed for lack of author consensus, but the thread documents the cost of leaving the intent undocumented: users repeatedly filed URI-parsing bugs against wallets after copying URIs straight out of the document (@schildbach), and it tripped up someone using the examples as test vectors (@evoskuil), who asked for exactly this kind of warning. #1861 later resolved it for BIP 21 by documenting the intent instead of changing the address. This PR extends the same treatment to BIP 321.
One difference from BIP 21
BIP 321's examples also include bech32/bech32m addresses, added after the fork from BIP 21, and unlike the base58 one their checksums are valid:
| Address | Status |
|---|---|
175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W |
invalid checksum (intentional) |
bc1qufgy354j3kmvuch987xe4s40836x3h0lg8f5n2 |
valid bech32, witness v0, mainnet |
bc1p5swkugezn97763tl0yty6556856uug0q6jflljvep9m4p7339x5qzyrh4g |
valid bech32m, witness v1, mainnet |
tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg |
valid bech32, witness v0, testnet |
So BIP 21's exact wording ("the addresses used in these examples are intentionally invalid") would be inaccurate here, and misleading in the direction that matters: it would tell readers that two spendable mainnet addresses are safe. The wording used here states the illustration-only intent for all the examples and attributes the invalid checksum specifically to the base58 address:
Note: The addresses used in these examples are for illustration only and must not be used to send funds; the base58 address has an intentionally invalid checksum to prevent accidental transactions.
The three options
| PR | Approach | Diff | |
|---|---|---|---|
| #2228 | keep the addresses, word the note to match reality | +2 | this PR |
| #2229 | invalidate every address, add BIP 21's note verbatim | +7 / -5 | 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 #2229. 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. This PR 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.
