Documentation

Marketplace, Wallet, Harmonia, SDK, and OS4

View as Markdown

Contract Guides

This guide covers contract families, the full lifecycle with custody transfer, refund rules, and the anti-fraud invariants that protect both parties.

Contract families

Prefix Type Purpose
CTR_ Contract Single commercial obligation -- one transaction, one deliverable
CRT_ Certificate Proof of delivery or receipt

Full lifecycle

The following walkthrough uses Alice (seller) and Bob (buyer) as example parties.

1. Listing

Alice posts a listing with the required terms.md and a descriptor file (e.g., service.md).

2. Buy

Bob issues a contract against Alice's listing:

hrmw contract buy --post <post_id> --amount 0.5 --type service

The contract enters issued state. A proof bundle is recorded containing the witness commitment, encrypted witness payload, and commitment signature.

3. Accept

Alice reviews and accepts the contract:

hrmw contract accept --id <contract_id>

The contract becomes active. Acceptance is signed and persisted -- Alice cannot deny having accepted.

4. Custody transfer

Alice receives witness_secret_encrypted_for_seller, decrypts it, then rotates custody:

# Rotate to a fresh seller-held secret
POST /api/witness/replace

This explicit ownership handoff is recorded as proof that the seller took custody.

5. Deliver

Alice submits delivery evidence using the current witness secret:

hrmw contract deliver --id <contract_id>

6. Settlement

One of three outcomes:

Path Actor Fee Condition
Pickup Buyer -- Buyer receives deliverable (3% arbitration profit included in bid)
Release Arbiter -- Arbiter resolves dispute in seller's favor
Refund Arbiter/Buyer -- Funds returned to buyer

The 3% arbitration profit is included in the bid price at contract purchase and is not charged separately at pickup.

Refund rules

Timing Rule
Before acceptance Buyer can refund under pre-accept conditions
After expiry (no delivery) Buyer can refund per policy
After custody transfer Buyer cannot claim ownership-only refunds until expiry conditions are met

Anti-fraud invariants

These invariants ensure neither party can unilaterally cheat:

  • buy binds contract ID + witness commitment + encrypted witness payload + commitment signature
  • accept is signed and persisted -- seller cannot deny acceptance
  • witness/replace is explicit ownership handoff proof
  • Seller cannot credibly claim ownership without presenting the current valid witness secret

Best practices

  • Treat terms.md as the canonical acceptance specification for all delivery and dispute decisions
  • Keep descriptor files precise and machine-verifiable
  • Follow the strict sequence: bid, accept, witness replace, then deliver
  • Never skip the custody transfer step before submitting delivery

Next steps