BIP 321: URI Scheme (Replace BIP 21 with a new BIP containing information about more modern usage of it)#1555
Conversation
|
(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:
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: josibake@07339bd |
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.
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.
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:
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. |
No, they are not the same. This is especially relevant if wallets are using a BIP21 library: my wallet supports new address type
I'm not really sure what you're getting at here? My proposal is that any new payment addresses must use |
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.
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. |
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 |
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). |
Effectively, this is what you get with my proposal:
The only distinction is newer bech32m address types can also be placed in the root. If you're planning to allow |
This is unrelated to the K/V/no-K/V discussion. We can get it either way.
I don't think we should allow this. It would be nice to only have one place to look for a given address type. |
|
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. |
bip-0021.mediawiki
Outdated
| (See also [[#Simpler syntax|a simpler representation of syntax]]) | ||
|
|
||
| bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ] | ||
| bitcoinurn = "bitcoin:" [ bitcoinaddress ] [ "?" bitcoinparams ] |
There was a problem hiding this comment.
I have not been following, but did you consider rejecting empty string after colon, and removing unnecessary interrogation character?
| bitcoinurn = "bitcoin:" [ bitcoinaddress ] [ "?" bitcoinparams ] | |
| bitcoinurn = "bitcoin:" ( bitcoinaddress [ "?" bitcoinparams ] | bitcoinparams ) |
murchandamus
added
Proposed BIP modification
PR Author action required
There was a problem hiding this comment.
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.
bip-0021.mediawiki
Outdated
| *lno: Lightning BOLT12 offers | ||
| *sp: Silent Payment addresses | ||
|
|
||
| New payment instructions using bech32 encodings SHOULD reuse their address format's Human Readable Part as the parameter key. |
There was a problem hiding this comment.
| New payment instructions using bech32 encodings SHOULD reuse their address format's Human Readable Part as the parameter key. | |
| New payment instructions using bech32m as address encoding SHOULD reuse their address format's Human Readable Part as the parameter key. |
There was a problem hiding this comment.
They aren't always addresses.
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
the
2024-03-uris-without-bodies
branch
from
039f1e7 to
76c8049
Compare
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
the
2024-03-uris-without-bodies
branch
from
106b136 to
fedb378
Compare
Done |
|
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. 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 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). |
The point of the proposed change isn't to define 'sp' specifically but to define the rules for new formats going forward.
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.
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. |
|
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. |
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. |
|
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. |
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 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
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. |
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
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. |
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. |
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?) |
|
@vitorpamplona because of the QR thing, I believe the entire thing should be just replaced with some form of P2EP. |
|
I don't know about the QR needs, but we found a way for Android apps to receive multiple intents (uris) and pay them all at the same time. The app just needs to be aware that multiple calls are part of the same payment. |
|
Regarding describing the status quo, I'd like to add two cents:
|
This was already implied, but I've added an example.
While this is great on android, we probably should focus here on cross-platform behavior, and sadly intents are very android-specific. That said, with a PoP URI callback, building an identical UI should be doable, as the URI callback can simply be a deep link back to the calling application which resumes where it left off, no different than if it had received an intent result. Okay, I believe I've addressed all pending feedback! |
murchandamus
left a comment
murchandamus
left a comment
There was a problem hiding this comment.
The last commit reverted the number assignment in the preamble.
|
Hey, what’s the next step here? I can make these minor outstanding editorial changes, if that is all that’s missing. |
TheBlueMatt
force-pushed
the
2024-03-uris-without-bodies
branch
from
dd5093e to
61fd5e5
Compare
|
Apologies. I cleaned up the git history and pushed the fixes requested: $ git diff-tree -U1 dd5093e 61fd5e5
diff --git a/bip-0321.mediawiki b/bip-0321.mediawiki
index 7d8529f..3262f54 100644
--- a/bip-0321.mediawiki
+++ b/bip-0321.mediawiki
@@ -1,3 +1,3 @@
<pre>
- BIP: XXXX
+ BIP: 321
Layer: Applications
@@ -6,6 +6,6 @@
Comments-Summary: No comments yet.
- Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-XXXX
+ Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0321
Status: Draft
Type: Standards Track
- Created: 2024-07-13
+ Created: 2024-11-15
License: BSD-2-Clause
@@ -180,2 +180,5 @@ Many QR codes utilize all-uppercase URIs, which should be handled fine
+A testnet segwit addresses must be included in the `tb` parameter
+ bitcoin:?tb=tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg
+
Characters must be URI encoded properly.
@@ -196,2 +199,5 @@ Multiple proof of payment URIs must not appear, even if they are sometimes prefi
+A testnet segwit addresses must be included in the `tb` parameter, not the `bc` parameter.
+ bitcoin:?bc=tb1qghfhmd4zh7ncpmxl3qzhmq566jk8ckq4gafnmg
+
==== Proof of Payment ==== |
murchandamus
removed
the
PR Author action required
TheBlueMatt
force-pushed
the
2024-03-uris-without-bodies
branch
2 times, most recently
from
1f6b303 to
bd2455c
Compare
murchandamus
left a comment
murchandamus
left a comment
There was a problem hiding this comment.
Some quick editorial feedback, I also intend to read it for content again, but haven’t gotten around to it yet.
bip-0021.mediawiki
Outdated
| =Superseded by BIP 321= | ||
|
|
||
| This BIP has been superseded and replaced with BIP 321. Please see [[bip-0321.mediawiki|BIP 321]] instead. | ||
|
|
||
| =Original BIP= | ||
|
|
There was a problem hiding this comment.
This PR is just adding BIP 321 as Draft, so it might be premature to mark BIP 21 as superseded. It would be more fitting when BIP 321 is moved from Proposed to Final.
Per the BIP 2 process, when BIP 21 is marked as superseded, please use the Superseded-By: <BIP number> header in the preamble for that purpose and update the status of BIP 21 to "Replaced".
There was a problem hiding this comment.
Given the set of changes is small, I'm not really sure its worth waiting? Also is there a new process for moving a BIP to Final? Historically that process has taken ~forever, so definitely not worth waiting that long :)
There was a problem hiding this comment.
As far as I am aware, it hasn’t taken that long in the past year, as long as a reasonable argument was made why something should be final.
Added bech32 and bech32m address types to reflect the newer SegWit and Taproot addresses. Co-Authored-By: Reese Russell <reese.russell@ymail.com>
TheBlueMatt
force-pushed
the
2024-03-uris-without-bodies
branch
2 times, most recently
from
095fd8c to
b44805d
Compare
|
Fixed some editorial comments: $ git diff-tree -U1 bd2455c b44805d
diff --git a/README.mediawiki b/README.mediawiki
index 72b80d3..9faae19 100644
--- a/README.mediawiki
+++ b/README.mediawiki
@@ -126,3 +126,3 @@ Those proposing changes should consider that ultimately consent may rest with th
| Standard
-| Final
+| Replaced
|- style="background-color: #cfffcf"
@@ -985,3 +985,3 @@ Those proposing changes should consider that ultimately consent may rest with th
| Applications
-| Updated URI Scheme
+| URI Scheme
| Matt Corallo
diff --git a/bip-0021.mediawiki b/bip-0021.mediawiki
index 502cb16..cd322a1 100644
--- a/bip-0021.mediawiki
+++ b/bip-0021.mediawiki
@@ -8,5 +8,6 @@
Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0021
- Status: Final
+ Status: Replaced
Type: Standards Track
Created: 2012-01-29
+ Superseded-By: 321
</pre>
diff --git a/bip-0321.mediawiki b/bip-0321.mediawiki
index 3262f54..ec5b2d5 100644
--- a/bip-0321.mediawiki
+++ b/bip-0321.mediawiki
@@ -11,11 +11,15 @@
License: BSD-2-Clause
+ Replaces: 21
</pre>
-==Copyright==
+== Copyright ==
+
This BIP is licensed under the BSD 2-clause license.
-==Abstract==
+== Abstract ==
+
This BIP proposes a URI scheme for describing Bitcoin payment instructions.
-==Motivation==
+== Motivation ==
+
The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.
@@ -24,3 +28,3 @@ This BIP is a modification of [[bip-0021.mediawiki|BIP 0021]] to add information
-==Specification==
+== Specification ==
@@ -32,2 +36,3 @@ They SHOULD require the user to manually approve each payment individually, thou
=== Operating system integration ===
+
Graphical bitcoin clients SHOULD register themselves as the handler for the "bitcoin:" URI scheme by default, if no other handler is already registered. If there is already a registered handler, they MAY prompt the user to change it once when they first run the client.
@@ -104,3 +109,4 @@ Other payment schemes will define their own Payment Information format. This BIP
-===Payment identifiers, not person identifiers===
+=== Payment identifiers, not person identifiers ===
+
Best practices are that a unique address should be used for every transaction on-chain.
@@ -108,3 +114,4 @@ Therefore, a URI which contains an on-chain payment address MUST NOT represent a
-==Forward compatibility==
+== Forward compatibility ==
+
Query parameter keys which are prefixed with a req- are considered required. If a client does not implement handling a query parameter which has a key prefixed with req-, it MUST consider the entire URI invalid. Any other query parameters which are not implemented, but which are not prefixed with a req-, can be safely ignored.
@@ -113,3 +120,4 @@ As future new address types should be added using query parameters rather than t
-==Backward compatibility==
+== Backward compatibility ==
+
Compared to BIP 21, this document describes standard query parameters containing payment instructions, makes query parameters case-insensitive, 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. |
TheBlueMatt
force-pushed
the
2024-03-uris-without-bodies
branch
from
b44805d to
7634fe5
Compare
|
Okay, dropped the changes to BIP 21 but updated BIP 321 to mark it |
murchandamus
left a comment
murchandamus
left a comment
There was a problem hiding this comment.
Did another full read of the document. This looks almost ready to be merged, but I was a bit surprised by the dangling "Proof of Payment" section. Could you please have a look at that and let me know whether that is intended or amend 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 321 to suggest that future address formats do this. Further, it updates BIP 321 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. Finally, it defines a new query parameter, the `pop` parameter, which allows the initiating application to receive callbacks for proof of payment completion.
TheBlueMatt
force-pushed
the
2024-03-uris-without-bodies
branch
from
7634fe5 to
f5cb29f
Compare
|
Oops, sorry, indeed, I moved that paragraph into the rationale section and made it a subsection. |
17 participants
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.