BIP21: clarify that example addresses are intentionally invalid #1861

1. 
   ethicnology commented at 2:13 pm on May 29, 2025: contributor

   Clarify to readers that the addresses used in the examples are intentionally invalid to prevent accidental transactions.
2. jonatack added the label Pending acceptance on May 29, 2025
3. jonatack added the label Bug fix on May 29, 2025
4. 
   jonatack commented at 3:57 pm on May 29, 2025: member

   cc BIP author @TheBlueMatt for feedback
5. ethicnology renamed this:
   fix: Invalid address in BIP21 example
   BIP21: correct invalid address in BIP21 example
   on May 29, 2025
6. ethicnology renamed this:
   BIP21: correct invalid address in BIP21 example
   BIP21: correct invalid address in examples
   on May 29, 2025
7. 
   murchandamus commented at 0:45 am on May 31, 2025: contributor

   This may have been on purpose, given that it is examples and not test vectors, because in the past people have sent money to addresses published in BIPs or Bitcoin books which were no longer held by anyone or for which it was then unclear where the funds should be sent.
8. 
   kristapsk commented at 1:38 pm on May 31, 2025: none

   I think it’s ok here to have invalid addresses on purpose, but maybe that should be mentioned in text that these example addresses aren’t real, I also have spent some extra time in past with tests because of this.
9. jonatack removed the label Bug fix on Jun 1, 2025
10. jonatack added the label Proposed BIP modification on Jun 1, 2025
11. 
    jonatack commented at 3:11 pm on June 1, 2025: member

    @murchandamus @kristapsk good points; this has come up occasionally in Bitcoin Core as well, where the developer notes state:

    0- Use *invalid* bech32 addresses (e.g. in the constant array `EXAMPLE_ADDRESS`) for
    1  `RPCExamples` help documentation.
    2
    3  - *Rationale*: Prevent accidental transactions by users and encourage the use
    4    of bech32 addresses by default.
    

12. 
    ethicnology commented at 4:47 pm on June 1, 2025: contributor

    I can replace legacy addresses to encourage the use of bech32.

    Why should we prevent accidental transactions rather than providing valid examples ?

    EDIT: Using valid regtest/testnet/signet addresses could solve both issues

13. 
    jonatack commented at 4:58 pm on June 1, 2025: member

    I’d suggest updating this as @kristapsk suggested.
14. ethicnology force-pushed on Jun 1, 2025
15. 
    ethicnology commented at 5:09 pm on June 1, 2025: contributor

    Amended with bc1q09vm5lfy0j5reeulh4x5752q25uqqvz34hufdl from EXAMPLE_ADDRESS
16. ethicnology force-pushed on Jun 1, 2025
17. 
    ethicnology commented at 10:24 pm on June 1, 2025: contributor

    rename commit from fix: bip21 example invalid address to refactor: replace BIP21 legacy addresses to bech32
18. murchandamus changes_requested
19. 
    murchandamus commented at 9:56 pm on June 3, 2025: contributor

    BIP 21 is Final and was specified with use of base58 addresses as it predates segwit. While some people have more recently also applied the described scheme to native segwit addresses, these examples do not conform to the specification of this proposal. I don’t think changing the examples to bech32 addresses makes sense in this context.

    Recently, BIP 321 was proposed as a replacement for BIP 21. Perhaps what you were looking for is part of BIP 321?

20. 
    ethicnology commented at 10:47 pm on June 3, 2025: contributor

    @murchandamus

    Initially, I came to report that the addresses in the examples were invalid, and that this could lead some developers, like myself or kristapsk, to waste time debugging and questioning our integration, when in fact the issue came from the example itself being invalid

    Following the creation of this issue, it appears that the invalid addresses weren’t random but intentionally used to prevent accidental transactions.

    I suggested replacing the invalid addresses with ones from test networks like testnet, signet, or regtest, in order to keep the example valid while still avoiding accidental transactions. However, it doesn’t seems to be convincing, so I’ve amended my commit with an invalid bech32 address from EXAMPLE_ADDRESSES as recommended in the bitcoin core developers notes.

    If the BIP is final and we shouldn’t change anything then we can close my PR

21. 
    murchandamus commented at 7:50 pm on June 4, 2025: contributor

    Hey @ethicnology, I touched base with @TheBlueMatt. The addresses were indeed invalid on purpose. So, I would also suggest what @kristapsk proposed: to add a line that informs readers that the addresses are invalid on purpose. If you would like to take a stab at that, please edit this branch, otherwise, please feel free to close it and probably @jonatack, myself, or someone else will open a PR to amend BIP 21 to add the warning.
22. refactor: add warning about invalid example addresses in BIP-21 fad325e7a1
23. ethicnology force-pushed on Jun 4, 2025
24. ethicnology renamed this:
    BIP21: correct invalid address in examples
    BIP21: invalid address in examples
    on Jun 4, 2025
25. 
    ethicnology commented at 7:59 pm on June 4, 2025: contributor

    @murchandamus done in https://github.com/bitcoin/bips/pull/1861/commits/fad325e7a11902ca7e73fece9ee78985e9dcd844
26. murchandamus approved
27. 
    murchandamus commented at 8:04 pm on June 4, 2025: contributor

    LGTM, thanks!
28. jonatack renamed this:
    BIP21: invalid address in examples
    BIP21: clarify that example addresses are intentionally invalid
    on Jun 4, 2025
29. 
    jonatack commented at 8:22 pm on June 4, 2025: member

    ACK fad325e7a11902ca7e73fece9ee78985e9dcd844

    Updated the PR title and description.

30. jonatack removed the label Pending acceptance on Jun 4, 2025
31. jonatack merged this on Jun 4, 2025
32. jonatack closed this on Jun 4, 2025

    ---

Contributors
ethicnology jonatack murchandamus kristapsk

Labels
Proposed BIP modification