Merge pull request #1 from TheBlueMatt/master

Various update to bip 21.

1 files changed, 29 insertions, 43 deletions

diff --git a/bip-0021.md b/bip-0021.md
index 1ece4f9..55d3143 100644
--- a/bip-0021.md
+++ b/bip-0021.md
@@ -2,10 +2,10 @@
   BIP: 21
   Title: URI Scheme
   Author: Nils Schneider <nils.schneider@gmail.com>
-          Matt Corallo
+          Matt Corallo <bip21@bluematt.me>
   Status: Draft
   Type: Standards Track
-  Created: 29-01-2011
+  Created: 29-01-2012
 </pre>
 
 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.
@@ -30,16 +30,15 @@ Graphical bitcoin clients SHOULD register themselves as the handler for the "bit
 
 (See also [[#Simpler syntax|a simpler representation of syntax]])
 
- bitcoinurn      = "bitcoin:" bitcoinaddress [ ";version=" bitcoinversion ] [ "?" bitcoinparams ]
- bitcoinaddress  = base58 *base58
- bitcoinversion  = "1.0"
- bitcoinparams   = *bitcoinparam
- bitcoinparam    = amountparam | labelparam | messageparam | sendparam | otherparam
- amountparam     = "amount=" *digit [ "." *digit ]
- labelparam      = "label=" *pchar
- messageparam    = "message=" *pchar
- sendparam       = "send=" *pchar
- otherparam      = pchar *pchar "=" *pchar
+ bitcoinurn     = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]
+ bitcoinaddress = base58 *base58
+ bitcoinparams  = *bitcoinparam
+ bitcoinparam   = amountparam | labelparam | messageparam | otherparam | reqparam
+ amountparam    = "amount=" *digit [ "." *digit ]
+ labelparam     = "label=" *pchar
+ messageparam   = "message=" *pchar
+ otherparam     = pchar *pchar "=" *pchar
+ reqparam       = "req:" pchar *pchar "=" *pchar
 
 === Query Keys ===
 
@@ -47,18 +46,17 @@ Graphical bitcoin clients SHOULD register themselves as the handler for the "bit
 *address: bitcoin address
 *message: message that shown to the user after scanning the QR code
 *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
 
 ==== Transfer amount/size ====
 
-If an amount is provided, it must be specified in decimal BTC.
-I.e. amount=50.00 is treated as 50 BTC.
+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===
@@ -72,10 +70,10 @@ Other proposed names sound much more cryptic; the chance that someone googles th
 Also, very likely, what he will find are mostly technical specifications - not the best introduction to bitcoin.
 
 ==Forward compatibility==
-We want URIs generated in 2011 to still work in 2036: think about extensibility.
-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.
-Make it possible for later generations to improve our work, to mend our errors, without breaking the URIs created now.
+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 ==
 
@@ -86,45 +84,33 @@ Please see the [[#BNF grammar|BNF grammar]] above for the normative syntax.
 
 [foo] means optional, <bar> are placeholders
 
- bitcoin:<address>[;version=1.0][?amount=<amount>][?label=<label>][?message=<message>][?send=<private key>]
+ bitcoin:<address>[?amount=<amount>][?label=<label>][?message=<message>]
 
 === Examples ===
 
 Just the address:
- bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L
+ bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W
 
 Address with name:
- bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?label=Luke-Jr
+ bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?label=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:
- bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz
-
-Send 1 BTC:
- bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=1&send=S4b3N3oGqDqR5jNuxEvDwf
-
-Characters must be URI encoded properly.
+ bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=50&label=Luke-Jr&message=Donation%20for%20project%20xyz
 
-===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:
+Some future version that has variables which are (currently) not understood and required and thus invalid:
+ bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?req:somethingyoudontunderstand=50&req:somethingelseyoudontget=999
 
- <pubkey> OP_CHECKSIG
+Some future version that has variables which are (currently) not understood but not required and thus valid:
+ bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?somethingyoudontunderstand=50&somethingelseyoudontget=999
 
-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.
+Characters must be URI encoded properly.
 
 == Reference Implementations ==
 === 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]]
 [[Category:Technical]]