Proof chain

How EnfinitOS signs and hash-chains every delivery, activity, and operating action — and how the open-source auditor walks the chain offline.

Every governed action in EnfinitOS produces a proof event. Proof events are grouped into proof packs — signed, hash-chained documents that anyone with the published verification key can verify without contacting EnfinitOS.

Pack shape

A proof pack is a canonical JSON document with three top-level fields:

{
  "header": {
    "tenantId": "tnt_...",
    "sequence": 42,
    "previousPackHash": "0a1b2c…",
    "issuedAt": "2026-05-14T10:00:00.000Z",
    "verificationKeyId": "vk_2026_v1"
  },
  "body": {
    "campaignId": "cmp_...",
    "events": [ /* delivery, audit, policy, metering events */ ],
    "meteringProjection": { /* re-projectable from events */ },
    "settlementReconciliation": { /* re-runnable from projection */ }
  },
  "signature": "base64-encoded-ed25519-signature"
}

Canonical-JSON serialisation

The signature is computed over the canonical JSON serialisation of { header, body }. Canonical means: sorted keys, no whitespace, deterministic number formatting. The auditor library reproduces the exact serialisation before checking the signature.

Hash chain

header.previousPackHash is the SHA-256 of the previous pack’s signed bytes for the same tenant. The first pack issued to a tenant uses a hash of 32 zero bytes.

A missing or tampered pack breaks the chain at the next pack’s previousPackHash field. The auditor walks the chain end-to-end and reports the first break.

What the auditor does, in code-level detail

1. Decode the pack into header, body, signature.
2. Reproduce the canonical-JSON serialisation of { header, body }.
3. Verify the Ed25519 signature against the verification key identified by header.verificationKeyId.
4. Compare header.previousPackHash to the hash of the previous pack (or zero hash for sequence 0).
5. Re-project metering from body.events and assert bit-equality against body.meteringProjection.
6. Re-run settlement reconciliation against the projected metering and assert bit-equality against body.settlementReconciliation.

If any step fails, verification fails. No partial-credit verdicts.

See the auditor SDK page for the open-source implementation.