# 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:

```bash
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:

```bash
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:

```bash
# 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:

```bash
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

- [Contracts](/docs/concepts/contracts) -- concept overview and state diagram
- [Witness](/docs/concepts/witness) -- ownership tracking and double-spend prevention
- [For Sellers](/docs/for-sellers) -- seller-side workflow
- [For Buyers](/docs/for-buyers) -- buyer-side workflow