BIP321: make all example addresses intentionally invalid - #2229
Merged
Conversation
The base58 example address has an intentionally invalid checksum, but the bech32 and bech32m examples added later have valid checksums, so they are spendable addresses that a reader may pay by accident -- the very hazard that motivated the invalid base58 address in bitcoin#119. Two of them are mainnet: bc1qufgy354j3kmvuch987xe4s40836x3h0lg8f5n2 (bech32, witness v0) bc1p5swkugezn...vep9m4p7339x5qzyrh4g (bech32m, witness v1) tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg (bech32, testnet) Alter the final checksum character of each, and document the intent with the note BIP 21 received in bitcoin#1861. Bech32 detects any single-character substitution, so the modified strings cannot be valid addresses. The human-readable part, charset and length are unchanged, so the examples remain structurally representative of P2WPKH and P2TR. The uppercase QR-code variants are updated to match, and the changed testnet address in the "Invalid URIs" section still demonstrates the same point (a `tb` address in the `bc` parameter). Alternative to bitcoin#2228, which leaves the addresses untouched and instead words the note to match them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Jul 31, 2026
fametrano
added a commit
to fametrano/bips
that referenced
this pull request
Jul 31, 2026
Revives bitcoin#119, closed in 2015 for lack of author consensus. 175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W has a deliberately broken checksum -- the address from the Wikipedia Bitcoin page of the time with its final character replaced -- while every other address in the document, the bech32 and bech32m examples added after the fork from BIP 21, has a valid checksum. That inconsistency has a documented cost: users have filed URI-parsing bugs against wallets after copying URIs straight out of the document (schildbach in bitcoin#119), and the examples cannot be used as test vectors as they stand (evoskuil in bitcoin#119, who opened it for exactly this reason). Use 1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L, the replacement bitcoin#119 proposed. It is BIP 20's example address, where it is already paired with the same label=Luke-Jr used here, so the labels in the examples stay coherent -- luke-jr's objection in bitcoin#119. Every address in the document is now valid and parseable, so the examples work as test vectors, and a note states that they are illustrative and must not be paid. That addresses laanwj's objection in bitcoin#119 -- that valid example addresses are spendable ones -- by warning the reader rather than by breaking the encoding. Alternatives: bitcoin#2228 and bitcoin#2229, which keep the addresses unspendable instead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
jonatack
reviewed
Jul 31, 2026
jonatack
left a comment
jonatack
left a comment
Member
There was a problem hiding this comment.
Approach ACK. Per #119 (comment), the BIP author doesn't mind either way and this follows what was already done in #1861.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
175tWpb8K1S7NmH4Zx6rewF9WQrcZv245Whas 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:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245Wbc1qufgy354j3kmvuch987xe4s40836x3h0lg8f5n2bc1p5swkugezn97763tl0yty6556856uug0q6jflljvep9m4p7339x5qzyrh4gtb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmgSo 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:
Properties preserved:
tbaddress in thebcparameter), not the checksum.The three options
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.