BIP 321: URI Scheme (Replace BIP 21 with a new BIP containing information about more modern usage of it)

TheBlueMatt commented at 5:10 pm on March 1, 2024: contributor

As Bitcoin has grown, the introduction of new address formats describing new forms of payment instructions has become increasingly fraught with compatibility issues. Not only does there exist traditional on-chain addresses, but some recipients wish to receive Lightning (when the sender supports it) or newer formats such as Silent Payments.

This has led to increasing use of the BIP 21 query parameters to encode further optional payment instructions.

Looking forward, as new payment instructions get adopted, it makes much more sense to include them in query parameters rather than replace the existing address field, ensuring compatibility with senders and recipients who may or may not be upgraded to support all the latest payment instructions.

This updates BIP 21 to suggest that future address formats do this.

Further, it updates BIP 21 to allow an empty bitcoin address in cases where new payment instructions have moved to becoming mandatory. This isn’t a backwards-incompatible change any more than switching to a new address format is, so doesn’t impact existing BIP 21 implementations in a new way, however provides a nice conclusion to the query-parameter-based upgrade path - once a form of payment instructions has broad adoption, senders can simply drop the existing address field, keeping their existing query parameter encoding, rather than replace the existing address field. It also addresses the question of what to do if a wallet no longer wishes to receive some legacy on-chain address, but has multiple payment instruction formats that they wish to include - deciding which one to place in the address field would be a difficult task.

josibake commented at 12:05 pm on March 4, 2024: member

(Background discussion for context: https://delvingbitcoin.org/t/revisiting-bip21/630)

Thanks for starting this! Conceptually, I agree with the updates but I think we can get a bigger win by advising the use of HRPs directly instead of key-value pairs. The benefits of this approach are:

Better taproot support: using HRPs directly would allow us to construct backwards compatible taproot URIs of the form bitcoin:bc1q...?bc1p...=o / bitcoin:bc1q...?bc1p...
Support for future payment instructions: any new payment protocol that encodes their payment instructions using bech32m can be included directly, e.g. bitcoin:bc1q...?newprotocol1<bech32m encoded data>=o
Existing unified QR codes can be made smaller: following an upgrade period to allow clients to update, we would be able to create URIs bitcoin:bc1q...?lnbc1...=o (instead of ?lightning=lnbc1...) and fully static URIs bitcoin:sp1q...?lno1...=o

For senders, this simplifies implementing support for new address types in that clients can implement support for a generic BIP21 URI using HRPs as keys. As the client supports new bech32m encoded addresses, they are supported automatically without any additional changes.

Clients would still need to support new payment instructions that instead decided to use a query parameter, but I would expect most (if not all) clients to prefer bech32m encodings now that they get BIP21 support for free.

I wrote a rough draft here, feel free use / modify as needed if you find it useful: https://github.com/josibake/bips/commit/07339bdb929113a9e7218f55ef1bfa72b3976f8e

TheBlueMatt commented at 3:08 pm on March 7, 2024: contributor

Better taproot support: using HRPs directly would allow us to construct backwards compatible taproot URIs of the form bitcoin:bc1q…?bc1p…=o / bitcoin:bc1q…?bc1p…

I think this ship has sailed, but K/V-vs-no-K has no impact on this. We could do bitcoin:bc1q…?taproot=bc1p. or whatever just fine. Ultimately its probably too late to update how any taproot anything appears in QR codes/URIs.

Support for future payment instructions

This is similarly untrue, the only difference is it reduces the characters used for future instructions, but whether it supports future instructions or not, both do.

Existing unified QR codes can be made smaller: following an upgrade period to allow clients to update, we would be able to create URIs bitcoin:bc1q…?lnbc1…=o (instead of ?lightning=lnbc1…) and fully static URIs bitcoin:sp1q…?lno1…=o

Indeed, we can save a few characters here or there. I think the ship has similarly sailed for BOLT 11, but of course we can do something different for BOLT 12.

Ultimately I think the only difference between the two proposals are:

Skipping the key has slightly less bytes in the QR code, which helps very slightly on the margin.
Skipping the key means parsing is a bit trickier if/when we have some new payment instructions that don’t use bech32m - do clients need to check the bech32m checksum for unknown payment instruction types? What do they do if its wrong? What happens when someone (without thinking) defines some payment instructions that match a bech32m HRP spuriously (but I guess probably the checksum would be wrong?). These should all be written out and considered if we want to go this path.

I think the right approach here is the simpler one, but there’s not a really strong reason to prefer either over the other, honestly.

josibake commented at 4:19 pm on March 7, 2024: member

This is similarly untrue, the only difference is it reduces the characters used for future instructions, but whether it supports future instructions or not, both do.

No, they are not the same. This is especially relevant if wallets are using a BIP21 library: my wallet supports new address type abc1xxxx, which (according to your proposal) also gets a abc key defined (i.e. abc=abc1xxx. My wallet can parse the address but since my BIP21 library I am using hasn’t added support for the new key, I am unable to parse these URIs. With my proposal of allowing bech32m encoded addresses to be used without a key, everything Just Works.

Skipping the key means parsing is a bit trickier if/when we have some new payment instructions that don’t use bech32m - do clients need to check the bech32m checksum for unknown payment instruction types? What do they do if its wrong? What happens when someone (without thinking) defines some payment instructions that match a bech32m HRP spuriously (but I guess probably the checksum would be wrong?). These should all be written out and considered if we want to go this path.

I’m not really sure what you’re getting at here? My proposal is that any new payment addresses must use bech32m if they want to be used without a key, otherwise they must define a key. Everything you just mentioned was predicated on the assumption “what if they don’t use bech32m and don’t define a key,” which means they wouldn’t be following the spec.

TheBlueMatt commented at 5:06 pm on March 7, 2024: contributor

No, they are not the same. This is especially relevant if wallets are using a BIP21 library: my wallet supports new address type abc1xxxx, which (according to your proposal) also gets a abc key defined (i.e. abc=abc1xxx. My wallet can parse the address but since my BIP21 library I am using hasn’t added support for the new key, I am unable to parse these URIs. With my proposal of allowing bech32m encoded addresses to be used without a key, everything Just Works.

That applies both to a K/V parameter and a non-K/V parameter equally - there’s really no difference here. A BIP21 parsing library should pass all parameters that it doesn’t know.

I’m not really sure what you’re getting at here? My proposal is that any new payment addresses must use bech32m if they want to be used without a key, otherwise they must define a key. Everything you just mentioned was predicated on the assumption “what if they don’t use bech32m and don’t define a key,” which means they wouldn’t be following the spec.

Ah, okay, I misunderstood the proposal. I’m not really super excited to bake “future addresses will use bech32m” into the spec in that way, because at some point we’re gonna want “bech32n” or some other encoding (which would make sense for stuff that’s only in QR codes as you could get the QR a bit denser) and then we’ll be back having this same discussion, except now we have to shove everything in K/V pairs because we restricted non-K/V pairs to bech32m-only.

josibake commented at 5:58 pm on March 7, 2024: member

I’m not really super excited to bake “future addresses will use bech32m” into the spec in that way, because at some point we’re gonna want “bech32n”

While certainly not perfect, I think this is better than the alternative of whitelisting a set of addresses that are allowed in a root in this BIP and requiring new formats to specify extension keys. My proposal gives us a way to specify a taproot address in a backwards compatible way, it allows for clients to save space by not needing to redundantly specify hrp=hrp..., leaves open the possibility for implementations to move to use the BOLT11 HRP directly to save space, and provides some future proofing for new address formats insomuch as bech32m continues to be the standard.

TheBlueMatt commented at 6:51 pm on March 7, 2024: contributor

While certainly not perfect, I think this is better than the alternative of whitelisting a set of addresses that are allowed in a root in this BIP and requiring new formats to specify extension keys. My proposal gives us a way to specify a taproot address in a backwards compatible way, it allows for clients to save space by not needing to redundantly specify hrp=hrp…, leaves open the possibility for implementations to move to use the BOLT11 HRP directly to save space, and provides some future proofing for new address formats insomuch as bech32m continues to be the standard.

To be clear, I think we should “whitelist the set of addresses that are allowed in the root” either way. IMO it was a (now-clear) mistake to have taproot at the root rather than in a parameter. Whether we go with K/V or not-K/V we still want to have all future address types in parameters rather than the URI root (and eventually basically phase out the URI root entirely, or at least make it taproot-only).

josibake commented at 9:24 am on March 8, 2024: member

To be clear, I think we should “whitelist the set of addresses that are allowed in the root” either way.

Effectively, this is what you get with my proposal:

The bitcoinaddress body MUST be either a legacy base58 address (P2PKH, P2SH), or a bech32(m) encoded address. Future address formats that do not use bech32m encoding MUST instead be placed in query keys. Query keys SHOULD be defined by the respective BIP for the new address format.

The only distinction is newer bech32m address types can also be placed in the root. If you’re planning to allow bitcoin:?hrp=hrpxxx...&anotherhrp=anotherhrpxxx&amount=<>, that’s exactly the same as bitcoin:hrpxxx...?anotherhrpxxx&amount=<>, just more compact.

TheBlueMatt commented at 4:29 pm on March 8, 2024: contributor

Effectively, this is what you get with my proposal:

This is unrelated to the K/V/no-K/V discussion. We can get it either way.

The only distinction is newer bech32m address types can also be placed in the root.

I don’t think we should allow this. It would be nice to only have one place to look for a given address type.

murchandamus commented at 6:07 pm on May 1, 2024: contributor

I noticed that there is another pending PR that seeks to amend BIP21 #1394. At first glance, it seems like the change suggested there could be incorporated here.

in bip-0021.mediawiki:42 in 039f1e7a07 outdated

38@@ -39,7 +39,7 @@ Elements of the query component may contain characters outside the valid range.
39 
40 (See also [[#Simpler syntax|a simpler representation of syntax]])
41 
42- bitcoinurn     = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]
43+ bitcoinurn     = "bitcoin:" [ bitcoinaddress ] [ "?" bitcoinparams ]

katesalazar commented at 11:58 am on May 4, 2024:

I have not been following, but did you consider rejecting empty string after colon, and removing unnecessary interrogation character?

0 bitcoinurn     = "bitcoin:" ( bitcoinaddress [ "?" bitcoinparams ] | bitcoinparams )

murchandamus added the label Proposed BIP modification on May 22, 2024

murchandamus added the label PR Author action required on May 22, 2024

in bip-0021.mediawiki:58 in 039f1e7a07 outdated

50@@ -51,14 +51,27 @@ Elements of the query component may contain characters outside the valid range.
51 
52 Here, "qchar" corresponds to valid characters of an RFC 3986 URI query component, excluding the "=" and "&" characters, which this BIP takes as separators.
53 
54-The scheme component ("bitcoin:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The rest of the URI is case-sensitive, including the query parameter keys.
55+The scheme component ("bitcoin:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The query parameter keys are also case-insensitive. Query parameter values and bitcoin address fields may be case-sensitive depending on their content.
56+
57+=== Bitcoin Address ===
58+
59+The bitcoinaddress body MUST be either a base64 P2SH or P2PKH address, bech32 Segwit version 0 address, bech32m Segwit address, or empty. Future address formats SHOULD instead be placed in query keys as optional payment instructions to provide backwards compatibility during upgrade cycles. After new addres types are near-universally supported, or for recipients wishing to avoid a standard on-chain fallback, the bitcoinaddress part of the URI MAY be left empty.

murchandamus commented at 2:37 pm on May 22, 2024:

0The bitcoinaddress body MUST be either a Base58Check P2SH or P2PKH address, bech32 Segwit version 0 address, bech32m Segwit address, or empty. Future address formats SHOULD instead be placed in query keys as optional payment instructions to provide backwards compatibility during upgrade cycles. After new address types are near-universally supported, or for recipients wishing to avoid a standard on-chain fallback, the bitcoinaddress part of the URI MAY be left empty.

in bip-0021.mediawiki:74 in 039f1e7a07 outdated

71+
72+*lightning: Lightning BOLT 11 invoices
73+*lno: Lightning BOLT12 offers
74+*sp: Silent Payment addresses
75+
76+New payment instructions using bech32 encodings SHOULD reuse their address format's Human Readable Part as the parameter key.

murchandamus commented at 2:39 pm on May 22, 2024:

0New payment instructions using bech32m as address encoding SHOULD reuse their address format's Human Readable Part as the parameter key.

TheBlueMatt commented at 9:48 pm on May 30, 2024:

They aren’t always addresses.

in bip-0021.mediawiki:88 in 039f1e7a07 outdated

84@@ -72,8 +85,8 @@ For example, so long as the majority of users work in BTC units, values should a
85 == Rationale ==
86 
87 ===Payment identifiers, not person identifiers===
88-Current best practices are that a unique address should be used for every transaction.
89-Therefore, a URI scheme should not represent an exchange of personal information, but a one-time payment.
90+Current best practices are that a unique address should be used for every transaction on-chain.

murchandamus commented at 2:41 pm on May 22, 2024:

0Best practices are that a unique address should be used for every transaction on-chain.

in bip-0021.mediawiki:89 in 039f1e7a07 outdated

84@@ -72,8 +85,8 @@ For example, so long as the majority of users work in BTC units, values should a
85 == Rationale ==
86 
87 ===Payment identifiers, not person identifiers===
88-Current best practices are that a unique address should be used for every transaction.
89-Therefore, a URI scheme should not represent an exchange of personal information, but a one-time payment.
90+Current best practices are that a unique address should be used for every transaction on-chain.
91+Therefore, a URI which contains on-chain payment data MUST NOT represent an exchange of personal information, but a one-time payment. URIs which represent only reusable non-address-reusing payment instructions (like Lightning BOLT12 offers or Silent Payments) MAY be reused as a wallet sees fit.

murchandamus commented at 2:42 pm on May 22, 2024:

0Therefore, a URI which contains on-chain payment data MUST NOT represent an exchange of personal information, but a one-time payment instruction. URIs which represent only reusable non-address-reusing payment instructions (like Lightning BOLT12 offers or Silent Payments) MAY be reused as a wallet sees fit.

in bip-0021.mediawiki:87 in 039f1e7a07 outdated

 96@@ -84,8 +97,7 @@ Also, very likely, what he will find are mostly technical specifications - not t
 97 ==Forward compatibility==
 98 Variables which are prefixed with a req- are considered required.  If a client does not implement any variables which are prefixed with req-, it MUST consider the entire URI invalid.  Any other variables which are not implemented, but which are not prefixed with a req-, can be safely ignored.
 99 
100-==Backward compatibility==

murchandamus commented at 2:45 pm on May 22, 2024:

It seems to me that this update should have its own Backward Compatibility section. Also, generally addressing Backward Compatibility is required in a BIP, so removing this section makes the document violates the formatting rules.

murchandamus changes_requested

murchandamus commented at 2:54 pm on May 22, 2024: contributor

I’m a bit on the fence regarding this PR. There clearly exists a divergence of the practical use from the specification, and it makes sense to address this and make them line up better. On the other hand, it generally seems counterproductive to ship a new version of a spec under the same label.

I would at least request that the changes are discussed on the mailing list and a Change Log section be added to document when and how the spec was amended. Perhaps it would be better to place these changes into an Appendix that comments on the practical use today and proposes these amendments.

Overall I would prefer a new BIP over changes to a final BIP.

TheBlueMatt commented at 8:48 pm on May 28, 2024: contributor

I’m a bit on the fence regarding this PR. There clearly exists a divergence of the practical use from the specification, and it makes sense to address this and make them line up better. On the other hand, it generally seems counterproductive to ship a new version of a spec under the same label.

Yea, I see that its a bit weird to update something “final”, but I think there’s also tremendous value in being able to update something so that people aren’t led to something that is stale, which would almost certainly happen given the number of existing links and references to “BIP 21”. I would also be fine copying + pasting BIP 21 to a new BIP number if we update the headers with a “Superseded: See BIP XXXX” header, however, if we really don’t want to update it.

I’ll wait to address feedback until we have clarity on the forward direction.

TheBlueMatt force-pushed on May 28, 2024

murchandamus commented at 4:55 pm on May 30, 2024: contributor

I’ll wait to address feedback until we have clarity on the forward direction.

It might be useful to posit this amendment idea to the mailing list in order to get more input on the forward direction.

TheBlueMatt force-pushed on May 30, 2024

TheBlueMatt commented at 9:54 pm on May 30, 2024: contributor

It might be useful to posit this amendment idea to the mailing list in order to get more input on the forward direction.

Done

harding commented at 8:42 am on June 5, 2024: contributor

I think there’s a lot of advantage to updating even final BIPs with information about how those specifications are being widely used in practice, i.e. bitcoinaddress = *base58 / *bech32 / *bech32m.

I don’t like adding proposed new features to a final BIP, i.e. defining new keys that haven’t be used in practice (like sp). One reason I don’t like adding new features to a final BIP is well illustrated in the discussion between @TheBlueMatt and @josibake: they each have slightly different visions for the future of bitcoin: URIs but Matt will be in a privileged position to push for his vision if the existing and widely linked-to standard of BIP21 is updated to reflect his preferences.

I’d prefer to see this PR revised to only document how BIP21 is used in practice today, with any new proposals placed in a new BIP (which can, of course, be a 99% copy of the existing text).

TheBlueMatt commented at 11:49 am on June 5, 2024: contributor

I don’t like adding proposed new features to a final BIP, i.e. defining new keys that haven’t be used in practice (like sp).

The point of the proposed change isn’t to define ‘sp’ specifically but to define the rules for new formats going forward.

One reason I don’t like adding new features to a final BIP is well illustrated in the discussion between @TheBlueMatt and @josibake: they each have slightly different visions for the future of bitcoin: URIs but Matt will be in a privileged position to push for his vision if the existing and widely linked-to standard of BIP21 is updated to reflect his preferences.

I don’t think this is a fair characterization. There was a lot of back-and-forth and my understanding is we got to a common ground (or at least equivalent suggestions where it didn’t matter all that much where to go). If @josibake still has a different view I’m more than happy to amend the proposal here to make sure we’re on the same page.

Rather, the back-and-forth there is a great example of why defining some new BIP just to suggest where to put new payment instructions in BIP 21s is going to lead to further fragmentation - lots of people have strong opinions about lots of equivalent naming schemes.

I’d prefer to see this PR revised to only document how BIP21 is used in practice today, with any new proposals placed in a new BIP (which can, of course, be a 99% copy of the existing text).

This would be pretty confusing, IMO, since we’d then specify “lighting” as a URI parameter here (since it’s already in broad use) and then say “oh, but that’s kinda a weird name, in the future please do something different and use the HRP instead” in a different doc. IMO that’s likely to lead to a continued proliferation of unrelated keys which is less useful going forward.

TheBlueMatt commented at 1:03 pm on June 5, 2024: contributor

Thinking on this more, I think a policy of “we can update a final BIP to describe what is actually happening in practice but not to give forward guidance on how to do things people are going to do” is inconsistent. This results in a neverending stream of changes to add query parameters that are being used in practice, but we can’t add guidance for what query parameters to use to avoid that.

harding commented at 5:04 pm on June 5, 2024: contributor

@TheBlueMatt

the back-and-forth there is a great example of why defining some new BIP just to suggest where to put new payment instructions in BIP 21s is going to lead to further fragmentation - lots of people have strong opinions about lots of equivalent naming schemes.

If there’s a reasonable difference of opinion, each person should have equal access to the process for advocating for their position. Each person creating a new BIP is equal access IMO. One person being able to update a final BIP that is already widely deployed and referenced, while other parties can only create a new BIP and try to build support for it, is inequitable IMO.

TheBlueMatt commented at 5:53 pm on June 5, 2024: contributor

Right, I believe my above claim is that there isn’t any (more) difference of opinion :). Still, more generally I’m not at all convinced that “access to a document” is somehow privileged, or at least its very explicitly not supposed to be - BIPs are author documents - they aren’t somehow blessed and implementers can do whatever they want, as evidenced by the fact that no one complies with BIP 21 given BIP 21 currently doesn’t allow bech32[m] payments :)

As I mentioned above I’m okay with just saying “no changes at all”, but I think your position that we can make some changes (to describe reality) but not others (to provide forward-looking guidance) results in a pretty bad outcome.

harding commented at 6:52 pm on June 5, 2024: contributor

@TheBlueMatt

my above claim is that there isn’t any (more) difference of opinion :)

I don’t see the resolution to the discussion about bare keys vs key/values above, so it seems open to me, but perhaps you and @josibake hashed it out somewhere else (or I’m just misreading). If it was resolved somewhere else public, I’d appreciate a link, as I was favoring several of Josie’s proposals and I’d like to see what persuaded him to accept the full k/v approach.

BIPs are author documents - they aren’t somehow blessed and implementers can do whatever they want

BIPs in the draft and proposed stage are author documents for sure, but it doesn’t seem clear to me that they should remain author documents once they enter the final state. If people implement a supposedly final specification and then the specification changes, that may unnecessarily lead to miscommunication. @ajtowns dealt with this problem in BINANAs by giving them revision numbers, so e.g. if I want to reference that a particular implementation of OP_CAT is based on the original proposal, I can say BIN24-1.0 and be protected against changes that become BIN24-1.1, etc. We don’t conveniently have that facility with BIPs (I’d have to refer to a commitish) and I think we deal with that by having a final state after which significant changes are not expected.

I’m okay with just saying “no changes at all”, but I think your position that we can make some changes (to describe reality) but not others (to provide forward-looking guidance) results in a pretty bad outcome.

I’m also ok with “no changes at all”. That said, I think describing reality, especially if it’s made clear that it differs from the original specification, is very advantageous to later implementers and those attempting to understand how their modern software works. Not providing post-final forward-looking guidance in the updated BIP doesn’t mean that we can’t provide that guidance elsewhere, such as a new BIP or a link to a wiki page (in BIP125, I included a link to a wiki page to help foster collaboration among implementers and provide a source of living documentation).

I do want to mention that none of the above is a hill I care to die on; it’s just my opinion about editing final BIPs. If nobody else thinks this is a problem, I’m ok with this PR being merged as-is.

TheBlueMatt commented at 0:28 am on June 6, 2024: contributor

That said, I think describing reality, especially if it’s made clear that it differs from the original specification, is very advantageous to later implementers and those attempting to understand how their modern software works.

The point of a BIP is to have the information people need to implement it in one convenient place. That includes guidance for how to do the things people want to do. Updating to say “btw, people put BOLT11s in the lightning key” without saying “and also we should put BOLT12s in the lno key” is possibly the worst outcome, IMO. I see the rationale for getting there, but the outcome is just confusing for everyone (how does one write a general BIP 21 parser? You might have K-V entries, you might have just values, they may be under colliding keys, etc.

Not providing post-final forward-looking guidance in the updated BIP doesn’t mean that we can’t provide that guidance elsewhere, such as a new BIP or a link to a wiki page.

As long as the BIP gets marked “superseded” with a big link to some new BIP I’m happy with that. Just providing a link in a footnote also does not accomplish this, though, because people will just miss it.

harding commented at 9:26 pm on June 6, 2024: contributor

@TheBlueMatt

The point of a BIP is to have the information people need to implement it in one convenient place.

That’s certainly ideal. However, I think in the case of final BIPs, that ideal conflicts with the ideal of not giving anyone unnecessarily privileged access to the specification process. If there is more than one reasonable way to do something, I don’t think the author of a long-adopted spec should be able to use that spec to favor their preferred choices.

Which ideal is more important, better documentation or less privilege? I don’t know, which is why I’m ok with this PR being merged even if I’d prefer to see it reduced to only describing how current widely adopted behavior differs from the original spec.

TheBlueMatt commented at 9:58 pm on June 6, 2024: contributor

the ideal of not giving anyone unnecessarily privileged access to the specification process

I’ll be honest, I’d never considered that an ideal of the BIP process, including the reason for final BIPs. Of course no one should have some kind of priviledged access to changing Bitcoin, but the BIP process hasn’t historically been the gate for that.

Admittedly I’m not quite sure what ideal/goal we seek to meet with having a “final” state - I’d always considered it to exist because we don’t have a concept of an “accepted” BIP (because the BIP process isn’t for “accepting” ideas), but we still need some way to mark something as different from “draft”/proposed. In that context, the “final” concept only really makes any sense for consensus change BIPs. You could argue that a BIP in sufficient adoption is “final” in that future changes don’t make sense as they invalidate existing implementations which makes no sense, but that doesn’t really answer what to do about forward guidance as is proposed here (presumably it’s fine?)

murchandamus commented at 7:39 pm on July 10, 2024: contributor

I would posit that it may be simpler, less controversial, and more in line with the BIP Process to open a new BIP with the final state (or another evolution making use of the additional leeway) of this proposal. Then this BIP’s Preamble could be updated to point to the successor with the Replaced-By header as described in BIP 2.

Copy BIP 21 into a new BIP XXXX with only the header changed 8a93e77e98

Update to include newer address types

Added bech32 and bech32m address types to reflect the newer SegWit and Taproot addresses.

Co-Authored-By: Reese Russell <reese.russell@ymail.com>

ab9519393a

TheBlueMatt force-pushed on Jul 13, 2024

TheBlueMatt renamed this:
~~Update BIP 21 with information about more modern usage of it~~
Replace BIP 21 with a new BIP containing information about more modern usage of it
on Jul 13, 2024

Update BIP XXXX with information about more modern usage of it

As Bitcoin has grown, the introduction of new address formats
describing new forms of payment instructions has become
increasingly fraught with compatibility issues. Not only does there
exist traditional on-chain addresses, but some recipients wish to
receive Lightning (when the sender supports it) or newer formats
such as Silent Payments.

This has led to increasing use of the BIP 21 query parameters to
encode further optional payment instructions.

Looking forward, as new payment instructions get adopted, it makes
much more sense to include them in query parameters rather than
replace the existing address field, ensuring compatibility with
senders and recipients who may or may not be upgraded to support
all the latest payment instructions.

This updates BIP XXX to suggest that future address formats do this.

Further, it updates BIP XXX to allow an empty bitcoin address in
cases where new payment instructions have moved to becoming
mandatory. This isn't a backwards-incompatible change any more than
switching to a new address format is, so doesn't impact existing
BIP 21 implementations in a new way, however provides a nice
conclusion to the query-parameter-based upgrade path - once a form
of payment instructions has broad adoption, senders can simply drop
the existing address field, keeping their existing query parameter
encoding, rather than replace the existing address field. It also
addresses the question of what to do if a wallet no longer wishes
to receive some legacy on-chain address, but has multiple payment
instruction formats that they wish to include - deciding which one
to place in the address field would be a difficult task.

ff719344ca

TheBlueMatt force-pushed on Jul 13, 2024

TheBlueMatt commented at 2:49 pm on July 13, 2024: contributor

Okay, updated this PR to instead add a new BIP.

sethforprivacy commented at 6:57 pm on July 13, 2024: contributor

I’ve been testing out BIP 353 which led me to trying to use Silent Payments + BOLT 12 in the same BIP 21 URI and ultimately finding this PR.

Could you clarify in the examples how to use two diverse payment codes together in one URI?

This is what I currently have for SP + BOLT 12, but I’m not sure it’s correct and a good example here would be helpful once merged:

bitcoin:?lno=lno1pgqpvggzrdhszmg5yafguxmkm779vd8jftxskjyadjdrallmq8uxfjdjfyaq&sp=sp1qqweplq6ylpfrzuq6hfznzmv28djsraupudz0s0dclyt8erh70pgwxqkz2ydatksrdzf770umsntsmcjp4kcz7jqu03jeszh0gdmpjzmrf5u4zh0c

f add examples of silent payment addresses 836ef064e4

TheBlueMatt commented at 7:45 pm on July 13, 2024: contributor

Yep, that’s right, I’ve added some examples.

harding commented at 7:31 pm on July 15, 2024: contributor

836ef064e433721238f0cddbf95da4b8c0ebe2b9 LGTM (obviously needs BIP # assigned and to be added to the index)

in bip-XXXX.mediawiki:11 in 836ef064e4 outdated

 6+  Comments-Summary: No comments yet.
 7+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-XXXX
 8+  Status: Proposed
 9+  Type: Standards Track
10+  Created: 2024-07-13
11+</pre>

murchandamus commented at 5:37 pm on July 16, 2024:

Missing License header, and should probably have a Replaces header:

0License: ?
1Replaces: 21
2</pre>

TheBlueMatt commented at 8:59 pm on October 8, 2024:

I cannot assign this document a license given a substantial portion was written by @luke-jr. I’m happy to assign my contributions whatever license he wants for his.

TheBlueMatt commented at 9:08 pm on October 8, 2024:

Ah apologies, BIP 20 is licensed.

jonatack commented at 11:53 pm on November 13, 2024:

If this Replaces: 21 then BIP21 could also be updated to Status: Replaced.

in bip-XXXX.mediawiki:91 in 836ef064e4 outdated

86+===Payment identifiers, not person identifiers===
87+Best practices are that a unique address should be used for every transaction on-chain.
88+Therefore, a URI which contains an on-chain payment address MUST NOT represent an exchange of personal information, but a one-time payment instruction. URIs which represent only reusable non-address-reusing payment instructions (like Lightning BOLT12 offers or Silent Payments) MAY be reused as a wallet sees fit.
89+
90+===Accessibility (URI scheme name)===
91+Should someone from the outside happen to see such a URI, the URI scheme name already gives a description.

murchandamus commented at 5:48 pm on July 16, 2024:

This sentence is confusing. Who is someone from the outside? What is “such a URI”?

TheBlueMatt commented at 9:27 pm on October 8, 2024:

I just removed this section. I don’t think we need to justify the use of the bitcoin: prefix these days lol.

in bip-XXXX.mediawiki:93 in 836ef064e4 outdated

88+Therefore, a URI which contains an on-chain payment address MUST NOT represent an exchange of personal information, but a one-time payment instruction. URIs which represent only reusable non-address-reusing payment instructions (like Lightning BOLT12 offers or Silent Payments) MAY be reused as a wallet sees fit.
89+
90+===Accessibility (URI scheme name)===
91+Should someone from the outside happen to see such a URI, the URI scheme name already gives a description.
92+A quick search should then do the rest to help them find the resources needed to make their payment.
93+Other proposed names sound much more cryptic; the chance that someone googles that out of curiosity are much slimmer.

murchandamus commented at 5:49 pm on July 16, 2024:

What is this referring to?

in bip-XXXX.mediawiki:8 in 836ef064e4 outdated

0@@ -0,0 +1,166 @@
1+<pre>
2+  BIP: XXXX
3+  Layer: Applications
4+  Title: URI Scheme
5+  Author: Matt Corallo <bip21@bluematt.me>
6+  Comments-Summary: No comments yet.
7+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-XXXX
8+  Status: Proposed

murchandamus commented at 5:53 pm on July 16, 2024:

Given that this is a fresh proposal, this should probably be Draft:

0  Status: Draft

in bip-XXXX.mediawiki:16 in 836ef064e4 outdated

11+</pre>
12+
13+This BIP is a modification of [[bip-0021.mediawiki|BIP 0021]] to add information about the modern usage of bitcoin: URIs as well as provide forward-looking guidance on how to incorporate new payment instructions. BIP 21 was based on BIP 20, which was, in turn based off an earlier document by Nils Schneider.
14+
15+==Abstract==
16+This BIP proposes a URI scheme for making Bitcoin payments.

murchandamus commented at 5:54 pm on July 16, 2024:

“making payments”?

0This BIP proposes a URI scheme to serve Bitcoin payment requests.

TheBlueMatt commented at 9:38 pm on October 8, 2024:

Went with This BIP proposes a URI scheme for describing Bitcoin payment receipt information.

in bip-XXXX.mediawiki:13 in 836ef064e4 outdated

 8+  Status: Proposed
 9+  Type: Standards Track
10+  Created: 2024-07-13
11+</pre>
12+
13+This BIP is a modification of [[bip-0021.mediawiki|BIP 0021]] to add information about the modern usage of bitcoin: URIs as well as provide forward-looking guidance on how to incorporate new payment instructions. BIP 21 was based on BIP 20, which was, in turn based off an earlier document by Nils Schneider.

murchandamus commented at 5:55 pm on July 16, 2024:

It seems to me that some of this would fit better in the Motivation, while other parts should probably be in the Abstract.

in bip-XXXX.mediawiki:99 in 836ef064e4 outdated

94+Also, very likely, what he will find are mostly technical specifications - not the best introduction to bitcoin.
95+
96+==Forward compatibility==
97+Variables which are prefixed with a req- are considered required.  If a client does not implement any variables which are prefixed with req-, it MUST consider the entire URI invalid.  Any other variables which are not implemented, but which are not prefixed with a req-, can be safely ignored.
98+
99+As future new address types should be added using query parameters rather than the `bitcoinaddress` field, URIs can seamlessly support many payment instructions while senders only support legacy instructions. This allows for senders to be able to pay newer recipients while still allowing the use of more modern payment instruction formats.

murchandamus commented at 6:01 pm on July 16, 2024:

This paragraph feels a bit repetitive.

0As future new address types should be added using query parameters rather than the `bitcoinaddress` field, URIs seamlessly support various payment instructions while senders only need to support legacy instructions. This allows for senders to be able to pay newer recipients while still allowing recipients to additionally offer modern payment instruction formats.

in bip-XXXX.mediawiki:104 in 836ef064e4 outdated

 99+As future new address types should be added using query parameters rather than the `bitcoinaddress` field, URIs can seamlessly support many payment instructions while senders only support legacy instructions. This allows for senders to be able to pay newer recipients while still allowing the use of more modern payment instruction formats.
100+
101+==Backward compatibility==
102+As this BIP is written, several clients already implement a bitcoin: URI scheme similar to this one, however usually without the additional "req-" prefix requirement.  Thus, it is recommended that additional variables prefixed with req- not be used in a mission-critical way until a grace period of 6 months from the finalization of this BIP has passed in order to allow client developers to release new versions, and users of old clients to upgrade.
103+
104+Compared to BIP 21, this document describes standard query parameters containing payment instructions, allows bech32 and bech32m `bitcoinaddress` fields, and allow for future URIs with an empty `bitcoinaddress` field. Use of bech32 and bech32m `bitcoinaddress` fields were long-since common practice in 2024, and the `lightning` query parameter storing BOLT 11 payment instructions became common practice in the year or three leading up to 2024. Inclusion of standard query parameters was added to provide guidance on query parameter usage going forward.

murchandamus commented at 6:06 pm on July 16, 2024:

Not sure why “future”. Wouldn’t it be allowed by any software implementing this BIP?

0Compared to BIP 21, this document describes standard query parameters containing payment instructions, allows bech32 and bech32m `bitcoinaddress` fields, and allows URIs with an empty `bitcoinaddress` field. Use of bech32 and bech32m `bitcoinaddress` fields were long-since common practice in 2024, and the `lightning` query parameter storing BOLT 11 payment instructions became common practice in the year or three leading up to 2024. Inclusion of standard query parameters was added to provide guidance on query parameter usage going forward.

in bip-XXXX.mediawiki:166 in 836ef064e4 outdated

161+* Bitcoin-Qt supports the old version of Bitcoin URIs (ie without the req- prefix), with Windows and KDE integration as of commit 70f55355e29c8e45b607e782c5d76609d23cc858.
162+
163+=== Libraries ===
164+* Javascript - https://github.com/bitcoinjs/bip21
165+* Java - https://github.com/SandroMachado/BitcoinPaymentURI
166+* Swift - https://github.com/SandroMachado/BitcoinPaymentURISwift

murchandamus commented at 6:06 pm on July 16, 2024:

This section seems outdated

in bip-XXXX.mediawiki:4 in 836ef064e4 outdated

0@@ -0,0 +1,166 @@
1+<pre>
2+  BIP: XXXX
3+  Layer: Applications
4+  Title: URI Scheme

murchandamus commented at 6:07 pm on July 16, 2024:

Did you want to use the exact same title?

TheBlueMatt commented at 2:25 am on October 9, 2024:

Yea, I don’t see why we’d change it.

in bip-XXXX.mediawiki:57 in 836ef064e4 outdated

52+
53+The scheme component ("bitcoin:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The query parameter keys are also case-insensitive. Query parameter values and bitcoin address fields may be case-sensitive depending on their content.
54+
55+=== Bitcoin Address ===
56+
57+The bitcoinaddress body MUST be either a base58 P2SH or P2PKH address, bech32 Segwit version 0 address, bech32m Segwit address, or empty. Future address formats SHOULD instead be placed in query keys as optional payment instructions to provide backwards compatibility during upgrade cycles. After new address types are near-universally supported, or for recipients wishing to avoid a standard on-chain fallback, the bitcoinaddress part of the URI MAY be left empty.

murchandamus commented at 6:10 pm on July 16, 2024:

[…] or for recipients wishing to avoid a standard on-chain fallback […]

Some of this last sentence repeats prior specification parts and the rest could probably be in Rationale

TheBlueMatt commented at 2:26 am on October 9, 2024:

This section describes normative behavior so we can’t move it (otherwise its not clear you can set the address part empty), not sure which parts are redundant with elsewhere, aside from the ABNF grammar, but I prefer to have it in text as well.

murchandamus commented at 8:17 pm on November 15, 2024:

I’m not sure what I exactly meant back then. Either way, it’s not clear to me why this mentions “After new address types are near-universally supported”. If the receiver wants to only offer specific optional payment methods even while they are not broadly supported, that’s up to the receiver.

0The bitcoinaddress body MUST be either a base58 P2SH or P2PKH address, bech32 Segwit version 0 address, bech32m Segwit address, or empty. Future address formats SHOULD instead be placed in query keys as optional payment instructions to provide backwards compatibility during upgrade cycles. The bitcoinaddress part of the URI MAY be left empty, if there is at least one optional payment instruction provided and the recipient does not want to provide a static on-chain payment method.

in bip-XXXX.mediawiki:113 in 836ef064e4 outdated

108+== Appendix ==
109+
110+=== Simpler syntax ===
111+
112+This section is non-normative and does not cover all possible syntax.
113+Please see the BNF grammar above for the normative syntax.

murchandamus commented at 6:12 pm on July 16, 2024:

The section above is “ABNF grammar”

0Please see the ABNF grammar above for the normative syntax.

in bip-XXXX.mediawiki:19 in 836ef064e4 outdated

14+
15+==Abstract==
16+This BIP proposes a URI scheme for making Bitcoin payments.
17+
18+==Motivation==
19+The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.

murchandamus commented at 6:14 pm on July 16, 2024:

You could perhaps expand a bit more here on how the current usage of BIP 21 differs from its specification

murchandamus commented at 6:18 pm on July 16, 2024: contributor

Did a quick first pass. This document is missing a Copyright section, I left a few more comments inline.

murchandamus removed the label Proposed BIP modification on Jul 16, 2024

murchandamus added the label New BIP on Jul 16, 2024

t-bast commented at 11:24 am on July 30, 2024: contributor

Concept ACK, sorry for the late review!

Kixunil commented at 6:02 pm on August 1, 2024: none

Just one note regarding updating a final BIP: there’s a huge difference between documenting which parameters people use (the spec specifically allows using custom parameters) and documenting that everyone actually ignores the specification in regard to bech32. It also looks to me that the requirement to use base58 was a mistake. I think it’d make sense to amend that part and that part only. Use a new BIP for everything else.

AndySchroder commented at 2:33 pm on September 13, 2024: none

In addition to a BOLT12 offer, I’d also like to see an option for a BOLT12 invoice_request. Possibly using the key lnir would work? This addresses the following use case from the BOLT12 spec:

https://github.com/rustyrussell/lightning-rfc/blob/db73bbb64d2dfc07fbc9c1dc09259d827f703868/12-offer-encoding.md?plain=1#L54

0The merchant-pays-user flow (e.g. ATM or refund):
11. The merchant publishes an *invoice_request* which contains offer fields
2   which refer to its attempt to send money, including an amount.
32. The user sends an *invoice* over the lightning network for the amount in the
4   *invoice_request*, using a (possibly temporary) *invoice_node_id*.
53. The merchant confirms the *invoice_node_id* to ensure it's about to pay the correct
6   person, and makes a payment to the invoice.

with more explanation later on….

https://github.com/rustyrussell/lightning-rfc/blob/db73bbb64d2dfc07fbc9c1dc09259d827f703868/12-offer-encoding.md?plain=1#L367

0The second case is publishing an `invoice_request` without an offer,
1such as via QR code.  It contains neither `offer_issuer_id` nor `offer_paths`, setting the
2`invreq_payer_id` (and possibly `invreq_paths`) instead, as it in the one paying: the
3other offer fields are filled by the creator of the `invoice_request`,
4forming a kind of offer-to-send-money.

TheBlueMatt commented at 5:34 pm on September 13, 2024: contributor

BOLT 12 invoice_requests are not intended to be published. What you’re looking for are BOLT 12 refunds. You are right that this could include refunds explicitly, however there’s no reason to - it specifies that new types should simply use the bech32 HRP as the key.

AndySchroder commented at 7:25 pm on September 13, 2024: none

Not sure how you can say invoice_requests are not intended to be published. That is literally stated in the spec that I quoted above.

Are you saying that the key lnr is already supported automatically by your new BIP because of its generality?

TheBlueMatt commented at 1:30 pm on September 18, 2024: contributor

Not sure how you can say invoice_requests are not intended to be published. That is literally stated in the spec that I quoted above.

I believe its just a stale line that has slipped in. There is now a dedicated “refund” type which addresses that use-case. Thanks for reporting https://github.com/lightning/bolts/pull/798#discussion_r1765062764

Are you saying that the key lnr is already supported automatically by your new BIP because of its generality?

Yep!

AndySchroder commented at 5:48 pm on September 24, 2024: none

Not sure how you can say invoice_requests are not intended to be published. That is literally stated in the spec that I quoted above.

I believe its just a stale line that has slipped in. There is now a dedicated “refund” type which addresses that use-case. Thanks for reporting lightning/bolts#798 (comment)

Looking at @rustyrussell’s reply, it seems as there is no explicit refund workflow, it is instead just a modified use case of the offer workflow that can use used for refunds if you want to. So, in that use case, yes, I do think that invoice_requests are intended to be published. Do you agree?

Are you saying that the key lnr is already supported automatically by your new BIP because of its generality?

Yep!

Great, what is cool about this once this is supported by wallets, you can basically make QR code and a paper note with this standard and pass that around to people similar to a paper check, redeemable instantly from your lightning node! This is a great way to make backup in case your phone gets smashed before going on a trip. You can make notes in many denominations and destroy them whenever you want.

AndySchroder commented at 7:44 pm on September 28, 2024: none

BIP-0353 uses this BIP (even though it says it uses BIP-0021). This BIP (and BIP-21) result in long URI. This presents a problem for QR code encoding and just simple writing of them in messages, etc. Wondering if we can have another URI form that will resolve a BIP-0353 address? For example, encoding something such as bip353:matt@mattcorallo.com is much shorter than bitcoin:bc1qztwy6xen3zdtt7z0vrgapmjtfz8acjkfp5fp7l?lno=lno1qsg95t28fvk7aefdum96rgwq3psqzyxvqfcsq3pv8dulvphcpuezmxx5n8h0evrqtx00ch2wevqzp8pvk4qeqqhw37mc9659ses3xkamaksfd9dspq6gkgmvzcl7eppzd3er2w80rgpq9ys6szwh4e33p82jmu42e9zgay44rhg6whr4gq9l6xe6jd7penguqqeua845ptusy3xs5wxwrytm9ck6dh8l739jmw2rfsu8nudvtef90hfn4aj55aw0ezxxf2excmead9vaqvjtuq6s9a580e85rz8mdvp26kuc5vr2llmuexrgxhxx66l400275a3535qpqvemxtpdvuvrwh83qkjl53eagqckyypeq87wey4833z750a5kr5ppfzemeuhtemw6jpty2gznf76zakkj0c. BIP-353 suggests using ₿matt@mattcorallo.com, but will that work for triggering apps with QR codes, clickable links, NFC intent on phones? Could we change it to ₿:matt@mattcorallo.com (but is that a valid link prefix type, and even if it is, is it easy for people to type?)? Alternatively, could we use BTC:matt@mattcorallo.com as a link prefix for BIP-0353?

Possibly this discussion is about BIP-0353 and not a replacement to BIP-0021, but I’m not sure of the latest discussion area for BIP-353 since it is already issued and it doesn’t really pertain to URI prefixes that trigger applications from the operating system, only how wallet applications should behave inside themselves.

stevenroose commented at 2:56 pm on September 30, 2024: contributor

Haven’t read the entire discussion here, but skimmed the proposed changes.

FWIW, we’re thinking of using BIP-21 for Ark addressing so that we can support bolt12 fallback easily. Also it gives flexibility to Ark implementations to support different arguments in a flexible key-value fashion.

The most important change (probably even only) to BIP21 that we need is to make the address part optional. I see that is already being proposed here. The URIs would then look something like this:

0bitcoin:?ark_aspid=deadbeef&ark_pk=02deadbeef&ark_roundconfs=6&lno=lnbc1sdfa

Note that a wallet that doesn’t support Ark can just read the bolt12 argument and deliver over lightning, while an Ark wallet can attempt to deliver straight over Ark.

Also, could this simply be an amendment to BIP21? Instead of getting a new number assigned?

TheBlueMatt commented at 5:30 pm on September 30, 2024: contributor

BIP-0353 uses this BIP (even though it says it uses BIP-0021). This BIP (and BIP-21) result in long URI. This presents a problem for QR code encoding and just simple writing of them in messages, etc. Wondering if we can have another URI form that will resolve a BIP-0353 address?

In generally you should strongly prefer not to do this. BIP 353 even says so explicitly, saying

Bitcoin wallets MUST NOT prefer to use DNS-based resolving when methods with explicit public keys or addresses are available. In other words, if a standard Bitcoin address or direct BIP 21 URI is available or would suffice, Bitcoin wallets MUST prefer to use that instead.

This is because if at all possible we should strongly prefer to avoid trusting the entire DNS+domain infrastructure - if there’s a communication channel between the sender and recipient, that should be used to exchange cryptographic keys directly, rather than introducing an entire centralized stack as a trusted third party. Addressing QR code size is something individual protocols should do on their own (eg BOLT 12 in the lightning world has very small “offers” by just communicating what’s required to fetch further payment instructions.

The most important change (probably even only) to BIP21 that we need is to make the address part optional. I see that is already being proposed here. The URIs would then look something like this:

Nice!

bitcoin:?ark_aspid=deadbeef&ark_pk=02deadbeef&ark_roundconfs=6&lno=lnbc1sdfa

It would be kinda nice to stick with the recommendations here of using bech32 HRPs as the keys in the query parameters. I assume you’ll want some kind of bech32 string to communicate ark recipient info anyway (yay checksums), so might as well use it as-is here?

Also, could this simply be an amendment to BIP21? Instead of getting a new number assigned?

Heh, lots of back-and-forth on that…BIP 21 is pretty ancient, so might as well just say we’re replacing it and mark it DEPRECATED in bold at the top :man_shrugging:

AndySchroder commented at 6:03 pm on September 30, 2024: none

This is because if at all possible we should strongly prefer to avoid trusting the entire DNS+domain infrastructure - if there’s a communication channel between the sender and recipient, that should be used to exchange cryptographic keys directly, rather than introducing an entire centralized stack as a trusted third party. Addressing QR code size is something individual protocols should do on their own (eg BOLT 12 in the lightning world has very small “offers” by just communicating what’s required to fetch further payment instructions.

I get what you are saying, but it seems like BOLT12 offers aren’t really that small. Here is a comparison of QR codes for both examples above (which I took the offer example from your proposed spec).

bitcoin:bc1qztwy6xen3zdtt7z0vrgapmjtfz8acjkfp5fp7l?lno=lno1qsg95t28fvk7aefdum96rgwq3psqzyxvqfcsq3pv8dulvphcpuezmxx5n8h0evrqtx00ch2wevqzp8pvk4qeqqhw37mc9659ses3xkamaksfd9dspq6gkgmvzcl7eppzd3er2w80rgpq9ys6szwh4e33p82jmu42e9zgay44rhg6whr4gq9l6xe6jd7penguqqeua845ptusy3xs5wxwrytm9ck6dh8l739jmw2rfsu8nudvtef90hfn4aj55aw0ezxxf2excmead9vaqvjtuq6s9a580e85rz8mdvp26kuc5vr2llmuexrgxhxx66l400275a3535qpqvemxtpdvuvrwh83qkjl53eagqckyypeq87wey4833z750a5kr5ppfzemeuhtemw6jpty2gznf76zakkj0c

BTC:matt@mattcorallo.com

I think there is a substantial difference, we may want to have the option to do such a thing, but not necessarily encourage it for the reasons you’ve suggested. I think LNURL brings the size down pretty small, and we are going to be competing with that.

TheBlueMatt commented at 6:26 pm on September 30, 2024: contributor

Yea, sadly BOLT12 seeks to have privacy through blinded paths, but receivers who struggle to fit things in QR codes can opt to reduce size by trading off privacy. Also note that if you’re putting a bech32 string in a QR code you really need to uppercase the entire thing, which makes things much less dense.

For people who want tons of options for payments in QR codes, we really should be thinking about something other than BIP 353 - we could publish full payment info in nostr or some other trivial bulletin board (in some kind of encrypted + blinded form where each fresh QR code leads to new payment details to avoid correlation), etc.

AndySchroder commented at 6:39 pm on September 30, 2024: none

For people who want tons of options for payments in QR codes, we really should be thinking about something other than BIP 353 - we could publish full payment info in nostr or some other trivial bulletin board (in some kind of encrypted + blinded form where each fresh QR code leads to new payment details to avoid correlation), etc.

This seems to me a bit like it is getting back to a heavy software stack, but maybe it is unavoidable.

I like to sticking to DNS as the datastore because it is fairly low on the software stack. Wondering if we can in any way to make a more compact URI that includes user@domain plus some hints to find their nameserver and a pubkey used to sign the DNS records? However, maybe at that point the length is approaching that of an offer with a blinded path…

TheBlueMatt commented at 6:57 pm on September 30, 2024: contributor

Wondering if we can in any way to make a more compact URI that includes user@domain plus some hints to find their nameserver and a pubkey used to sign the DNS records? However, maybe at that point the length is approaching that of an offer with a blinded path…

Signing the DNS content via a direct key is great, but you start hitting censorship risk. Just telling people a nameserver IP doesn’t really solve it, either, because in most cases people are trusting a third party to host that who can then censor them. You really just don’t want to use DNS for this.

Drop some stale stuff/respond to some of Murch's comments fff9ae9b51

Add PoP callbacks 62e166e52e

TheBlueMatt commented at 9:42 pm on October 8, 2024: contributor

Responded to some of the feedback, but still need to answer more. Since I’m writing a new BIP I’m gonna take this opportunity to define a new callback scheme which allows for wallets to return proof of payment to the initiating application. This is critical for lightning payments initiated by one app if the app itself isn’t the recipient of the payment.

Further comments from mark fe591e5817

Drop broken reference 7fba7a4cac

TheBlueMatt commented at 2:28 am on October 9, 2024: contributor

Okay, I believe I’ve addressed all the comments here.

mention lightning PoP for BOLT 11 6be4d54353

drop the stupid extra &pop in the response callback 37404d4ada

jonatack removed the label PR Author action required on Oct 17, 2024

in bip-XXXX.mediawiki:84 in 37404d4ada outdated

79+All amounts MUST contain no commas and use a period (.) as the separating character to separate whole numbers and decimal fractions.
80+I.e. amount=50.00 or amount=50 is treated as 50 BTC, and amount=50,000.00 is invalid.
81+
82+=== Proof of Payment ===
83+
84+The URI MAY include a "pop" (or "req-pop") parameter who's 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.

t-bast commented at 4:24 am on October 18, 2024:

nit:

0The 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.

in bip-XXXX.mediawiki:86 in 37404d4ada outdated

81+
82+=== Proof of Payment ===
83+
84+The URI MAY include a "pop" (or "req-pop") parameter who's 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.
85+
86+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 then append the Payment Information to the resulting URI and open it with the default system handler for the given URI.

t-bast commented at 4:32 am on October 18, 2024:

Why did you choose to directly append instead of providing the pop as a query param? It feels easier to parse to me if the wallet adds the pop as one or multiple query params added to the provided URI, for example:

for on-chain payments: txid=<tx_id>&tx=<hex_encoded_tx>
for bolt 11 payments: preimage=<hex_encoded_payment_preimage>
for bolt 12 payments: preimage=<hex_encoded_payment_preimage>&invoice=lni...

TheBlueMatt commented at 8:40 pm on October 18, 2024:

Why did you choose to directly append instead of providing the pop as a query param?

I originally had it this way, but decide its more generic to have the initiating wallet specify the URI how they want, as they can always specify a URI that ends in ?pop= and go from there.

multiple query params

Mmm, good point, I was thinking looking at something else that, duh, we need a way to expose which payment parameter was used…How about just doing payment arg=pop (with a special onchain arg if the address was in the uri body). So like it’d be onchain=hexencodedtx or lightning=preimage or lno=preimage_and_invoice (or whatever format we use for standardized bolt 12 pops)? That way its still clear what the PoP came from, it reuses the keys from the original bitcoin URI so its well known where they’re gonna be (and we don’t have to worry about defining them going forward and making sure things dont conflict) and the initiator can even pass &pop= at the end cause pop=lightning=preimage is a perfectly valid parameter!

t-bast commented at 2:41 am on October 21, 2024:

Good idea, that sounds good to me!

in bip-XXXX.mediawiki:135 in 37404d4ada outdated

130+
131+[foo] means optional, &lt;bar&gt; are placeholders
132+
133+ <nowiki>bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]</nowiki>
134+
135+=== Examples ===

t-bast commented at 4:35 am on October 18, 2024:

A few pop examples would be useful here!

One more attempt at PoP spec, this time with examples 3527ddddc3

if i had a quarter for every time a second-language english speaker corrected my english... 869b99a456

Link BIP 352 and add BIP 351 to list of keys d7c021a102

in bip-XXXX.mediawiki:74 in 869b99a456 outdated

69+
70+*lightning: Lightning BOLT 11 invoices
71+*lno: Lightning BOLT12 offers
72+*sp: Silent Payment addresses
73+
74+New payment instructions using bech32 or bech32m encodings SHOULD reuse their address format's Human Readable Part as the parameter key.

clarkmoody commented at 2:08 pm on October 19, 2024:

Should we mention BIP-351 Private Payments here, which use the form pay1qqqqqqqq?

t-bast approved

t-bast commented at 2:54 am on October 21, 2024: contributor

ACK https://github.com/bitcoin/bips/pull/1555/commits/d7c021a10278391580de33f847d443d5fcc1be53 @dpad85 @robbiehanson what do you think of this? It would be useful to have a prototype implementation of this in Phoenix.

in bip-XXXX.mediawiki:89 in d7c021a102

84+
85+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.
86+
87+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.
88+
89+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.

TheBlueMatt commented at 1:10 pm on October 21, 2024:

I want to get feedback on this line. My thinking here is that there may be some link to a bitcoin: URI in, eg, a social media site or some other context where the user might click it, pay, but then doesn’t want the callback to open a random website that then will reveal the sender’s IP. However, it does limit the utility somewhat. Specifically web apps will be unable to get callbacks directly without registering a URI handler.

I’m curious if/on what platforms registering a URI handler for a web app is annoying to deal with, and if the tradeoff here makes sense. I strongly dont want to introduce an IP leak because of this, but also there may be some platforms where we really have to.

kristapsk commented at 7:46 am on November 14, 2024:

If IP address leak is the only concern, “http” and “https” could be allowed with .onion and .i2p hostnames as exception.

TheBlueMatt commented at 7:45 pm on November 14, 2024:

Sure, some wallets could implement that, but in general if wallets are going to implement by opening with the system-default handler its pretty unlikely that a onion or .i2p is gonna work, so not sure its even worth calling out.

kristapsk commented at 10:49 pm on November 14, 2024:

Yes, system default handler then does not make much sense, but a lot of wallets already implement Tor and some also I2P and could handle http(s) themselves.

TheBlueMatt commented at 2:31 pm on November 15, 2024:

Yea, I guess I just see no need for a remote call for these callbacks - the whole point of the callbacks is to keep things local, if you’re going remote anyway the thing initiating the payment can just ask the recipient if they got it using HTTP…

in bip-XXXX.mediawiki:15 in d7c021a102

10+  Created: 2024-07-13
11+  License: BSD-2-Clause
12+</pre>
13+
14+==Abstract==
15+This BIP proposes a URI scheme for describing Bitcoin payment receipt information.

murchandamus commented at 4:50 pm on November 15, 2024:

“Invoice information” would make sense to me here, or “payment instructions”, but receipt doesn’t make sense to me here.

in bip-XXXX.mediawiki:16 in d7c021a102

11+  License: BSD-2-Clause
12+</pre>
13+
14+==Abstract==
15+This BIP proposes a URI scheme for describing Bitcoin payment receipt information.
16+

murchandamus commented at 7:58 pm on November 15, 2024:

Th Copyright section is missing. Judging from the header:

0
1==Copyright==
2This BIP is licensed under the BSD 2-clause license.

in bip-XXXX.mediawiki:53 in d7c021a102

48+ otherparam     = qchar *qchar [ "=" *qchar ]
49+ reqparam       = "req-" qchar *qchar [ "=" *qchar ]
50+
51+Here, "qchar" corresponds to valid characters of an RFC 3986 URI query component, excluding the "=" and "&" characters, which this BIP takes as separators.
52+
53+The scheme component ("bitcoin:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The query parameter keys are also case-insensitive. Query parameter values and bitcoin address fields may be case-sensitive depending on their content.

murchandamus commented at 8:08 pm on November 15, 2024:

It’s a good change, but please mention the case-insensitivity of query parameter keys in the Backwards Compatibility section, since BIP 21 specified query parameter keys to be case-sensitive.

in bip-XXXX.mediawiki:64 in d7c021a102

59+=== Query Keys ===
60+
61+The following keys are defined generally and apply to any URI regardless of payment instructions:
62+
63+*label: Label for that address (e.g. name of receiver)
64+*address: bitcoin address

murchandamus commented at 8:35 pm on November 15, 2024:

What is the “address” query key used for, if all base58, bech32, and bech32m addresses are permitted in the body, and new payment instructions using bech32[m] should use the HRP? Is the intent to provide a fall-back address from the set of addresses permitted in the body, in case the address in the body is not supported by the sender’s client?

Alternatively, should the body contain the type that is most likely to be supported by the client? Is there a way for the receiver to express which address type they’d prefer if multiple were provided?

If I wanted to express a preference for P2TR, have a P2WPKH fallback, and for people from the last decade also provide a P2PKH address, how would I do that?

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?address=bc1qp2wpkhaddress?bc=bc1ppaytotaprootaddress

bitcoin:bc1ppaytotaprootaddress?address=175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?bc=bc1qp2wpkhaddress

in bip-XXXX.mediawiki:75 in d7c021a102

70+*lightning: Lightning BOLT 11 invoices
71+*lno: Lightning BOLT12 offers
72+*pay: [[bip-0351.mediawiki|BIP 351 Private Payment addresses]]
73+*sp: [[bip-0352.mediawiki|BIP 352 Silent Payment addresses]]
74+
75+New payment instructions using bech32 or bech32m encodings SHOULD reuse their address format's Human Readable Part as the parameter key.

murchandamus commented at 8:57 pm on November 15, 2024:

In the discussion on this PR, some reviewers were suggesting using bc1q and bc1p as parameter keys for native segwit payment instructions. In case that was meant to be proposed here, I wanted to point out that the human-readable part for all native segwit versions is bc.

If you meant to propose that bc1q, bc1p, bc1z, to be used, this could be described as:

0New payment instructions using bech32 or bech32m encodings SHOULD reuse their address format's _human-readable part (HRP)_ as the parameter key. As all native segwit outputs share the same HRP,  Bech32m addresses for future native segwit output types SHOULD use the four-character prefix of the address as the parameter key, e.g. `bc1p`, `bc1z`, `bc1r`, etc.

in bip-XXXX.mediawiki:106 in d7c021a102

101+===Payment identifiers, not person identifiers===
102+Best practices are that a unique address should be used for every transaction on-chain.
103+Therefore, a URI which contains an on-chain payment address MUST NOT represent an exchange of personal information, but a one-time payment instruction. URIs which represent only reusable non-address-reusing payment instructions (like Lightning BOLT12 offers or Silent Payments) MAY be reused as a wallet sees fit.
104+
105+==Forward compatibility==
106+Variables which are prefixed with a req- are considered required.  If a client does not implement any variables which are prefixed with req-, it MUST consider the entire URI invalid.  Any other variables which are not implemented, but which are not prefixed with a req-, can be safely ignored.

murchandamus commented at 9:03 pm on November 15, 2024:

Did you mean “query parameters” instead of variables here?

in bip-XXXX.mediawiki:113 in d7c021a102

108+As future new address types should be added using query parameters rather than the `bitcoinaddress` field, URIs seamlessly support various payment instructions while senders only need to support legacy instructions. This allows old senders to pay newer recipients which offer more modern payment instruction formats.
109+
110+==Backward compatibility==
111+As this BIP is written, several clients already implement a bitcoin: URI scheme similar to this one, however usually without the additional "req-" prefix requirement.  Thus, it is recommended that additional variables prefixed with req- not be used in a mission-critical way until a grace period of 6 months from the finalization of this BIP has passed in order to allow client developers to release new versions, and users of old clients to upgrade.
112+
113+Compared to BIP 21, this document describes standard query parameters containing payment instructions, allows bech32 and bech32m `bitcoinaddress` fields, and allows for URIs with an empty `bitcoinaddress` field. Use of bech32 and bech32m `bitcoinaddress` fields were long-since common practice in 2024, and the `lightning` query parameter storing BOLT 11 payment instructions became common practice in the year or three leading up to 2024. Inclusion of standard query parameters was added to provide guidance on query parameter usage going forward.

murchandamus commented at 9:04 pm on November 15, 2024:

0Compared to BIP 21, this document describes standard query parameters containing payment instructions, allows bech32 and bech32m addresses in the `bitcoinaddress` field, and allows for URIs with an empty `bitcoinaddress` field. Use of bech32 and bech32m `bitcoinaddress` fields were long-since common practice in 2024, and the `lightning` query parameter storing BOLT 11 payment instructions became common practice in the year or three leading up to 2024. Inclusion of standard query parameters was added to provide guidance on query parameter usage going forward.

in bip-XXXX.mediawiki:117 in d7c021a102

112+
113+Compared to BIP 21, this document describes standard query parameters containing payment instructions, allows bech32 and bech32m `bitcoinaddress` fields, and allows for URIs with an empty `bitcoinaddress` field. Use of bech32 and bech32m `bitcoinaddress` fields were long-since common practice in 2024, and the `lightning` query parameter storing BOLT 11 payment instructions became common practice in the year or three leading up to 2024. Inclusion of standard query parameters was added to provide guidance on query parameter usage going forward.
114+
115+Additionally, this BIP describes the "pop" query parameter, which was unused and will be ignored by BIP 21 implementations.
116+
117+Any existing BIP 21 implementation should automatically be fully compliant with this BIP, as the changes only describe existing practice or impact future address format inclusion.

murchandamus commented at 9:07 pm on November 15, 2024:

As mentioned above, BIP 21 required query parameters to be case-sensitive

The rest of the URI is case-sensitive, including the query parameter keys.

while this proposal allows them to be any case. This should be mentioned in the Backward Compatibility section.

in bip-XXXX.mediawiki:134 in d7c021a102

129+This section is non-normative and does not cover all possible syntax.
130+Please see the ABNF grammar above for the normative syntax.
131+
132+[foo] means optional, &lt;bar&gt; are placeholders
133+
134+ <nowiki>bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]</nowiki>

murchandamus commented at 9:10 pm on November 15, 2024:

This section confuses me. It feels like I’m missing some context. Is this supposed to provide a simplified syntax for some part of the implementers? Who is supposed to use the simplified syntax? Under what circumstances should this syntax be used? What are the trade-offs?

in bip-XXXX.mediawiki:143 in d7c021a102

138+==== URIs ====
139+
140+Just the address:
141+ bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W
142+
143+Address with name:

murchandamus commented at 9:11 pm on November 15, 2024:

0Address with recipient’s name as label:

in bip-XXXX.mediawiki:20 in d7c021a102

15+This BIP proposes a URI scheme for describing Bitcoin payment receipt information.
16+
17+==Motivation==
18+The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.
19+
20+This BIP is a modification of [[bip-0021.mediawiki|BIP 0021]] to add information about the modern usage of bitcoin: URIs (including standard query parameters and modern address types) as well as provide forward-looking guidance on how to incorporate new payment instructions. It further adds an optional extension to provide the payment initiator with proof of payment. BIP 21 was based on BIP 20, which was, in turn based off an earlier document by Nils Schneider.

murchandamus commented at 9:15 pm on November 15, 2024:

0This BIP is a modification of [[bip-0021.mediawiki|BIP 0021]] to add information about the modern usage of bitcoin: URIs (including standard query parameters and modern address types) as well as provide forward-looking guidance on how to incorporate new payment instructions. It further adds an optional extension to provide the payment initiator with proof of payment. BIP 21 was based on BIP 20, which was, in turn based on an earlier document by Nils Schneider.

in bip-XXXX.mediawiki:138 in d7c021a102

133+
134+ <nowiki>bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]</nowiki>
135+
136+=== Examples ===
137+
138+==== URIs ====

murchandamus commented at 9:22 pm on November 15, 2024:

Perhaps it would be good to provide a couple more invalid examples. E.g. a common issue might be the reuse of a query parameter.

What is supposed to happen when e.g. two amounts are provided, or two addresses for the same key? Should that fail, use the first, or use the last value for the same query parameter key?

murchandamus commented at 9:23 pm on November 15, 2024: contributor

This is coming along nicely. I left a few comments and questions. Please add the missing Copyright section.

Let’s call this proposal BIP 321.

murchandamus commented at 9:26 pm on November 15, 2024: contributor

There also have been a few questions and comments recently on this proposal. Some of the points brought up in response may be useful to retain as footnotes or in the Rationale.

murchandamus added the label PR Author action required on Nov 15, 2024

murchandamus renamed this:
~~Replace BIP 21 with a new BIP containing information about more modern usage of it~~
BIP 321: URI Scheme (Replace BIP 21 with a new BIP containing information about more modern usage of it)
on Nov 15, 2024

vitorpamplona commented at 11:09 pm on November 15, 2024: none

Any comments on handling multiple invoices to separate receivers initially discussed at https://github.com/lightning/bolts/issues/1111?

Common payment (zap) splits in Nostr have 2-3 receivers to be paid at once. Less common ones might have between 5 to 10 invoices. Some extreme cases include up to 100 lightning invoices to be paid.

They won’t fit in the QR/URI, obviously, but it would be nice to accept what could fit in.

BIP 321: URI Scheme (Replace BIP 21 with a new BIP containing information about more modern usage of it) #1555

BIP 321: URI Scheme (Replace BIP 21 with a new BIP containing information about more modern usage of it) #1555