VEST Protocol Architecture Overview

ELI5

A post office where every letter gets a wax seal (Ed25519 signature), is stapled to its envelope in a numbered sequence, and is stored in a tamper-evident binder — if anyone removes or replaces a page, the numbering breaks and the seals no longer chain. VEST is that binder for timeline operations.

Technical Deep Dive

VEST (Verifiable Event State Tracker) is the cryptographic audit layer for the TimeChain collaborative platform. It ensures every timeline operation has non-repudiation, inclusion proof, and tamper-evidence.

Module Boundaries

src/lib.rs defines five modules and four public-export pairs:

Top-Level Orchestration

VestProtocol (defined in src/lib.rs) owns an AuditLog, a HashMap<String, TimelineProof>, and a ProofVerifier. Its three operations are:

1. audit_operation(op_id, op_data, signature) — verifies signature first, then appends
2. create_proof(op_id) — looks up entry, derives MerkleProof from it
3. verify_timeline(timeline_id) — delegates to ProofVerifier::verify_timeline_proof

Operation Flow

flowchart TD
    A[caller: audit_operation] --> B{verify_signature}
    B -->|fail| E[VestError::InvalidSignature]
    B -->|pass| C[AuditEntry::new]
    C --> D[AuditLog::append\nsets sequence_number]
    D --> F[return Ok]

    G[caller: create_proof] --> H{AuditLog::get}
    H -->|None| I[VestError::OperationNotFound]
    H -->|Some| J[MerkleProof::from_entry]
    J --> K[return MerkleProof]

Error Taxonomy

enum VestError {
    InvalidSignature(String),     // signature.verify_chain() == false
    InvalidProof(String),         // MerkleProof or ProofPath check failed
    ProofChainBroken(String),     // TimelineProof::verify_chain() == false
    OperationNotFound(String),    // op_id not in AuditLog
}

Wire Protocol & Production Scale

proto/protocols/vest.proto defines VESTProof, AuditEntry, SignedTreeHead, and SealedTimeline. Production targets (from requirements/SRS.md): 25,000 ops/s throughput, <30ms P95 verification, Tessera/Trillian as backing store.

Key Terms

• VestProtocol → top-level orchestrator in src/lib.rs; owns log, proof chain map, and verifier
• AuditLog → append-only Vec<AuditEntry> with HashMap index for O(1) lookup by op_id
• TimelineProof → per-timeline chain of StateProof objects anchored by a root AuditSignature
• ProofVerifier → stateful counter-tracking engine; methods return VerificationResult or Result<_, VestError>
• VestError → four-variant enum covering signature, proof, chain, and lookup failures

Q&A

Q: What prevents audit_operation from appending an entry before checking the signature? A: ProofVerifier::verify_signature is called first and returns Err(VestError::InvalidSignature) on failure; the ? operator short-circuits before AuditEntry::new is ever called.

Q: What is the default chain_depth of AuditSignature::default()? A: 1 — the default is a minimal chain starting at depth 1 with an all-zeros previous hash and all-zeros signature bytes.

Q: Does verify_timeline return Ok(false) or Err(...) when the timeline_id is unknown? A: Ok(false) — the HashMap::get returns None, so the else-branch returns Ok(false) without touching the verifier.

Examples

Sequence showing two operations being audited and a timeline proof being checked:

let mut vest = VestProtocol::new();
let sig = AuditSignature::default();          // chain_depth=1, valid chain
vest.audit_operation("op1", payload, sig)?;   // verifies sig, appends seq=0
let proof = vest.create_proof("op1")?;        // MerkleProof { tree_depth: 1, siblings: 5 }
let ok = vest.verify_timeline("tl-unknown");  // Ok(false) — timeline not in map