VeriLog Documentation

VeriLog is a Rust-based edge logging engine that turns device telemetry into a verifiable evidence stream. It provides append-only records, signed checkpoints, privacy-aware payloads, and a migration path toward zero-knowledge integrity proofs — all packaged as a single binary.

Quick Start

Build from source

# Clone and build
git clone https://github.com/pinkysworld/VeriLog.git
cd verilog
cargo build --release -p verilogd

# With admin console
cargo build --release -p verilogd --features admin-console

Basic workflow

# Initialize a new store
verilogd init --store ./my-store

# Append an entry
verilogd append --store ./my-store --kind "sensor.temperature" \
  --payload '{"value": 22.5, "unit": "celsius"}' --level info

# Verify the entire store
verilogd verify --store ./my-store

# Generate a membership proof
verilogd proof membership --store ./my-store --index 0 --out proof.json

# Create a signed checkpoint
verilogd checkpoint create --store ./my-store --label "daily-anchor"

# Export as JSON lines
verilogd export --store ./my-store --out export.jsonl

CLI Reference

The verilogd binary provides the following commands:

  • init — Initialize a new log store with key generation
  • append — Append a signed entry to the log
  • verify — Verify the full integrity of a store
  • status — Show store status (leaf count, root, last entry)
  • export — Export entries as JSON Lines
  • proof membership — Generate a Merkle membership proof
  • proof verify — Verify a membership proof
  • checkpoint create — Create a signed checkpoint snapshot
  • checkpoint verify — Verify a checkpoint signature
  • license install|status|issue|vendor-keygen — License management
  • serve — Start the admin console HTTP server (requires feature flag)

System Design

VeriLog is architected as a single executable (verilogd) that embeds a verifiable append-only log store, a license verifier, an optional admin console, and optional enterprise hooks.

Crate Structure

  • verilog-core — Core library: LogStore, MerkleFrontier, crypto, DP primitives, energy policy
  • verilog-license — Ed25519-based license verification and device ID generation
  • verilog-enterprise-api — Enterprise feature traits and hooks (OSS stubs only)
  • verilogd — CLI binary integrating all crates with Clap argument parsing

Data Flow

Append operation

  1. Client calls LogStore::append(kind, payload, level)
  2. Store reads previous entry hash and Merkle frontier
  3. Builds unsigned entry with hash chain link and rolling window commitment
  4. Computes leaf hash, pushes to Merkle frontier, gets new root
  5. Signs the entry hash with Ed25519
  6. Appends record to entries.bin, leaf hash to leaves.bin
  7. Atomically updates meta.json

Verification

  1. Iterate all entries sequentially
  2. Re-compute hash chain, window commitments, leaf hashes, Merkle roots
  3. Verify every Ed25519 signature
  4. Fail fast on any mismatch

Trust Boundaries

The device running VeriLog may be partially compromised after evidence is captured. The log provides tamper-evidence for historical data. Enterprise features are gated by license checks and compiled only in private builds.

Storage Format

Each store is a directory with four files:

  • entries.bin — Length-prefixed postcard-serialized log entries
  • leaves.bin — Raw 32-byte leaf hashes, sequential
  • meta.json — Store metadata: tree height, leaf count, frontier, previous hashes
  • signing_key.json — Ed25519 keypair (generated on init)

Entries use a length-delimited format: [4-byte LE length][postcard bytes]. This allows sequential reads without a separate index (index optimization is on the roadmap).

Hash Chain

Every entry stores the hash of the previous entry as prev_entry_hash. Entry index 0 uses a zero hash. This creates a linear chain — modifying any entry breaks all subsequent links.

Additionally, a rolling window hash (window_hash = H(prev_window || prev_entry_hash)) provides a sliding commitment for forensic post-compromise analysis.

Merkle Tree

VeriLog uses a fixed-height incremental Merkle frontier. Only the frontier nodes (one per level) are kept in memory — not the full tree. Empty positions are padded with zero hashes.

  • Default height: 32 levels (supports ~4 billion entries)
  • Update cost: O(height) per append
  • Proof size: 32 × height bytes (sibling path)
  • Hash function: BLAKE3

Checkpoints

A signed checkpoint captures:

  • Current Merkle root
  • Last entry hash
  • Leaf count
  • Timestamp
  • Verifying key (for self-contained verification)
  • Optional label

Checkpoints are signed with the same Ed25519 key and can be verified independently. They serve as portable anchoring points for external timestamping and archival.

Differential Privacy

The base edition includes primitives for per-event differential privacy:

  • Laplace noise: Added to numeric telemetry values before they enter the evidence pipeline
  • Token-bucket budget: Tracks cumulative ε consumption
  • Integration point: Noise is applied before signing, so the signed record includes the privatized value

Budget Management

The privacy budget is a finite resource. Once exhausted, the system can either refuse to log sensitive values or fall back to high-redaction modes. Future work includes formal privacy accounting with verifiable budget proofs.

Threat Model

VeriLog is designed under these assumptions:

  • The device may be partially or fully compromised after evidence has been written
  • An adversary may attempt to modify, insert, delete, or truncate log entries
  • The signing key resides on-device and may be extracted after compromise (forward security is a future research track)
  • External anchoring (checkpoints sent to a remote system) provides tamper-evidence even against total device takeover

Key Management

Keys are generated on init and stored in signing_key.json. The current prototype does not implement key rotation or hardware-backed key storage — both are planned for Phase 1 hardening.

License System

VeriLog uses Ed25519-signed license files for enterprise feature gating:

  1. Vendor generates a keypair (vendor-keygen)
  2. Vendor issues a signed license with entitlements, device binding, and validity window
  3. Device installs the license (license install)
  4. Runtime checks verify the license signature and entitlements before allowing enterprise operations

Enterprise Features

Enterprise features are defined in verilog-enterprise-api as trait-based hooks. The OSS base ships only the API surface — implementations live in the private enterprise crate. Current feature IDs include:

  • ZK proof generation and verification
  • Compliance export bundles
  • Cross-device correlation
  • Advanced energy policies

Research Tracks (R01–R30)

The research agenda spans 30 tracks across four pillars. See the Research Agenda section on the main page for the full listing. Key tracks by priority:

  1. R04 / R09 — Integrity primitives (shipped)
  2. R10 — Checkpoint formalization and external anchoring
  3. R03 — Per-event DP with accounting
  4. R02 — ZK proof of log integrity (Poseidon experiment first)
  5. R14 / R20 — Secure forwarding and mesh sync

Novelty Program

The novelty program identifies four differentiation wedges that make VeriLog meaningfully different from other secure logging systems:

  • Wedge A: Evidence-first edge telemetry (not just logging)
  • Wedge B: Privacy-preserving observability (DP on the proof surface)
  • Wedge C: Verifiable archival and selective disclosure
  • Wedge D: Multi-device evidence graphs (long-term research)

Each wedge has defined validation criteria: benchmarks, verifier artifacts, demo transcripts, and clear threat assumptions.