Receipt Format

Source

This page normatively reflects spec/PROTOCOL.md in the chio repository, the sections Receipt Identity And DAG and 6.1 through 6.4. Status: Current bounded Chio release profile. Version 1.0, dated 2026-04-14. The document uses MUST, MUST NOT, and MAY as requirement words.

The wire form is the record schema spec/schemas/chio-wire/v1/receipt/record.schema.json ($id https://chio-protocol.dev/schemas/chio-wire/v1/receipt/record/v1). The companion schemas in the same directory, as the signed-artifact registry lists them:

• admission-metadata.schema.json (chio.admission-receipt.v1): Chio Durable Admission Receipt Metadata.
• delivery-contract.schema.json (chio.delivery-contract.v1): Chio Delivery Contract Receipt Metadata.
• finding-delivery.schema.json (chio.finding.delivery.v1): Chio Finding Delivery Receipt Metadata.
• inclusion-proof.schema.json: Chio Receipt Merkle Inclusion Proof.
• lineage_statement.schema.json (chio.receipt_lineage_statement.v1): Chio receipt lineage statement.
• record.schema.json (chio.receipt.v1): Chio Receipt Record.

Behavior is checked against the crate crates/core/chio-core-types/src/receipt (body.rs, decision.rs, kinds.rs, metadata.rs, signing.rs, economics.rs, governance.rs, and lineage.rs), the kernel signing primitive in crates/kernel/chio-kernel-core/src/receipts.rs, the metadata assembly in crates/kernel/chio-kernel/src/receipt_support/receipt_metadata.rs, and the CLI flags in crates/products/chio-cli/src/cli/types/receipt.rs. Where the specification and a crate disagree, the crate is the behavior, cited by line.

Synopsis

// schema: chio.receipt.v1
pub struct ChioReceipt {
    pub id: String,
    pub timestamp: u64,
    pub capability_id: String,
    pub tool_server: String,
    pub tool_name: String,
    pub action: ToolCallAction,
    pub decision: Option<Decision>,  // omitted when None
    pub receipt_kind: ReceiptKind,
    pub boundary_class: BoundaryClass,
    pub observation_outcome: Option<ObservationOutcome>,  // omitted when None
    pub tool_origin: ToolOrigin,
    pub redaction_mode: RedactionMode,
    pub actor_chain: Vec<ActorRef>,  // omitted when empty
    pub content_hash: String,
    pub policy_hash: String,
    pub evidence: Vec<GuardEvidence>,  // omitted when empty
    pub metadata: Option<serde_json::Value>,  // omitted when None
    pub trust_level: TrustLevel,
    pub tenant_id: Option<String>,  // omitted when None
    pub bbs_projection_version: Option<String>,  // omitted when None
    pub kernel_key: PublicKey,
    pub bbs_signature: Option<BbsReceiptSignature>,  // omitted when None
    pub algorithm: Option<SigningAlgorithm>,  // omitted when None or ed25519
    pub signature: Signature,
}

The shape of ChioReceipt (body.rs lines 42 to 109) with the serde omission rule beside each field that has one, under the schema id chio.receipt.v1 (CHIO_RECEIPT_SCHEMA, line 38).

ChioReceipt

ChioReceipt is the signed record. The table reads each field, its type, and its doc comment from the struct; the last three columns say when serde drops the field from the wire, whether the field is part of ChioReceiptIdInput (the id preimage, lines 180 to 210), and whether it sits under the signature through ChioReceiptBody (lines 111 to 144).

The struct declares 24 fields. 20 of them form the id preimage, 21 sit under the signature, and 9 carry an omission rule.

Field behavior the doc comments do not state

• id is sha256_hex(canonical_json_bytes(ChioReceiptIdInput)) (body.rs lines 239 to 244). The preimage leaves out id, bbs_signature, algorithm, and signature (lines 180 to 210). The schema fixes it to 64 lowercase hex characters (record schema line 30).
• decision is required on a mediated_decision receipt and refused on a trace_observation or advisory_evaluation receipt (metadata.rs lines 94 to 131; record schema lines 178 to 215).
• receipt_kind fixes trust_level: signing refuses any other pairing (body.rs lines 164 to 175). The pairings are in the semantic fields section.
• boundary_class never carries cannot_see on a signed receipt: validate_decision refuses it (metadata.rs lines 82 to 87) and the schema enum omits it (record schema lines 67 to 75).
• content_hash is recomputed by the signer over the canonical content preimage before any signing work; the preimage is the RFC 8785 canonical JSON of a value output, the concatenated per-chunk digest preimage of a stream receipt, or the canonicalization of null for an empty output (receipts.rs lines 43 to 51 and 79 to 100).
• policy_hash has no hex pattern in the schema, because some deployments embed a symbolic policy version id (record schema lines 115 to 119).
• metadata is schema-less at the top level (record schema lines 127 to 129). The keys the kernel reserves are in the kernel metadata blocks section.
• bbs_projection_version is the constant chio.bbs-projection.receipt.v1 (signing.rs line 21; record schema lines 144 to 148). It and bbs_signature are present together or absent together: the schema declares them dependent (lines 174 to 177) and validate_bbs_receipt_binding refuses one without the other (signing.rs lines 167 to 190).
• bbs_signature, when present, rides in ChioReceiptSigningBody (signing.rs lines 99 to 104), so the receipt signature covers it even though it sits outside ChioReceiptBody. Its fields and pinned constants are BbsReceiptSignature, lines 16 to 47.
• algorithm takes the values ed25519, p256, p384, or hybrid (crypto.rs lines 88 to 100). serde drops it when it is unset or the default Ed25519 (lines 136 to 141). A hint that disagrees with the signature material fails verification with AlgorithmMismatch (body.rs lines 517 to 526).
• kernel_key and signature are hex strings whose prefix names the algorithm. The encodings are in the signing section.

Decision

Decision is an internally tagged enum: the tag field is verdict and the variant names serialize in snake_case (decision.rs lines 8 to 31; record schema lines 334 to 406).

The specification preserves cancelled and incomplete outcomes as distinct verdicts instead of one error state (spec/PROTOCOL.md lines 1027 to 1035).

The deny receipt the quickstart captured records the refusal in decision.reason; its guard is kernel and the receipt carries no evidence entries, because capability-scope validation refused the call before the guard pipeline ran.

$ chio --receipt-db .chio/receipts.db --session-db "$(mktemp -d)/admission.db" check \
    --policy ./policy.yaml --server hello --tool drop_tables --params '{}'

verdict:    DENY
tool:       drop_tables
server:     hello
reason:     requested tool drop_tables on server hello is not in capability scope
receipt_id: 28b6e2576ca2ccbd031e769d8d2bd504317161115a600f27771a7f932307a284
policy:     69e943b96e9ce64d0264bb56bf8930e77bd4e68adf68fcf1395790dae03e6b55
source:     0d35135e8b19230b7aa42b0cc5982579450f5dc4a0280822e8b339e7786d2296
mode:       preflight
fixture:    false

WARN chio_kernel::kernel::evaluation::async_evaluation_core message=capability rejected request_id=check-001 reason=requested tool drop_tables on server hello is not in capability scope

{  "id": "28b6e2576ca2ccbd031e769d8d2bd504317161115a600f27771a7f932307a284",  "timestamp": 1788529912,  "capability_id": "cap-01a06cb0-aae3-7ad3-8ba7-01350a3e01a0",  "tool_server": "hello",  "tool_name": "drop_tables",  "action": {    "parameters": {},    "parameter_hash": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"  },  "decision": {    "verdict": "deny",    "reason": "requested tool drop_tables on server hello is not in capability scope",    "guard": "kernel"  },  "receipt_kind": "mediated_decision",  "boundary_class": "prevent",  "tool_origin": "caller_executed",  "redaction_mode": "none",  "content_hash": "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",  "policy_hash": "69e943b96e9ce64d0264bb56bf8930e77bd4e68adf68fcf1395790dae03e6b55",  "metadata": {    "attribution": {      "delegation_depth": 0,      "issuer_key": "3dbf7b1230475796d5c78cdcf441c84721d9e3c24362fbbfb4225e307d1b9fb4",      "subject_key": "af2da8097f2c133affd89145302f029c7a5854e4e3a692a92b0cd20f84d07b37"    },    "chio_receipt_signing_nonce": "rcpt-01a06cb0-ab51-70d0-bcb3-72a8b78fe057",    "receipt_context": {      "request_id": "check-001"    }  },  "trust_level": "mediated",  "kernel_key": "3dbf7b1230475796d5c78cdcf441c84721d9e3c24362fbbfb4225e307d1b9fb4",  "signature": "e89f7a9cbe6c6b207cf5ac0c3e197a3957d62d2994217a7dcaeeeb9869abef1233680328432ee7a502a76238eb6ee9e72b19715e2458a3ef85aebfbed0df9202"}

ToolCallAction

The action the kernel evaluated (decision.rs lines 33 to 40).

ToolCallAction::from_parameters computes parameter_hash as the SHA-256 of the RFC 8785 canonical JSON of parameters, and verify_hash recomputes it (lines 42 to 58). The schema fixes the hash to 64 lowercase hex characters (record schema lines 327 to 331). The figures on this page recompute it from the captured receipts.

GuardEvidence

One entry per guard that evaluated the call (metadata.rs lines 184 to 194). The evidence array leaves the wire when it is empty, which is why the receipts the quickstart captured carry none.

Signed semantic fields

The enums in kinds.rs serialize in snake_case. Their wire values:

ReceiptKind

BoundaryClass

ObservationOutcome

ToolOrigin

RedactionMode

TrustLevel

Pairings signing enforces

validate_decision (metadata.rs lines 80 to 132) and validate_signable_semantics (body.rs lines 161 to 177) accept exactly these combinations; the record schema states the same rule as conditional requirements (lines 178 to 266).

is_authorized is true only for mediated_decision with prevent, no observation outcome, and an allow decision (metadata.rs lines 134 to 140); ChioReceipt::is_allowed adds trust_level == mediated (body.rs lines 545 to 550). result_label renders that case as Authorized; a trace record is Observed, an advisory record is Advisory, and any other mediated decision is Allowed, Denied, Cancelled, Incomplete, or, with no decision, Invalid (lines 142 to 158). Trace and advisory records are evidence, never authorization (spec/PROTOCOL.md lines 1022 to 1024).

Kernel metadata blocks

The kernel writes its typed blocks under reserved top-level metadata keys, merges them last, and rejects a pre-existing collision from caller or hook metadata, so a verifier can treat a block found under a reserved key as kernel-authored and covered by the receipt signature (spec/PROTOCOL.md lines 1074 to 1092; metadata.rs lines 196 to 203). The admission terminal enforces the rejection for delivery_contract, finding_delivery, and finding_recovery (crates/kernel/chio-kernel/src/kernel/admission_coordinator/terminal.rs lines 2049 to 2063, 2093 to 2103, and 2115 to 2125); the allow path merges attribution after caller metadata with last write wins on each nested key (crates/kernel/chio-kernel/src/kernel/responses/allow_responses.rs lines 84 to 93; receipt_metadata.rs lines 87 to 112).

The keys chio-core-types declares, read from the constants at the pin:

Two reserved keys in the specification table are defined outside those constants. original_metadata is written by the signing path when a caller passed a non-object metadata value: the value moves under that key before the nonce is inserted (signing.rs line 107 and lines 127 to 135; spec/PROTOCOL.md line 1085). admission_operation is ADMISSION_RECEIPT_METADATA_KEY with schema ADMISSION_RECEIPT_SCHEMA in crates/kernel/chio-kernel/src/admission_operation.rs lines 29 to 30. Keys outside the reserved set, such as the receipt_context block the captured receipts carry, are not typed by chio-core-types.

admission_operation

A durable governed call carries an admission_operation block with schema chio.admission-receipt.v1. It binds the signed receipt to the admission operation and request namespace, the terminal projection and dispatch state, trusted time, the coordinator lease and store fence, the retained dispatch commit, and the optional tool outcome; unknown fields and unsupported schema versions fail closed (spec/PROTOCOL.md lines 1099 to 1106). The typed writer is AdmissionReceiptMetadataV1, declared deny_unknown_fields (crates/kernel/chio-kernel/src/admission_operation/projection.rs lines 52 to 71); the wire contract is admission-metadata.schema.json, which requires every field below (lines 7 to 24).

projected_state takes the wire name of one of the 18 states of AdmissionOperationState, of which 7 are terminal (crates/kernel/chio-kernel/src/admission_operation.rs; schema lines 32 to 53). The allow receipt the quickstart captured carries this block with projected_state completed.

delivery_contract

A digest-constrained governed call carries a delivery_contract block with schema chio.delivery-contract.v1: the expected_digest the grant fixed in advance, the observed_digest of the delivered output, both canonical lowercase 64-character hex SHA-256, and a result of matched or mismatched(spec/PROTOCOL.md lines 1108 to 1119; delivery-contract.schema.json lines 7 to 22). The block is present only when the exercised grant carried an output-digest constraint: matched accompanies an Allow and mismatched accompanies the persisted zero-charge Deny. It carries no signature of its own; the enclosing receipt authenticates it.

The typed struct is DeliveryContract, declared deny_unknown_fields (metadata.rs lines 243 to 258). On a mismatch observed_digest is a domain-separated commitment keyed by the expected digest, and the delivered output digest stays in privileged durable outcome evidence (lines 250 to 255). DeliveryContract::validate checks the pinned schema and both hex digests and does not re-derive result (lines 260 to 285); ChioReceipt::delivery_contract reads the block (body.rs lines 605 to 614).

finding_delivery

A reveal admitted under a provider-signed finding purchase marker carries a finding_delivery block beside the generic one, schema chio.finding.delivery.v1. It names the finding_id and listing_id the sale was admitted under, the kernel-proved transform_profile, the digest_check and media_type_check comparisons, the settlement_mode the admitted selector named, the canonical SHA-256 digests of the accepted-bid and venue-admission envelopes, and the authoritative reservation_id, purchase_intent_id, and authoritative_payment_operation_id. Every field derives from kernel-verified state, never from a caller-asserted value, and the block appears only when the purchase context arrived through verified signed records (spec/PROTOCOL.md lines 1121 to 1132; finding-delivery.schema.json lines 7 to 54).

The struct is FindingDelivery (metadata.rs lines 398 to 432). Its enums: transform_profile is identity (lines 294 to 301); digest_check is matched or mismatched; media_type_check is matched, mismatched, or not_evaluated (lines 303 to 313); settlement_mode is local_reversible_hold (lines 315 to 322). An optional status_proof carries the kernel-verified non-inclusion evidence for the delivered finding: feed_id, key_domain_nonce (the fixed constant 3318287169837494), map_epoch, status_epoch_artifact_sha256, proof_sha256, root_hash, and non_inclusion_checked_at (lines 324 to 347 of the metadata module, lines 73 to 94 of the schema file). A no-charge redelivery under a recovery grant carries finding_recovery instead, schema chio.finding.recovery.v1, with recovery_id, finding_id, original_capability_id, original_delivery_receipt_id, and purchase_key (lines 479 to 505).

budget_authority

A monetary receipt carries a budget_authority block with the budget hold lineage. The typed reader is FinancialBudgetAuthorityReceiptMetadata (economics.rs lines 140 to 154): guarantee_level, authority_profile, metering_profile, hold_id, optional budget_term, optional authority ({ authority_id, lease_id, lease_epoch }, lines 108 to 114), authorize (optional event_id and budget_commit_index, exposure_units, committed_cost_units_after, lines 116 to 125), and optional terminal (disposition, the same event fields, exposure_units, realized_spend_units, committed_cost_units_after, lines 127 to 138).

The kernel writes the block in two shapes. The store profile alone (guarantee_level, authority_profile, metering_profile) comes from budget_backend_receipt_metadata (crates/kernel/chio-kernel/src/kernel/validation.rs lines 909 to 925). A charge writes the full lineage through budget_execution_receipt_metadata, which also adds invocation_capture when a quota was captured and, when an execution nonce was presented, execution_nonce_id and mediated_spend.profile (lines 927 to 1048). The typed reader ignores keys it does not declare. ChioReceipt::financial_budget_authority_metadata reads the block (body.rs lines 597 to 603). The authoritative-spend checks over this block are on Authoritative Spend.

The other reserved keys

• attribution: ReceiptAttributionMetadata (metadata.rs lines 538 to 554): subject_key and issuer_key of the capability, delegation_depth, and grant_index when the request resolved to one grant. The kernel writes it on every allow and deny it signs from a capability (receipt_metadata.rs lines 655 to 667). Both captured receipts carry it.
• chio_receipt_signing_nonce: bound by bind_receipt_signing_nonce before the id is computed (signing.rs lines 106 to 141). The signing section describes the step.
• financial and governed_transaction: the two sections that follow.
• channel: ChannelReceiptMetadataV1, camelCase and deny_unknown_fields, with schema pinned to chio.channel.receipt-metadata.v1, channelId, openDigest, reservationId, reservationDigest (each 64 lowercase hex), sequence (a positive I-JSON integer), and settlementMode channelized (economics.rs lines 8 to 50).

Financial metadata

For an allow receipt under a monetary grant the kernel serializes FinancialReceiptMetadata under the financial key; a denial caused by budget exhaustion carries attempted_cost with the cost that would have been charged (economics.rs lines 52 to 58). ChioReceipt::financial_metadata reads it (body.rs lines 581 to 585).

The struct documents invariants the type system does not enforce and the kernel must uphold when it constructs the block (lines 60 to 75): cost_charged <= budget_total; budget_remaining reflects the post-charge balance at write time and may be a best-effort snapshot at read time under an HA split; and on a denial cost_charged is 0 and attempted_cost holds the rejected cost.

SettlementStatus

OracleConversionEvidence

The cross-currency conversion evidence under financial.oracle_evidence (crates/core/chio-core-types/src/oracle.rs lines 9 to 31). The struct is deny_unknown_fields, its schema is the constant chio.oracle-conversion-evidence.v1 (line 7), and it carries no per-field doc comments: the names and types are the contract.

Governed transaction metadata

A request that carried a governed intent gets a governed_transaction block holding the intent identifiers and the approval, commerce, metering, runtime-assurance, call-chain, and autonomy evidence the kernel verified. The struct is GovernedTransactionReceiptMetadata (governance.rs lines 104 to 143); the kernel assembles it in governed_request_metadata (receipt_metadata.rs lines 480 to 604) and reads it back through ChioReceipt::governed_transaction_metadata (body.rs lines 587 to 590).

economic_authorization

EconomicAuthorizationReceiptMetadata (economics.rs lines 303 to 330) keeps budget, meter, rail, and settlement truth in separate typed sub-blocks, serialized in snake_case. It is additive: the compatibility financial, commerce, metered_billing, approval, runtime_assurance, call_chain, and autonomy fields remain (spec/PROTOCOL.md lines 1133 to 1141). The kernel attaches it only when the request carried a governed intent and a verified payee binding, and it refuses to sign when the binding disagrees with the intent digest, the seller, the settlement destination, or the approval digest (receipt_metadata.rs lines 250 to 293 and 443 to 478).

Receipt id and signing

prepare_receipt_body_for_signing (body.rs lines 246 to 252) runs the first three steps in this order; the signing entry points (lines 290 to 314) run the rest.

1. Validate the semantics. validate_signable_semantics rejects a body whose kind, boundary, observation outcome, decision, and trust level do not form one of the accepted pairings (lines 161 to 177).
2. Bind the signing nonce. bind_receipt_signing_nonce takes the caller-supplied body.id, trimmed, and writes it to metadata.chio_receipt_signing_nonce. A non-object metadata value moves under original_metadata first; an empty id skips the binding (signing.rs lines 121 to 141). Because metadata is in the id preimage, the nonce is covered by the id and the signature.
3. Compute the id. id = sha256_hex(canonical_json_bytes(ChioReceiptIdInput)) over the nonce-bound body (lines 239 to 244). Canonical JSON is RFC 8785: keys sorted, no whitespace, deterministic number formatting.
4. Sign the signing body. ChioReceiptSigningBody is { id, body: ChioReceiptIdInput, bbs_signature? } (signing.rs lines 94 to 104). Its canonical JSON is signed with the kernel key: ChioReceipt::sign with an Ed25519 keypair leaves algorithm unset, and sign_with_backend records the backend algorithm (lines 289 to 314). Both refuse a kernel_key that is not the signer key (lines 292 and 304).
5. Recompute content_hash first, in the kernel. chio_kernel_core::receipts::sign_receipt takes the canonical content preimage with the body, recomputes sha256_hex over it before the kernel-key check and before any signing work, and returns ContentHashMismatch with the recomputed and claimed hashes when they differ (receipts.rs lines 74 to 103). KernelKeyMismatch follows when body.kernel_key is not the backend key (lines 136 to 146). sign_receipt_with_handle consumes a one-time ReceiptSigningHandle so one handle backs at most one signature (lines 226 to 238). sign_receipt_relaying_trusted_body trusts the caller hash and exists only for the FFI and WASM transport adapters that relay a body minted upstream (lines 105 to 139).

{  "id": "448440b65fa15559a364d24512cbe4f08631befe2c3d2ab471dad7204b8b69c8",  "timestamp": 1788529911,  "capability_id": "cap-01a06cb0-a7d2-7e10-b32d-b985627e17e7",  "tool_server": "hello",  "tool_name": "hello_world",  "action": {    "parameters": {      "name": "Chio"    },    "parameter_hash": "319910ed4307f4c6486b4d282a01d4276a7aec7626c66be0f7eb2173d4a973a3"  },  "decision": {    "verdict": "allow"  },  "receipt_kind": "mediated_decision",  "boundary_class": "prevent",  "tool_origin": "caller_executed",  "redaction_mode": "none",  "content_hash": "8813cfed2cad28d238168ce79dde8ff3b39d38f2a5bea3661c7726d63f69f5ad",  "policy_hash": "69e943b96e9ce64d0264bb56bf8930e77bd4e68adf68fcf1395790dae03e6b55",  "metadata": {    "admission_operation": {      "compensation_status": "not_compensated",      "coordinator_lease_epoch": 1,      "coordinator_lease_id": "01a06cb0-a712-7440-b724-c4fe54913090",      "operation_id": "a78bde4b5404092f9eecca27e3d5109dcda0a870befee69f32e9dcbd49e12343",      "projected_dispatch_state": "terminal",      "projected_operation_version": 8,      "projected_state": "completed",      "request_binding_hash": "91dc5c706136b424cd8c4bb77df99232e8f40028b2217d5d2a1c84adfd246e70",      "request_id": "check-001",      "request_namespace_digest": "b6fe626fa0256f31deefc202a2efaecb2defd6a4ba93a5237dbc5f063948a651",      "retained_dispatch_commit": {        "committed_version": 6,        "coordinator_lease_epoch": 1,        "coordinator_lease_id": "01a06cb0-a712-7440-b724-c4fe54913090",        "provider_attempt": {          "attempt_id": "attempt:a78bde4b5404092f9eecca27e3d5109dcda0a870befee69f32e9dcbd49e12343",          "operation_id": "a78bde4b5404092f9eecca27e3d5109dcda0a870befee69f32e9dcbd49e12343",          "transport_id": "kernel-tool-server:hello",          "transport_key_epoch": 1        },        "store_fence": {          "lease_id": "01a06cb0-a712-7440-b724-c4fe54913090",          "owner_epoch": 1,          "store_uuid": "01a06cb0-a62a-7ef0-a2bc-fee0de0a9828"        }      },      "schema": "chio.admission-receipt.v1",      "store_fence": {        "lease_id": "01a06cb0-a712-7440-b724-c4fe54913090",        "owner_epoch": 1,        "store_uuid": "01a06cb0-a62a-7ef0-a2bc-fee0de0a9828"      },      "tool_outcome_id": "74a24dc524ae52adfe5594445a9fabb7f54d5c8d4580be5124ceab8ca7a87144",      "tool_outcome_version": 2,      "trusted_time_unix_ms": 1788529911968    },    "attribution": {      "delegation_depth": 0,      "grant_index": 0,      "issuer_key": "e08d69a6a3bf74cf4971a7e0a1ff3f566129fad32ec5580c3342316859ecf436",      "subject_key": "bb82465acb67f9413d39ef26ba3ceda6b5cd6413739e41a58b33edeb2909d8d8"    },    "chio_receipt_signing_nonce": "rcpt-01a06cb0-a8c2-7ad2-a78a-562ac4366063",    "receipt_context": {      "request_id": "check-001"    }  },  "trust_level": "mediated",  "kernel_key": "e08d69a6a3bf74cf4971a7e0a1ff3f566129fad32ec5580c3342316859ecf436",  "signature": "676bef1ac96b8519f5b316a98c05de7b46300e06983e0da58bb70db6d6c02f619222d07e44da61f2ca689015ab731d9c9e7727aeb826ad4690a2428f9fa82a01"}

Key and signature encodings

kernel_key and signature are hex strings whose prefix selects the algorithm. Bare hex is Ed25519 (32-byte key, 64-byte signature); p256: and p384: select ECDSA with an uncompressed SEC1 point as the key and DER as the signature; hybrid: carries a classical part, ML-DSA-65 bytes, and the algorithm set (PublicKey::from_hex, crypto.rs lines 405 to 433; Signature::from_hex and to_hex, lines 757 to 808). The record schema fixes the wire patterns (lines 151 and 170):

kernel_key  ^([0-9a-f]{64}|p256:04[0-9a-f]{128}|p384:04[0-9a-f]{192}|hybrid:[0-9a-f]{64}:[0-9a-f]{3904}:ed25519\+mldsa65|hybrid:p256:04[0-9a-f]{128}:[0-9a-f]{3904}:p256\+mldsa65|hybrid:p384:04[0-9a-f]{192}:[0-9a-f]{3904}:p384\+mldsa65)$
signature   ^([0-9a-f]{128}|p256:([0-9a-f]{2})+|p384:([0-9a-f]{2})+|hybrid:[0-9a-f]{128}:[0-9a-f]{6618}:ed25519\+mldsa65|hybrid:p256:([0-9a-f]{2})+:[0-9a-f]{6618}:p256\+mldsa65|hybrid:p384:([0-9a-f]{2})+:[0-9a-f]{6618}:p384\+mldsa65)$

Verification dispatches off the signature material, and verify_signature_with_floor applies a ReceiptCryptoFloor before the cryptographic check: allow_classical (the default) rejects hybrid receipts, pq_required rejects classical ones, and allow_hybrid accepts both (body.rs lines 496 to 530; crypto_floor.rs lines 11 to 23).

Verification

A receipt verifies from its own fields plus the set of kernel keys the verifier trusts. ChioReceipt::verify_signature (body.rs lines 478 to 494) runs, in order:

1. Semantics. validate_signable_semantics on the extracted body; a rejected pairing verifies as false.
2. BBS binding. validate_bbs_receipt_binding between bbs_projection_version and bbs_signature; a mismatch verifies as false.
3. Id. chio_receipt_id(body) must equal id; a tampered identity-defining field verifies as false.
4. Signature. kernel_key.verify_canonical over the rebuilt ChioReceiptSigningBody.

ToolCallAction::verify_hash checks parameter_hash separately (decision.rs lines 53 to 58). Neither step decides whether the signer is trusted; a verifier compares kernel_key against its own trust store.

TypeScript

verifyReceipt(receipt, trustedSigners) in @chio-protocol/sdk/invariants is synchronous and returns a ReceiptVerification with snake_case fields (sdks/typescript/chio-ts/src/invariants/receipt.ts lines 65 to 78 and 201 to 232). signature_valid requires the id to verify and the semantics to be signable (lines 211 to 214); signer_trusted is true only when kernel_key matches a supplied signer (lines 208 to 209), so ok is false for an empty trusted set (line 230); authorized adds the mediated-decision, prevent, and allow test (lines 206 to 216). A signature in an algorithm the SDK does not implement verifies as false instead of throwing (lines 5 to 20). verifyReceiptJson parses and verifies text with no trusted signers (lines 241 to 243).

import { parseReceiptJson, verifyReceipt } from "@chio-protocol/sdk/invariants";

// The kernel_key hex values a deployment trusts come from its own
// configuration. A receipt never vouches for its own signer.
const trustedSigners: string[] = [kernelKeyHex];

const receipt = parseReceiptJson(receiptJsonText);
const result = verifyReceipt(receipt, trustedSigners);

if (!result.ok) {
  console.error("receipt rejected", result);
}

// result.signature_valid, result.parameter_hash_valid, result.receipt_id_valid,
// result.signer_trusted, result.authorized, and result.result
// ("Authorized", "Allowed", "Denied", "Cancelled", "Incomplete", "Observed",
// "Advisory", or "Invalid").

Run it

chio evidence export writes a verifiable package from the receipt store, and chio evidence verify checks one offline (receipt.rs lines 160 to 200). The export takes the same tenant boundary as a listing: --tenant or --admin-all, and --require-proofs fails it when a selected receipt lacks checkpoint coverage.

$ chio --receipt-db .chio/receipts.db evidence export --admin-all --output ./evidence
$ ls evidence

README.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

Expected output

$ chio evidence verify --input ./evidence

evidence 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

When it refuses

One appended byte in receipts.ndjson moves the file hash the manifest committed to. The verify step exits 1 and names the file; a script branches on the exit code.

$ cp -R evidence evidence-tampered
$ printf '\n' >> evidence-tampered/receipts.ndjson
$ chio evidence verify --input ./evidence-tampered

error [urn:chio:error:attest:provenance-missing]: evidence package file hash mismatch for receipts.ndjson
context: {"domain":"attest","severity":"error","stability":"unstable","string_code":"CHIO-ATTEST-PROVENANCE-MISSING"}
suggested fix: Regenerate the evidence bundle and include provenance before submitting the operation.

Receipt querying

chio receipt list reads the local store and prints one JSON receipt per line (receipt.rs lines 5 to 47). The HTTP surface with the same filters and cursor pagination is on Receipt Query API.

The read fails closed when neither --tenant nor --admin-all is supplied (lines 40 to 46), and clap refuses --min-cost or --max-cost without --cost-currency (lines 25 to 30). The quickstart lists its store with a jq projection, then selects the deny receipt as JSON:

$ chio --receipt-db .chio/receipts.db receipt list --admin-all \
    | jq -r '[.decision.verdict, .tool_server, .tool_name, .id] | @tsv'

allow	hello	hello_world	448440b65fa15559a364d24512cbe4f08631befe2c3d2ab471dad7204b8b69c8
deny	hello	drop_tables	28b6e2576ca2ccbd031e769d8d2bd504317161115a600f27771a7f932307a284

$ chio --receipt-db .chio/receipts.db receipt list --admin-all \
    | jq 'select(.decision.verdict == "deny")'

{
  "id": "28b6e2576ca2ccbd031e769d8d2bd504317161115a600f27771a7f932307a284",
  "timestamp": 1788529912,
  "capability_id": "cap-01a06cb0-aae3-7ad3-8ba7-01350a3e01a0",
  "tool_server": "hello",
  "tool_name": "drop_tables",
  "action": {
    "parameters": {},
    "parameter_hash": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
  },
  "decision": {
    "verdict": "deny",
    "reason": "requested tool drop_tables on server hello is not in capability scope",
    "guard": "kernel"
  },
  "receipt_kind": "mediated_decision",
  "boundary_class": "prevent",
  "tool_origin": "caller_executed",
  "redaction_mode": "none",
  "content_hash": "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b",
  "policy_hash": "69e943b96e9ce64d0264bb56bf8930e77bd4e68adf68fcf1395790dae03e6b55",
  "metadata": {
    "attribution": {
      "delegation_depth": 0,
      "issuer_key": "3dbf7b1230475796d5c78cdcf441c84721d9e3c24362fbbfb4225e307d1b9fb4",
      "subject_key": "af2da8097f2c133affd89145302f029c7a5854e4e3a692a92b0cd20f84d07b37"
    },
    "chio_receipt_signing_nonce": "rcpt-01a06cb0-ab51-70d0-bcb3-72a8b78fe057",
    "receipt_context": {
      "request_id": "check-001"
    }
  },
  "trust_level": "mediated",
  "kernel_key": "3dbf7b1230475796d5c78cdcf441c84721d9e3c24362fbbfb4225e307d1b9fb4",
  "signature": "e89f7a9cbe6c6b207cf5ac0c3e197a3957d62d2994217a7dcaeeeb9869abef1233680328432ee7a502a76238eb6ee9e72b19715e2458a3ef85aebfbed0df9202"
}

chio receipt explain renders one receipt as a triage summary. It takes the receipt id, an optional --input-file holding one receipt or a bilateral co-sign document, --depth (default 8) and --fanout-limit (default 32) for the parent rendering, --inspect-bilateral for a structural trace of a bilateral envelope without signature verification, and the same tenant boundary (lines 78 to 122).

$ DENY=$(chio --receipt-db .chio/receipts.db receipt list --admin-all \
    | jq -r 'select(.decision.verdict == "deny") | .id')
$ chio --receipt-db .chio/receipts.db receipt explain "$DENY" --admin-all

receipt: 28b6e2576ca2ccbd031e769d8d2bd504317161115a600f27771a7f932307a284
schema: chio.receipt.v1
identity: 28b6e2576ca2ccbd031e769d8d2bd504317161115a600f27771a7f932307a284
decision: deny
reason: requested tool drop_tables on server hello is not in capability scope
guard: kernel
policy_hash: 69e943b96e9ce64d0264bb56bf8930e77bd4e68adf68fcf1395790dae03e6b55
scope_diff: requested scope vs granted scope is not embedded in this receipt
parents: 0
repair_hint: inspect the guard and policy_hash, then mint or narrow a matching capability

Storage and checkpoints

The local receipt store keeps every signed receipt with a sequence number, and chio receipt checkpoint create signs the next batch as a kernel checkpoint with the kernel seed file and a batch bound (--max-batch, default 1024); status and verify report and check the chain, and chio receipt audit runs the claim-log projection validation plus the full chain check (receipt.rs lines 56 to 67 and 139 to 158).

KernelCheckpointBody (crates/kernel/chio-kernel/src/checkpoint.rs lines 98 to 137, deny_unknown_fields) carries schema, checkpoint_seq, batch_start_seq, batch_end_seq, tree_size, merkle_root, issued_at, kernel_key, and the optional previous_checkpoint_sha256 and chain_root (an RFC 6962 root over the checkpoint-chain leaves that consistency proofs verify against). KernelCheckpoint is that body plus an Ed25519 signature over its canonical JSON (lines 140 to 148).

ReceiptInclusionProof names the checkpoint_seq, receipt_seq, leaf_index, merkle_root, and a MerkleProof, and verifies the receipt canonical bytes against an expected root (lines 150 to 173). The wire form of the proof is inclusion-proof.schema.json: tree_size (at least 1), leaf_index (below tree_size), and audit_path, the ordered sibling hashes from the leaf up to the root, each 32 bytes as lowercase hex with a 0x prefix, with right-edge siblings carried upward without pairing omitted (lines 8 to 29). The evidence package the verification section exports carries the checkpoints and inclusion proofs as NDJSON files beside the receipts.

Receipt lineage

ChioReceipt carries no lineage field (body.rs lines 42 to 109). Lineage between receipts is a separate signed record, the ReceiptLineageStatement, with schema chio.receipt_lineage_statement.v1 (lineage.rs line 211). One statement links one parent receipt to one child receipt; multi-parent views are derived aggregates over these pairwise statements (lineage_statement.schema.json line 5). The body serializes in camelCase (lines 228 to 247); the signed record adds signature over the canonical JSON of the body, and verify_signature checks the pinned schema before the key (lines 319 to 399).

The crate also defines the ordering types a DAG verifier uses: ReceiptHybridLogicalClock (wallSeconds, logical, kernelId; camelCase, deny_unknown_fields; lines 62 to 69), whose advance_from_parent takes the larger wall clock and increments the logical counter on a tie (lines 71 to 90); ReceiptDagParent (receiptId, chainId, dagOrdinal; lines 92 to 99); and parent_set_hash, the SHA-256 of the canonical JSON of the sorted, deduplicated parent receipt ids (lines 101 to 118). The record that carries chain_id, parent_set_hash, and dag_ordinal is the swarm join receipt (crates/kernel/chio-swarm-authority/src/types.rs lines 184 to 200), on Swarm Protocol.

Child request receipts

Nested flows such as sampling, elicitation, and resource reads under a parent call produce a ChildRequestReceipt (lineage.rs lines 24 to 43; spec/PROTOCOL.md lines 1060 to 1072). The signature covers the canonical JSON of ChildRequestReceiptBody, the record without algorithm and signature (lines 45 to 60 and 120 to 195). The child links to its parent through parent_request_id; a lineage statement is a separate record.

Related

• Receipts: the concept and the receipt kinds.
• Quickstart: the scenario that captured the receipts on this page.
• Receipt Query API: the HTTP query, analytics, and report endpoints.
• Query audit receipts and Verify receipts offline: the task guides.
• Wire Protocol: the framing that carries receipts and the schema contract.
• Schemas and errors: the signed-artifact registry and the error codes.
• Delivery contract: the digest comparison behind the delivery_contract block.
• Authoritative Spend: the checks over the budget_authority block and the execution nonce.
• Swarm Protocol: the join receipt that carries the DAG ordering fields.