bitcoin-bips/bip-draft.mediawiki

<pre>
  BIP: 999*
  Layer: Applications
  Title: Pay to Contract Protocol
  Author: Omar Shibli <omar@commerceblock.com>
          Nicholas Gregory <nicholas@commerceblock.com>
  Comments-Summary: No comments yet.
  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0999
  Status: Draft
  Type: Informational Track
  Created: 2017-07-17
</pre>

&ast; 999 is a temporary BIP number.

==Abstract==

Utilizing hierarchical deterministic wallets as described in BIP-0032 and the "Purpose Field" in BIP-0043, this document specifies the multiparty pay-to-contract key derivation scheme outlined by Ilja Gerhardt and Timo Hanke.[0]

This BIP is a particular application of BIP-0043 and is based on BIP-0044.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

==Motivation==

A Bitcoin transaction represents a "real world" contract between two parties to transfer value. The payer may want cryptographic proof that the payee has agreed to the terms of this contract. Using the technique described in this BIP, an address can be provably derived from the terms of a contract in a completely hidden manner which does not bloat the UTXO. This scheme can also be used as a foundation for a variety of protocols, such as advanced color coin schemes.

Counterparties in a business interaction traditionally keep track of a payment with bills (invoices) and payment receipts. Delivery of a good is made by a merchant once the customer has signed the receipt, agreeing to pay for the items on the bill. Gerhardt and Hanke [0] formulate this interaction within the confines of the Bitcoin protocol using homomorphic payment addresses and the pay-to-contract protocol. The protocol is constructed in such a way that the payment itself provides proof of both who is being paid and for what.

This scheme is based on the foundations of BIP-0032, providing a consistent way for preexisting wallet developers to implement the specification.

==Specification==

This key derivation scheme requires two parties: a payer (customer) and a payee (merchant).
The customer submits to the merchant a purchase request, specifying what goods/services they would like to buy. From the purchase request the merchant constructs an invoice (contract), specifying the billable items and total amount to be paid.
The merchant must give this contract alongside a “payment base” extended public key to the customer. Given this information, the customer will be able to fulfill the contract by generating the public key of the payment address associated with the contract and the payment base and sending the funds there.

We define the following levels in BIP32 path:

<code>
m / purpose' / coin_type' / contract_hash
</code>

<code>contract_hash</code> consists of mulitple levels.

Apostrophe in the path indicates that BIP32 hardened derivation is used.

We define the following extended public keys:

Payment base denoted as <code>payment_base</code>:

    m / purpose' / coin_type'

Payment address denoted as <code>payment_address</code>:

    m / purpose' / coin_type' / contract_hash
    or
    m / payment_base / contract_hash

Each level has special meaning described in the chapters below.

===Purpose===

Purpose is a constant set to <code>999'</code> (or <code>0x800003E7</code>) following the BIP-0043 recommendation. It indicates that the subtree of this node is used according to this specification.

<code>
m / 999' / *
</code>

Hardened derivation is used at this level.

===Coin type===

The coin type field is identical to the same field in BIP-0044.

Hardened derivation is used at this level.

===Payment Address Generation===

For a given contract documents denoted by c<sub>1</sub> ,...,c<sub>n</sub>, payment base extended public key denoted by <code>payment_base</code>, and cryptographic hash function denoted by <code>h</code>.

1. Compute cryptographic hashes for all contract documents, by applying the hash function.

  h(c1),...,h(cn)

2. Sort all hashes lexicographically.

  hash_1,...,hash_n

3. Concatenate the sorted hashes and apply the hash function.

  h(hash_1+...+hash_n)

4. Compute a partial BIP32 derivation path from the combined hash as defined in Hash to Partial Derivation Path Mapping procedure below.

  contract_hash

5. Prepend <code>payment_base</code> to contract_hash derivation path.

  payment_base / contract_hash

6. Compute public extended key from the derivation path in step 5.

7. Compute address of the public extended key (P2PKH) from step 6.

===Payment Address Verification===

For a given Bitcoin address, <code>payment_base</code> extended public key, contract documents denoted by c<sub>1</sub>,...,c<sub>n</sub>, and cryptographic hash function denoted by <code>h</code>, we can verify the integrity of the address by the following steps:

1. Compute contract address from the given inputs as described in Contract Address Generation section.

2. Compare the computed address from step 1 with the given Bitcoin address as an input.

===Redemption===

The merchant is able to construct the private key offline using the method described in the Payment Address Generation section.
The merchant should actively monitor the blockchain for the payment to the payment address.
Because the address is generated from the payment base and the contract, the merchant must implicitly agree to those terms in order to spend the funds.
The act of making the payment to that address thus serves as a receipt for the customer.

===Hash to Partial Derivation Path Mapping===

At this section, we define hash to partial BIP32 derivation path mapping procedure that maps between an arbitrary hex number to a partial BIP32 derivation path.

For a given hex number, do the following:

1. Partition hex number into parts, each part length is 4 chars.

2. Convert each part to integer in decimal format.

3. Concatenate all numbers with slash <code>/</code>.

==Examples==

For the following given inputs:

  master private extended key:
  xprv9s21ZrQH143K2JF8RafpqtKiTbsbaxEeUaMnNHsm5o6wCW3z8ySyH4UxFVSfZ8n7ESu7fgir8imbZKLYVBxFPND1pniTZ81vKfd45EHKX73
  coin type:
  0

we can compute payment base as follows:

  payment base derivation path:
  m/999'/0'
  contract base public extended key:
  xpub6A7Bkv1CFa275xd2vyheGLS1NX8zNizxU82ufcL3fnwnhS7DBpruR16oSFZGUQVtJNEjghCe3ZdPManUWCZFJo6t5U98KC2cYMpXtqNCwi3

In the below examples, we are going to use SHA256 as a cryptographic hash function, and the above contract base public key.

payment address generation:

As an input, we have a contract that consists of two documents, below are contents:

  document 1:
  bar
  document 2:
  foo

1. Apply the hash function:

  document 1:
  fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
  document 2:
  2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae


2. Sort all hashes lexicographically:

  2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae
  fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9

3. Concatenate hashes and apply the hash function.

  concatenated hash:
  2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7aefcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9
  combined hash:
  ec321de56af3b66fb49e89cfe346562388af387db689165d6f662a3950286a57

4. Compute the partial BIP32 derivation path of the combined hash.

  60466/7653/27379/46703/46238/35279/58182/22051/34991/14461/46729/5725/28518/10809/20520/27223

5. Prepend <code>payment_base</code> to <code>contract_hash</code> derivation path.

  contract_base_pub/60466/7653/27379/46703/46238/35279/58182/22051/34991/14461/46729/5725/28518/10809/20520/27223
  or
  m/999'/0'/60466/7653/27379/46703/46238/35279/58182/22051/34991/14461/46729/5725/28518/10809/20520/27223

6. Compute public extended key.

  xpub6h8197UZpVMsYirUuHZUDbn8d8dewqW6UkZiXFNRf6WsvkgDsJQN5Atn8PUExFmyofccfoY6dMWqb9SpnJ5HDibi6kKbq931Z531ELCXHTn

7. Compute address of the public extended key (P2PKH).

  1LeYXs63uVSDu2XSb82xdEc7RumohCpB7Q


verification example 1 (negative test):

Similarliy to the input above, excpet this time we have a contract that consists of one document, below is content:

  document 1:
  baz

1. Apply the hash function.

  baa5a0964d3320fbc0c6a922140453c8513ea24ab8fd0577034804a967248096

2. Apply the hash function second time (list of one item).

  3a08605829413ce0bf551b08d21e4a28dbda6e407f90eff1c448e839050c73a1

3. Compute the partial derivation path.

  14856/24664/10561/15584/48981/6920/53790/18984/56282/28224/32656/61425/50248/59449/1292/29601

4. Prepend contract_base<sub>pub</sub> to contract_hash derivation path.

  contract_base_pub/14856/24664/10561/15584/48981/6920/53790/18984/56282/28224/32656/61425/50248/59449/1292/29601
  or
  m/999'/0'/14856/24664/10561/15584/48981/6920/53790/18984/56282/28224/32656/61425/50248/59449/1292/29601

5. Compute public extended key.

  xpub6gvNX6yBEaBu5nGg9rrtEQgSgvAL5vtcbD8MpCfQgd1Wzuga8Kk3bJkhpTzDWvsx5sLj65UQvQaAgW34SwnGBEmxLvWDshBgPyJstd6RQdB

7. Compute address of the public extended key (P2PKH).

  1JwnGxLhT9K6RbUsWcjL2mtmpPEHsLFvXG

8. As expected the address doesn't match the Bitcoin address from the last example <code>1LeYXs63uVSDu2XSb82xdEc7RumohCpB7Q</code>.

Verification operation will succeed only if we use identical documents to ones that have been used in the contract address generation.

==Reference implementations==

* Reference wallet implementation, based on Copay project : https://github.com/commerceblock/copay ([[https://github.com/commerceblock/copay/pull/1|pull_request]])
* Reference implementaion to Hash to Partial Derivation Path Mapping in javascript ([[https://github.com/commerceblock/pay-to-contract-lib/blob/master/lib/contract.js|https://github.com/commerceblock/pay-to-contract-lib]])

==Reference==

* [[bip-0032.mediawiki|BIP32 - Hierarchical Deterministic Wallets]]
* [[bip-0043.mediawiki|BIP43 - Purpose Field for Deterministic Wallets]]
* [[bip-0044.mediawiki|BIP44 - Multi-Account Hierarchy for Deterministic Wallets]]
* [[https://arxiv.org/abs/1212.3257|Homomorphic Payment Addresses and the Pay-to-Contract Protocol]]

==Copyright==

This document is placed in the public domain.