# Receipt format

> Read the signed receipt schema and verify a sample bundle offline with a dependency-free Node script; no Excellent installation is required.

A receipt is what a verification run leaves behind. It binds the work, the evidence, the
policy and the verdict into one document, hashes that document canonically, and signs the
hash with an Ed25519 key. The point of it is that you do not have to trust the machine
that produced it, or us.

That claim is only worth something if you can check it. This page publishes the format
(a JSON Schema) and a verifier you can read in one sitting and run on a machine that has
never had Excellent on it. Both are served from this site:

- [receipt-schema.json](https://www.excellent.so/receipt-schema.json): the format, as JSON Schema 2020-12
- [verify-receipt.mjs](https://www.excellent.so/verify-receipt.mjs): a verifier, Node 18+, no dependencies
- [receipt-example.json](https://www.excellent.so/receipt-example.json): an example receipt pack
- [receipt-example-key.pub.pem](https://www.excellent.so/receipt-example-key.pub.pem): the public key it was signed with

## Check one in under a minute

```bash
curl -fsSLO https://www.excellent.so/verify-receipt.mjs
curl -fsSLO https://www.excellent.so/receipt-example.json
curl -fsSLO https://www.excellent.so/receipt-example-key.pub.pem

node verify-receipt.mjs receipt-example.json --pubkey receipt-example-key.pub.pem
```

Real output, from that exact command:

```console
Excellent receipt check — receipt-example.json

  PASS  pack shape
        schemaVersion 1, envelope and trust root present
  PASS  signature algorithm is Ed25519
        signature.algorithm = ed25519
  PASS  canonical binding present
        the receipt is bound to a work snapshot, contract, evidence snapshot, evaluator, determination, enforcement decision, review and build
  PASS  payload matches its hash
        recomputed sha256:ee27611cb8b1d02d3edca0ad12308a64409930de759f7fc64c9f39042387b5bc from the receipt content and it matches envelope.payloadHash
  PASS  envelope summary agrees with the receipt
        publicVerification restates the receipt id, run, tenant, key and hash without contradicting them
  PASS  receipt and envelope carry the same signature
        receipt.signature mirrors envelope.signature
  PASS  Ed25519 signature verifies
        the signature over sha256:ee27611cb8b1d02d3edca0ad12308a64409930de759f7fc64c9f39042387b5bc checks out against the public key you supplied
  PASS  signing key is declared by the pack
        trustRoot declares key_example_2026_09
  PASS  key fingerprint matches the one you pinned
        sha256 over your PEM file is sha256:7e7b79a7135e246e76931580fd56a5d49fe94b2024c18dc81157038822bd1b4c, which is the fingerprint the pack declares for key_example_2026_09
  PASS  ledger anchor
        the ledger and audit log match anchor sha256:ba2658d08481e61503a281a16ab83a37edcd54521475e33d5571fc6809258c0f, recorded to operator-held-file at 2026-09-23T17:05:00.000Z

RESULT: VERIFIED
```

The script then prints what that result does and does not establish. It exits 0 when the
pack verifies, 8 when it does not, and 2 on a usage error, the same contract as
`excellent-mcp receipt verify`. Add `--json` for one machine-readable line instead.

Then break it, and watch it fail. Change any character of the receipt's content (the
verdict, a timestamp, one hex digit of an evidence hash) and run it again:

```console
  FAIL  payload matches its hash
        envelope.payloadHash is sha256:ee27611cb8b1d02d3edca0ad12308a64409930de759f7fc64c9f39042387b5bc but the content canonicalizes to sha256:7930319d69b2c1fceb5c0a4bc0187b57789c55df8a2dbc523685827afa6a08e2 — the receipt body has been altered since it was hashed

RESULT: NOT VERIFIED
```

The signature is still valid: it is a signature of the original payload. What no longer holds
is that the document in front of you is the document that was signed. Reformatting is a
different matter: minify the file, reorder its keys, change its indentation, and it still
verifies, because the signature covers a canonical rendering rather than the bytes on
disk.

## What the verifier checks

In order, and each one independently:

1. **The pack is the right shape.** `schemaVersion` 1, with an envelope and a trust root.
2. **The signature algorithm is Ed25519.** An authoritative receipt signed any other way
   is refused rather than downgraded.
3. **A binding is present.** Without one, a `PASS` is a verdict about nothing in particular.
4. **The payload matches its hash.** The canonical payload is rebuilt from the receipt and
   the binding, hashed, and compared to `envelope.payloadHash`. This is the tamper check.
5. **The envelope's summary agrees with the receipt.** `publicVerification` is a
   convenience copy and is not signed, so it is treated as a claim and cross-checked.
6. **The receipt and the envelope carry the same signature.**
7. **The Ed25519 signature verifies** against the public key you passed on the command
   line, never a key read out of the pack itself.
8. **The pack declares the signing key**, and
9. **the key's fingerprint matches the one you pinned**: sha256 over the bytes of your PEM
   file, compared to the fingerprint the pack states.
10. **The ledger anchor holds.** The anchor's id is recomputed from its contents, and the
    ledger and audit log are compared entry by entry against what it commits to.

Only the first nine are about the receipt. The tenth is about whether the chain it sits in
has been rewritten.

## The schema

[receipt-schema.json](https://www.excellent.so/receipt-schema.json) describes the whole pack: the signed envelope,
the receipt inside it, the binding that says what the receipt is about, the trust root, and
the ledger anchor. Every field in it exists in the code that mints receipts; optional
fields are marked optional, and fields whose meaning is not obvious from their name carry a
description.

Four things the schema says that are easy to miss, and that matter if you are writing your
own verifier:

**The signature does not cover the file.** It covers a canonical rendering of a fixed field
list: `predicate`, `schemaVersion`, `id`, `tenantId`, `runId`, `parentReceiptId`, `status`,
`checkResultIds`, `evidenceHashes`, `policyVersionRefs`, `engineVersion`, `issuedAt`,
`binding`, and `decision` when the receipt carries one. Object keys are sorted, id arrays
are sorted, there is no whitespace, and absent optional keys are omitted rather than
written as null. Everything else in the file is outside the signature.

**`publicVerification` is outside it.** It restates the receipt id, run, tenant, key and
hash so a third party can check the signature without parsing the rest, but nothing stops
someone editing it. A verifier has to re-derive those facts from the receipt and reject a
document where the two disagree.

**Absent is not the same as empty, except where it is.** In the binding, an absent
`obligationResultIds` canonicalizes to `[]`, so absent and empty hash identically. An absent
`decision` is omitted from the payload entirely, so absent and present-but-empty do not.
That asymmetry is deliberate: receipts issued before `decision` existed are signed and
immutable, and emitting the key unconditionally would have stopped every one of them
verifying.

**`status` is an aggregate, `decision` is not.** A run whose predicate was evaluated and
came back false, and a run where nothing evaluated the predicate at all but one evidence
artifact was unregistered, both aggregate to `FAIL`. `decision` is the field that separates
them. When it is absent, the receipt does not disclose whether anything was decided, which
is not the same as saying nothing was.

## The example receipt

The document below is the file at [receipt-example.json](https://www.excellent.so/receipt-example.json). It is a
**synthetic example**, and the line between what is invented and what is not matters here.
The work it describes is invented: a throwaway task, a throwaway tenant, ids that point at
nothing. The document around that work is not. It was produced by the same envelope
builder, the same canonical hash, the same Ed25519 signing convention and the same anchor
construction that a customer's receipts go through, signed with a keypair generated for
this page and then discarded, and it verifies both under the script above and under
Excellent's own offline verifier.

A receipt from real work names a real repository, a real commit and a real task. Publishing
one of those is a separate decision, and this page is built so that such a receipt can take
this slot without anything else here changing.

```json
{
  "schemaVersion": 1,
  "generatedAt": "2026-09-23T17:05:00.000Z",
  "envelope": {
    "schemaVersion": 1,
    "serviceVersion": "2026-08-16.v1",
    "receipt": {
      "schemaVersion": 1,
      "id": "receipt_example_a1b2c3",
      "tenantId": "tenant_example",
      "runId": "run_example_7f3a",
      "parentReceiptId": null,
      "status": "PASS",
      "decision": {
        "decided": true,
        "decidedBy": "excellent.evaluator.unit-test-predicate@1.4.0",
        "predicateStatus": "PASS",
        "undecidedReasonCode": null
      },
      "checkResultIds": [
        "check_example_unit_tests",
        "check_example_typecheck",
        "check_example_evidence_integrity"
      ],
      "evidenceHashes": [
        "sha256:0ae18d55145fdfa9be069b98ea6afa2e16070cba8b2b025c76dea1b6ed52d35e",
        "sha256:70d6383e2b282c115efcac1f436506827d7d01964f5a95645b1b7dfd51d18976",
        "sha256:db792624ecd6a865a2155a8bbf457f33c7b11fa8a47bc1a38118ddaa641f2b44"
      ],
      "policyVersionRefs": [
        "excellent.policy.agent-work@2026-08-16",
        "sha256:9f2c1d6b5a4e38f70c1b2d3e4f50617283940a1b2c3d4e5f60718293a4b5c6d7"
      ],
      "engineVersion": "excellent-verification-engine@2026-08-16.v1",
      "issuedAt": "2026-09-23T17:04:11.000Z",
      "signature": {
        "keyId": "key_example_2026_09",
        "algorithm": "ed25519",
        "value": "ed25519:nAAB2y8VQ5kvh5md75R42aIcMhfsKBlVEPP_kmhuYcN9VdiQn3x-fh8AvtZTmRfBJr-lqP4-uGNY2hD9TAHdDg"
      }
    },
    "binding": {
      "predicate": "excellent.verification.agent-work-receipt.v1",
      "workItemId": "work_example_add_retry",
      "workSnapshotId": "snapshot_example_0f11",
      "attemptId": "attempt_example_01",
      "runManifestId": "manifest_example_01",
      "contractId": "contract_example_unit-tests-must-pass@3",
      "evidenceSnapshotId": "evidence_snapshot_example_51ab",
      "evidenceGraphDigest": "sha256:06e23d6cc15f57df2d8e123fbe2520e8291472fa4f2dcc573aa18a903e93d598",
      "obligationResultIds": [
        "obligation_example_tests",
        "obligation_example_types"
      ],
      "evaluatorRefs": [
        "excellent.evaluator.unit-test-predicate@1.4.0"
      ],
      "determinationId": "determination_example_9c2",
      "validityStateId": "validity_example_current",
      "enforcementDecisionId": "enforcement_example_promote",
      "enforcementEffectIds": [
        "effect_example_merge_allowed"
      ],
      "reviewDecisionIds": [
        "review_example_auto_accept"
      ],
      "outcomeObservationIds": [
        "outcome_example_no_regression_7d"
      ],
      "auditEventIds": [
        "audit_example_mint"
      ],
      "buildRef": "build_example_2026-09-23.1",
      "subject": {
        "treeHash": "sha1:4d9f1c0b7a6e5d4c3b2a19087f6e5d4c3b2a1908",
        "commitSha": "c0ffee1234567890abcdef1234567890abcdef12",
        "buildId": "build_example_2026-09-23.1",
        "imageDigest": "sha256:1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809",
        "tenantId": "tenant_example",
        "environmentId": "env_example_ci",
        "policyDigest": "sha256:9f2c1d6b5a4e38f70c1b2d3e4f50617283940a1b2c3d4e5f60718293a4b5c6d7"
      }
    },
    "payloadHash": "sha256:ee27611cb8b1d02d3edca0ad12308a64409930de759f7fc64c9f39042387b5bc",
    "signature": {
      "keyId": "key_example_2026_09",
      "algorithm": "ed25519",
      "value": "ed25519:nAAB2y8VQ5kvh5md75R42aIcMhfsKBlVEPP_kmhuYcN9VdiQn3x-fh8AvtZTmRfBJr-lqP4-uGNY2hD9TAHdDg"
    },
    "publicVerification": {
      "algorithm": "sha256",
      "payloadHash": "sha256:ee27611cb8b1d02d3edca0ad12308a64409930de759f7fc64c9f39042387b5bc",
      "signatureAlgorithm": "ed25519",
      "keyId": "key_example_2026_09",
      "receiptId": "receipt_example_a1b2c3",
      "runId": "run_example_7f3a",
      "tenantId": "tenant_example",
      "issuedAt": "2026-09-23T17:04:11.000Z",
      "parentReceiptId": null
    }
  },
  "trustRoot": {
    "tenantId": "tenant_example",
    "generatedAt": "2026-09-23T17:05:00.000Z",
    "declaredKeys": [
      {
        "keyId": "key_example_2026_09",
        "fingerprint": "sha256:7e7b79a7135e246e76931580fd56a5d49fe94b2024c18dc81157038822bd1b4c",
        "algorithm": "ed25519"
      }
    ],
    "signedByKeyId": "key_example_2026_09",
    "signatureAlgorithm": "ed25519"
  },
  "ledgerAnchor": {
    "schemaVersion": 1,
    "id": "sha256:ba2658d08481e61503a281a16ab83a37edcd54521475e33d5571fc6809258c0f",
    "target": "operator-held-file",
    "anchoredAt": "2026-09-23T17:05:00.000Z",
    "ledgerHead": "sha256:fabe76b800f3d84dde97be85a1e32b72c096491d02f4c826400d54a207ba6e33",
    "ledgerLength": 2,
    "ledgerEntryHashes": [
      "sha256:91ba2f9aa2f63fa36df1bb719959bcaebb8034852886bbee141b2a5825a059d3",
      "sha256:fabe76b800f3d84dde97be85a1e32b72c096491d02f4c826400d54a207ba6e33"
    ],
    "auditLogHead": "sha256:033be47f7c89645acecf79fd7f6976622c62f18dd105331dd1771c8d2d03a5f4",
    "auditLogLength": 1,
    "auditLogEntryHashes": [
      "sha256:033be47f7c89645acecf79fd7f6976622c62f18dd105331dd1771c8d2d03a5f4"
    ]
  },
  "ledger": [
    {
      "id": "ledger_example_1",
      "entryHash": "sha256:91ba2f9aa2f63fa36df1bb719959bcaebb8034852886bbee141b2a5825a059d3"
    },
    {
      "id": "ledger_example_2",
      "entryHash": "sha256:fabe76b800f3d84dde97be85a1e32b72c096491d02f4c826400d54a207ba6e33"
    }
  ],
  "auditLog": [
    {
      "id": "audit_example_1",
      "entryHash": "sha256:033be47f7c89645acecf79fd7f6976622c62f18dd105331dd1771c8d2d03a5f4"
    }
  ],
  "legacyReadOnly": false
}
```

## Checking a receipt of your own

The script takes any receipt pack, not just this one. Excellent writes them; point the
script at yours and pin your own key:

```bash
node verify-receipt.mjs my-receipt-pack.json --pubkey my-key.pub.pem
```

If you also hold an anchor id from outside the pack, supply it and rollback becomes
detectable too. Both flags are required together: an anchor id with no time cannot tell a
pack that is merely out of date from one attesting a different ledger:

```bash
node verify-receipt.mjs my-receipt-pack.json --pubkey my-key.pub.pem \
  --expect-anchor-id sha256:… --expect-anchored-at 2026-09-23T17:05:00.000Z
```

`verify-receipt.mjs` is a second, independent implementation of the format described here.
The reference implementation is `excellent-mcp receipt verify <pack.json> --pubkey <key.pem>`,
which runs the same checks from inside the product and reports them as one JSON line. The
two agreeing is the useful signal. The two disagreeing would be a bug worth telling us
about, in whichever one turns out to be wrong.

## What a valid signature does not establish

A valid signature means the receipt has not been altered since the holder of that key
signed it, and that the verdict is bound to a named work snapshot, contract, evidence
snapshot and build. That is tamper-evidence, and it is real.

It does not establish that the work was good. A receipt records that checks ran and what
they concluded. Whether those were the right checks (whether they test anything worth
testing) is a judgement the signature cannot make for you. The receipt names its checks by
id precisely so that you can go and look.

It does not establish who signed. A signature proves custody of a key, never an identity.
If you obtained the key from the same system that issued the verdict, a forged receipt
re-signed under an attacker's key verifies exactly as cleanly as a genuine one. Confirm the
key's fingerprint through a channel that system does not control, then pin it. That is
what `--pubkey` is for, and why the script refuses to read a key out of the pack it is
checking.

And with no independently held anchor, it does not establish that you are holding the
current pack. A genuine anchor from an earlier state, presented with the ledger rewound to
match it, verifies exactly like a current one.

## Related

- [Sample receipt](https://www.excellent.so/docs/sample-receipt): the product's real release receipt (verdict `FAIL`), field by field, and a tamper being caught.
- [Receipts](https://www.excellent.so/docs/receipts): the short version.
- [How verification decides](https://www.excellent.so/docs/how-verification-decides): what has to be true before a receipt can say `PASS`.
- [CLI reference](https://www.excellent.so/docs/cli): the CLI verifier's flags and exit codes, and which CLI release has it.

Source: https://www.excellent.so/docs/receipt-format
