# Ledger format

> Entry shape, the hash chain, signatures and offline verification.

Reading time: 9 min. Source: https://www.voidagent.tech/docs/ledger

The ledger is append only, hash chained and signed per workspace. It is the undo stack and the compliance record in one object, which is the whole point: an undo stack nobody trusts is not a record, and a record you cannot execute is not an undo stack.

## Entry

```entry.json
{
  "sequence": 1042,
  "workspace": "acme",
  "agent": "billing-ops",
  "timestamp": "2026-08-21T09:14:11.204Z",
  "intent": "issue_refund",
  "tool": "stripe.refunds.create",
  "payload_digest": "sha256:7d19..c4b2",
  "blast_radius": { "systems": ["payments", "ledger", "mail"], "records": 3 },
  "class": "R3",
  "policy": { "decision": "hold", "rule": "irreversible transfer" },
  "approved_by": "dana@acme.example",
  "result": { "status": "ok", "external_id": "re_3P9k" },
  "snapshot": null,
  "compensation": null,
  "budget_entry": "r3:2026-08-21:1of2",
  "prev_hash": "0x9f3c..77d1",
  "hash": "0xa10e..3b08",
  "signature": "ed25519:5f21..ee90"
}
```

## The chain

hash = sha256(canonical_json(entry without hash and signature) || prev_hash). The signature covers the hash. Removing an entry breaks every hash after it, and forging a replacement chain requires the workspace key.

## Verification

```shell
$ void verify ./export.jsonl --key pk.pem
  + 18,422 entries, chain intact
  + 18,422 signatures valid
  + 0 gaps detected
  + head 0xa10e..3b08 matches manifest
```

> Verification is offline by design. An auditor needs the export file, the public key and the verifier binary. No network access to VOID is required.

## Compensation entries

A replay writes its own entries, so rewinding is itself auditable. A compensation entry references the sequence number it reverses.

```compensation.json
{
  "sequence": 1103,
  "kind": "compensation",
  "reverses": 1039,
  "class": "R0",
  "action": "restore(sha256:4c2e..91af)",
  "result": { "status": "ok", "digest_match": true },
  "operator": "dana@acme.example",
  "prev_hash": "0xbb41..09c2",
  "hash": "0xcc77..1d40",
  "signature": "ed25519:9a03..7fb1"
}
```

## Sinks

| sink | durability | use |
| --- | --- | --- |
| file:// | local disk | development and shadow mode |
| s3:// or gs:// | object storage with object lock | production, recommended |
| postgres:// | append only table with a trigger | when you already run Postgres and want SQL access |
| stdout | none | piping into your own pipeline |

---

This document is the markdown form of https://www.voidagent.tech/docs/ledger, published for agents that read
text rather than a rendered page. It is generated from the same data the page
renders, so the two cannot disagree.