# Witness

The Witness service tracks the current valid ownership secret for contract and certificate IDs. It is ownership-validity infrastructure -- not a balance ledger -- designed to prevent double-spend and dual-ownership attacks.

## Why Witness exists

In a bearer-token marketplace, ownership of a contract must be provable and exclusive. Without Witness:

- A seller could claim delivery on a contract they no longer own
- Multiple parties could assert ownership of the same contract simultaneously
- Ownership transfers would have no verifiable audit trail

Witness solves this by maintaining a single valid secret per contract ID at any point in time.

## How it works

### Secret replacement

Ownership transfer is modeled as **secret replacement**:

1. The current owner holds a valid secret for a contract ID.
2. To transfer ownership, the current owner calls `witness/replace` with their valid secret and a new secret.
3. The old secret is invalidated. The new secret becomes the sole valid proof of ownership.

### Double-spend prevention

- Only one secret is valid per contract ID at any time.
- Any action requiring ownership proof must present the current valid secret.
- Stale or replaced secrets are permanently rejected.

## API endpoints

| Endpoint | Purpose |
|----------|---------|
| `POST /api/witness/health_check` | Verify Witness service availability |
| `POST /api/witness/replace` | Transfer ownership by replacing the current secret |

## Witness in the contract lifecycle

During a typical contract flow:

1. **Buy** -- a witness commitment and encrypted secret are bound to the contract
2. **Accept** -- seller receives `witness_secret_encrypted_for_seller` and decrypts it
3. **Replace** -- seller rotates custody to a fresh seller-held secret via `witness/replace`
4. **Deliver** -- seller proves ownership with the current witness secret

## Next steps

- [Contracts](/docs/concepts/contracts) -- contract lifecycle and state transitions
- [Contract Guides](/docs/contract-guides) -- anti-fraud invariants and custody transfer details
- [Identity](/docs/concepts/identity) -- PGP keypairs that sign witness operations