Forensic ledger substrate

The TokenAuditEvent table and the appendAuditEvent helper are the substrate of the entire product. Every forensic-relevant action becomes a new row whose hash covers the previous row's hash — producing a tamper-evident chain-of-custody.

Walkthrough — Forensic ledger substrate

What it is

A hash-chained, append-only ledger. Any mutation or deletion of a past row breaks every hash after it — so the chain itself is the evidence that nothing was altered after the fact.

Schema — prisma/schema.prisma: the TokenAuditEvent model (sequence, hash, prevHash, payload, eventType, actorUserId) and the AuditEventType enum.
Append path — src/lib/ledger.ts: appendAuditEvent is the only sanctioned way to write a row.

How it works

appendAuditEvent runs inside a transaction: it reads the current tip, computes sha256(prevHash | eventType | actor | payload), and inserts the new row. Concurrent appends are serialized by the transaction, so the chain has exactly one total order. The first event has an empty prevHash.

Append-only is a hard invariant

There is exactly one ledger and one append path by design. A second write path to TokenAuditEvent — or any UPDATE / DELETE — is a P0 defect, not a feature. Errors in the append path propagate loudly; a silently dropped audit event is undetectable corruption of the evidence trail.

Why it matters

It is the reason anything downstream is admissible. An analyst or compliance officer can point at an evidence bundle and show the chain is intact. Without this substrate, every other pillar is just a dashboard; with it, they produce evidence, not information.

The scaffold-era ledger is a single global chain. Pillar 1 — Tamper-evident capture hardens it into per-tenant, signed chains.

Last updated 14 May 2026