Audit trail

Produce audit events

Open a broker with defaults (no compression, no retention) to preserve the full history—critical for audit scenarios. Produce 50 events with structured JSON payloads containing user, action, resource, and timestamp fields.

let broker = Broker::open(BrokerConfig::new(dir.path())).unwrap();
let producer = Broker::producer(&broker);

let users = ["alice", "bob", "charlie", "diana", "eve"];
let actions = ["CREATE", "READ", "UPDATE", "DELETE", "LOGIN"];

for i in 0..50 {
    let event = AuditEvent {
        user: users[i % users.len()].to_string(),
        action: actions[i % actions.len()].to_string(),
        resource: resources[(i * 3) % resources.len()].to_string(),
        ts: 1700000000 + i as u64,
    };
    producer.send(&ProducerRecord::new(
        "audit", Some(event.user.clone()),
        serde_json::to_string(&event).unwrap(),
    )).unwrap();
}

Generate and verify merkle proofs

Access the partition directly through broker.topic().partition(). For each of 5 sampled offsets, call partition.proof(offset) to generate a Proof struct containing the leaf hash, sibling hashes, and the root. Then verify with MerkleTree::verify_proof().

let topic = broker.topic("audit").unwrap();
let part_arc = topic.partition(0).unwrap();
let partition = part_arc.read().unwrap();

let sample_offsets = [0, 10, 25, 37, 49];
for &offset in &sample_offsets {
    let proof = partition.proof(offset).unwrap().unwrap();
    let valid = MerkleTree::verify_proof(
        &proof, partition.store()
    ).unwrap();
    assert!(valid);
}

The proof depth reflects the tree height at that offset. Offset 49 (the last leaf of 50) has depth 3 because the tree's right edge is shorter than the interior.

Root hash progression

Capture the merkle root, append 10 more events, and capture it again. The root changes because each append creates new branch nodes that propagate up to a new root.

let root_before = partition.merkle_root().unwrap().unwrap();

// Produce 10 more events...

let root_after = partition.merkle_root().unwrap().unwrap();
assert_ne!(root_before, root_after);

In practice, you would publish or escrow the root hash at regular intervals. Any future claim that “the log contained X at time T” can be verified against the escrowed root.

Proof stability after appending

The 5 proofs generated before appending are re-verified after the 10 new records are added. All still pass. This is a key property of merkql's merkle tree: new leaves are added to the right, and the existing tree nodes are immutable in the content-addressed object store.

for proof in &earlier_proofs {
    let valid = MerkleTree::verify_proof(
        proof, partition.store()
    ).unwrap();
    assert!(valid);
}

Note: each proof was captured with the root hash at the time of generation. The proof verifies against that root, not the current one. Since the underlying tree nodes haven't changed, the proof remains valid even though the tree has grown.

Tamper detection

This step demonstrates what happens when data is modified on disk. The example reads a record at offset 10, computes its SHA-256 hash, then directly corrupts the pack file by flipping bytes at the entry's storage location. When the data is re-read through the object store and re-hashed, the hash no longer matches.

// Read the record and compute its expected hash
let record = partition.read(tamper_offset).unwrap().unwrap();
let serialized = record.serialize();
let expected_hash = Hash::digest(&serialized);

// Corrupt the pack file on disk (flip bytes at the entry)...
tamper_pack_file(&pack_path, &expected_hash);

// Re-read through the store — still finds the entry by offset,
// but the bytes are now different
let corrupted_data = partition.store().get(&expected_hash).unwrap();
let corrupted_hash = Hash::digest(&corrupted_data);
assert_ne!(expected_hash, corrupted_hash);

The tamper function walks the pack file's entry format ([4B length][32B hash][data]) to find and corrupt the target entry. In production, you wouldn't need this—the hash comparison alone detects any modification.