# Civilization Ledger

Not a game.

`vm-ledger` is a cryptographic, append-only, tamper-evident ledger for governance/law/memory/AI accountability.

## Properties (v0)

- Append-only log with a hash-chain.
- Signed entries (Ed25519).
- Deterministic verification: replay from genesis, verify hashes + signatures, emit an audit report.
- Local-first: no services required.
- No plaintext secrets committed; key material lives outside the repo.

## Quick start

```bash
# from this repo root
cd vm-ledger

cargo run -p ledger-cli -- keygen --out ~/.config/civ-ledger/keys/operator.json
cargo run -p ledger-cli -- init --dir ./my-ledger

ENTRY_HASH="$(cargo run -q -p ledger-cli -- append --dir ./my-ledger \
  --key ~/.config/civ-ledger/keys/operator.json \
  --namespace law \
  --payload-format json \
  --payload '{"type":"policy","id":"P-001","text":"No plaintext secrets in Git."}')"

cargo run -p ledger-cli -- checkpoint --dir ./my-ledger

cargo run -p ledger-cli -- keygen --out ~/.config/civ-ledger/keys/witness.json
cargo run -p ledger-cli -- attest --dir ./my-ledger --witness-key ~/.config/civ-ledger/keys/witness.json
cargo run -p ledger-cli -- verify-attestations --dir ./my-ledger --format json

cargo run -p ledger-cli -- receipt --dir ./my-ledger --entry-hash "$ENTRY_HASH" --out ./receipt.json --require-attestation
cargo run -p ledger-cli -- verify-receipt --receipt ./receipt.json --require-attestation

cargo run -p ledger-cli -- verify --dir ./my-ledger --format json
```

## On-disk layout (v0)

- `log/entries.cborseq` — concatenated CBOR-encoded `Entry` items (append-only).
- `log/checkpoints.jsonl` — optional Merkle checkpoints (append-only).
- `log/checkpoints.attestations.jsonl` — witness attestations over checkpoints (append-only).

## Spec

See `vm-ledger/FORMAT.md`.