Skip to content

btcpop scheme

Jump to bottom Edit New page
Kalle Rosenbaum edited this page May 24, 2015 · 12 revisions

URI scheme for Proof of Payment requests

Abstract

This is a proposal for a URI scheme to be used in the Proof of Payment process.

Motivation

To make a proof of payment, the party that wants the proof needs to transfer a Proof of Payment request to the wallet software of the other party. To make that transfer easy, a new URI scheme representing the PoP request is proposed. This URI can then be encoded in QR images or sent over NFC in order to transfer it to the wallet. The scheme deliberately resembles the bitcoin: scheme specified in BIP0021.

Specification

The specification is the same as BIP0021, with the following differences:

  • The scheme is btcpop instead of bitcoin
  • The path component, i.e. the address part, is always empty.
  • A mandatory p parameter whose value contains the destination for the PoP. This could for example be a https: URL or a mailto: URI.
  • A mandatory n parameter whose value represents the nonce is a Base58 encoded unsigned integer.
  • An optional txid parameter containing the Base58 encoded hash of the transaction to prove.

Just as in BIP0021, elements of the query component may contain characters outside the valid range. These must first be encoded according to UTF-8, and then each octet of the corresponding UTF-8 sequence must be percent-encoded as described in RFC 3986.

All parameters except p and n are hints on which transaction to create a PoP for.

The extensibility of BIP0021 applies to this scheme as well. For example, a date parameter or a toaddr parameter might be useful. req-* parameters are also allowed and obey the same rules as in BIP21, clients not supporting a req-* parameter MUST consider the URI invalid.

Keep URIs short

Implementors SHOULD keep the URIs as short as possible. This is because it makes QR decoding more stable. A camera with a scratched lens or low resolution may run into problems scanning huge QR codes. This is why the txid parameter is encoded in Base58 instead of the classic hex encoded string. We get away with 44 characters instead of 64. Also, the nonce parameter is Base58 encoded for the same reason.

Interpretation

Transaction hints

The wallet processing the URI must use the hints in the PoP request to filter its transaction set. The label, amount and message parameters MUST, if present in the URI, exactly match the data associated with the original payment according to the following table:

btcpop: URI parameter bitcoin: URI parameter BIP70 PaymentDetails data
label label merchant_data
amount amount sum of outputs.amount
message message memo

The txid parameter value MUST match the transaction hash of the payment.

The interpretation of extension parameters, both optional and req-* parameters is undefined in this specification.

After filtering, the resulting transaction set is displayed to the user who selects one of them to prove. An implementation could also automatically select a transaction in the filtered set, but there must still be a way for the user to select freely among the matching transactions. If the filtered set is empty, no transaction fits the hints and a message about that is presented to the user. If the filtered set contains exactly one transaction, which is preferable, that transaction can be automatically selected.

PoP destination p

The p parameter value is the destination where to send the signed PoP to. This destination is typically a https: URL or a http: URL, but it could be any type of URI, for example mailto:. To keep btcpop: URIs short, users SHOULD not make their p parameter unneccesarily long.

http: and https: URLs

Wallet implementations MUST support the http: and https: schemes in which case POST method must be used. The content type of the POST request MUST be set to

Content-Type: application/bitcoin-pop
Content-Transfer-Encoding: binary

Examples

Send PoP for transaction with label "video 42923" to https://www.example.com/pop/352, using nonce 201034798685579:

btcpop:?p=https://www.example.com/pop/352&n=2a3qukR1t&label=video 42923

Send PoP through mail using mailto:pop@example.com?subject=pop444, amount is 13370000 satoshis, nonce is 66837073551048. Note that the ? before subject is ok according to RFC3986, since the query part starts from the first ?:

btcpop:?p=mailto:pop@example.com?subject%3Dpop444&n=XGhQKP43&amount=0.1337

Send PoP for transaction with id cca7507897abc89628f450e8b1e0c6fca4ec3f7b34cccf55f3f531c659ff4d79 to pizza place at http://pizza.example.com/pop/laszlo111 using nonce 60994432923222

btcpop:?p=http://pizza.example.com/pop/laszlo111&n=UdDnAxwf&txid=Emt9MPvt1joznqHy5eEHkNtcuQuYWXzYJBQZN6BJm6NL
Add a custom footer
Add a custom sidebar
Clone this wiki locally