Skip to content

ADR-0030: Event Store as Source of Truth for the TigerBeetle Ledger

ADR-0030: Event Store as Source of Truth for the TigerBeetle Ledger

Section titled “ADR-0030: Event Store as Source of Truth for the TigerBeetle Ledger”
  • Status: Proposed
  • Date: 2026-09-21
  • Deciders: @revant.one
  • Supersedes: N/A
  • Superseded by: N/A

TigerBeetle is a deterministic financial state machine. It persists only fixed-size structs — Account, Transfer — and the materialized balances derived from them. There is no event log, no audit history, no arbitrary metadata, no key-value store, and no query language. A bare TigerBeetle cluster answers “what is the current balance”, never “why”, “when”, “who approved it”, or “what was the ledger at a point in time”.

Regulatory/audit bookkeeping and disaster recovery require an immutable, replayable record of every mutation. The ledger must be provably reconstructible from that record alone.

  1. KurrentDB is the canonical event log behind the EventStorePort (libs/ledger-core/ledger_core/interfaces.py). Postgres event_store_events is the fallback behind the same port. TigerBeetle becomes a projection of the log, not a record of it.
  2. Every ledger mutation dual-writes: the domain event is appended and the resulting state lands in the ledger. This dual-write already exists in FinanceLedgerService and StockLedgerService.
  3. Replay is a port-to-port hydrator implemented once in ledger_core.replay, fed by EventStorePort.read_all (global ordered reads) and writing through a shared LedgerSink — a real ledger (LedgerPortSink), a JSONL file (FileSink), or an in-memory mirror used for --verify.
  4. The commands live in the domain libs, not in apps/business-m: m replay-finance (registered by libs/finance) and m replay-stock (registered by libs/wms), each dispatching through its own bootstrap adapter and translator. Macroservices deploy finance/wms standalone (INSTALLED_APPS=finance, INSTALLED_APPS=wms) without business-m-shell, so a command registered only in the shell would be absent there. Distinct names keep both commands available in the monolith (both libs installed) without a CommandCollisionError in the CLI plugin loader.
  5. The external script files/new/replay_hydration.py is deprecated; its deterministic-ID and verify ideas carry into ledger_core.replay / --verify.
  • Postgres position is per-tenant. The real-Postgres event_store_events table is hash-partitioned on tenant_id (ledger_core/ddl/postgres.py), which forbids IDENTITY columns and requires any unique constraint to include the partition key. A global BIGSERIAL UNIQUE is therefore impossible; the replay cursor is UNIQUE (tenant_id, position). Ordering still matches Kurrent within a tenant — the only scope replay needs.
  • Replay keeps an in-run original→fresh transfer-ID remap and an event index. Pending/void/reversal events reference the original run’s transfer IDs (PendingTransferCommitted.transfer_id, StockTransferVoided.pending_id, reversal original_transfer_id). A clean rebuild mints fresh UUIDs, so the hydrator remaps each created transfer back to its original ID (via TransferCommand.replay_key) and resolves reversals through an index of events keyed by transfer_id. Without this, post/void/reverse replay would fail and balances would not reconcile.
  • Full audit history and point-in-time reconstruction: read_all doubles as the audit-export (--output JSONL) and verification (--verify vs LedgerPort.get_balance) path.
  • TigerBeetle stays a lean projection — it is rebuilt, not queried.
  • Usable in every topology: finance-only, wms-only, and the monolith each get exactly the commands they ship.
  • Original IDs are preserved in event data even though rebuilt ledgers mint fresh UUIDs.
  • One extra durable write per transfer — the event append after each ledger commit.
  • Event schema must be forward-compatible; translators can only replay event types they know.
  • Rebuilt transfer UUIDs differ from the original run (documented and accepted).
  • The transfer-ID remap is in-memory per run; cross-run idempotency without a checkpoint is not addressed yet (deterministic transfer IDs are the documented upgrade path).
  1. Wipe the ledger backend (TigerBeetle or Postgres projection).
  2. Rebuild from the event log: m replay-finance --reset --verify / m replay-stock --reset --verify.
  3. --verify recomputes expected per-account balances from read_all and compares them against LedgerPort.get_balance, exiting non-zero on any mismatch.
  4. Rerun the verify on a recurring cadence (scheduled) so drift is caught early, not at recovery time.