Ricardian contract documentation for services

1. OpenBazaar
Ricardian Contracts
Services
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
Service
1. Title
• Name of the item
2. Description
• Character limited description of the item
3. Price
• Bitcoin: shipping fee in bitcoin
• Fiat: shipping fee in fiat that the bitcoin price floats to
4. 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
5. Keywords
• Used for reverse-lookup on the distributed hash table (i.e.
search)
6. Process Time
• The maximum predicted time it will take a Vendor to ship the
item after receiving an order
7. Ephemeral
• Defines how long the content is available for (time, downloads)
if applicable

7. 7
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

8. 8
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

9. 9

10. 10
Stage 2: Buyer places an order
2. Buyer places an order, funds multisig address (funds are now in
escrow)
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.

11. 11
Stage 2: Buyer places an order
2. Buyer places an order, funds multisig address (funds are now in
escrow)
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

12. 12
Stage 2: Buyer places an order
2. Buyer places an order, funds multisig address (funds are now in
escrow)
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

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.
Digital Content
1. Semantics
• Any data the buyer needs to give to the Vendor
to make a purchase
• E.g. Quality
2. Service address
• The address where the service will be performed
• Encrypted address: address is XOR’d with a
nonce and encrypted with the Vendor’s PGP
public key
• SHA256 nonce: necessary to determine the
service address; used to verify against
• Encrypted nonce: nonce encrypted to the
Buyer’s public 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.
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

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.
Signatures
• Bitcoin
• Multisig signing key of the Buyer is used to
sign JSON data from ‘02_buyer.01_order’

16. 16

17. 17
Step 3: Vendor ships the item
3. Vendor indicates that the service has been performed;
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

18. 18
Step 3: Vendor ships the item
3. Vendor indicates that the service has been performed;
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

19. 19
Step 3: Vendor ships the item
3. Vendor indicates that the service has been performed;
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
Services Rendered
1. Comments
• Any comments the Vendor feels to make
2. 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

20. 20
Step 3: Vendor ships the item
3. Vendor indicates that the service has been performed;
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’

21. 21

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

23. 23
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 service was performed;
signs transaction and release funds from multisig to
the Vendor. Attaches rating/review.

24. 24
Service
1. Service Rendered
• Was the service rendered (Boolean)?
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the service was performed;
signs transaction and release funds from multisig to
the Vendor. Attaches rating/review.

25. 25
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 service was performed;
signs transaction and release funds from multisig to
the Vendor. Attaches rating/review.

26. 26
Rating
1. Transaction rating
• Select from choices:
• Positive
• Neutral
• Negative
2. Service quality
• Rate out of 5 stars
3. Service description
• Rate out of 5 stars
4. Feedback
• Character limited text reviewing the
transaction
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the service was performed;
signs transaction and release funds from multisig to
the Vendor. Attaches rating/review.

27. 27
Step 4: Buyer confirms item received
Bob
The Buyer
4. Buyer indicates that the service was performed;
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?

28. 28
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 service was performed;
signs transaction and release funds from multisig to
the Vendor. Attaches rating/review.