BIP 0020

This is about creating a URI scheme for bitcoin. Previous discussion was in this forum thread. x-btc specification is at x-btc.

RFC 3986

the following is taken from wikipedia

Internet standard STD 66 (also RFC 3986) defines the generic syntax to be used in all URI schemes. Every URI is defined as consisting of four parts, as follows:

<scheme name> : <hierarchical part> [ ? <query> ] [ # <fragment> ]

The scheme name consists of a letter followed by any combination of letters, digits, and the plus ("+"), period ("."), or hyphen ("-") characters; and is terminated by a colon (":").

The hierarchical part of the URI is intended to hold identification information hierarchical in nature. Usually this part begins with a double forward slash ("//"), followed by an authority part and an optional path.

• The authority part holds an optional user information part terminated with "@" (e.g. username:password@), a hostname (i.e. domain name or IP address), and an optional port number preceded by a colon ":".

• The path part is a sequence of segments (conceptually similar to directories, though not necessarily representing them) separated by a forward slash ("/"). Each segment can contain parameters separated from it using a semicolon (";"), though this is rarely used in practice.

The query is an optional part separated with a question mark, which contains additional identification information which is not hierarchical in nature. The query string syntax is not generically defined, but is commonly organized as a sequence of <key>=<value> pairs separated by a semicolon or separated by an ampersand, for example:

Semicolon: key1=value1;key2=value2;key3=value3
Ampersand: key1=value1&key2=value2&key3=value3

The fragment is an optional part separated from the front parts by a hash ("#"). It holds additional identifying information that provides direction to a secondary resource, e.g. a section heading in an article identified by the remainder of the URI. When the primary resource is an HTML document, the fragment is often an id attribute of a specific element and web browsers will make sure this element is visible.

Proposed specification

[] means optional, <> are placeholders

bitcoin:<address>[?][amount=<size>][&][label=<label>][&][message=<message>]

Query Keys

• label: Label for that address (e.g. name of receiver)
• address: bitcoin address
• message: optional message that is shown to the user after scanning the QR code
• size: amount of base bitcoin units (cuBTCents/TBCᵇ-- NOT full DecimalBitCoins/BTC nor TonalBitCoins/TBC; see below)

Transfer amount/size

If an amount is provided, it may be specified either in decimal or, when prefixed with a single "x" character, hexadecimal. The number SHOULD be followed by "X" <digits> to signify an exponent to the base multiplier. That is, "X8" multiplies your number by 100,000,000. For decimal values, this means the standard BTC unit. For hexadecimal values, this means ᵇTBC units (which are equivalent to 42.94967296 BTC). If exponent is omitted, implementations SHOULD assume X8 for decimal numbers, and X4 for hexadecimal numbers. I.e. amount=50.00 is treated as 50 BTC, and amount=x40 is treated as 40 TBC. When specifying bitcoin base units, "X0" SHOULD be used.

Examples

Just the address:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L

Address with name:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?label=Luke-Jr

Request to send 20.30 BTC to "Luke-Jr":

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=20.3X8&label=Luke-Jr

Request to send 400 TBC:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=x400X4

Request to send 4000 TBC:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=x4X7

Request to send 5 uBTC:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=5X2

Request to send 50 BTC with message:

bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L?amount=50X8&label=Luke-Jr&message=Donation%20for%20project%20xyz

Characters must be URI encoded properly.

BNF syntax

bitcoinurn      = "bitcoin:" bitcoinaddress [ ";version=" bitcoinversion ] [ "?" bitcoinparams ]
bitcoinaddress  = FIXME :)
bitcoinversion  = "1.0"
bitcoinparams   = *bitcoinparam
bitcoinparam    = amountparam | labelparam | messageparam
amountparam     = "amount=" amount
amount          = amountdecimal | amounthex
amountdecimal   = digits [ "X" digits ]
amounthex       = "x" hexdigits [ "X" hexdigits ]
labelparam      = "label=" *uchar
messageparam    = "label=" *uchar

Parsing amount

ECMAScript

reAmount = /^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$/i;
function parseAmount(txt) {
	var m = txt.match(reAmount);
	return m[5] ? (
		(
			parseInt(m[5], 16) +
			(m[7] ? (parseInt(m[7], 16) * Math.pow(16, -(m[7].length))) : 0)
		) * (
			m[9] ? Math.pow(16, parseInt(m[9], 16)) : 0x10000
		)
	) : (
			m[2]
		*
			(m[4] ? Math.pow(10, m[4]) : 1e8)
	);
}

Python

m = re.match(r'^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$', amount, re.IGNORECASE)
if m.group(5):
    amount = float(int(m.group(5), 16))
    if m.group(7):
        amount += float(int(m.group(7), 16)) * pow(16, -(len(m.group(7))))
    if m.group(9):
        amount *= pow(16, int(m.group(9), 16))
    else:
        amount *= 0x10000
else:
    amount = Decimal(m.group(2))
    if m.group(4):
        amount *= 10 ** int(m.group(4))
    else:
        amount *= 100000000

C#

Regex amountExpression = new Regex(@"^(([\d.]+)(X(\d+))?|x([\da-f]*)(\.([\da-f]*))?(X([\da-f]+))?)$", RegexOptions.IgnoreCase);
Match match = amountExpression.Match(value);
if (match.Success)
{
    if (match.Groups[5].Success)
    {
        long hexDecimal = 0;
        if (match.Groups[7].Success)
            hexDecimal = Convert.ToInt64(match.Groups[7].Value, 16) * (long)Math.Pow(16, -match.Groups[7].Length);

        long hexExponent = 0x10000;
        if (match.Groups[9].Success)
            hexExponent = (long)Math.Pow(16, Convert.ToInt32(match.Groups[9].Value, 16));

        Amount = (Convert.ToInt64(match.Groups[5].Value, 16) + hexDecimal) * hexExponent;
    }
    else
    {
        long decimalExponent = 100000000;
        if (match.Groups[4].Success)
            decimalExponent = (long)Math.Pow(10, int.Parse(match.Groups[4].Value));
        Amount = (long)(decimal.Parse(match.Groups[2].Value) * decimalExponent);
    }
}

Requirements

Payment identifiers, not person identifiers

In my opinion, the most basic idea of the URI scheme (as this is a currency) is to facilitate payment. So the URIs should represent first and foremost payments. If it represents something else, this needs to be specified. Thus bitcoin:1NS17iag9jJgTHD1VXjvLCEnZuQ3rJED9L represents a payment to me using my bitcoin address, not my bitcoin address itself. So after parsing the URI (via link/qr/whatever) the application should open a transaction window with the address filled in. You then need to add an amount and confirm the payment. If your application is smart, it will also have a button "just store the address". But the point I am trying to make is that the default use of the URI should be for payment, nor for exchanging addresses.

Accessibility

Imported from the forum: I like the simplicity of bitcoin:xxxxxxxxxxxxx and very much approve of its accessibility. Should someone from the outside happen to see such a URI, the protocol name already gives a description. A quick google search should then do the rest. x-btc sounds much more cryptic; the chance that someone googles that out of curiosity are much slimmer. Also, very likely, what s/he will find are mostly technical specifications. Not a good introduction to bitcoin.

For the same reason I am for using '&' as a delimiter for key-value pairs. People know it from URLs. Make it easy for people to understand what is going on.

Keep it simple

Don't explicitly write down information that can be inferred. Don't mark the address as an address. If there is no address, this does lose much of its utility. We could, however, specify 'address' as a reserved word, so that bitcoin:address?amount=50X8 would initiate a transaction with the amount filled in, but with a blank address. I am not convinced that there is a use case, though.

Use-cases

Before the URI scheme is finalised one should think long and hard about use cases. in what circumstances will which people use this, and for what?

• an online shop has a 'buy this' link, which uses the URI scheme.
  • PROBLEM: click on the link opens the application; how does the merchant notice this?
    • POSSIBLE SOLUTION: javascript can detect the click.
    • POSSIBLE SOLUTION: the checkout site checks its bitcoin account for payment via HTTP request.
  • PROBLEM: the time problem (~10 minutes) is very apparent here; nobody wants to wait 10 minutes for the transaction to be confirmed.
• a person only has an online client, no actual application
  • PROBLEM: how to redirect the URI so that the online client gets a notice?
    • POSSIBLE SOLUTION: Small application and/or browser plugins to redirect the handler call to the designated online wallet.

Backwards compatibility

We want URIs generated in 2011 to still work in 2036. Think about extensibility. Of course we can make only educated guesses (and nothing more!) 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. Version incompatibility is the easiest thing to drive users crazy: "I just upgraded to this shiny new version. What? It doesn't support the old format? AAAAAAARRRGH!"