Merkle Proofs

Cryptographic proof for any event — verifiable without exposing the full chain.

Merkle checkpoints batch events into a Merkle tree and compute a root hash. You can then prove any specific event is included in the checkpoint without revealing other events. Auditors can verify proofs independently — no access to your system required.

Why Merkle proofs matter

Without Merkle proofs:

"Trust us, this event exists in our log."

With Merkle proofs:

"Here's mathematical proof this event exists. Verify it yourself."

This is the difference between self-attestation and cryptographic proof.

How it works

bash

Events:     [E1]  [E2]  [E3]  [E4]
              \   /       \   /
Hashes:      [H12]       [H34]
                \       /
Root:           [Root Hash]

Events are hashed (leaf nodes)
Pairs of hashes are combined and hashed (internal nodes)
Process repeats until a single root hash remains
The root commits to all events in the batch

To prove E2 exists, you only need: E2's hash, H1, and H34. The verifier can recompute the root and check it matches.

Creating checkpoints

Checkpoints batch all events since the last checkpoint into a Merkle tree.

API

bash

curl -X POST "https://api.xmdb.cloud/v1/checkpoints?workspace_id=prod&scope_id=project" \
  -H "Authorization: Bearer $XMDB_API_TOKEN"

Response:

bash

{
  "checkpoint_id": "chk_abc123",
  "merkle_root": "v+IAy8gqQMQZpXMeuGgDd9bRJPjUclMqLUDv9seJgjE=",
  "event_count": 47,
  "first_event_id": "evt_001",
  "last_event_id": "evt_047",
  "tree_height": 6,
  "prev_checkpoint_id": "chk_xyz789",
  "created_at": "2025-01-16T10:30:00Z"
}

CLI

bash

xmdbctl checkpoints create --workspace prod --scope project

Listing checkpoints

bash

# API
curl "https://api.xmdb.cloud/v1/checkpoints?workspace_id=prod&scope_id=project"

# CLI
xmdbctl checkpoints list --workspace prod --scope project

Generating inclusion proofs

Prove a specific event exists in a checkpoint:

API

bash

curl "https://api.xmdb.cloud/v1/checkpoints/chk_abc123/proof/evt_023?workspace_id=prod&scope_id=project" \
  -H "Authorization: Bearer $XMDB_API_TOKEN"

Response:

bash

{
  "checkpoint_id": "chk_abc123",
  "event_id": "evt_023",
  "event_hash": "sha256:8f3a2b...",
  "merkle_root": "v+IAy8gqQMQZpXMeuGgDd9bRJPjUclMqLUDv9seJgjE=",
  "leaf_index": 22,
  "proof": [
    {"hash": "sha256:1a2b3c...", "position": "left"},
    {"hash": "sha256:4d5e6f...", "position": "right"},
    {"hash": "sha256:7g8h9i...", "position": "left"}
  ]
}

CLI

bash

xmdbctl checkpoints proof --workspace prod --scope project \
  --checkpoint-id chk_abc123 \
  --event-id evt_023

Verifying proofs

Server verification

bash

curl -X POST "https://api.xmdb.cloud/v1/checkpoints/verify" \
  -H "Authorization: Bearer $XMDB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_hash": "sha256:8f3a2b...",
    "merkle_root": "v+IAy8gqQMQZpXMeuGgDd9bRJPjUclMqLUDv9seJgjE=",
    "leaf_index": 22,
    "proof": [...]
  }'

Offline verification (no server needed)

This is the key feature — auditors can verify proofs without any access to your system:

bash

xmdbctl checkpoints verify --local \
  --event-hash "sha256:8f3a2b..." \
  --merkle-root "v+IAy8gqQMQZpXMeuGgDd9bRJPjUclMqLUDv9seJgjE=" \
  --leaf-index 22 \
  --proof '[{"hash":"sha256:1a2b3c...","position":"left"},...]'

Or from a proof file:

bash

# Generate proof and save to file
xmdbctl checkpoints proof --checkpoint-id chk_abc123 --event-id evt_023 > proof.json

# Send proof.json to auditor

# Auditor verifies (no API access needed)
xmdbctl checkpoints verify --local --proof-file proof.json

Chained checkpoints

Checkpoints are linked via prev_checkpoint_id, forming a chain of checkpoints over time. This provides:

Complete coverage of all events
Verifiable checkpoint ordering
Efficient sync (compare checkpoint roots to detect divergence)

Best practices

Checkpoint regularly — Daily or after significant event batches
Store roots externally — Publish roots to external systems for additional trust
Use external anchoring — Anchor roots to RFC 3161 for third-party attestation (see External Anchoring)
Keep proofs — Generate and store proofs for critical events

Next Steps

External Anchoring — Third-party timestamp attestation
Beliefs — Track agent conclusions
CLI Reference — All checkpoint commands

Documentation

Merkle Proofs

Why Merkle proofs matter

How it works

Creating checkpoints

API

CLI

Listing checkpoints

Generating inclusion proofs

API

CLI

Verifying proofs

Server verification

Offline verification (no server needed)

Chained checkpoints

Best practices

Next Steps

Ready to add durable memory?