Skip to content

BIP321: add reference implementation, mention BIP21 replacement #1983

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

Merged
merged 2 commits into from
Oct 1, 2025
Merged

BIP321: add reference implementation, mention BIP21 replacement #1983

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
daf64c4
BIP321: add reference implementation section
jonatack Sep 24, 2025
c16a336
BIP321: mention replacement of BIP21
jonatack Sep 24, 2025
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
8 changes: 7 additions & 1 deletion bip-0321.mediawiki
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ This BIP proposes a URI scheme for describing Bitcoin payment instructions.

The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.

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.
This BIP is a modification and intended replacement 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 @@ -120,6 +120,12 @@ For payments completed on-chain, this is largely addressed by having the payment

In order to avoid inadvertently revealing the sender's IP address or other information to the recipient, proof URIs must only be opened when they will simply switch to another locally-installed application (i.e. the application which initiated the payment). When clicking a URI from a website, the website should already have plenty of logic on its backend to process payment completion and a proof-of-payment callback is unnecessary.

== Reference Implementation ==

Documentation: https://docs.rs/bitcoin-payment-instructions

Code repository: https://github.com/rust-bitcoin/bitcoin-payment-instructions

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