Receipt Format Reference

ChioReceipt

The ChioReceipt is the top-level signed structure. Every field is present in the canonical JSON serialization.

Decision

The Decision enum represents the kernel's verdict. It is serialized as a tagged union with a verdict discriminator field.

JSON Serialization

{
  "verdict": "allow"
}

{
  "verdict": "deny",
  "reason": "path matches forbidden pattern **/.env",
  "guard": "forbidden-path"
}

{
  "verdict": "cancelled",
  "reason": "user cancelled the operation"
}

{
  "verdict": "incomplete",
  "reason": "tool server did not respond within timeout"
}

ToolCallAction

Describes the tool call that was evaluated. Contains the raw parameters and their canonical hash for integrity verification.

The parameter_hash is computed by serializing parameters to canonical JSON (RFC 8785), then computing the SHA-256 hex digest. This allows verifiers to confirm that parameters were not modified after receipt creation.

{
  "parameters": {
    "path": "./workspace/README.md"
  },
  "parameter_hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}

GuardEvidence

Evidence from a single guard's evaluation. The evidence array contains one entry per guard that was evaluated.

[
  { "guard_name": "forbidden-path", "verdict": true },
  { "guard_name": "path-allowlist", "verdict": true },
  { "guard_name": "shell-command", "verdict": true },
  { "guard_name": "egress-allowlist", "verdict": true },
  { "guard_name": "mcp-tool", "verdict": true },
  { "guard_name": "secret-leak", "verdict": true },
  { "guard_name": "patch-integrity", "verdict": true },
  {
    "guard_name": "forbidden-path",
    "verdict": false,
    "details": "path matches forbidden pattern **/.env"
  }
]

Financial Metadata

For tool calls governed by monetary grants, the metadata field includes a financial key with detailed cost and budget information.

OracleConversionEvidence

Evidence for cross-currency conversions when the cost was denominated in a currency different from the grant currency. The struct is deny_unknown_fields: a consumer parsing metadata.financial.oracle_evidence must expect exactly this field set.

Governed Transaction Metadata

The flat financial block above is retained for backward compatibility. Governed receipts also carry a governed_transaction block under metadata, holding the intent identifiers plus optional approval, commerce, metering, runtime-assurance, and call-chain evidence bound into the request.

economic_authorization

A versioned typed envelope that consolidates budget, meter, rail, and settlement truth into separate sub-blocks. It is additive: the compatibility financial, commerce, metered_billing, approval, runtime_assurance, call_chain, and autonomy fields remain intact beside it.

Signing Process

The receipt signing process is deterministic and reproducible. Any party with the receipt body can verify the signature.

1. Validate receipt semantics. Reject any body whose receipt_kind, boundary_class, decision, and trust_level combination is invalid (for example a mediated_decision without a decision).
2. Bind the signing nonce. Before the id is computed, write the pre-binding id into metadata["chio_receipt_signing_nonce"]. Because metadata is part of ChioReceiptIdInput, the nonce is covered by both the receipt id and the signature. This is a normative step of the receipt-id algorithm, not an incidental detail.
3. Compute the content-addressed id. id = H(canonical_jcs(ChioReceiptIdInput)) over the now-nonce-bound body.
4. Sign the signing body. Serialize ChioReceiptSigningBody ({ id, body, bbs_signature? }) to RFC 8785 canonical JSON — keys sorted lexicographically, no whitespace, deterministic number formatting — and sign those bytes with the kernel's signing key (Ed25519 by default; P-256 or P-384 when configured).
5. Attach signature. Embed the algorithm-aware signature and the kernel's public key in the receipt.

Verification

Receipt verification can be performed by any party with no additional context. The receipt is self-contained.

1. Re-validate semantics. Confirm the receipt_kind / boundary_class / decision / trust_level combination is well-formed. A malformed combination fails verification.
2. Re-derive the id. Recompute H(canonical_jcs(ChioReceiptIdInput)) and confirm it equals id. A mismatch means the identity-defining fields were altered.
3. Verify the signature. Re-serialize ChioReceiptSigningBody to RFC 8785 canonical JSON and verify signature against those bytes using kernel_key. The verifier dispatches off the self-describing signature encoding (Ed25519 / P-256 / P-384), not the algorithm hint.
4. Verify parameter hash. Recompute the SHA-256 over RFC 8785 canonical JSON of action.parameters and compare with action.parameter_hash.

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

// Parse the receipt from JSON
const receipt = parseReceiptJson(receiptJsonString);

// Verify signature and parameter hash
const result = await verifyReceipt(receipt);

if (result.signatureValid && result.parameterHashValid) {
  console.log("Receipt is valid");
} else {
  console.error("Receipt verification failed", result);
}

# Verify using openssl (manual)
# 1. Extract body (all fields except "signature")
# 2. Serialize to canonical JSON
# 3. Verify Ed25519 signature against kernel_key

# Or use the SDK:
$ node -e "
  const { verifyReceiptJson } = require('@chio-protocol/sdk/invariants');
  const fs = require('fs');
  const receipt = fs.readFileSync('receipt.json', 'utf8');
  verifyReceiptJson(receipt).then(r => console.log(r));
"

Complete JSON Example

{
  "id": "7c1e5a2b9d34f60e8a1b4c7d0e3f6a9b2c5d8e1f4a7b0c3d6e9f2a5b8c1d4e70",
  "timestamp": 1744537862,
  "capability_id": "cap_7f3a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7de91d",
  "tool_server": "srv-files",
  "tool_name": "read_file",
  "action": {
    "parameters": {
      "path": "./workspace/README.md"
    },
    "parameter_hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
  },
  "decision": {
    "verdict": "allow"
  },
  "receipt_kind": "mediated_decision",
  "boundary_class": "prevent",
  "tool_origin": "caller_executed",
  "redaction_mode": "none",
  "content_hash": "d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8",
  "policy_hash": "b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
  "evidence": [
    { "guard_name": "forbidden-path", "verdict": true },
    { "guard_name": "path-allowlist", "verdict": true },
    { "guard_name": "shell-command", "verdict": true },
    { "guard_name": "egress-allowlist", "verdict": true },
    { "guard_name": "mcp-tool", "verdict": true },
    { "guard_name": "secret-leak", "verdict": true },
    { "guard_name": "patch-integrity", "verdict": true }
  ],
  "metadata": {
    "financial": {
      "grant_index": 0,
      "cost_charged": 1,
      "currency": "USD",
      "budget_remaining": 999,
      "budget_total": 1000,
      "delegation_depth": 0,
      "root_budget_holder": "ca-prod-01",
      "settlement_status": "settled",
      "cost_breakdown": {
        "base": 1
      }
    }
  },
  "trust_level": "mediated",
  "kernel_key": "9c7b3f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e",
  "signature": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6"
}

Deny Receipt Example

{
  "id": "b8d2f47a06c19e35d7a0b3c6e9f2a5b8c1d4e70f3a6b9c2d5e8f1a4b7c0d3e69",
  "timestamp": 1744537863,
  "capability_id": "cap_7f3a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7de91d",
  "tool_server": "srv-files",
  "tool_name": "read_file",
  "action": {
    "parameters": {
      "path": "./workspace/.env"
    },
    "parameter_hash": "f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
  },
  "decision": {
    "verdict": "deny",
    "reason": "path matches forbidden pattern **/.env",
    "guard": "forbidden-path"
  },
  "receipt_kind": "mediated_decision",
  "boundary_class": "prevent",
  "tool_origin": "caller_executed",
  "redaction_mode": "none",
  "content_hash": "c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
  "policy_hash": "b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
  "evidence": [
    {
      "guard_name": "forbidden-path",
      "verdict": false,
      "details": "path matches forbidden pattern **/.env"
    }
  ],
  "trust_level": "mediated",
  "kernel_key": "9c7b3f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e",
  "signature": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6"
}

Receipt Querying

Receipts can be queried from the receipt store using filters. The CLI and SDK both support the same filter set:

# All denials in the last hour
$ chio receipt list --outcome deny --since $(date -v-1H +%s)

# Financial receipts over $1.00
$ chio receipt list --min-cost 100

# Receipts for a specific capability
$ chio receipt list --capability cap_7f3a...e91d --limit 100

Storage and Merkle-Committed Log

The local receipt store durably persists every signed receipt along with its sequence number. Beyond durable storage, receipts are periodically batched into checkpoints: each checkpoint commits to a Merkle root over the receipts it contains, letting verifiers check inclusion of any single receipt with an O(log n) proof instead of replaying the entire log.

• Checkpoint. A signed commitment over a Merkle root of a contiguous window of receipts, plus the window's first and last sequence numbers and timestamp.
• Inclusion proof. For a given receipt, the set of sibling hashes needed to reconstruct the Merkle root. A verifier recomputes the root from the receipt hash and sibling hashes, then matches it against the checkpoint root.
• Offline verification. With a checkpoint plus an inclusion proof, a third party can confirm a receipt was part of the committed log without access to the full receipt store.

Receipt Lineage (Multi-Parent DAG)

Receipts can declare multi-parent lineage so a verifier can order and connect them across kernels. When present, a receipt carries the following signed lineage fields:

The verifier rejects a child unless its parent descriptors match the signed parent set, every parent shares the same chainId, and dagOrdinal strictly exceeds every parent's. This rejects cross-kernel cycles without relying on one global clock. This multi-parent lineage is distinct from the ChildRequestReceipt mechanism below; the two can coexist on the same operation.

Child Request Receipts

For nested operations (tool calls that spawn child requests), the kernel also produces ChildRequestReceipt records. These track the session, parent request, child request, operation kind, and terminal state, all signed with the same canonical-JSON process. Child receipts link to the originating tool call via parent_request_id. This is a separate mechanism from the multi-parent receipt lineage described above.

// Parent receipt (tool call that spawned a nested operation)
{
  "id": "a4f0c9d2e5b81736a0c3d6e9f2b5a8c1d4e70f3a6b9c2d5e8f1a4b7c0d3e692f",
  "tool_name": "run_task",
  "action": { "parameters": { "task": "analyze" }, "parameter_hash": "..." },
  "decision": { "verdict": "allow" },
  "receipt_kind": "mediated_decision",
  ...
}

// Child request receipt linked via parent_request_id
{
  "id": "child-4b8e-8f1d",
  "session_id": "sess_4b8e",
  "parent_request_id": "req_2b8e",
  "request_id": "req_8f1d",
  "operation_kind": "subtool_call",
  "terminal_state": "completed",
  "outcome_hash": "...",
  "policy_hash": "...",
  "kernel_key": "...",
  "signature": "..."
}