BIP 21 Updates

206 views
Skip to first unread message

Matt Corallo

unread,
May 30, 2024, 6:00:02 PMMay 30
to Bitcoin Development Mailing List
It was recently pointed out at [1] that BIP 21 mandates only base58 adresses, and doesn't allow for
segwit or taproot addresses in the body of the URI. This is obviously somewhat nonsensical as nearly
every wallet supporting BIP 21 today handles Segwit (and many even Taproot) just fine in that
position today.

Further, nearly every BIP 21-handling lightning wallet today also supports decoding lightning
payment instructions in the query parameters. With Silent Payments and BOLT 12 starting to get
adoption and BIP 21 being the obvious place to put extra payment instructions with an (optional)
on-chain fallback, there needs to be a standard way to decide which query parameter describes which
payment instruction, and BIP 21 should document this in-practice usage.

Further, as future payment schemes (and existing ones like Silent Payments) may wish to not have the
standard on-chain fallback, I'm also proposing the body of the URI be made optional.

None of these changes impact any existing wallets, as wallets already support bech32 and bech32m
addresses, new query parameters are ignored by any existing spec-compliant wallet, and a BIP 21 URI
with no body would only exist to provide a URI *without* a fallback for existing wallets, which
would correctly reject them as invalid.

Thus, I'm proposing a change to (the already "Final") BIP 21. The relatively minimal change set is
available at https://github.com/bitcoin/bips/pull/1555 but I'm open to discussion on it here as well.

[1] https://github.com/bitcoin/bips/pull/1394

Matt Corallo

unread,
Nov 12, 2024, 12:02:45 PMNov 12
to Bitcoin Development Mailing List
Quick update on this. There was various pushback on the idea of updating a "Final" BIP, so instead
this is gonna be a new BIP.

Since its a new BIP we have the opportunity to add a bit more, so I went ahead and added a "payment
info callback" parameter. Like the original proposed change this doesn't impact any existing
wallets, but it does provide a new (important) feature for some use-cases, especially things like
nostr zaps. The same PR is still where the new BIP lives, and there's examples and rationale, but to
higlight the new (normative) section, it is included below:

=== Proof of Payment ===

The URI MAY include a "pop" (or "req-pop") parameter whose value can be used to build a URI which
the wallet application can, after payment completes, "open" to provide proof the payment was
completed or other information about the payment.

The value of a "pop" (or "req-pop") parameter shall be a percent-encoded (per RFC 3986 section 2.1)
URI prefix. The wallet application, if it supports providing payment information SHOULD
percent-decode the provided URI once, append the query parameter key from which the payment
instructions used were read, append a single =, and finally append the Payment Information to the
resulting URI and open it with the default system handler for the URI. For payment instructions read
from the body of the URI, "onchain" SHALL be used in place of the key.

A wallet MUST validate that the provided URI's scheme is not (case-insensitive) "http", "https",
"file", "javascript", "mailto" or any other scheme which will open in a web browser prior to opening it.

If a wallet will not open the pop scheme (either because it does not support returning payment
information for the selected payment method or because it uses a URI scheme which should not be
opened) and the parameter was passed as a "req-pop" parameter, the wallet MUST NOT initiate payment.

For payments made using an on-chain transaction, the Payment Information shall be the full
(including witness data) Bitcoin transaction as it was broadcasted to the Bitcoin network, encoded
in hex.

For payments made using a BOLT 11 invoice (communicated via the `lightning` parameter), the Payment
Information shall be the hex-encoded payment preimage.

Other payment schemes will define their own Payment Information format. This BIP may be updated from
time to time with Payment Information formats for other payment schemes.
Reply all
Reply to author
Forward
0 new messages