OpenBazaar Ricardian Contracts - physical goods

1

OpenBazaar

Ricardian ContractsPhysical Goods

2

3

Step 1: Vendor makes a listing

Listing

4


Metadata1. OBCV

• OpenBazaar contract version• Contract schemas may evolve over time and it may be

necessary to track what version of the contract is being used

2. Expiry• The date until the contract is a valid listing

3. Category• Category of Ricardian Contract• Current categories: physical goods, digital goods, services• More categories will appear with time

4. Sub-category• At the moment, sub-category refers to the type of

payment model• Future sub-categories: auction, barter etc

5


ID (Vendor details)1. GUID

• OpenBazaar network ID2. Pubkeys

• Bitcoin: multisig signing key• PGP: transportable identity if the vendor has >1 node

3. Passcard• Onename’s Passcard username• Used to establish broader ID of the Vendor

6


Item1. Title

• Name of the item2. Description

• Character limited description of the item3. Condition

• Condition of the item• Options from a pull-down menu in the application

4. Price• Bitcoin: shipping fee in bitcoin• Fiat: shipping fee in fiat that the bitcoin price floats to

5. Images• Image hash: SHA256 hash of the image to lock in identity of the

image• Image URLs: if not locally hosted by the Vendor’s node

6. Keywords• Used for reverse-lookup on the distributed hash table (i.e.

search)7. Process Time

• The maximum predicted time it will take a Vendor to ship the item after receiving an order

7


Shipping1. Free

• Will the item be shipped for free (out of the profit margin of the item)

• Boolean state2. Flat fee

• A flat fee for domestic and/or international shipping• Bitcoin: shipping fee in bitcoin• Fiat: shipping fee in fiat that the bitcoin price floats to

3. Estimated delivery• Estimated delivery windows (in days) after the item has been

shipped (domestic and/or international)4. API

• If the Vendor wants a shipping cost specific to the destination address, they can designate an accepted shipping API to estimate the cost

• API source: company name (e.g. Shippo)• Carriers: shipping services the Vendor is willing to use• Package: Package dimensions necessary to obtain a shipping

cost estimate; will feed directly into the API• Shipping origin: the country or zip code the item will be shipped

from

8


Moderator1. GUID

• OpenBazaar network ID2. Pubkeys

• PGP: transportable identity if the Moderator has >1 node

• Escrow Pubkey: public key combined with the buyer’s 32 byte chain code to generate Moderator’s multisignature signing key

3. Passcard• Onename’s Passcard username• Used to establish broader ID of the Vendor

4. Service• Service fee: percentage or flat fee per transaction• Service description: activities and terms of service

9

Vendor cryptographic keys shown in ‘01_listing’ are used to digitally sign all of

the ‘01_listing’ data, which proves that the owner of the keys created this data


{"01_metadata":{"01_obcv":"","02_expiry":"","03_category":"physical good","04_category_sub":"fixed price"},"02_id":{"01_guid":"","02_pubkeys":{"bitcoin":"","pgp":""},"03_passcard":""},"03_item":{"01_title":"","02_description":"","03_condition":"","04_price":{"bitcoin":"","fiat":{"01_price":"","02_currency_code":""}},"05_images":{"image_hashes":[""],"image_urls":[""]},"06_keywords":[""],"07_process_time":""},"04_shipping":{"01_free":false,"02_flat_fee":{"01_bitcoin":{"01_domestic":"","02_international":""},"02_fiat":{"01_price":{"01_domestic":"","02_international":""},"02_currency_code":""}},"03_est_delivery":{"01_domestic":"","02_international":""},"04_api":{"01_api_src":"Shippo","02_carriers":["FedEx","UPS"],"03_package":{"01_length":"","02_width":"","03_height":"","04_distance_unit":"","05_weight":"","06_mass_unit":""},"04_shipping_origin":{"01_country":"","02_zip":""}}},"05_moderator":{"01_guid":"","02_pubkeys":{"pgp":"","pgp_sig":"sig(selfsig_pubkey)","pubkey":"xxx"},"03_passcard":"","04_service":{"01_service_fee":"","02_service_desc":""}}}

What it looks like in JSON

10

11

Stage 2: Buyer places an order

2. Buyer places an order, funds multisig address (funds are now in escrow), and send shipping address

Buyer generates a 32 byte chain code, combines with Moderator public key to generate a pubkey for the Moderator. The Moderator can generate the private key in the event of a dispute after the 32

byte chain code is disclosed. Multisignature escrow address can now be generated from the Vendor, Buyer and Moderator’s pubkeys.

12





Reference Hash1. Reference

• Contract ID (listing) that the order applies to• Example:

• RIPEMD-160(01_vendor): cca4b4bf91a16ee76e1944624c4f7c0f8729a6f1• Base58(RIPEMD-160[01_vendor]): 3rMrSZ2VDgb63ZvgEsdVjiscXurg• Final: OB3rMrSZ2VDgb63ZvgEsdVjiscXurg

13





ID (Buyer)1. Pubkeys

• Unlike the Vendor, the Buyer is only identified in the contract by their bitcoin signing key

• Bitcoin: multisig signing key

14





Item Details1. Semantics

• Any data the buyer needs to give to the Vendor to make a purchase• E.g. Colour, size

2. Shipping• Encrypted address: the Buyer’s shipping

address XOR’d with a random nonce, and then encrypted with the Vendor and Moderator’s PGP public keys

• SHA256 nonce: the SHA256 hash of the random nonce used to XOR the shipping address

• Encrypted nonce: plain text nonce encrypted with the Vendor’s PGP public key

• API shipping cost: cost of shipping quoted by the API (if used)

15





Multisignature Details1. Chain code

• 32 bytes of random data used to generate the Moderator’s multisig signing public key

2. Multisignature address• Multisig address generated from the Vendor,

Buyer and Moderator’s bitcoin pubkeys3. Redemption script

• To verify that the multisig address is comprised of the pubkeys listed in the contract

4. Transaction ID (txid)• Evidence that the Buyer has funded the

multisignature address with the purchase amount in the listing

• Optional, in the sense that if the payment is made from the Bitcoin purse, the TXID can be automatically filled in

16





Signatures• Bitcoin

• Multisig signing key of the Buyer is used to sign JSON data from ‘02_buyer.01_order’

17

18

Step 3: Vendor ships the item

3. Vendor indicates that the order is processed and the item is shipped (tracking number); sends a signed transaction releasing funds from escrow to their payout address (signature required from Buyer or Moderator to release funds after item delivered)Alice

The Vendor

19



The Vendor


• Contract ID (order) that the data applies to

20



The Vendor

Shipping1. Tracking ID

• Self explanatory2. Shipper

• Name of the shipping company3. Payout

• Payout address: Vendor’s bitcoin address where the multisig funds will be released to after the item is delivered

• Signed transaction: signed transaction releasing funds from multisig to the payout address; requires only 1 more signature from Buyer or Moderator to be accepted

4. Revised estimated delivery• More accurate estimate of the shipping time if

the original time is incorrect

21



The Vendor

Pickup1. Encrypted address

• The Vendor’s pickup address XOR’d with a random nonce, and then encrypted with the Buyer and Moderator’s Bitcoin ECC public keys

2. SHA256 nonce• The SHA256 hash of the random nonce used to XOR the pickup address

3. Encrypted nonce• Plain text nonce encrypted with the Buyer’s ECC public keys

22



The Vendor


• Multisig signing key of the Vendor is used to sign JSON data from ‘03_vendor.01_invoice’

• PGP• PGP key of the Vendor is used to sign JSON data from

‘03_vendor.01_invoice’

23

24

Step 4: Buyer confirms item received

BobThe Buyer

4. Buyer indicates that the item was received; signs transaction and release funds from multisig to the

Vendor. Attaches rating/review.

25


• Contract ID (shipping notice) that the data applies to


BobThe Buyer



26

Item1. Received

• Was the item received (Boolean)?


BobThe Buyer



27

Payout1. Signed transaction

• The Buyer-signed transaction from the Vendor (in `03_vendor`) that releases funds from multisig to the Vendor’s payout address

2. Transaction ID (txid)• Reference to the bitcoin transaction

releasing funds from multisig• Automatically done if there is a

Bitcoin Purse


BobThe Buyer



28

Rating1. Transaction rating

• Select from choices:• Positive• Neutral• Negative

2. Item quality• Rate out of 5 stars

3. Item description• Rate out of 5 stars

4. Shipping time• Rate out of 5 stars

5. Customer service• Rate out of 5 stars

6. Review• Character limited text reviewing the

transaction


BobThe Buyer



29


BobThe Buyer



Dispute1. Dispute

1. Does the Buyer flag a dispute? (boolean)2. Claim

• If there is a dispute, what does the Buyer claim as the grievance?

30


• Multisig signing key of the Vendor is used to sign JSON data from ‘04_buyer.01_receipt’


BobThe Buyer



OpenBazaar Ricardian Contracts - physical goods

Software