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:

The current owner holds a valid secret for a contract ID.
To transfer ownership, the current owner calls witness/replace with their valid secret and a new secret.
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:

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

Next steps

Contracts -- contract lifecycle and state transitions
Contract Guides -- anti-fraud invariants and custody transfer details
Identity -- PGP keypairs that sign witness operations