From fedb378b24a3f2c1c2b9f88b68c4b0e124adfd2c Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Thu, 30 May 2024 21:52:00 +0000 Subject: [PATCH] f tweaks from murch --- bip-0021.mediawiki | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/bip-0021.mediawiki b/bip-0021.mediawiki index b1bef6a49c..c003675afd 100644 --- a/bip-0021.mediawiki +++ b/bip-0021.mediawiki @@ -55,7 +55,7 @@ The scheme component ("bitcoin:") is case-insensitive, and implementations must === Bitcoin Address === -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. +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. === Query Keys === @@ -71,7 +71,7 @@ The following keys are currently defined for payment instructions of various for *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. +New payment instructions using bech32 or bech32m encodings SHOULD reuse their address format's Human Readable Part as the parameter key. ==== Transfer amount ==== @@ -85,8 +85,8 @@ For example, so long as the majority of users work in BTC units, values should a == Rationale == ===Payment identifiers, not person identifiers=== -Current best practices are that a unique address should be used for every transaction on-chain. -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. +Best practices are that a unique address should be used for every transaction on-chain. +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. ===Accessibility (URI scheme name)=== Should someone from the outside happen to see such a URI, the URI scheme name already gives a description. @@ -99,6 +99,9 @@ Variables which are prefixed with a req- are considered required. If a client d 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. +==Backward compatibility== +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. + == Appendix == === Simpler syntax === @@ -140,3 +143,7 @@ Characters must be URI encoded properly. * Javascript - https://github.com/bitcoinjs/bip21 * Java - https://github.com/SandroMachado/BitcoinPaymentURI * Swift - https://github.com/SandroMachado/BitcoinPaymentURISwift + +=== Changelog === + +In 2024, this document was changed to describe standard query parameters containing payment instructions, allow 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.