Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 13 commits into
base: master
Choose a base branch
from
Open

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

Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8a93e77
Copy BIP 21 into a new BIP XXXX with only the header changed
TheBlueMatt Jul 13, 2024
ab95193
Update to include newer address types
dplusplus1024 Dec 19, 2022
ff71934
Update BIP XXXX with information about more modern usage of it
TheBlueMatt Jul 13, 2024
836ef06
f add examples of silent payment addresses
TheBlueMatt Jul 13, 2024
fff9ae9
Drop some stale stuff/respond to some of Murch's comments
TheBlueMatt Oct 8, 2024
62e166e
Add PoP callbacks
TheBlueMatt Oct 8, 2024
fe591e5
Further comments from mark
TheBlueMatt Oct 9, 2024
7fba7a4
Drop broken reference
TheBlueMatt Oct 9, 2024
6be4d54
mention lightning PoP for BOLT 11
TheBlueMatt Oct 17, 2024
37404d4
drop the stupid extra &pop in the response callback
TheBlueMatt Oct 17, 2024
3527ddd
One more attempt at PoP spec, this time with examples
TheBlueMatt Oct 18, 2024
869b99a
if i had a quarter for every time a second-language english speaker c…
TheBlueMatt Oct 18, 2024
d7c021a
Link BIP 352 and add BIP 351 to list of keys
TheBlueMatt Oct 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Further comments from mark
  • Loading branch information
@TheBlueMatt
TheBlueMatt committed Oct 9, 2024
commit fe591e58173e51a1df4cdb792d6a38d4302a9d43
19 changes: 6 additions & 13 deletions bip-XXXX.mediawiki
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ This BIP proposes a URI scheme for describing Bitcoin payment receipt informatio
==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.
TheBlueMatt marked this conversation as resolved.
Show resolved Hide resolved

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. 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.
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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 on an earlier document by Nils Schneider.


==Specification==

Expand Down Expand Up @@ -104,12 +104,14 @@ Therefore, a URI which contains an on-chain payment address MUST NOT represent a
==Forward compatibility==
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you mean "query parameters" instead of variables here?


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

==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.

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.
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Compared 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.


Additionally, this BIP describes the "pop" query parameter, which was unused and will be ignored by BIP 21 implementations.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


Expand All @@ -124,7 +126,7 @@ For payments completed on-chain, this is largely addressed by having the payment
=== Simpler syntax ===

This section is non-normative and does not cover all possible syntax.
Please see the BNF grammar above for the normative syntax.
Please see the ABNF grammar above for the normative syntax.

[foo] means optional, <bar> are placeholders

Expand Down Expand Up @@ -169,12 +171,3 @@ Some future version that has variables which are (currently) not understood but
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999

Characters must be URI encoded properly.

== Reference Implementations ==
=== Bitcoin clients ===
* Bitcoin-Qt supports the old version of Bitcoin URIs (ie without the req- prefix), with Windows and KDE integration as of commit 70f55355e29c8e45b607e782c5d76609d23cc858.

=== Libraries ===
* Javascript - https://github.com/bitcoinjs/bip21
* Java - https://github.com/SandroMachado/BitcoinPaymentURI
* Swift - https://github.com/SandroMachado/BitcoinPaymentURISwift