aegis-ledger
Ledger / append-only engine — named ledgers of immutable, hash-chained entries. Each entry’s hash covers the previous entry’s hash, so the log is tamper-evident and verifiable end to end. The thirteenth data paradigm.
Overview
aegis-ledger stores an append-only sequence of entries per ledger. Each append adds an entry whose hash is computed over the previous hash, the sequence number, the timestamp, and the canonical payload — forming a chain. A retroactive edit to any entry changes its hash and breaks every subsequent link, which verify detects and localizes.
Modules
| Module | Responsibility |
|---|---|
types.rs | LedgerEntry, VerifyResult, LedgerError, chain_hash (SHA-256), chain_hash_fnv1a (legacy v1), genesis_hash |
engine.rs | LedgerEngine — ledgers, append, get/range, verify, stats (tip hash, hash version), snapshot + logical clock |
Hash chain
The entry hash is SHA-256 (64 hex chars) over prev_hash || seq || timestamp || canonical(payload). The first entry chains off a genesis hash of 64 zeros.
Each ledger records a hash_version. Ledgers created from v0.6 on are version 2 (SHA-256). Ledgers from older snapshots have no version field and load as version 1, the original 128-bit FNV-1a digest (two lanes, 32 hex chars, 32-zero genesis). They keep verifying and chaining under that algorithm, so an upgrade never reports a broken chain. verify recomputes each entry’s hash and checks that its prev_hash matches the prior entry’s hash and its seq matches its position, returning the first broken sequence if the chain is invalid.
SHA-256 makes the chain tamper-evident: altering any entry breaks every later link. Legacy version 1 ledgers use a non-cryptographic digest that detects corruption and naive tampering, not a forging adversary.
API Endpoints
| Method | Path | Description |
|---|---|---|
| GET / POST | /api/v1/ledger/ledgers | List / create ({name}) |
| GET / DELETE | /api/v1/ledger/ledgers/:name | Stats (count, tip hash, hash_version) / drop (admin only) |
| GET / POST | /api/v1/ledger/ledgers/:name/entries | Read range (?start=&limit=) / append {payload, timestamp?} |
| GET | /api/v1/ledger/ledgers/:name/entries/:seq | Get entry by sequence |
| GET | /api/v1/ledger/ledgers/:name/verify | Verify the hash chain |
All endpoints require authentication. verify returns { valid, entries, broken_at }.
Persistence
The full ledger set plus the logical clock is written to ledger.ncb as a NexusCompress blob frame on graceful shutdown and reloaded on startup; appends after a restore continue the same chain.
Tests
Workspace total includes sequence/hash chaining, full-chain verification, tamper-detection, range + stats, error paths, and snapshot round-trip with continued appends.