Documentation

Marketplace, Wallet, Harmonia, SDK, and OS4

View as Markdown

Bid Lifecycle

A contract begins when a buyer issues a bid and progresses through a deterministic state machine until settlement. Each transition is cryptographically signed and bound to witness custody proofs.

Contract State Machine

                          +---------+
                          | issued  |
                          +----+----+
                               |
                         seller accept
                               |
                          +----v----+
                          | accepted|
                          +----+----+
                               |
                       seller deliver
                               |
                          +----v----+
                          |delivered|
                          +----+----+
                              / \
                             /   \
                   buyer    /     \   buyer
                   pickup  /       \  refund
                          v         v
                    +---------+ +---------+
                    | settled | | refunded|
                    +---------+ +---------+

Sequence

1. Buyer issues the contract

POST /api/arbitration/contracts/buy

The buyer submits three cryptographic fields:

Field Purpose
witness_proof Public commitment binding custody to the contract ID
encrypted_witness_secret Seller-targeted encrypted custody secret
witness_zkp Signed commitment hash proving buyer identity binding

The contract is created in the issued state.

2. Seller accepts

POST /api/arbitration/contracts/{id}/accept

The response includes witness_secret_encrypted_for_seller. The seller decrypts this locally using their private key.

3. Seller rotates custody

POST /api/witness/replace

The seller calls replace with the decrypted buyer secret and a fresh seller-generated secret. This transfers witness ownership to the seller.

4. Seller delivers

POST /api/arbitration/contracts/{id}/deliver

Delivery requires the currently valid seller-held witness secret as proof of custody.

5. Settlement

The buyer finalizes via pickup (deliverable received; no additional fee) or refund (funds returned to buyer).

Fraud Resistance

The bid lifecycle provides three non-repudiation guarantees:

Guarantee Mechanism
Seller cannot deny acceptance Acceptance is cryptographically signed and stored on-chain
Seller cannot claim ownership without custody transfer Witness replacement creates an auditable ownership trail
Buyer cannot fake contract custody Only a valid, current witness secret is accepted by the server

Related