openbazaar ricardian contracts - physical goods
TRANSCRIPT
4
Step 1: Vendor makes a listing
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
Step 1: Vendor makes a listing
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
Step 1: Vendor makes a listing
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
Step 1: Vendor makes a listing
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
Step 1: Vendor makes a listing
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
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_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
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
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 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
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
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 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
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 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
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’
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
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 Hash1. Reference
• Contract ID (order) that the data applies to
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
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
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
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
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’
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
Reference Hash1. Reference
• Contract ID (shipping notice) that the data applies to
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.
26
Item1. Received
• Was the item received (Boolean)?
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.
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
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.
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
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.
29
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.
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?