How it works
A capsule has two sides. The organisation whose agent acts creates the record at the moment of the action. Later, someone who was not in the room asks for part of it and checks the answer for themselves. This page walks through both sides, in that order.
A diary is not a signed record
Most agents already write logs. A log and a signed record answer different questions.
An ordinary log
- Editable
- Deletable
- Reorderable
- Often collected late, after something went wrong
- Written by the system it describes
seal()
- Content-addressed: the record carries digests, and the content stays with you
- Signed at the boundary, by a key the model never holds
- Chained locally and append-only; checkpoints are registered with a witness
- Checkable by anyone, offline, with published public keys
log() call, and it is not the diary on the left. A log() entry is chained, checkpointed and witnessed like a sealed capsule. It only leaves out the producer's signature, so a verifier reports its authorship as not claimed. Use seal() when it matters who made the record.The line
A log is enough, until someone else has to believe it.
| A log is good for | A log is not enough when |
|---|---|
| debugging | money moves — a payment, a trade, a refund |
| ops dashboards | a duty applies — a regulator, a contract, a customer's right |
| “what happened last night” | someone else was harmed — a counterparty, an evaluator, a court |
| the author's own memory |
Each case on the right has a party who was not in the room and does not take your word for it. For the operator, a diary is fine. Once a second party is entitled to the truth, the diary is a claim, not evidence. The rest of this page is what it takes for that party to believe a record without trusting whoever wrote it.
1 of 2 · Creating capsules
Everything in this half happens inside the organisation, before anyone asks a question.
Nothing to verify yet. Nobody has asked.
Nothing has left the organisation but a checkpoint, and the date is already fixed.
● sealed by the organisation · ○ received, signed by someone else · ▲ checkpoint · ✓ witness receipt
- Seal at the boundary. Each consequential action is sealed where it leaves the agent, by a key the model never holds. The capsule carries digests of the inputs and outputs. The content itself stays in your payload store.
- Carry in the other side's half. When a counterparty sends its own signed record,
received()commits those exact bytes as they arrived. It never re-signs them, so the record stays theirs. - Seal what applied, and what was decided. The same log can hold the obligation an action was under (here, a disclosure duty) and any judgment made against it. They are ordinary sealed records; the format has no special case for them.
- Checkpoint. The checkpointed local log (CLL) chains every entry, append-only. At intervals it signs a checkpoint: one small value that commits to its whole history so far, with its size and the tree's peaks.
- Witness. Only the checkpoint goes to a witness, a SCITT Transparency Service that registers checkpoints under a published consistency policy. It returns a Receipt saying the checkpoint was registered no later than a given time. Under that policy, a checkpoint that carries a consistency proof is registered only if it extends the previous one. The organisation does not operate the witness, and you can register with more than one. See witness anywhere.
2 of 2 · Using capsules
Months later, someone entitled to the truth asks. The organisation discloses the record, and only the part that was asked for.
withheld: digest only
▲ checkpoint · ✓ receipt
inclusion proofs
judgments
The date was fixed before anyone asked.
by: a party entitled to ask
inclusion in checkpoint 09:41Z ✓
receipt ✓ consistency-verified
counts recomputed ✓
sealed → chained → checkpointed → registered → asked → disclosed → recomputed
The relying party recomputes everything offline. They trust the arithmetic and the published keys, not the organisation.
The exchange follows draft-mih-agent-evidence-request, an individual Internet-Draft. A request names a slice (what evidence is wanted) and the checkpoint the answer has to verify against. Every request ends in exactly one of three outcomes:
| Outcome | What it is | Who signs it |
|---|---|---|
| The records | A bundle with the requested capsules, the checkpoint and its witness receipt, and an inclusion proof for each record. Anything outside the slice appears only as a digest. | The organisation, plus the witness's receipt |
| A signed refusal | A refusal with a machine-readable reason, such as not_authorized or no_such_subject (“we hold no such record”). It is an answer, and the asker can keep it and show it to others. | The organisation |
| Absence | No answer arrived before the asker's deadline. Nobody sends an absence; the asker records its own request and the window in which nothing came. | The asker, about its own attempt |
The three are never converted into one another. An asker cannot turn a timeout into a refusal, and an organisation that stays silent has not refused. Silence is recorded as silence. And because the records were checkpointed and witnessed when they were sealed, an answer given months later cannot be backdated: the date was fixed before anyone asked.
Nine on your copy, one on theirs
These are ten questions an investigator asks about an agent's record. Nine can be answered from your own copy, by recomputation. The tenth needs the other party's copy.
capsule_id is recomputed from the bytes; any change breaks it.received(), or their own copy. See bilateral attestation.