Guide · Reference

What the audit trail captures

Every transaction creates an immutable domain event. This guide describes what each event records, how sequence numbers prevent retroactive insertion, and how to request an audit report.

TransactionPosted events

When you post a transaction, On The Ledger writes a TransactionPosted domain event to the append-only event log. This event is written once and never modified or deleted — the application rejects any update or deletion attempt.

Fields in every TransactionPosted event

transaction_id — unique identifier for the transaction
ledger_id — the ledger this transaction belongs to
sequence_number — ledger-scoped position in the event log; never reused
occurred_at — when the event was generated
recorded_at — when the event was persisted to the log
effective_at — the business date of the transaction
effective_at_epoch_us — effective_at as microseconds since Unix epoch (used in hash computation)
description — the transaction description
reference_number — optional external reference
adjusting — whether this is an adjusting entry
metadata — arbitrary key/value data attached at posting time
actor_id — the user or system that posted the transaction
strong_content_hash — SHA-256 digest of the canonical payload
previous_hash — hash of the immediately preceding transaction (nil for the first)
entries — each debit and credit: account_id, direction, amount_cents, currency
idempotency_key — prevents duplicate posts for the same operation

Example TransactionPosted event (abbreviated)

{
  "event_type":      "TransactionPosted",
  "sequence_number": 2,
  "occurred_at":     "2026-01-16T14:22:00.000Z",
  "recorded_at":     "2026-01-16T14:22:00.033Z",
  "payload": {
    "transaction_id":        "tx-uuid-2",
    "ledger_id":             "ledg-7f3a9c2d",
    "idempotency_key":       "vendor-payment-acme-2026-01-16",
    "effective_at":          "2026-01-16T14:22:00.000Z",
    "effective_at_epoch_us": 1737035880000000,
    "description":           "Vendor payment -- Acme Co.",
    "adjusting":             false,
    "reference_number":      "VND-2026-0116",
    "metadata":              {},
    "actor_id":              "usr-9a3f2b",
    "strong_content_hash":   "c94d3b81...",
    "previous_hash":         "b1e7a429...",
    "entries": [
      { "account_id": "acct-cash",   "direction": "credit", "amount_cents": 85000, "currency": "USD" },
      { "account_id": "acct-vendor", "direction": "debit",  "amount_cents": 85000, "currency": "USD" }
    ]
  }
}

TransactionVoided events

Voiding a posted transaction creates a TransactionVoided event. The original TransactionPosted event is never removed. Both events remain in the log, giving a complete record of the original posting and its reversal.

Fields in every TransactionVoided event

transaction_id — the voided transaction
reversal_transaction_id — the reversing transaction created to zero out the original entries
ledger_id — the ledger this void belongs to
void_reason — the reason provided for the void
voided_by — the user or system that initiated the void
voided_at — when the void was recorded

How sequence numbers work

Every domain event carries a sequence_number scoped to its ledger. The number is assigned when the event is written and increments monotonically. The application never reuses or skips a number. Any gap or duplicate in the sequence would indicate a missing or injected event — a condition the audit chain check detects.

sequence_number enforces ordering within a ledger. It is distinct from transaction amount or account balance — it is purely a position indicator in the event log.

Requesting an audit report

Run a chain audit at any time from the On The Ledger dashboard. The audit verifies every transaction's stored hash against a freshly computed hash, and confirms that each previous_hash matches the hash of the transaction that precedes it in recorded_at order.

If the chain is intact: status :ok, checked_count, and a tip_hash you can store externally.
If the chain is broken: status :error, divergence_at (the first transaction where a mismatch was detected), and a description of what was found.

An audit report is point-in-time evidence. You can run audits on demand and export results for compliance or partner review.