# Becoming a witness

Mirror clears nothing on two banks' word alone. Two parties with a stake in a price stating the same number is agreement, not confirmation. So a `reconciled` reading needs a third party with **no stake in the price** to have agreed: a customs office, a terminal that weighed the container, a laboratory that assayed the metal. This page is for the organisation that could be that party. It covers what you would run, what you would publish, what you would never see, and how the banks would admit you.

**Status:** no witness is connected. No terminal, customs office, carrier or laboratory has agreed to be one. Until one does, the live rail answers `undetermined` (`insufficient_independence`) where it would otherwise clear. That is by design, not a fault.

## Who can be a witness, and of what

A witness is ratified under a class, and a class is competent only on the evidence it actually holds. A terminal can confirm a mass; it can never confirm a price.

| Class | What it witnesses | The axes it can confirm |
|---|---|---|
| `customs` | The declared customs value and quantity | unit price, total value, quantity |
| `terminal` | The gross mass weighed at gate-in (the verified gross mass under SOLAS) | quantity |
| `port` | The mass or unit count the port authority recorded | quantity |
| `weighbridge` | A certified weighing | quantity |
| `carrier` | The cargo received on board | quantity |
| `warehouse` | Goods held under an independent warehouse receipt | quantity |
| `inspectorate`, `surveyor` | An independent pre-shipment inspection, or a draft or tally survey | quantity, quality |
| `assayer` | An independent assay of grade or fineness | quality |
| `certifier` | Hours or work performed on a services contract, by someone with no position in its price | quantity |

**Not witnesses, and why.** A cargo insurer's sum insured is usually derived from the invoice value, the very number under test. A credit or payment insurer pays out on the invoice. A ship's AIS track is broadcast by the ship itself and can be spoofed or switched off. A bank financing the trade has a stake in its price.

## What a terminal or a weighbridge runs

One dependency-free tool, `witness/mirror-witness.js`. It writes files and opens no network connection.

```
node witness/mirror-witness.js init --org "Example Container Terminal" --class terminal --out witness-private.jwk
node witness/mirror-witness.js weigh --container CSQU3054383 --port NLRTM --load-date 2026-09-20 --kg 8250 --table kg.json --log bulletin.log --receipt-out receipt.txt
node witness/mirror-witness.js publish --log bulletin.log --out bulletin.json --key witness-private.jwk --previous last-bulletin.json
node witness/mirror-witness.js verify --bulletin bulletin.json --public witness-public.jwk --previous last-bulletin.json
```

1. **`init`** makes the witness key: a file for a trial, or a key held in your own HSM with `--custody`. It prints the public key and the ratification event the banks will sign.
2. **`weigh`**, at gate-in, records one weighing. It writes one opaque entry in your log and a **receipt code** that belongs on the cargo's papers and nowhere else. `kg.json` is the public table of mass bands the corridor uses.
3. **`publish`** turns the log into a bulletin: the entries, a head signed with the witness key, and a proof that it extends your previous bulletin. It refuses to publish a head that does not extend the last one, so a restored backup missing entries cannot become a fork by accident.
4. **Host `bulletin.json` wherever you choose,** such as your own website. Mirror does not fetch it. The banks do.
5. A bank holding the receipt code from the cargo's papers proves that the cargo's entry is in your bulletin (`mirror-bander bulletin-anchor`) and attaches that proof to its reconciliation.

A weighbridge that prefers to sign each weighing rather than publish a log uses `measure`. A laboratory uses `issue-certificate` for one lot, then `measure --axis quality`.

## What a customs office runs

A customs administration already holds the declared value and quantity of every consignment it clears. It witnesses them by signing its **own leg**: the band of the declared value, under the corridor's table and key, exactly as a bank bands its invoice. It is the only class that can confirm a **price**.

```
node witness/mirror-witness.js init --org "Example Customs Administration" --class customs --out customs-witness.jwk
mirror-bander band --in declarations.csv --out legs.json --edges <the corridor's table> --closed --secret-file corridor.txt --sign --key customs-witness.jwk
```

1. **`init --class customs`** makes the witness key (in a file for a trial, in the office's own HSM with `--custody`) and prints the ratification event. The members ratify it by quorum, as for a terminal.
2. **The office holds the corridor key.** The members share it at their ceremony, or the office's HSM holds it. That is the real cost of a customs witness, stated plainly: like each member bank, the office could compute the band of any leg on that corridor it was shown. It is shown none, because legs go to the operator and never to a witness. The members decide in writing whether to admit it on those terms.
3. **`band --sign`** writes the customs leg (role `customs`) as commitments only: no value, no quantity, no reference. The operator clears on it only if the office's ratified key signed it, and the record names the office and the axes it confirmed. On a [ratio corridor](/ratio-corridors) the office bands its declared value against the same cited public reference as the banks (`--reference-set`), so it never has to hold a price table at all.

A local dry run of the whole path is `node server/customs-witness.test.js`. It uses the real tools and an operator inside one process, and touches no network and no live rail. It shows a bank and the office clearing within a ratified ceiling, and what does not clear: two banks alone, a declaration that disagrees, a price four times above the table even when everyone states it, and a key that calls itself customs without being ratified.

## What you see, and what you never see

- **You see what you already see:** the container, the port, the day and the weight. A terminal weighs the container at gate-in anyway.
- **You never see** the price, the invoice, the banks involved, which bank looked up an entry, or whether anyone did.
- **Your entries reveal nothing on their own.** Each is salted with that cargo's receipt code, so without the papers an entry cannot be tied to a container.

## How the banks admit you

- `init` prints the event: `{ "type": "witness.propose", "kid", "org", "class", "jwk" }`. A member bank signs it and submits it to the operator's `/registry/event`. A quorum of distinct members ratifies it with `witness.ratify`. Until then, nothing your key signs anchors anything.
- **The registry refuses a witness key that is also a member key.** It demotes a witness that shares an organisation with a stakeholder to `relayed`, which counts only where the corridor accepts relays.
- **Suspension is by quorum** (`witness.suspend`). Each bank whose clears rested on a suspended witness gets a signed recall notice (`/recall/notice`).
- **Two histories convict their signer.** Two different signed heads at one tree size are proof of equivocation (`/witness/forks`). The members then act on it through governance.

## What your signature means, and what it does not

- **It attests what you measured: a mass, a grade, a declared value.** It never attests contents or a price. A terminal that confirms the mass says nothing about the price, so two parties who over-invoice a real shipment still clear on the price axis. Every reading names which axes an independent party confirmed, so nobody reads more into it.
- **It cannot vouch for calibration.** Publish what you weighed. The rail records whose scale it was.
- **It produces no score and no finding about anyone.** It is evidence that one fact agreed.

## The cold start: relays

A bank's operations desk already holds terminal receipts, warehouse warrants and inspection certificates. Under a separate relay key, made in a separate ceremony from the trade-finance desk (`mirror-bander relay-keygen`, `relay-measure`), it can commit the measured band from such a document.

- That is segregation of duties, not independence.
- A relayed anchor counts only on a corridor whose members ratified `anchor.accept_relayed`.
- It is always recorded as `relayed`, never as `direct`.

## Money and terms

Mirror moves no money. Any fee a bank pays a witness, and any terms between them, are agreed between those parties alone. Nothing passes through Mirror.

## A different kind of witness: the log witness

Anyone, including a bank, a regulator or an auditor, can also witness the operator's **transparency log**. `witness/mirror-witness-cli.js` pulls the operator's signed log head, co-signs what it saw, swaps heads with other witnesses outside the operator, and exits non-zero if it ever sees a fork. That role makes the operator's log append-only by observation, from buildings the operator does not control. It anchors no trade and sees no trade data.

Nothing on this page requires an account, a contract or a call before you try it. The tool runs on a laptop with a trial key, and [`verify`](#what-a-terminal-or-a-weighbridge-runs) checks a bulletin the way the banks would.