Architecture
Deep Dive

The technical foundation of VerityDB's compliance guarantees.

Start Reading

The One Invariant

Everything in VerityDB derives from a single mathematical invariant.[1]

Fig. 1 The fundamental equation that governs all state in VerityDB.
S = A(S0, L)
Current state equals the apply function over initial state and the log

What This Means

S
Current state — what you query
S0
Initial state — empty or genesis
L
Log — ordered sequence of events
A
Apply function — deterministic state machine

Why It Matters

Deterministic replay — Same log always produces same state
Time travel — Reconstruct state at any point
Verifiability — State can be independently computed
Fault tolerance — State is always rebuildable

Log Structure

The append-only log is the foundation. Every entry is hash-chained and CRC-protected.

Fig. 2 Binary entry format with integrity layers. 
+------------------+
| Length (u32)     |  4 bytes
+------------------+
| CRC32 (u32)      |  4 bytes - covers payload
+------------------+
| Prev Hash (32)   |  32 bytes - SHA-256
+------------------+
| Timestamp (u64)  |  8 bytes - nanoseconds
+------------------+
| Type Tag (u8)    |  1 byte
+------------------+
| Payload          |  Variable length
+------------------+

Integrity Layers

Two independent checks:

  • CRC32 for corruption detection
  • SHA-256 chain for tamper evidence

Ordering Guarantee

Hash chain enforces:

  • Total order of events
  • No gaps possible
  • No reordering possible

Durability

Write path guarantees:

  • fsync before ack
  • Atomic append
  • Recovery on crash

Dual-Hash Cryptography

We use two hash algorithms, each optimized for its purpose.[3][4]

SHA-256

Compliance

Used where regulatory acceptance matters:

Hash chain links
Checkpoints
Signed exports
Audit attestations

FIPS 180-4 compliant. Auditors recognize it.

BLAKE3

Performance

Used for internal hot paths:

Content addressing
Merkle tree construction
Deduplication
Parallel hashing

10x faster than SHA-256 with SIMD.

Fig. 3 Compile-time enforcement prevents mixing hash algorithms. 
/// Compile-time enforcement of hash algorithm selection.
pub enum HashPurpose {
    /// External-facing, compliance-critical paths
    Compliance,  // Uses SHA-256

    /// Internal hot paths where speed matters
    Internal,    // Uses BLAKE3
}

Functional Core / Imperative Shell

The kernel is a pure state machine. All I/O lives at the edges.[5]

Fig. 4 Watch how commands flow through the architecture.
Fig. 5 The kernel interface. No I/O, no clocks, no randomness. 
/// Pure core: No I/O, no clocks, no randomness
fn apply_committed(
    state: State,
    cmd: Command
) -> Result<(State, Vec<Effect>)>

/// Impure shell: Executes effects, handles I/O
impl Runtime {
    fn execute_effect(&mut self, effect: Effect) -> Result<()>
}

Benefits for Testing

  • Deterministic simulation[6]
  • Fast property-based tests
  • Reproducible bug reports
  • No mocking required

Benefits for Correctness

  • State transitions are explicit
  • Side effects are trackable
  • Replay is trivial
  • Reasoning is local

Design Constraints

Hard rules enforced across the codebase.

Code Quality

No unsafe code — Workspace lint denies it
No recursion — Bounded loops with explicit limits
No unwrap in library code — Use expect() with reason
70-line soft limit — Per function

Assertion Density

Every function should have 2+ assertions:

Preconditions at entry
Postconditions at exit
Paired assertions at write/read sites

"Parse, don't validate" — validate at boundaries once.

References

  • 1
    Martin Fowler. Event Sourcing. 2005. martinfowler.com
  • 2
    Pat Helland. Immutability Changes Everything. CACM, Vol. 59, No. 1. 2016. doi:10.1145/2844112
  • 3
    NIST. FIPS 180-4: Secure Hash Standard (SHS). 2015. csrc.nist.gov
  • 4
    O'Connor, et al. BLAKE3: One function, fast everywhere. 2020. blake3.pdf
  • 5
    Gary Bernhardt. Functional Core, Imperative Shell. Destroy All Software. 2012. destroyallsoftware.com
  • 6
    Tyler Neely. Simulation Testing for Liveness. 2020. sled.rs

Explore the Code

The architecture is fully documented in code. Start with the kernel for the core state machine, or vdb-crypto for the cryptographic foundation.

View on GitHub Back to Home