Difference between revisions of "BIP 0021"

From Bitcoin Wiki
Jump to: navigation, search
(BIP 21 aka BIP 20 without Luke's crap which was voted against.)
 
(Update BIP text with latest version from https://github.com/bitcoin/bips/blob/b5723035e23896d0/bip-0021.mediawiki)
 
(17 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
{{bip}}
 +
{{BipMoved|bip-0021.mediawiki}}
 +
 
<pre>
 
<pre>
   BIP: 20
+
   BIP: 21
 +
  Layer: Applications
 
   Title: URI Scheme
 
   Title: URI Scheme
   Author: Luke Dashjr <luke+bip@dashjr.org>
+
   Author: Nils Schneider <nils.schneider@gmail.com>
          Nils Schneider <nils.schneider@gmail.com>
+
          Matt Corallo <bip21@bluematt.me>
 +
  Comments-Summary: No comments yet.
 +
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0021
 
   Status: Final
 
   Status: Final
 
   Type: Standards Track
 
   Type: Standards Track
   Created: 10-01-2011
+
   Created: 2012-01-29
 
</pre>
 
</pre>
 +
 +
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.
  
 
==Abstract==
 
==Abstract==
Line 25: Line 33:
 
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.
 
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.
  
=== BNF grammar ===
+
=== 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 ===
  
 
(See also [[#Simpler syntax|a simpler representation of syntax]])
 
(See also [[#Simpler syntax|a simpler representation of syntax]])
  
  bitcoinurn     = "bitcoin:" bitcoinaddress [ ";version=" bitcoinversion ] [ "?" bitcoinparams ]
+
  bitcoinurn     = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]
  bitcoinaddress = base58 *base58
+
  bitcoinaddress = *base58
  bitcoinversion = "1.0"
+
  bitcoinparams = bitcoinparam [ "&" bitcoinparams ]
bitcoinparams   = *bitcoinparam
+
  bitcoinparam   = [ amountparam / labelparam / messageparam / otherparam / reqparam ]
  bitcoinparam   = amountparam | labelparam | messageparam | sendparam | otherparam
+
  amountparam   = "amount=" *digit [ "." *digit ]
  amountparam     = "amount=" *digit [ "." *digit ]
+
  labelparam     = "label=" *qchar
  labelparam     = "label=" *pchar
+
  messageparam   = "message=" *qchar
  messageparam   = "message=" *pchar
+
  otherparam    = qchar *qchar [ "=" *qchar ]
  sendparam      = "send=" *pchar
+
  reqparam      = "req-" qchar *qchar [ "=" *qchar ]
  otherparam      = pchar *pchar "=" *pchar
+
 
 +
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 ===
Line 44: Line 61:
 
*label: Label for that address (e.g. name of receiver)
 
*label: Label for that address (e.g. name of receiver)
 
*address: bitcoin address
 
*address: bitcoin address
*message: message that shown to the user after scanning the QR code
+
*message: message that describes the transaction to the user ([[#Examples|see examples below]])
 
*size: amount of base bitcoin units ([[#Transfer amount/size|see below]])
 
*size: amount of base bitcoin units ([[#Transfer amount/size|see below]])
*send: used to send bitcoin, rather than to request them
 
 
*(others): optional, for future extensions
 
*(others): optional, for future extensions
  
 
==== Transfer amount/size ====
 
==== Transfer amount/size ====
  
If an amount is provided, it must be specified in decimal BTC.
+
If an amount is provided, it MUST be specified in decimal BTC.
I.e. amount=50.00 is treated as 50 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.
 
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.
 
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.
 
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 ==
  
Line 71: Line 87:
  
 
==Forward compatibility==
 
==Forward compatibility==
We want URIs generated in 2011 to still work in 2036: think about extensibility.
+
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.
Of course we can make only educated guesses about the future, but don't act as if there is none.
+
 
This should be the best we can do, but it should not be seen as set in stone.
+
==Backward compatibility==
Make it possible for later generations to improve our work, to mend our errors, without breaking the URIs created now.
+
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 ==
Line 81: Line 97:
  
 
This section is non-normative and does not cover all possible syntax.
 
This section is non-normative and does not cover all possible syntax.
Please see the [[#BNF grammar|BNF grammar]] above for the normative syntax.
+
Please see the BNF grammar above for the normative syntax.
  
[foo] means optional, <bar> are placeholders
+
[foo] means optional, &lt;bar&gt; are placeholders
  
  bitcoin:<address>[;version=1.0][?amount=<amount>][?label=<label>][?message=<message>][?send=<private key>]
+
  <nowiki>bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]</nowiki>
  
 
=== Examples ===
 
=== Examples ===
  
 
Just the address:
 
Just the address:
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L
+
  bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W
  
 
Address with name:
 
Address with name:
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?label=Luke-Jr
+
  bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr
  
 
Request 20.30 BTC to "Luke-Jr":
 
Request 20.30 BTC to "Luke-Jr":
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=20.3&label=Luke-Jr
+
  bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=20.3&label=Luke-Jr
  
 
Request 50 BTC with message:
 
Request 50 BTC with message:
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz
+
  bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz
  
Send 1 BTC:
+
Some future version that has variables which are (currently) not understood and required and thus invalid:
  bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=1&send=S4b3N3oGqDqR5jNuxEvDwf
+
  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
  
 
Characters must be URI encoded properly.
 
Characters must be URI encoded properly.
 
===Sending money via private key===
 
To send a payment to someone else first construct a new keypair. You may want to use a [[mini private key format]], or you may also use a full private key for more security depending on the amount being sent and how long you expect to pass before a claim. Now create and publish a transaction with an output of the amount you wish to send. Use this script in that output:
 
 
<pubkey> OP_CHECKSIG
 
 
Construct an address from the public key. Encode the URI as below:
 
 
bitcoin:<address>?send=<base 58 encoded private key>
 
 
You may optionally include amount or message fields as well. In a wallet to claim money sent this way search for an incoming transaction with the output script form above, where <address> matches the public key in the script. When you find the transaction create a claim transaction with an input script of this form:
 
 
<sig>
 
 
This claims the money you were sent. Until your claim transaction has confirmed the sender may take their money back.
 
  
 
== Reference Implementations ==
 
== Reference Implementations ==
 
=== Bitcoin clients ===
 
=== Bitcoin clients ===
* [[Bitcoin-Qt]] supports all valid Bitcoin URIs, with Windows and KDE integration as of commit 70f55355e29c8e45b607e782c5d76609d23cc858.
+
* Bitcoin-Qt supports the old version of Bitcoin URIs (ie without the req- prefix), with Windows and KDE integration as of commit 70f55355e29c8e45b607e782c5d76609d23cc858.
  
[[Category:Developer]]
+
=== Libraries ===
[[Category:Technical]]
+
* Javascript - https://github.com/bitcoinjs/bip21
[[Category:BIP|D]]
+
* Java - https://github.com/SandroMachado/BitcoinPaymentURI
 +
* Swift - https://github.com/SandroMachado/BitcoinPaymentURISwift

Latest revision as of 17:58, 24 September 2019

This page describes a BIP (Bitcoin Improvement Proposal).
Please see BIP 2 for more information about BIPs and creating them. Please do not just create a wiki page.

Please do not modify this page. This is a mirror of the BIP from the source Git repository here.

  BIP: 21
  Layer: Applications
  Title: URI Scheme
  Author: Nils Schneider <nils.schneider@gmail.com>
          Matt Corallo <bip21@bluematt.me>
  Comments-Summary: No comments yet.
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0021
  Status: Final
  Type: Standards Track
  Created: 2012-01-29

This BIP is a modification of an earlier 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

This BIP proposes a URI scheme for making Bitcoin payments.

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

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

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

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

(See also 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

  • label: Label for that address (e.g. name of receiver)
  • address: bitcoin address
  • message: message that describes the transaction to the user (see examples below)
  • size: amount of base bitcoin units (see below)
  • (others): optional, for future extensions

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

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)

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

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

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

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

Just the address:

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W

Address with name:

bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=Luke-Jr

Request 20.30 BTC to "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

Some future version that has variables which are (currently) not understood and required and thus invalid:

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

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