Bitcoin QR-code specification

[jgarzik]

Today's #bitcoin-dev featured an interesting discussion of mobile phone use, centered around the following use case:

• customer walks into real-world stores, selects several items, and walks to cashier to check out
• cashier displays QR-code on customer-facing screen
• customer uses mobile phone to take picture of QR-code
• mobile phone displays "Big Box Store Corporation, Inc, requests a payment of 300 BTC.  Do you agree?  Yes / No"
• customer agrees (or cancels the sale), triggering BTC transfer from customer to merchant

As such, tcatm, nelisky and I started typing out notes for APIs at http://www.bitcoin.org/wiki/doku.php?id=phone_api   I'll let tcatm or nelisky talk about payment requests if they wish, but I wanted to focus on defining a QR-code specification that people could start using immediately.

Each of these is a text string in the style of RFC822 headers (“key: value”), where “value” is further separated by semicolons. Strings containing semicolons or spaces may be quoted with double-quotes (").  Double-quotes themselves are escaped in the obvious way, with a back-slash.

1) Bitcoin address.  Not directly related to the purchase-via-mobile-phone scenario just described, but obviously necessary.

Code:

bitcoin-address1: name="John Q. Public"; pubkey=1LGpwDU5djqsR1X14Tcass3y9fULTzxJq3

Using this QR-code, you may share bitcoin addresses with others via mobile phone.  Use this QR-code on the forum or your website, to give out your bitcoin donation address!


2) Merchant request for direct payment via bitcoin network.

Code:

btcpayment-request1: name=“My Bitcoin Inc.”; pubkey=1LGpwDU5djqsR1X14Tcass3y9fULTzxJq3; amount=300

Using this QR-code, the mobile phone knows enough to ask the user if they wish to pay 300 BTC to My Bitcoin, Inc. at the given bitcoin address.  Presumably the mobile phone has the ability to make bitcoin payments, either directly (a lightweight bitcoin client) or indirectly via a payment API such as this.


3) Merchant request for indirect payment via a custom payment processor.

Code:

payment-request1: merchant=1234; name=“My Bitcoin Inc.”; tx_id=1234bacd;
     payment-processor=http://mtgox.com/apiv1; api=mtgox; amount=300; currency=BTC

Using this QR-code, assuming that the mobile phone app is aware of an API known as "mtgox", the mobile phone knows enough to ask the user if they wish to pay 300 BTC to My Bitcoin, Inc., using the specified custom Web API.

The "1" suffix implies version 1 of that QR-code.  An incompatible change would imply "bitcoin-address1" becomes "bitcoin-address2", etc.

[MoonShadow]

Qr codes are a workaround that likely won't need to exist after Android 2.3 because that version supports Near Field Communications protocols.  It's a ten cent chip added to the smartphone that would make the camera on the phone the expensive hardware.  If the consumers could reasonably be expected to use QR codes, then the credit card companies would have them everywhere already.

[jgarzik]

Qr codes are a workaround that likely won't need to exist after Android 2.3 because that version supports Near Field Communications protocols.  It's a ten cent chip added to the smartphone that would make the camera on the phone the expensive hardware.  If the consumers could reasonably be expected to use QR codes, then the credit card companies would have them everywhere already.

NFC could easily transfer these strings too...

[theymos]

x-btc was designed with QR codes in mind. In particular, it has concise syntax to keep code size small, and to avoid reaching the QR code maximum size (~4000 characters).

Equivalents of your first two examples:

Code:

x-btc:addr=1LGpwDU5djqsR1X14Tcass3y9fULTzxJq3;store

Code:

x-btc:addr=1LGpwDU5djqsR1X14Tcass3y9fULTzxJq3?My%20Bitcoin%20Inc.;value=300;send

Sending to a merchant API service would be better done through the standard Bitcoin IP interface, I think, with the merchant ID and other info as a message. (Authentication extensions would be necessary, of course.)

QR codes already have checksum data, so it seems wasteful to include entire addresses (which also have check codes). It would be better to convert the address to a hash160 and include that, encoded in base64. It can be losslessly converted back to an address at the receiving end.

1LGpwDU5djqsR1X14Tcass3y9fULTzxJq3
becomes
02ikqmJrjm4wJIqMf42kYPiwxks

[bitcoinex]

Encourage to use a DataMatrix!

QR-code is more proprietary than DataMatrix and DataMatrix fully implemented in very good open source library and utils called 'dmtx'.

Here on the end of the page you can see the comparison of the codes with same text: https://btcex.com/

QR-code has one advantage - it is recognizable by 'typical users'.

[jgarzik]

QR-codes are well supported by open source tools, and are in more common use.

[bitcoinex]

QR-codes are well supported by open source tools,

I could not find open source utility that would be correctly encoded raw 8-bit data (for pgp keys backup)

Also, the shape of the big Data Matrix labels will not necessarily be square, as far as I know.

and are in more common use.

Almost any computer parts already contains a small datamatrix label

[mndrix]

customer walks into real-world stores, selects several items, and walks to cashier to check out

In this scenario, would the customer need to wait in the store for several minutes while his bitcoin payment is accepted into a block and confirmed by several more blocks?

[Cdecker]

Basically this is duplicating the work we are doing on the bitcoin URI scheme. Since we can encode the URIs can easily be represented using QR codes I think we should stick with the bitcoin:-URI Scheme 

Just my 0.02 BTC

[MoonShadow]

customer walks into real-world stores, selects several items, and walks to cashier to check out

In this scenario, would the customer need to wait in the store for several minutes while his bitcoin payment is accepted into a block and confirmed by several more blocks?

Not unless we are talking about expensive products, such as a car.  There normally isn't a need to wait for confirmation, as the store's own client has the most recent blockchain, it can tell immediately if the buyer owned the coins he is trying to spend ten minutes ago.  It's also possible, and in the future likely, that a more sophisticated point-of-sale client would be able to scan the pending transactions queue for any attempt at a coordinated double-spend fraud in progress, as well as an even more sophisticated network split double spend attack.  Such additional checks are possible, but not in the current client and not with a 'lightweight' client such as would likely exist on future smartphones.

EDIT:  Waiting for confirmation from the blockchain is akin to going to a notary public to sell your car to someone that you don't know for cash.  It's not really neccessary for most everyday transactions.

[Sandoz]

Basically this is duplicating the work we are doing on the bitcoin URI scheme. Since we can encode the URIs can easily be represented using QR codes I think we should stick with the bitcoin:-URI Scheme 

Just my 0.02 BTC

There is however the other usecase where I just want to share an address and a name:
- I go out with friends and want them to have my public account address
- I just want to put a donations image on my homepage

Ideally that would contain a name (If in one evening I get a dozen of addresses from friends I want to be able to distinguish them later), a description and an address.

That is imho not handled by URI's or x-btc. There is a need for standartizing that kind of information

Encourage to use a DataMatrix!

QR-code is more proprietary than DataMatrix and DataMatrix fully implemented in very good open source library and ...

The vector of the information is irrelevant! It needs to be so short it can fit in a QR, tweet, DataMatrix, SMS, needs to be unique, possibly human readable and that's it.

Let's worry about the vector later. As soon as there is a good standard we can all get behind, we can worry about how and where to encode the information