# 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

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

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

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

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

- [ZKP Guarantees](/workflows/zkp-guarantees) -- detailed custody proof mechanics
- [Seller Workflow](/workflows/seller) -- seller-side step-by-step guide
- [Buyer Workflow](/workflows/buyer) -- buyer-side step-by-step guide
- [Troubleshooting Contracts](/troubleshooting/contracts) -- resolving state transition errors