Subject: Re: [Bitcoin-development] Payment Protocol Proposal: Invoices/Payments/Receipts

From: Gavin Andresen <[email-masked]>
Date: Sat, 1 Dec 2012 14:25:17 -0500

Spec updated: https://gist.github.com/4120476

Changes are:

Version numbers:  a couple of people asked privately about adding
version numbers to the messages. In general, Protocol Buffers don't
need version numbers if later versions add only optional fields.

And best-practice is to know what version of something you're
expecting BEFORE you start parsing that something.

So, if a bitcoin client is getting Invoice messages via email or from
a web server, the version will be specified as part of the MIME type;
for example:
   Content-Type: application/x-bitcoin-invoice; version=1
The version= syntax is part of the MIME standard.

Following that best-practice of knowing what you're parsing before you
parse it, I added an invoice_version field to the SignedInvoice
message. It is now:

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

Handling of receiptURI errors:

Following discussion here, I changed the spec to say:

"Clients may handle errors communicating with the receiptURI server
however they like, but should assume that if they cannot communicate
at all with the server then the Payment should either be retried later
or immediately rejected."

and under Receipt added:

"The Bitcoin client must be prepared to handle the case of an evil
merchant that returns accepted=false but broadcasts the transactions
anyway."

I also added a TODO "Test Vectors" section with base64-encoded
examples of everything.

-- 
--
Gavin Andresen