Building Hash-Chained Audit Logs for Reconciliation Events #

An auditor pulls last quarter's break log to reconstruct why a $2.4M wire posted, and you need to prove the 4,000 events in front of them are byte-for-byte what the engine wrote — not a version edited after the incident. A plain append-only table cannot prove that: anyone with write access could have altered a row and left no trace. A hash-chained log can, because each event carries the cryptographic fingerprint of the one before it, so a single edit anywhere cascades into a detectable break. This page sits inside the immutable audit trails reference within the broader Reg E, NACHA and audit controls framework, and gives you the full chaining construction and the verify() that finds tampering at the exact event it occurred.

The chain is not encryption and it is not access control. It is tamper evidence: it does not stop a write, it makes any unauthorized write mathematically obvious on the next verification. That is precisely the property a SOX §404 or FFIEC review needs, and it is why hash chaining pairs with, rather than replaces, the write-once WORM storage that physically prevents the write in the first place.

Concept Spec #

Let $e_n$ be the canonical byte serialization of the $n$-th audit event and $H$ be a cryptographic hash (SHA-256). Each event stores the hash of its predecessor and derives its own hash from both:

where $\Vert$ is concatenation and $h_{-1}$ is a fixed genesis constant (64 zero hex characters). Because $e_n$ itself contains $h_{n-1}$, the predecessor's hash is bound into the digest twice over — once as the stored prev_hash field and once transitively through the recursion. Editing any event $k$ changes $h_k$, which no longer equals the prev_hash recorded in event $k+1$; verification detects the mismatch at $k+1$ and every subsequent link is invalid too. Computing the chain is $O(n)$ with $O(1)$ additional memory per event, and verification is a single $O(n)$ pass — one SHA-256 per event, a few microseconds each, so a 100,000-event day verifies in well under a second.

The security rests entirely on $H$ being collision-resistant and on $e_n$ being canonical: the same logical event must serialize to the same bytes every time, or an honest event will fail its own verification. Canonicalization — sorted keys, integer cents, an explicit encoding — is therefore not a stylistic choice but a correctness requirement.

Full Annotated Python Implementation #

The class below builds and verifies a chain. It is deliberately storage-agnostic: _records is an in-memory list here, but the identical logic runs over a WORM object store or an append-only table. Every monetary field is integer cents, never float, so re-serialization on the verify pass reproduces the exact bytes that were hashed on the write pass.

from __future__ import annotations

import hashlib
import json
from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Any, Iterator

GENESIS_HASH: str = "0" * 64  # h_{-1}: the fixed anchor every chain starts from


@dataclass(frozen=True)
class ChainedEvent:
    """An audit event plus its chain linkage. Frozen so it cannot mutate
    after it has been hashed and appended."""
    seq: int
    payload: dict[str, Any]      # the reconciliation decision (canonical-safe values only)
    prev_hash: str
    event_hash: str
    logged_at: str


def _canonical_bytes(seq: int, payload: dict[str, Any], prev_hash: str,
                     logged_at: str) -> bytes:
    """Deterministic byte image of an event for hashing.

    sort_keys makes key order irrelevant; the compact separators strip
    insignificant whitespace; ensure_ascii=False fixes one UTF-8 encoding.
    The payload MUST contain only canonical-safe values (int cents, str,
    bool, None, or nested dicts/lists of those) — never a float, whose repr
    is platform-dependent and would break re-hash.
    """
    envelope = {
        "seq": seq,
        "prev_hash": prev_hash,     # binds this event to its predecessor
        "logged_at": logged_at,
        "payload": payload,
    }
    return json.dumps(
        envelope, sort_keys=True, separators=(",", ":"), ensure_ascii=False
    ).encode("utf-8")


def _reject_floats(payload: dict[str, Any]) -> None:
    """Fail loudly if any float reaches the digest. A float amount would
    hash inconsistently across platforms and silently break verify()."""
    def walk(v: Any) -> None:
        if isinstance(v, float):
            raise TypeError("float in audit payload; use integer cents or str")
        if isinstance(v, dict):
            for x in v.values():
                walk(x)
        elif isinstance(v, (list, tuple)):
            for x in v:
                walk(x)
    walk(payload)


@dataclass
class HashChainedLog:
    """Append-only, SHA-256 hash-chained audit log with tamper detection."""
    _records: list[ChainedEvent] = field(default_factory=list)

    @property
    def tip_hash(self) -> str:
        return self._records[-1].event_hash if self._records else GENESIS_HASH

    def append(self, payload: dict[str, Any]) -> ChainedEvent:
        """Hash `payload` onto the tip and append. The only write path."""
        _reject_floats(payload)
        seq = len(self._records)
        prev = self.tip_hash
        logged_at = datetime.now(timezone.utc).isoformat()
        digest = hashlib.sha256(
            _canonical_bytes(seq, payload, prev, logged_at)
        ).hexdigest()
        event = ChainedEvent(seq, payload, prev, digest, logged_at)
        self._records.append(event)
        return event

    def verify(self) -> None:
        """Recompute the whole chain; raise at the FIRST broken link.

        Detects three tamper classes: an edited payload (event_hash no longer
        matches the recomputed digest), a broken link (prev_hash != the real
        predecessor hash, i.e. an insertion/deletion), and a reordered chain
        (seq out of order).
        """
        prev = GENESIS_HASH
        for i, ev in enumerate(self._records):
            if ev.seq != i:
                raise ValueError(f"reorder/gap at index {i}: seq={ev.seq}")
            if ev.prev_hash != prev:
                raise ValueError(f"broken link at seq {ev.seq}: prev_hash mismatch")
            recomputed = hashlib.sha256(
                _canonical_bytes(ev.seq, ev.payload, ev.prev_hash, ev.logged_at)
            ).hexdigest()
            if recomputed != ev.event_hash:
                raise ValueError(f"tampered payload at seq {ev.seq}")
            prev = ev.event_hash

    def stream(self) -> Iterator[ChainedEvent]:
        yield from self._records

Calibration & Configuration #

Three decisions determine whether the chain holds up under scrutiny.

• What goes into the digest. Include everything that defines the decision — subject reference, decision type, actor, keys tried, rule version, exact variance in cents, confidence, and the trusted timestamp. Exclude only fields unknown at hash time (event_hash itself). Anything omitted from the digest is unprotected: an attacker could alter it without breaking the chain, so if a field matters for an examiner, it must be inside _canonical_bytes.
• Canonical serialization. Fix the serialization once and never let it drift. sort_keys=True removes key-order sensitivity, compact separators remove whitespace ambiguity, and ensure_ascii=False pins one UTF-8 encoding. Amounts are integer cents; if you must carry a decimal, serialize it as a fixed-precision string, never a float. Changing the canonical form later invalidates every previously computed hash, so version the format if you ever must evolve it.
• Sharding and anchoring. One chain is single-writer by nature — appends serialize to keep seq gap-free. Shard by settlement day, rail, or ledger so shards append in parallel, each independently verifiable. For strong non-repudiation, periodically publish the tip hash to an external, independent store (or a WORM object) so even a full-chain replacement is caught by comparing against the anchored fingerprint.

Validation Example: Before and After #

Append three reconciliation decisions, then simulate an analyst quietly rewriting the middle one to hide that a match was forced.

log = HashChainedLog()
log.append({"subject_ref": "trace-0000417", "decision": "MATCH_ACCEPTED",
            "actor": "engine@matcher", "variance_cents": 0})
log.append({"subject_ref": "trace-0000417", "decision": "TOLERANCE_APPLIED",
            "actor": "engine@matcher", "rule_version": "v14", "variance_cents": 1500})
log.append({"subject_ref": "trace-0000417", "decision": "STATE_TRANSITION",
            "actor": "analyst_12", "payload_note": "to RESOLVED"})

log.verify()   # passes — chain intact

The clean chain verifies. Now tamper with event 1 in place, as a raw storage edit would:

# Attacker lowers the recorded variance to make a forced match look clean.
forged = log._records[1].payload | {"variance_cents": 0}
log._records[1] = ChainedEvent(
    seq=1, payload=forged,
    prev_hash=log._records[1].prev_hash,     # left unchanged to look legitimate
    event_hash=log._records[1].event_hash,   # stale hash of the ORIGINAL payload
    logged_at=log._records[1].logged_at,
)

log.verify()
# ValueError: tampered payload at seq 1

The recomputed digest of the forged payload no longer equals the stored event_hash, so verify() raises at seq 1 — the exact event that was altered. Had the attacker also recomputed event_hash to match the forged payload, the new hash would differ from the prev_hash recorded in event 2, and verification would instead fail at seq 2. Either way the tamper is localized and provable; there is no edit that leaves the chain consistent without rewriting every subsequent event, which the anchored tip hash then exposes.

Failure Modes & Guardrails #

1. Non-canonical JSON breaks honest events. If the write path and the verify path serialize differently — one sorts keys, the other does not; one emits ": " separators, the other ":" — an untampered event fails its own hash and you get false tamper alarms that erode trust in the whole trail. Route every serialization through the single _canonical_bytes function; never hand-build the JSON at a call site.
2. A float amount poisons the digest. json.dumps(0.1) and a Decimal-derived string are different bytes, and float repr can differ across platforms and Python builds, so a chain written on one host may fail verification on another. _reject_floats fails the append rather than letting a float into the digest — keep amounts as integer cents from ingestion through the log.
3. A missing or wrong genesis. If the first event's prev_hash is empty, None, or a per-run random value instead of the fixed GENESIS_HASH, two things break: chains are no longer comparable across runs, and a verifier cannot confirm the head is really the head. Anchor every chain to the same 64-zero constant, assert it in verify(), and treat a genesis mismatch as a hard tamper signal, not a warning.

Frequently Asked Questions #

Related guides in this collection #

• Immutable Audit Trails for Reconciliation Decisions — the parent reference on append-only, hash-chained, WORM-backed trails and what an examiner needs from each event.
• Write-Once (WORM) Storage for Reconciliation Audit Events — the storage layer that physically prevents the overwrite this chain is designed to detect.
• Regulation E Error Resolution for ACH Disputes — the dispute timelines whose evidentiary record these hash-chained events protect.
• Reg E, NACHA & Audit Controls — the parent reference for the regulatory envelope around the reconciliation pipeline.