Hash Chain

Overview

Every event in the Cosmictron WAL includes the SHA-256 hash of the previous event. This forms a chain: changing any historical event breaks every subsequent hash link, making tampering immediately detectable.

Chain structure

Genesis event
  │ hash: H₀
  ▼
Event 1  ← content + prev_hash=H₀  → H₁ = SHA-256(content || H₀)
  │ hash: H₁
  ▼
Event 2  ← content + prev_hash=H₁  → H₂ = SHA-256(content || H₁)
  │ hash: H₂
  ▼
   ...

The genesis event has prev_hash = [0u8; 32] (all zeros).

What the hash covers

H_n = SHA-256(
  seq_bytes       ||   // 8-byte big-endian
  reducer_bytes   ||   // UTF-8 reducer name
  identity_bytes  ||   // sender identity
  timestamp_bytes ||   // 8-byte i64 microseconds
  payload_bytes   ||   // BSATN-encoded event content
  prev_hash_bytes      // 32-byte previous hash
)

Verification

The chain can be re-verified at any time:

cosmictron-cli audit verify --check hash-chain

The verifier:

1. Reads all events in order from the WAL
2. Recomputes each hash from the payload and prev_hash
3. Compares to the stored hash
4. Reports the first broken link (if any)

Gap detection

If events have been deleted from the middle of the log, the hash chain break pinpoints the exact gap:

Chain break at seq=12345: stored prev_hash does not match hash of seq=12344

Relationship to Ed25519 signatures

The hash is included in the signed payload. This means:

• Forging a chain link requires forging a signature
• The chain and the signature are mutually reinforcing — both must be valid for an event to pass full verification

For compliance purposes, the hash chain provides evidence that events have not been deleted (chain gaps) while the signatures provide evidence that events have not been modified.