Skip to content

Instantly share code, notes, and snippets.

@globalcitizen
Forked from gavinandresen/btcpayments.rst
Created November 29, 2012 00:37
Show Gist options
  • Save globalcitizen/4165865 to your computer and use it in GitHub Desktop.
Save globalcitizen/4165865 to your computer and use it in GitHub Desktop.
Invoices, Payments and Receipts

Invoices, Payments and Receipts for Bitcoin Transactions

This document proposes protocol buffer-based formats for signed, authenticated "invoices" and "receipts" -- requests for payment, and proof-of-payment.

Separate documents will propose an extension to the Bitcoin URI syntax and new MIME types to support them.

Motivation

The idea of a "payment protocol" to improve on Bitcoin addresses has been around for over a year. Users have been asking for some features in this proposal (like the ability to provide a refund address so overpayments or refunds can be returned to customers without the need to ask them for their address) for two or three years, and have started to work around shortcomings in the Bitcoin payment process with creative (but inefficient) uses of transactions.

The key features of this proposal are:

  • OUT OF SCOPE (BETTER TO IMPLEMENT OUT OF BITCOIN): Requests for payment (Invoices) are tied to authenticated identities using the only widely-deployed identity authentication system we have right now (X.509 certificates signed by root certificate authorities)
  • OUT OF SCOPE (BETTER TO IMPLEMENT OUT OF BITCOIN): Invoices include a user-friendly description of what the payment is for
  • Payments include where refunds should be sent (THIS BIT ALONE POSSIBLY MAKES SENSE WITHIN BITCOIN)
  • CURVEBALL: At the end of the payment process, the customer has a signed Invoice and bitcoin transaction that can be used as proof-of-payment if there is any dispute with the merchant. (HOW DOES THIS PROVIDE A HIGHER FORM OF GUARANTEE THAN A BITCOIN TRANSACTION ID THAT APPEARS IN THE PUBLIC BLOCKCHAIN, SINCE ULTIMATELY THE BLOCKCHAIN IS THE SOURCE OF TRUTH? HOW CAN IT DO SO IMMEDIATELY, SINCE ROLLBACKS MAY OCCUR?)

Specification

Invoice/SignedInvoice

An Invoice is a request for payment from a merchant to a customer:

message Output {
    optional uint64 amount = 1;
    required bytes script = 2;
}

amount: Number of satoshis (0.00000001 BTC) to be paid. If not given or zero, then the customer will be asked how much to pay.

script: a "TxOut" script to which the customer should direct payment. This will normally be one of the standard Bitcoin transaction script (e.g. pubkey OP_CHECKSIG).

message Invoice {
    repeated Output outputs = 1;
    required uint64 time = 2;
    optional uint64 expires = 3;
    optional bool single_use = 4 [default = true];
    optional string memo = 5;
    optional string receiptURI = 6;
    optional bytes merchant_data = 7;
}

outputs: one or more outputs where Bitcoins are to be sent.

time: Unix timestamp (seconds since 1-Jan-1970) when the Invoice was created.

expires: Unix timestamp after which the Invoice should be considered invalid.

single_use: If true, this Invoice should be used for only one payment. If false, it may be added to the user's address book and used repeatedly until it expires (e.g. for donations or a recurring payment).

memo: UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this Invoice is for.

receiptURI: Secure (https) URI where a Payment message (see below) may be sent to obtain a Receipt.

merchant_data : Arbitrary data that may be used by the merchant to identify the Invoice. May be omitted if the merchant does not need to associate Payments with Invoices or if they associate each Invoice with a separate payment address.

message SignedInvoice {
    required bytes pki_data = 1;
    required string pki_type = 2 [default = "x509"];
    required bytes serialized_invoice = 3;
    required bytes signature = 4;
}

pki_data: PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).

pki_type : public-key infrastructure (PKI) system being used to identify the merchant. X.509 certificates are the default that all implementations should support.

serialized_invoice: A protocol-buffer serialized Invoice message.

signature: digital signature using the SHA-256 HMAC of the concatenation of the pki_data, pki_type, and serialized_invoice and the public key in pki_data.

When a Bitcoin client receives a SignedInvoice, it must authorize payment by doing the following:

  1. Validate the merchant's identity and signature using the PKI system (e.g. validate the X.509 certificates in pki_data up to a list of root certificate authorities, extract the public key from the first certificate, compute SHA256(pki_data+pki_type+serialized_invoice), and validate the signature).
  2. Validate that the time on the customer's system is before Invoice.expires
  3. Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate).

Payment

message Payment {
    optional bytes merchant_data = 1;
    repeated bytes transactions = 2;
    repeated Output refund_to = 3;
    optional string memo = 4;
}

merchant_data : copied from Invoice.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to Invoices.

transactions : One or more valid, signed Bitcoin transactions that fully pay the Invoice

refund_to : One or more outputs where the merchant may return funds, if necessary.

memo : UTF-8 encoded, plain-text note from the customer to the merchant.

If the customer authorizes payment, then the Bitcoin client:

  1. Creates and signs a transaction with one output sending the Invoice.script
  2. If there is no Invoice.receiptURI, then the transaction is broadcast on the Bitcoin p2p network.
  3. Else POST a Payment message to Invoice.receiptURI and expect a Receipt in response.

Invoice.receiptURI must be secure against man-in-the-middle attacks that might alter Payment.refund_to.

Receipt

message Receipt {
    required Payment payment = 1;
    required bool accepted = 2;
    optional string memo = 3;
}

accepted : true if the Payment is accepted and will be broadcast on the Bitcoin p2p network.

memo : UTF-8 encoded note that should be displayed to the customer indicating that the transaction is complete.

Upon receiving a Receipt, a Bitcoin client should display the Receipt.memo to the customer.

If a Receipt is not received for any reason (timeout, error) and Payment.transactions has not been broadcast by the merchant on the Bitcoin p2p network, then the Bitcoin client should assume that the payment failed, inform the customer that the payment failed, and return coins involved in the transaction to the customer's wallet.

Once broadcast on the Bitcon p2p network, payments are like any other Bitcoin transaction and may be confirmed or not.

Certificates

The default PKI system is X.509 certificates (the same system used to authenticate web servers). The format of pki_data when pki_type is "x509" is a protocol-buffer-encoded certificate chain [RFC5280]:

message X509Certificates {
    repeated bytes certificate = 1;
}

Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The certificate containing the public key of the entity that digitally signed the Invoice MUST be the first certificate. This MAY be followed by additional certificates, with each subsequent certificate being the one used to certify the previous one. The recipient MUST verify the certificate chain according to [RFC5280] and reject the Invoice if any validation failure occurs.

*What should we say about root certificates and certificate management in general? Any requirements, or leave it up to each Bitcoin client to determine which root CA's are trustworthy, as happens with web browsers? Gavin suggests trusting only (say) ten of the Extended Validation authorities: http://en.wikipedia.org/wiki/Extended_Validation_Certificate#Extended_Validation_certificate_identification *

*X.509 is widely criticised for doing too much. However, it is the PKI system we're stuck with. Do web browsers / certificate authorities support the full X.509 spec, or only a subset? Should Bitcoin clients only support some well-defined subset of X.509 ? More research needed here... *

Use Cases

Merchant Payment Service

A merchant payment service (like Paysius or bit-pay.com) would use Invoices and Receipts as follows:

  1. Merchant pays for a certificate from a certificate authority, and then gives the payment service the certificate and their private key. This could be the same certificate and private key as is used for the merchant's web site, but best security practice would be to purchase a separate certificate for authenticating Invoices. Very successful merchant payment services might act as intermediate certificate authorities, issuing certificates for their merchants.
  2. Customer goes through the checkout process on either the merchant's or payment service's web site.
  3. At the end of the checkout process, a SignedInvoice is generated and sent to the customer's Bitcoin client.
  4. Customer's Bitcoin client displays the Invoice, showing that the payment is for the merchant.
  5. On customer approval, a Payment is sent to the payment service's paymentURI. The merchant is notified of the payment, and the customer receives a Receipt.
  6. The payment service broadcasts the Payment.transactions, and the customer's Bitcoin client show the transaction as it is confirmed. The merchant ships product to the customer when the transaction has N confirmations.

SatoshiDice

SatoshiDice (www.satoshidice.com) is an extremely popular game that uses tiny transactions for some customer/service communications. In particular, customers can add an extra output to their transactions to indicate where winnings should be sent. And SatoshiDice creates tiny transactions to let their customers know that a bet was received, but lost.

Assuming Bitcoin clients upgrade to support this proposal, a bet on SatoshiDice would proceed as follows:

  1. Customer clicks on a link on SatoshiDice.com and their Bitcoin client receives a SignedInvoice.
  2. Customer authorizes payment, and their Bitcoin client creates a Payment message and submits it directly to https://satoshidice.com/something
  3. The SatoshiDice web server checks to make sure the transaction is valid, broadcasts it, and determines whether the customer wins or loses. It returns a Receipt with either a "You win" or "You lost" memo.
  4. If the customer won, it broadcasts a transaction to pay them using Payment.refund_to
  5. Customer's Bitcoin client displays the win/lose memo, and if they won the winnings appear in their wallet when received over the p2p network.

Multiperson Wallet

This use case starts with a multi-signature Bitcoin address or wallet, with keys held by two different people (Alice and Bob). Payments from that address/wallet must be authorized by both Alice and Bob, and both are running multi-signature-capable Bitcoin clients.

Alice begins the payment process by getting a SignedInvoice from a merchant that needs to be paid. She authorizes payment and her Bitcoin client creates a Payment message with a partially-signed transaction, which is then sent to Bob any way that is convenient (email attachment, smoke signals...).

Bob's Bitcoin client validates the SignedInvoice and asks Bob to authorize the transaction. He says OK, his Bitcoin client completes the transaction by providing his signature, submits the payment to the merchant, and then sends a message to Alice with the Receipt he received from the merchant, completing the payment process.

Design Notes

Why X.509 Certificates?

This proposal uses X.509 certificates as the identity system for merchants because most of them will have already purchased a certificate to secure their website and will be familiar with the process of proving their identity to a certificate issuing authority.

Implementing a better global PKI infrastructure is outside the scope of this proposal. If a better PKI infrastructure is adopted, the only change to this proposal would be to add a new pki_type and new formats for pki_data and signature with whatever that better infrastructure uses to identify entities.

Why not JSON?

Invoice, Payment and Receipt messages could all be JSON-encoded. And the Javascript Object Signing and Encryption (JOSE) working group at the IETF has a draft specification for signing JSON data.

But the spec is non-trivial. Signing JSON data is troublesome because JSON can encode the same data in multiple ways (whitespace is insignificant, binary data must be encoded into strings using base64 or some other encoding, etc.), and the standards committee identified at least one security-related issue that will require special JSON parsers for handling JSON-Web-Signed (JWS) data (duplicate keys must be rejected by the parser, which is more strict than the JSON spec requires).

A binary message format has none of those complicating issues. Which encoding format to pick is largely a matter of taste, but Protocol Buffers is a simple, robust, multi-programming-language, well-documented, easy-to-work-with, extensible format.

Why not an existing electronic invoice standard?

There are several existing standards for electronic invoices (EDIFACT, OAGIS, UBL, ISDOC). They are all over-designed for Bitcoin's purposes.

However, it would be trivial to extend the Invoice message to include more extensive invoice details encoded as specified by one of those standards (e.g. add a ubl_invoice string that is an XML-encoded UBL invoice).

What about a merchant-pays-fee feature?

It is desireable to allow a merchant to pay the cost of any Bitcoin network transaction processing fees, so if a customer is paying for a 1 BTC item they pay exactly 1 BTC.

The consensus is to change the transaction selection code used by Bitcoin miners so that dependent transactions are considered as a group. Merchants or payment services with one or more unconfirmed zero-fee transaction from customers will periodically create a pay-to-self transaction with a large enough fee to get the transactions into a block.

Checking for revoked certificates

The Online Certificate Checking Protocol (OCSP) is supposed to be a quick and easy way for applications to check for revoked certificates.

In practice, it doesn't work very well. Certificate Authorities have no financial incentive to support a robust infrastructure that can handle millions of OCSP validation requests quickly.

Ideally, Bitcoin clients would use OCSP to check certificate statuses every time they received or re-used an Invoice. But if that results in long pauses or lots of false-positive rejections (because an OCSP endpoint is offline or overwhelmed, perhaps) then merchants and customers might revert to just using "never fails" Bitcoin addresses.

References

Public-Key Infrastructure (X.509) working group : http://datatracker.ietf.org/wg/pkix/charter/

RFC 2560, X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP : http://tools.ietf.org/html/rfc2560

Protocol Buffers : https://developers.google.com/protocol-buffers/

See Also

Javascript Object Signing and Encryption working group : http://datatracker.ietf.org/wg/jose/

Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice especially the list of Electronic Invoice standards

sipa's payment protocol proposal: https://gist.github.com/1237788

ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html

@gavinandresen
Copy link

RE: HOW DOES THIS PROVIDE A HIGHER FORM OF GUARANTEE THAN A BITCOIN TRANSACTION ID :

I claim: I paid you 9.8038 BTC just now. Here is the transaction id:
http://blockchain.info/tx/4f4f580bdd6cb21da1d4569ff0896543605572b28f896838568265a8959df4a4
Now I want that pony you promised to give me RIGHT NOW!

You can swear up-and-down that address 13Bwk66VSM2vVbych5czLeKJNdL8wYMXXP is not the address that you gave me and you never promised to give me a pony, and I will swear up and down that you DID promise to give me a pony if I sent bitcoins to that address.


Now if I have a SignedInvoice and a bitcoin transaction that was accepted by the network (has more than 6 or so confirmations) then I have a much more secure proof-of-payment. A certificate authority must have validated your identity, and I've got your digital signature on a statement that says "pay here".

RE: OUT OF SCOPE:

okey dokey. Suggest alternative, workable solutions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment