Ricardian contract documentation for physical goods

1. OpenBazaar
Ricardian Contracts
Physical Goods
1

2. 2

3. 3
Step 1: Vendor makes a listing
Listing

4. 4
Step 1: Vendor makes a listing
Metadata
1. 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. 5
Step 1: Vendor makes a listing
ID (Vendor details)
1. GUID
• OpenBazaar network ID
2. 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. 6
Step 1: Vendor makes a listing
Item
1. Title
• Name of the item
2. Description
• Character limited description of the item
3. 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. 7
Step 1: Vendor makes a listing
Shipping
1. Free
• Will the item be shipped for free (out of the profit margin of the
item)
• Boolean state
2. 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. 8
Step 1: Vendor makes a listing
Moderator
1. GUID
• OpenBazaar network ID
2. 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. 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
Step 1: Vendor makes a listing
{"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_tit
le":"","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_deli
very":{"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_servic
e":{"01_service_fee":"","02_service_desc":""}}}
What it looks
like in JSON

10. 10

11. 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. 12
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.
Reference Hash
1. Reference
• Contract ID (listing) that the order applies to
• Example:
• RIPEMD-160(01_vendor): cca4b4bf91a16ee76e1944624c4f7c0f8729a6f1
• Base58(RIPEMD-160[01_vendor]): 3rMrSZ2VDgb63ZvgEsdVjiscXurg
• Final: OB3rMrSZ2VDgb63ZvgEsdVjiscXurg

13. 13
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.
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. 14
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.
Item Details
1. 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. 15
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.
Multisignature Details
1. 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 pubkeys
3. 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. 16
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.
Signatures
• Bitcoin
• Multisig signing key of the Buyer is used to
sign JSON data from ‘02_buyer.01_order’

17. 17

18. 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. 19
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
Reference Hash
1. Reference
• Contract ID (order) that the data
applies to

20. 20
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
Shipping
1. Tracking ID
• Self explanatory
2. Shipper
• Name of the shipping company
3. 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. 21
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
Pickup
1. 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. 22
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
Signatures
• Bitcoin
• 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. 23

24. 24
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the item was received; signs
transaction and release funds from multisig to the
Vendor. Attaches rating/review.

25. 25
Reference Hash
1. Reference
• Contract ID (shipping notice) that the
data applies to
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the item was received; signs
transaction and release funds from multisig to the
Vendor. Attaches rating/review.

26. 26
Item
1. Received
• Was the item received (Boolean)?
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the item was received; signs
transaction and release funds from multisig to the
Vendor. Attaches rating/review.

27. 27
Payout
1. 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
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the item was received; signs
transaction and release funds from multisig to the
Vendor. Attaches rating/review.

28. 28
Rating
1. 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
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the item was received; signs
transaction and release funds from multisig to the
Vendor. Attaches rating/review.

29. 29
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the item was received; signs
transaction and release funds from multisig to the
Vendor. Attaches rating/review.
Dispute
1. 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. 30
Signatures
• Bitcoin
• Multisig signing key of the Vendor is used to sign
JSON data from ‘04_buyer.01_receipt’
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the item was received; signs
transaction and release funds from multisig to the
Vendor. Attaches rating/review.