You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Copy file name to clipboardExpand all lines: bip-XXXX.mediawiki
+34-6
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@
10
10
Created: 2024-07-13
11
11
</pre>
12
12
13
-
This BIP is a modification of an earlier [[bip-0020.mediawiki|BIP 0020]] by Luke Dashjr. BIP 0020 was based off an earlier document by Nils Schneider. The alternative payment amounts in BIP 0020 have been removed.
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
14
15
15
==Abstract==
16
16
This BIP proposes a URI scheme for making Bitcoin payments.
@@ -38,7 +38,7 @@ Elements of the query component may contain characters outside the valid range.
38
38
39
39
(See also [[#Simpler syntax|a simpler representation of syntax]])
@@ -50,14 +50,27 @@ Elements of the query component may contain characters outside the valid range.
50
50
51
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
52
53
-
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.
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.
54
58
55
59
=== Query Keys ===
56
60
61
+
The following keys are defined generally and apply to any URI regardless of payment instructions:
62
+
57
63
*label: Label for that address (e.g. name of receiver)
58
64
*address: bitcoin address
59
65
*message: message that describes the transaction to the user ([[#Examples|see examples below]])
60
-
*(others): optional, for future extensions
66
+
67
+
The following keys are currently defined for payment instructions of various forms:
68
+
69
+
*lightning: Lightning BOLT 11 invoices
70
+
*lno: Lightning BOLT12 offers
71
+
*sp: Silent Payment addresses
72
+
73
+
New payment instructions using bech32 or bech32m encodings SHOULD reuse their address format's Human Readable Part as the parameter key.
61
74
62
75
==== Transfer amount ====
63
76
@@ -71,8 +84,8 @@ For example, so long as the majority of users work in BTC units, values should a
71
84
== Rationale ==
72
85
73
86
===Payment identifiers, not person identifiers===
74
-
Current best practices are that a unique address should be used for every transaction.
75
-
Therefore, a URI scheme should not represent an exchange of personal information, but a one-time payment.
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.
76
89
77
90
===Accessibility (URI scheme name)===
78
91
Should someone from the outside happen to see such a URI, the URI scheme name already gives a description.
@@ -83,9 +96,15 @@ Also, very likely, what he will find are mostly technical specifications - not t
83
96
==Forward compatibility==
84
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.
85
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.
100
+
86
101
==Backward compatibility==
87
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.
88
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.
105
+
106
+
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.
107
+
89
108
== Appendix ==
90
109
91
110
=== Simpler syntax ===
@@ -111,6 +130,15 @@ Request 20.30 BTC to "Luke-Jr":
0 commit comments