Export and verify evidence
Export your receipt store as a portable package, verify it offline, and read each failure before a reviewer sees it.
On this page
Hand a reviewer one directory, and they can check every decision your kernel signed without reaching your systems. The package carries the signed receipts, their capability lineage, any checkpoints, and a manifest that hashes each file.
Work in the application you already run. One recorded call is enough to export, allowed or refused, under any tool name.
StartThe verifier works from the exported bytes
Export reads receipts and checkpoints from the store into one directory. The verifier checks it with no access to the producer’s kernel. Export and verify evidence.
- checkpoint signerbackground · chio-store-sqlite
Every
checkpoint_batch_sizereceipts (100 by default; 0 turns it off), commits the batch’s canonical bytes to an RFC 6962 Merkle root and signs aKernelCheckpointwhose body carriesprevious_checkpoint_sha256and achain_root.With a checkpoint: whether a receipt was in its batch, from an inclusion proof against
merkle_root, and whether checkpoints chain.- evidence packagechio evidence export
A directory holding
receipts.ndjson,checkpoints.ndjson,inclusion-proofs.ndjson,capability-lineage.ndjson, the checkpoint transparency records, andretention.json, withmanifest.jsonlisting a hash for every file.From the package alone: whether any file changed since export. The manifest is not authenticated against an outside source.
- verifierchio evidence verify
Checks the file hashes, the signatures the package carries, and its inclusion proofs, with no access to the producer’s kernel. The receipt-verification project repeats the receipt checks in Python, JavaScript, and Go.
It computes integrity and inclusion from bytes. Whether an external effect happened is outside what a receipt can show.
checkpoint.rs:139/// A signed kernel checkpoint statement.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct KernelCheckpoint {
/// The signed body.
pub body: KernelCheckpointBody,
/// Ed25519 signature over canonical JSON of `body`.
pub signature: Signature,
}
1. Export the store your application wrote
Run the export in the directory where your application keeps its receipt store. A project that runs chio locally, including a coding agent on the filesystem connection, keeps it at .chio/receipts.db, the path below. Stop a short-lived demo first if you want a stable record count.
$ chio --receipt-db .chio/receipts.db evidence export --admin-all --output ./evidence
$ ls evidenceREADME.txt capability-lineage.ndjson checkpoint-consistency-proofs.ndjson checkpoint-equivocations.ndjson checkpoint-publications.ndjson checkpoint-witnesses.ndjson checkpoints.ndjson child-receipts.ndjson inclusion-proofs.ndjson manifest.json query.json receipts.ndjson retention.json
You should see thirteen entries, manifest.json among them. The pricing API's MCP host writes one store per session, at ../pricing-api/sessions/latest/receipts.db for the most recent session your client printed. --admin-all reads every tenant in the database; a tenant-specific handoff uses that tenant’s read boundary. Use a fresh output directory for each export.
Application code writes the same package with project.history.export(...), shown in Inspect your receipts.
2. Verify the package away from your application
The verifier reads only the directory. It needs neither the original database nor a running Chio service.
$ chio evidence verify --input ./evidenceevidence package verified tool_receipts: 2 child_receipts: 0 checkpoints: 0 checkpoint_publications: 0 checkpoint_witnesses: 0 checkpoint_consistency_proofs: 0 checkpoint_equivocations: 0 capability_lineage: 2 inclusion_proofs: 0 uncheckpointed_receipts: 2 authorized_receipts: 1 trace_observations: 0 advisory_evaluations: 0 verified_files: 12 child_receipt_scope: FullQueryWindow transparency_preview_logs: 0 publication_state: transparency_preview
You should see evidence package verified and a coverage summary. This capture holds two tool receipts, one of them an authorized allow; your counts follow the calls your application made. uncheckpointed_receipts equals the receipt count until the kernel signs its first checkpoint, and Verify receipts offline shows how to require that coverage at export.
3. Break a copy and read the refusal
Copy the package, append one newline to the copy’s receipts, and verify the copy.
$ cp -R evidence evidence-tampered
$ printf '\n' >> evidence-tampered/receipts.ndjson
$ chio evidence verify --input ./evidence-tamperederror[CHIO-ATTEST-PROVENANCE-MISSING]: evidence package file hash mismatch for receipts.ndjson help: receipts.ndjson changed after the package was exported; verify the package as exported, or export it again code: urn:chio:error:attest:provenance-missing docs: https://chio.computer/docs/reference/errors#error-attest-provenance-missing
You should see exit status 1 and a file hash mismatch for receipts.ndjson. The manifest check runs first, so one changed byte stops verification before any signature is read. Keep the original package for your handoff and discard the copy.
4. Verify against the key your reviewer pins
A clean result shows the package is intact and each record verifies under the key it names. Your reviewer decides which key that should be, obtains it from you out of band, and pins it.
chio evidence verify --input evidence --trusted-kernel-pubkey kernel.pubverified 2 receipts from 1 kernel, signatures verified against pinned keys
You should see the receipts verified against the pinned key (illustrative line). A partner who added your partner card pins your kernel by name with --partner, so the key comes from the card your organization published, never from the package under review.
Each failure names the check that stopped it
The error names the check that stopped verification. Start by confirming that every file the manifest names arrived unchanged.
File hash mismatch
The named file’s bytes changed after export. Fetch the original export instead of editing the manifest: the manifest lists hashes, and a receipt changed under a matching manifest still fails its receipt ID and signature.
Receipt signature failure
A receipt fails verification under its signing key because the record changed after signing. Obtain the original export from its producer.
Signer outside the pinned set
The signatures verify under a key your reviewer did not pin. Confirm the key through your partner card or another authenticated channel, or reject the package.
A passing package proves integrity and attribution for the records it carries. Whether it holds every call is answered by checkpoints and their publication, described in Verifiable evidence, and what a receipt shows about an external effect is the mediation boundary.