mirror of
https://github.com/bitcoinbook/bitcoinbook
synced 2024-11-29 19:38:25 +00:00
224 lines
7.8 KiB
Plaintext
224 lines
7.8 KiB
Plaintext
---------------------------------------------------
|
||
BIP: 21
|
||
Title: URI Scheme
|
||
Author: Nils Schneider <nils.schneider@gmail.com>
|
||
Matt Corallo <bip21@bluematt.me>
|
||
Status: Accepted
|
||
Type: Standards Track
|
||
Created: 2012-01-29
|
||
---------------------------------------------------
|
||
|
||
This BIP is a modification of an earlier link: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.
|
||
|
||
[[abstract]]
|
||
Abstract
|
||
~~~~~~~~
|
||
|
||
This BIP proposes a URI scheme for making Bitcoin payments.
|
||
|
||
[[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.
|
||
|
||
[[specification]]
|
||
Specification
|
||
~~~~~~~~~~~~~
|
||
|
||
[[general-rules-for-handling-important]]
|
||
General rules for handling (important!)
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Bitcoin clients MUST NOT act on URIs without getting the user's
|
||
authorization. They SHOULD require the user to manually approve each
|
||
payment individually, though in some cases they MAY allow the user to
|
||
automatically make this decision.
|
||
|
||
[[operating-system-integration]]
|
||
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.
|
||
|
||
[[general-format]]
|
||
General Format
|
||
^^^^^^^^^^^^^^
|
||
|
||
Bitcoin URIs follow the general format for URIs as set forth in RFC
|
||
3986. The path component consists of a bitcoin address, and the query
|
||
component provides additional payment options.
|
||
|
||
Elements of the query component may contain characters outside the valid
|
||
range. These must first be encoded according to UTF-8, and then each
|
||
octet of the corresponding UTF-8 sequence must be percent-encoded as
|
||
described in RFC 3986.
|
||
|
||
[[abnf-grammar]]
|
||
ABNF grammar
|
||
^^^^^^^^^^^^
|
||
|
||
(See also link:#Simpler_syntax[a simpler representation of syntax])
|
||
|
||
`bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]` +
|
||
`bitcoinaddress = *base58` +
|
||
`bitcoinparams = bitcoinparam [ "&" bitcoinparams ]` +
|
||
`bitcoinparam = [ amountparam / labelparam / messageparam / otherparam / reqparam ]` +
|
||
`amountparam = "amount=" *digit [ "." *digit ]` +
|
||
`labelparam = "label=" *qchar` +
|
||
`messageparam = "message=" *qchar` +
|
||
`otherparam = qchar *qchar [ "=" *qchar ]` +
|
||
`reqparam = "req-" qchar *qchar [ "=" *qchar ]`
|
||
|
||
Here, "qchar" corresponds to valid characters of an RFC 3986 URI query
|
||
component, excluding the "=" and "&" characters, which this BIP takes as
|
||
separators.
|
||
|
||
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.
|
||
|
||
[[query-keys]]
|
||
Query Keys
|
||
^^^^^^^^^^
|
||
|
||
* label: Label for that address (e.g. name of receiver)
|
||
* address: bitcoin address
|
||
* message: message that describes the transaction to the user
|
||
(link:#Examples[see examples below])
|
||
* size: amount of base bitcoin units (link:#Transfer_amount/size[see
|
||
below])
|
||
* (others): optional, for future extensions
|
||
|
||
[[transfer-amountsize]]
|
||
Transfer amount/size
|
||
++++++++++++++++++++
|
||
|
||
If an amount is provided, it MUST be specified in decimal BTC. All
|
||
amounts MUST contain no commas and use a period (.) as the separating
|
||
character to separate whole numbers and decimal fractions. I.e.
|
||
amount=50.00 or amount=50 is treated as 50 BTC, and amount=50,000.00 is
|
||
invalid.
|
||
|
||
Bitcoin clients MAY display the amount in any format that is not
|
||
intended to deceive the user. They SHOULD choose a format that is
|
||
foremost least confusing, and only after that most reasonable given the
|
||
amount requested. For example, so long as the majority of users work in
|
||
BTC units, values should always be displayed in BTC by default, even if
|
||
mBTC or TBC would otherwise be a more logical interpretation of the
|
||
amount.
|
||
|
||
[[rationale]]
|
||
Rationale
|
||
~~~~~~~~~
|
||
|
||
[[payment-identifiers-not-person-identifiers]]
|
||
Payment identifiers, not person identifiers
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Current best practices are that a unique address should be used for
|
||
every transaction. Therefore, a URI scheme should not represent an
|
||
exchange of personal information, but a one-time payment.
|
||
|
||
[[accessibility-uri-scheme-name]]
|
||
Accessibility (URI scheme name)
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
Should someone from the outside happen to see such a URI, the URI scheme
|
||
name already gives a description. A quick search should then do the rest
|
||
to help them find the resources needed to make their payment. Other
|
||
proposed names sound much more cryptic; the chance that someone googles
|
||
that out of curiosity are much slimmer. Also, very likely, what he will
|
||
find are mostly technical specifications - not the best introduction to
|
||
bitcoin.
|
||
|
||
[[forward-compatibility]]
|
||
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.
|
||
|
||
[[backward-compatibility]]
|
||
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]]
|
||
Appendix
|
||
~~~~~~~~
|
||
|
||
[[simpler-syntax]]
|
||
Simpler syntax
|
||
^^^^^^^^^^^^^^
|
||
|
||
This section is non-normative and does not cover all possible syntax.
|
||
Please see the BNF grammar above for the normative syntax.
|
||
|
||
[foo] means optional, <bar> are placeholders
|
||
|
||
`bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]`
|
||
|
||
[[examples]]
|
||
Examples
|
||
^^^^^^^^
|
||
|
||
Just the address:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W`]
|
||
|
||
Address with name:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr`]
|
||
|
||
Request 20.30 BTC to "Luke-Jr":
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr`]
|
||
|
||
Request 50 BTC with message:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz`]
|
||
|
||
Some future version that has variables which are (currently) not
|
||
understood and required and thus invalid:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req-somethingyoudontunderstand=50&req-somethingelseyoudontget=999`]
|
||
|
||
Some future version that has variables which are (currently) not
|
||
understood but not required and thus valid:
|
||
|
||
bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999[`bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999`]
|
||
|
||
Characters must be URI encoded properly.
|
||
|
||
[[reference-implementations]]
|
||
Reference Implementations
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
[[bitcoin-clients]]
|
||
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.
|
||
|