LanternDOCS

Verifiable Receipts

When a headless agent finishes, you can ask the runtime for a signed receipt — tamper-evident, offline-verifiable proof of what actually ran. The receipt is signed over the run's journal hash, so any post-hoc edit to the run's event log invalidates the signature.

What a receipt attests

The receipt binds together the run's identity and the cryptographic hash of its event-sourced journal. Because the journal is the authoritative record of every step that executed, signing over its hash means the receipt attests to the exact sequence of steps that ran — not a summary that could drift from reality.

Payload fields

The Ed25519 signature covers the canonical JSON of a receiptPayload struct with these fields (alphabetically sorted keys, compact JSON, no whitespace):

  • agentName — always present
  • agentVersion — omitted when blank
  • costUsd — accumulated cost for the run
  • issuedAt — RFC3339 timestamp
  • journalHash — SHA-256 of the ordered journal_events rows
  • model — omitted when blank
  • provider — omitted when blank
  • runId — always present
  • status — succeeded or failed
  • tenantId — always present
  • tokensIn / tokensOut — prompt and completion token counts
  • version — schema version (currently 1)

The canonical JSON is produced by a three-step round-trip: marshal the struct, unmarshal into map[string]any, re-marshal (Go sorts map keys alphabetically on re-marshal). The result is compact JSON with keys in alphabetical order — reproducible offline with any JSON library that sorts keys.

Issuing a receipt

Issue and persist a signed receipt for a completed run:

POST /v1/runs/{id}/receipt

The receipt is an Ed25519 signature over the journal hash. It is persisted alongside the run, so it can be retrieved and re-verified later.

Verifying offline

Verification needs no privileged access. The signing key's algorithm and fingerprint are published at a well-known endpoint, so an external party can verify a receipt without calling back into your control plane:

GET /.well-known/lantern-receipts

Anyone holding a receipt and the published key fingerprint can confirm:

  • the receipt was signed by this deployment's key, and
  • the journal hash inside it matches the run's actual event log — i.e. nothing was altered after the fact.
Note: A receipt is signed over the journal hash, so tampering with even one event after issuance breaks verification. The journal is also what durable execution replays on recovery — the same record underpins both crash-safety and provenance.

Why it matters

  • Provenance. Cryptographic proof of exactly which steps a run executed.
  • Tamper-evidence. Editing the journal after the fact invalidates the signature.
  • Offline verification. The key fingerprint at /.well-known/lantern-receipts lets external verifiers check a receipt without trusting (or contacting) your control plane.

Receipts share the same signing + verification machinery as run receipts elsewhere on the platform — see the API reference for the full request/response shape.