VectorLedger Docs v1.5.1

Overview

VectorLedger is a purpose-built, append-only financial ledger written entirely in Rust. Every journal entry is linked by a tamper-evident BLAKE3 hash chain, every page of data is encrypted at rest with AES-256-GCM, and every query result can carry a cryptographic Merkle proof that the returned data has not been modified since it was written.

Historical tampering is cryptographically detectable any modification to a past record invalidates every hash in the chain from that point to the present, provided that verification checkpoints are independently protected (which the HSM architecture is specifically designed to enforce).

Built by VectorGuard Labs · Version 1.5.1 · License: BUSL-1.1

Why VectorLedger?

Traditional relational databases treat audit trails as an afterthought: triggers that can be disabled, log tables that can be truncated, and backup files that can be silently replaced. For organizations operating under SOC 2, PCI-DSS, financial regulation, or internal zero-trust policies, this is not good enough.

• A row written five years ago cannot be changed without invalidating every hash in the chain from that point to the present.
• Every SELECT response optionally carries a Merkle proof that any client can independently verify.
• The audit log is WORM-append-only each event is hashed into the next, forming a second independent tamper-evident chain.
• The compliance engine generates machine-generated technical evidence supporting SOC 2 Type II and PCI-DSS v4 control assessments — not pre-written documentation. This evidence supports an auditor's work; it does not by itself make an organization compliant. Organizational compliance requires additional controls, policies, and independent auditor assessment beyond what any database engine can provide.

Deployment Architecture

VectorLedger supports two PyHSM deployment models. Model 1 is suitable for development and single-server production. Model 2 isolates key material on a dedicated host with no public IP, which is the recommended configuration for production.

See Model 1 Local PyHSM and Model 2 Remote PyHSM for full setup instructions.

Prerequisites

No other runtime dependencies are required. All cryptographic libraries are statically linked via Cargo.

Installation

Option 1 Install via curl (recommended)

The fastest way to install VectorLedger. The installer detects your OS and architecture, downloads the correct pre-built binary, verifies its SHA-256 checksum, and places vledger on your PATH.

Install a specific version

Install to a custom directory

Installer environment variables

After installation, verify it works:

Windows (PowerShell)

Run this in PowerShell 5.1+ or PowerShell 7+:

The installer detects your architecture (x86_64 or ARM64), downloads the signed release zip, verifies its SHA-256 checksum, installs vledger.exe to %LOCALAPPDATA%\vledger\bin, and adds it to your user PATH.

Install a specific version

Install to a custom directory (with parameters)

Windows installer parameters

Option 2 Build from source

The binary is written to target/debug/vledger (dev) or target/release/vledger (release). Install to your PATH:

Expected output:

Quick Start

VectorLedger uses PyHSM a VectorGuard Labs product as its default key management backend. PyHSM acts as a local software HSM: VectorLedger's master encryption key is sealed inside PyHSM's encrypted keystore and never touches disk in plaintext.

The steps below walk through the full setup from scratch. If you are not using PyHSM and prefer a different key backend, jump to Key Source Backends.

PyHSM ships as both a Python package and a TypeScript daemon. VectorLedger connects to the TypeScript daemon via a Unix domain socket.

Install Node.js (18+) if you don't have it

Clone PyHSM and install dependencies

Generate a PyHSM master password

Start the PyHSM daemon

Expected output: [PyHSM] Listening on /tmp/pyhsm.sock

Confirm the socket is ready in a new terminal:

Verify the backend was recorded correctly:

On first start, credentials are written to ./vledger-data/catalog/.admin_initial_credentials (mode 0600) not printed to the terminal.

Once in the REPL, use \x to toggle expanded (vertical) display — useful for wide rows like ledger entries. Use \? to see all available meta-commands.

Reset / Starting Over

If you lose the admin password, or need to wipe the database and start fresh, delete the data directory and re-initialise. Make sure PyHSM is running before you init.

The first start after a fresh init writes a new admin credential file. Read it, change the password, and delete the file before doing anything else.

vledger init

Initialise a new database.

vledger start

Start the server. Responds to SIGTERM and CTRL-C with a graceful drain — in-flight connections are allowed to complete before the process exits.

Prometheus metrics

A Prometheus metrics server starts automatically on a separate port (default 127.0.0.1:9090, configurable via --metrics-addr). It exposes two endpoints:

The /health endpoint is suitable for load-balancer and orchestrator health checks (AWS ALB, Kubernetes livenessProbe, etc.). It does not require authentication and remains reachable when the connection semaphore is saturated.

Available metrics

Two background tasks run automatically after startup:

• Hourly integrity check — calls VERIFY_CHAIN() every 60 minutes. Any failure is logged as an error and written to the audit log as INTEGRITY_ALERT.
• 15-minute invariant monitor — checks that Σ(Assets+Expenses) == Σ(Liabilities+Equity+Income) every 15 minutes. Violations are logged as INVARIANT_ALERT.

When started with --with-proofs, every SELECT response in the vledger sql REPL includes a Merkle proof and root hash.

WAL sync modes

vledger sql

Interactive SQL REPL or single-statement execution. The REPL includes built-in line editing (arrow keys, up/down history). When vledger start is running, the CLI automatically detects it and connects over TLS. Use --server to point at a non-default address.

Natural-language queries

REPL meta-commands

The prompt changes to vledger (expanded)> while expanded mode is active. Use \x again to toggle back.

vledger verify

Verify WAL integrity and the ledger hash chain. Use --self-test to run the full integrity suite against an isolated temporary database — your production data is never touched.

vledger status

Show database version, WAL segment count, and active segment.

vledger backup

Create a point-in-time backup archive with a BLAKE3 manifest. Private key material is excluded only public keys are archived.

vledger restore

Restore a backup archive. Decrypts every file using the .key sidecar, then verifies each file's BLAKE3 hash against the manifest before completing. --force is required to overwrite an existing data directory.

vledger backup-verify

Verify a backup archive without restoring it — checks the manifest hash and, when the master key is available, decrypts and hash-checks every file. Use --decrypt false to verify the manifest hash only (no decryption, no master key required).

vledger rotate-keys

Rotate all HSM key slots and record audit events. Old key versions are archived for decryption of existing data; new versions are used for all new writes.

vledger audit-export

Export the WORM audit log, optionally filtered by date range.

Audit log export is tier-gated:

vledger audit-package

Generate a portable, self-contained cryptographic audit evidence package. Default (commitment-only) mode computes the Merkle root over all entries in a single O(n) pass, signs it with the database Ed25519 key, and writes a compact JSON commitment. Completes in seconds at any scale.

The output JSON meta block includes all provided fields:

vledger audit-proof

Generate a single-entry inclusion proof against a commitment package. Produces a self-contained JSON file the auditor can verify without any database access.

vledger verify-audit-package

Verify an audit package or entry proof. Requires no database access, no server, and no key files. Works on all three package types: commitment, entry_proof, and full.

Example output:

Auditors who cannot install software can download a pre-built binary from the GitHub release page (no Rust toolchain required):

vledger compliance-report

Generate a SOC 2 or PCI-DSS compliance evidence report. Reports are generated by running checks against real filesystem state not pre-written text.

vledger license

Show the active license tier, features, and expiry. Place the signed license.json file provided by VectorGuard Labs into your data directory to unlock paid features. If no file is present, the engine runs in Free tier.

vledger start-primary

Start a WAL replication primary listener. Requires a Growth or Enterprise license.

Reads <data-dir>/replication.json. If the file does not exist, a default config is written on first run. The primary auto-generates replication_secret.hex (mode 0o600) on first start — copy this file to every replica before starting them.

vledger start-replica

Start a WAL replication replica. Requires a Growth or Enterprise license. The replication_secret.hex file must already be present (copied from the primary) before this command will succeed.

The replica connects to the primary, performs the BLAKE3 HMAC handshake, and streams WAL records continuously. It reconnects automatically on disconnection with exponential backoff.

vledger user

Manage user accounts. All subcommands read the user store directly from the data directory the server does not need to be running.

vledger seed

Populate the database with randomly generated journal entries for testing and benchmarking. Does not require a running server — opens the data directory directly.

vledger migrate-to-sqlite

One-time migration that populates the SQLite entry index (vledger.db) from the WAL. Run this if the SQLite index is empty after a large bulk import or after upgrading from a version that predates the SQLite index. The server must NOT be running.

Reads the WAL in batches and writes entries to the SQLite index incrementally. Progress is printed every 100,000 entries. It is safe to interrupt and re-run — already-indexed entries are skipped. On completion it writes wal-checkpoint.json so future startups skip the WAL replay.

After migration completes, run vledger verify --data-dir ./vledger-data to confirm WAL and chain integrity.

FTS Index Rebuild (Automatic on Startup)

From v1.0.30, VectorLedger maintains a SQLite FTS5 full-text index over all entry metadata. This index is built and maintained automatically — no manual action is required in normal operation.

Example progress output in nohup.out during backfill:

No manual steps are required. The index works with any metadata field name — future CSV imports with different column layouts are automatically searchable without schema changes.

vledger import

Import journal entries from a CSV or JSON file. Every row goes through the full post_entry() integrity path — debit/credit validation, account existence, currency check, balance constraints, idempotency, hash chain, WAL persistence. The server must NOT be running.

Amount handling: Decimal amounts are automatically converted to minor units (cents). 915.87 becomes 91587. If your source column is already in minor units, it is passed through unchanged.

Recommended workflow

vledger reconcile

Recompute all account balances from journal entries and compare against the running balance cache. Exits non-zero if any discrepancy is found. Does not require a running server.

A clean ledger produces:

vledger settle

Transition a journal entry through the settlement lifecycle. Status transitions: Posted → Pending → Settled | Failed. The original entry row is never modified — transitions are stored as append-only SettlementEvent records. Legal holds block settlement transitions. Does not require a running server.

vledger hold

Manage legal holds on accounts. While a hold is active, no new entries, reversals, or settlement transitions involving any line of the held account are permitted. Does not require a running server.

vledger retention

Manage data retention policies. Policies are stored in <data-dir>/catalog/retention_policy.json. Does not require a running server. Use --days 0 to keep forever; --domain applies the policy to a specific domain only.

vledger rules

Record and track accounting rule versions. Rule versions are stored in <data-dir>/catalog/accounting_rules.json. Does not require a running server.

vledger mcp

Start the MCP (Model Context Protocol) server. Requires AgenticAI license feature (Starter, Growth, or Enterprise). Auto-detects a running vledger start on port 5433 and switches to network mode automatically.

MCP Server Overview

VectorLedger ships a Model Context Protocol server (port 3000, HTTP+SSE) that lets AI assistants — Claude Desktop, Cursor, Kiro, and any other MCP-capable client — query and write to the ledger directly without SQL. Requires AgenticAI license feature (Starter, Growth, or Enterprise).

All 15 MCP Tools

All tools execute through the same parse → plan → privilege-check → execute pipeline as direct SQL. No tool bypasses RBAC.

MCP Client Configuration

Add to your AI assistant's MCP config file (Claude Desktop, Cursor, Kiro):

AGENT_SYSTEM_PROMPT

A public AGENT_SYSTEM_PROMPT constant is exported from vledger-mcp and returned in the MCP initialize response's instructions field. It contains financially-aware instructions covering minor-units semantics, double-entry rules, account type normal balances, entry status lifecycle, tool routing guidance, and behavioral rules.

Agent Query Billing

One Agent Query is counted per initialize JSON-RPC request (one conversation), regardless of how many internal tool calls the agent makes within that session.

Session idle timeout: 30 minutes. After 30 minutes of inactivity, the next question starts a new Agent Query.

The counter file (mcp_queries.json) resets automatically on the first day of each UTC month. It is a commercial metering mechanism — not a security control.

Natural-Language Queries (--ask)

The vledger sql --ask flag translates a natural-language question into SQL via an LLM and executes it. Requires OPENAI_API_KEY and the AgenticAI license feature (Starter, Growth, or Enterprise).

The generated SQL is printed to stderr as → SQL: ... before execution. No ledger data, credentials, or key material is transmitted to the LLM provider — only the user's question text and static schema context.

Environment Variable

Best for containerised environments where secrets are injected as environment variables (Kubernetes Secrets, AWS ECS task definitions, etc.).

HashiCorp Vault KV v2

VAULT_TOKEN must be set in the environment before starting the server. VectorLedger checks the token's TTL at startup and logs a warning if it expires within 24 hours.

AWS KMS

On first start, VectorLedger calls GenerateDataKey and caches the encrypted ciphertext blob locally (kms_data_key.enc). On subsequent restarts, it calls Decrypt against the cached blob. The cache file is protected with an HMAC-SHA256 integrity check a tampered blob is detected before any network call.

File (development only)

Generates a random key and writes it to vledger-data/keys/master_key.hex with mode 0o600.

Key Backend Summary

PyHSM (Recommended)

PyHSM is a VectorGuard Labs product and the default key backend for VectorLedger. The master encryption key is sealed inside PyHSM's AES-256-GCM-SIV encrypted keystore and never touches disk in plaintext.

Two ways to install PyHSM

Option A TypeScript daemon (required for VectorLedger integration)

This is what VectorLedger connects to. The daemon listens on a Unix domain socket and handles all key operations via IPC.

Option B Python CLI

The Python package installs the vectorguard-pyhsm command a key management CLI for generating, rotating, and inspecting keys. VectorLedger does not connect to it; use it to administer the keystore independently.

PyHSM environment variables

How VectorLedger uses PyHSM across restarts

Model 1 Local PyHSM Same Server

PyHSM and VectorLedger run on the same host. Communication uses a Unix domain socket at /tmp/pyhsm.sock. Zero network overhead. Suitable for development, CI, and single-server production deployments.

Model 2 Remote PyHSM Separate Server

PyHSM runs on a dedicated server in the same region's private subnet. VectorLedger connects over TLS 1.3 with mutual certificate authentication (mTLS) on port 8443. PyHSM's private key material is never accessible from the VectorLedger host. Recommended for production.

Model 2 environment variables

Model 2 Step-by-Step Setup

This section walks through every step required to connect VectorLedger on Server A to PyHSM running on Server B, on the same-region private subnet.

No other inbound rule is needed on Server B. There must be no public IP on Server B and no 0.0.0.0/0 rule for port 8443.

Run on Server A. Replace 10.0.1.50 with Server B's private IP:

Verify key_source.json shows "backend": "remote_py_hsm". If it shows "env" or "file", the connection to PyHSM failed delete the data directory, confirm PyHSM is reachable, and re-run init.

On every start, VectorLedger connects to the remote PyHSM, decrypts the master key blob, uses the key briefly for derivation, and immediately zeroizes it. If PyHSM is unreachable, startup fails closed it never falls back to a weaker key source.

Rotating the Client Certificate

The mTLS client certificate should be rotated before it expires (90-day validity recommended). No data migration is required only the transport credential changes.

Replay-Attack Prevention (Model 2)

Every request sent to a remote PyHSM over TLS includes two additional fields that PyHSM should validate:

These fields are injected automatically by VectorLedger — no configuration required. They are not present on Model 1 (local socket) requests, where replay is not a meaningful threat.

PyHSM on Windows

PyHSM uses TCP instead of a Unix socket on Windows. Start the daemon with PYHSM_TCP_PORT and pass the TCP address to VectorLedger:

Hardware HSM PKCS#11 Integration Enterprise

VectorLedger does not link a PKCS#11 .so directly. Instead it communicates with a separate PyHSM daemon (a TypeScript/Node.js process) over either a Unix socket (Model 1, same server) or mTLS over TCP (Model 2, separate server). Raw key material never leaves PyHSM — the master key is AES-wrapped inside it, and VectorLedger only ever holds the ciphertext blob on disk.

Step 1 — Ensure an Enterprise license is installed

Step 2 — Start the PyHSM daemon

PyHSM must be listening on /tmp/pyhsm.sock (Model 1) before VectorLedger is initialized or started.

Step 3 — Initialize with PyHSM as the key source

This writes vledger-data/keys/key_source.json — for Model 1 it looks like:

Step 4 — Start the server normally

On every boot VectorLedger sends the cached blob to PyHSM to unwrap. If PyHSM is not running at startup, VectorLedger fails immediately — it never falls back silently to a weaker key source.

Dedicated hardware backends (AWS CloudHSM & Azure Dedicated HSM)

For actual hardware HSMs, bridge sidecars translate the JSON IPC protocol to hardware PKCS#11 calls:

Configure the bridge via vledger-data/keys/hsm_config.json. Example for AWS CloudHSM:

Raw key material never crosses the hardware boundary on either cloud provider — all cryptographic operations run inside the device. Contact engineering@vectorguardlabs.com for bridge sidecar setup guides.

Compliance Reporting

SOC 2 Type II controls covered

CC6.1, CC6.2, CC6.3, CC6.6, CC6.7, CC7.2, CC8.1, A1.1

PCI-DSS v4 controls covered

Req 2.2, 3.4, 3.5, 4.2, 7.1, 10.2, 10.3, 10.5, 11.5

Generate reports

Cryptographic Audit Package

VectorLedger can generate a portable, self-contained cryptographic audit evidence package that any third party can verify independently — no database access, no server, no credentials required.

Three-tier design:

Tier 1 — Commitment package (default, fast at any scale)

Computes the Merkle root over all entries in a single O(n) pass, signs it with the database Ed25519 key, and writes a compact JSON commitment. Completes in seconds regardless of ledger size.

Tier 2 — On-demand entry proof (prove one specific entry)

Generates a single Merkle inclusion proof proving that a specific entry belongs to the committed root. The auditor receives a self-contained file they can verify without database access.

Tier 3 — Full export (small ledgers only)

Embeds all entries and per-entry proofs. Only practical for ledgers with fewer than ~10,000 entries.

Verification (no database access required)

Example output:

Auditors who cannot install software can use the pre-built binary from the GitHub release (no Rust toolchain required):

SQL Reference

VectorLedger supports a financial-ledger SQL dialect over both the native TLS connection (port 5433) and the PostgreSQL wire protocol (port 5432). It is PostgreSQL-compatible — not PostgreSQL — so standard PostgreSQL system catalog queries (\l, \dt, pg_catalog.*) are not supported.

Scan Safety — Default Row Cap

Unbounded full-table scans on a large ledger load all matching rows into memory before returning, which can exhaust server RAM. VectorLedger protects against this with an automatic 10,000-entry cap on non-point-lookup queries that have no explicit LIMIT.

When the cap fires you will see: 10000 rows (capped at 10000 — use LIMIT n or WHERE sequence = x to paginate)

To page through a large dataset, use sequence-based pagination:

Tables

ledger — one row per journal entry

Columns: sequence, id, status, description, domain, effective_at, posted_at, external_ref, content_hash, chain_hash, lines, metadata

The lines column contains all debit and credit lines as a single semicolon-separated string. Use ledger_lines for the traditional accounting view.

The metadata column is an optional JSON blob for arbitrary extra fields (e.g. sender name, channel, original transaction ID). It is hash-protected — included in the entry's content hash so any post-hoc modification breaks the chain. Example value: {"sender_name":"John Smith","channel":"wire","status":"settled"}

Entry status values: Posted, Reversed, Reversal, PendingApproval, Rejected, Pending, Settled, Failed. The last three are part of the settlement lifecycle and are derived from append-only SettlementEvent records — the original entry row is never mutated.

ledger_lines — one row per debit/credit line

Returns each debit and credit as its own row — the standard double-entry accounting view that accountants expect.

Columns: date, sequence, entry_id, description, domain, account_id, dr_cr, amount, currency, status, metadata

Amounts are displayed as integers in minor units (e.g. 100000 = $1,000.00 for USD). The metadata column mirrors the entry-level metadata JSON blob. The cap applies to the number of entries before line expansion — a cap of 10,000 entries yields up to 20,000 rows (two lines per entry) for a standard two-line transaction.

Example output:

accounts — chart of accounts

Columns: id, code, name, account_type, currency, status, domain, balance, legal_hold

The legal_hold column is true when the account is under a legal hold. While active, no entries, reversals, or settlement transitions involving this account are permitted.

Write Commands

Post a journal entry

• amount is in minor units (cents for USD — 100000 = $1,000.00)
• debit_account and credit_account accept either account code or UUID
• Optional fields: external_ref, idempotency_key
• Entries are append-only — UPDATE and DELETE are not supported

Create an account

Post a correction (reversal)

Corrections are made by posting a new reversal entry, never by modifying the original:

Full reversal & correction workflow

The recommended 5-step process for correcting a posted entry:

The original entry is never modified or deleted. All three entries (original, reversal, correction) remain permanently in the ledger. A reversal without a correction is also valid — post only the reversal if the transaction should simply not exist.

Financial Functions

Aggregates & Window Functions

Joins

Supports INNER JOIN and LEFT OUTER JOIN.

Metadata Search

Every entry carries a metadata field — an arbitrary JSON blob (e.g. {"sender_name":"Alice","receiver_name":"Bob","channel":"mobile"}). From v1.0.30, metadata is indexed using a SQLite FTS5 full-text index, making search instant regardless of ledger size.

• Supported on both ledger and ledger_lines. Results are ordered by sequence.
• Works with any metadata field name — future CSV imports with different column layouts (e.g. beneficiary, payee) are automatically searchable without schema changes.
• LIKE performs case-sensitive matching; ILIKE is case-insensitive.

Multiple Point Lookups (IN)

Use IN to fetch multiple specific entries or accounts in a single query. These are treated as point lookups — no scan cap applies.

Compatibility Queries

These queries are supported for ORM and connection pooler health checks:

What Is Not Supported

Replication

VectorLedger supports synchronous hot-standby WAL replication with three independent security layers: TLS 1.3, optional mTLS, and BLAKE3-keyed HMAC challenge-response inside TLS.

Additional integrity guarantees:

• Replica verifies the BLAKE3 hash of every received WAL record before applying it — a tampered record is rejected and the connection closed.
• Exponential reconnect backoff (500 ms → 30 s) with faster escalation on auth failures (max 60 s).
• Replication secret generated from OsRng, stored at mode 0o600.
• Divergence detection via periodic DivergenceCheckpoint messages carrying a rolling BLAKE3 WAL chain hash — a mismatch means the replica must be re-seeded.

Replication Setup

The primary auto-generates a 32-byte HMAC secret at vledger-data/replication_secret.hex (mode 0o600) on first run. This secret must be copied to every replica.

The replica connects to the primary, performs the HMAC handshake, and begins streaming WAL records. It reconnects automatically on disconnection.

replication.json Reference

Replication Limitations

These limitations do not affect the security properties of the WAL integrity or tamper-evidence guarantees.

Multi-Node Deployment (WAL Replication) Growth+

The primary runs a WAL shipper on port 5434; replicas connect and stream WAL records in real time. A shared 32-byte HMAC secret authenticates the channel inside TLS 1.3.

On the primary — create replication.json

Start the primary

On first run this auto-generates replication_secret.hex (mode 0o600). Copy that file to the replica before starting it:

On the replica — create replication.json

Start the replica

The replica connects to the primary, performs a BLAKE3 HMAC challenge-response inside TLS, then streams WAL records continuously. It verifies the BLAKE3 hash of every record before writing and reconnects automatically with exponential back-off (500 ms → 30 s) on disconnection.

Client SDKs

Native client libraries are included for three languages, all located under clients/ in the repository.

Any standard PostgreSQL client library can also connect to the PostgreSQL wire-protocol listener on port 5432 when the server is started with --pgwire (Starter tier and above).

Licensing

VectorLedger uses a tiered license model. The binary enforces feature availability at startup by verifying a signed license.json file in your data directory. If no license file is present, the engine runs in Free tier mode.

Licenses are issued by VectorGuard Labs. Purchase at vledger.vectorguardlabs.com — your license.json is generated automatically and delivered to the email on your account.

Pricing

Annual billing available on all paid tiers — pay for 10 months, get 12. Contact pavon@vectorguardlabs.com for multi-instance or custom pricing.

Installing a license

Feature availability by tier

Annual billing available on all paid tiers pay for 10 months, get 12. Contact pavon@vectorguardlabs.com for multi-instance or custom pricing.

Production Deployment Checklist

Before putting VectorLedger in front of production traffic:

Core setup

• PyHSM daemon running with a persistent, backed-up keystore (PYHSM_KEYSTORE_PATH points to a durable location)
• vledger init completed with --key-source pyhsm (Model 1) or --key-source remote-pyhsm (Model 2)
• key_source.json shows "backend": "py_hsm" or "backend": "remote_py_hsm" not "env" or "file"
• keys/MASTER_KEY_PLACEHOLDER.txt deleted (its presence fails the PCI-DSS compliance check)
• Admin credential file read, password changed, and catalog/.admin_initial_credentials deleted
• Data directory permissions locked (chmod 700 on vledger-data/ and all subdirectories)
• Volume encryption enabled on the disk hosting vledger-data/
• Replace the self-signed TLS certificate with a CA-signed one pass --tls-cert-path and --tls-key-path at startup
• Configure replication with a secondary node (replication.json) or document a backup-based HA strategy
• Install a valid license.json for your paid tier (vledger license --data-dir ./vledger-data to confirm)
• Test a full backup and restore drill: vledger backup → vledger restore → vledger verify
• Schedule regular vledger backup runs (cron or your orchestrator)
• Schedule regular vledger verify runs (recommended: after each backup)
• Ship audit/audit.log to an append-only off-host destination in real time
• Run compliance reports and confirm zero FAIL items: vledger compliance-report --standard pci-dss

Additional items for Model 2 (remote PyHSM)

• PyHSM server has no public IP accessible only via private subnet
• Security group / firewall allows VectorLedger → PyHSM (port 8443) only no other inbound
• CA certificate, client certificate, and client key stored at paths that survive reboots and are mode 0600
• PYHSM_CA_CERT, PYHSM_CLIENT_CERT, PYHSM_CLIENT_KEY environment variables set (or paths baked into key_source.json)
• mTLS client certificate has a short validity period (90 days recommended) with a rotation schedule
• PyHSM configured to validate requestId (reject duplicates within 5-minute window) and reject stale timestamp values
• Verified that vledger start fails cleanly when PyHSM is unreachable never falls back silently

Testing & Verification

This section documents every testing mechanism available in VectorLedger. Run these commands on your own server to independently verify correctness, durability, and tamper-evidence before deploying to production.

Prerequisites

Start the server before running any tests that require a live connection:

1. Benchmark Tests (TPS)

Measures transactions per second across INSERT, SELECT, and mixed workloads. Restart the server between each workload run to clear connection state.

2. PostgreSQL Wire Protocol Compatibility

Verifies that VectorLedger accepts connections from standard PostgreSQL clients. Start the server with --pgwire and connect with psql:

3. Concurrent Transaction Test

Runs the benchmark in one terminal while querying live from another to confirm no torn reads, duplicate sequences, or chain failures under concurrent load.

Terminal 1

Terminal 2 (while benchmark runs)

4. WAL Corruption Test

Confirms that VectorLedger detects and rejects corrupted WAL data during recovery.

5. Logical Tampering Test

Confirms that the BLAKE3 hash chain detects in-memory data manipulation. TAMPER_ENTRY mutates an entry's description without updating its hash - simulating what a malicious actor would need to do to falsify a record.

6. Crash / Restart Recovery Test

Confirms that committed transactions survive a hard kill mid-write and that uncommitted transactions are rolled back cleanly.

7. Integrity Self-Test Suite

The built-in self-test runs five automated phases against a completely isolated temporary database. Your production data is never touched.

What the self-test verifies

Inspecting the self-test database manually

8. Chain Range Verification

Verify a specific range of entries rather than the full chain:

9. Direct SQL Queries (without psql)

Query the production database directly from the terminal without starting psql:

Each vledger sql invocation opens a fresh TLS connection, authenticates, runs the query, and closes. There is no persistent session between calls, so credentials are prompted every time by default.

To avoid retyping credentials on every query, set environment variables:

Alternatively, use psql for an interactive session - authenticate once and run as many queries as you want:

10. Audit Package (Cryptographic Evidence Export)

Generate a portable audit evidence package and verify it independently — no database access required for verification.

Running the Test Suite

VectorLedger has 498 automated tests across 11 packages, all passing on every release.

Test coverage by area

Security Hardening Methods (v1.0.31–v1.0.34)

In addition to the automated test suite and fuzz targets, VectorLedger uses three industry-standard verification methods to harden the financial and cryptographic code paths.

Static Analysis — cargo clippy with custom deny rules

scripts/static-analysis.sh runs two-pass clippy across the workspace:

• Pass 1 (financial and crypto packages): denies unwrap_used, expect_used, panic, cast_possible_truncation, cast_sign_loss, indexing_slicing, ptr_arg, todo, unimplemented. Every existing violation was either fixed or annotated with a #[allow] plus a // SAFETY: comment.
• Pass 2 (all packages): denies correctness, suspicious, await_holding_lock, let_underscore_lock across all code including tests.
• Amount arithmetic operators (Neg, Add, Sub) now use checked_neg / checked_add / checked_sub — a silent overflow in financial math is now a compile-time error.

Mutation Testing — cargo-mutants

scripts/mutation-test.sh runs cargo-mutants v27 scoped to 7 financial/crypto packages. Mutation testing injects plausible-but-wrong code changes and verifies the test suite catches each one.

Initial results on vledger-crypto: 57 mutants caught, 20 survived (74% mutation score). Surviving mutants are documented test gaps — the most significant are compute_chain_hash returning a default hash, and DerivedKey::into_signing_seed returning zeros.

Formal Verification — Kani proof harnesses

crates/vledger-kani/ contains 21 Kani proof harnesses that exhaustively verify properties for all possible inputs within bounded types — not just a sample.

Fuzz Targets (12 total)

VectorLedger ships 12 fuzz targets covering the WAL, SQL planner, pgwire codec, backup/restore, auth, transaction bincode deserialization, replication, backup key sidecar, audit log, compliance report, CSV import, and multi-segment WAL recovery.

WAL Sync Modes

VectorLedger ships with three WAL sync modes selectable at startup.

Connection Resource Controls

Per-listener resource controls to prevent resource exhaustion:

Production Status

This matrix reflects the current tested and verified state of each capability. Status labels are conservative a capability is only marked Production after it has been exercised under real or realistic load with the full mTLS / key pipeline in place.

Performance Benchmarks

Memory allocator

VectorLedger uses jemalloc as its global allocator on Linux and macOS (via tikv-jemallocator). jemalloc aggressively returns freed memory to the OS after large working-set operations — in particular WAL recovery, where processing 25 M+ records with the default ptmalloc allocator causes ~7 GB of RSS to accumulate and never be returned. jemalloc eliminates this entirely. On Windows the default MSVC allocator is used unchanged.

No configuration is required. The allocator is compiled in automatically on non-MSVC targets.

Development baseline: benchmarked on Apple Silicon (MacBook, macOS) running in group_commit WAL mode with a mixed read/write workload (10 concurrent clients, 1,000 transactions each, 70% INSERT / 30% SELECT):

Benchmark environment matrix

The table below will be populated as benchmarks are run on server-class hardware. Contributions and independent reproduction are welcome. All measurements use --wal-sync-mode group_commit (default) with a 70% INSERT / 30% SELECT mixed workload unless noted otherwise. per_record mode will show lower TPS and higher p99.

Financial Invariants Enforced at the Engine Level

VectorLedger enforces 16 financial invariants in code — not by policy or documentation. Every invariant is verified by the automated test suite on every release.

Core double-entry rules

Account validity

Balance protection

Legal and compliance controls

Reversal rules

Cryptographic and structural integrity

Asset precision

Idempotency & global equation

Changelog

v1.5.1 — Workspace-wide version bump

• Workspace-wide version bump — all crates at 1.5.1

v1.5.0 — AgenticAI feature gate + monthly Agent Query limits

• Bug fix: require_feature() was only checking the explicit features list, not the tier's default features — licenses on paid tiers were incorrectly blocked from tier-default features. Fixed by checking both the explicit list and tier default features. No security impact — this was an over-blocking bug, not an under-blocking one.
• MCP server and vledger sql --ask gated behind Feature::AgenticAi (Starter, Growth, Enterprise)
• Monthly Agent Query limits enforced: Starter 10, Growth 100, Enterprise unlimited

v1.4.5 — propose_correction and execute_correction MCP tools

• Added propose_correction MCP tool — shows reversal+correction plan, writes nothing
• Added execute_correction MCP tool — executes reversal + correction after mandatory human confirmation
• Both tools post through the normal post_entry pipeline subject to the same RBAC and all 16 financial invariants; neither tool can modify or delete existing entries

v1.4.4 — resolve_account identity enforcement MCP tool

• Added resolve_account MCP tool — mandatory identity gate resolving name/code/UUID to an authoritative account ID before any write
• NOT_FOUND or MULTIPLE_FOUND results halt the operation; all lookups are subject to the caller's RBAC session

v1.4.3 — JSON-RPC notifications return HTTP 204 (Kiro V3 fix)

• JSON-RPC notifications (no id field) now return HTTP 204 — fixes Kiro V3 stuck on loading

v1.4.2 — SSE endpoint event sends full absolute URL (Kiro CLI V3 fix)

• SSE endpoint event now sends full absolute URL — fixes Kiro CLI V3

v1.4.1 — vledger mcp auto-detects running server

• vledger mcp now auto-detects a running vledger start on port 5433 and switches to network mode automatically

v1.4.0 — Financial semantic layer: 5 new MCP reasoning tools + AGENT_SYSTEM_PROMPT

• 5 new MCP reasoning tools: explain_balance, reconcile_account, find_policy_violations, summarize_period, audit_report
• AGENT_SYSTEM_PROMPT constant exported from vledger-mcp and returned in MCP initialize response's instructions field
• Richer --ask schema context with full financial domain knowledge

v1.0.39 — Merkle root display truncation fixed

• Bug fix: Merkle root display was truncated to 32 hex characters (16 bytes) at 3 display sites due to &root_hex[..root_hex.len().min(32)]; now shows full 64-character BLAKE3 hash
• Display-only bug — no data integrity issue; all three display sites now show the full hash

v1.0.38 — Column projection fix

• Bug fix: Column projection (SELECT specific, columns FROM ledger) now works correctly for all 3 tables (ledger, ledger_lines, accounts)

v1.0.37 — MERKLE_ROOT() single-argument form

• to_seq is now optional — MERKLE_ROOT(n) is equivalent to MERKLE_ROOT(n, n) and returns the Merkle root for that single entry
• Previously passing a single argument returned an error requiring two arguments; both forms are now fully equivalent

v1.0.36 — MERKLE_ROOT(from_seq, to_seq) SQL function

• Added MERKLE_ROOT(from_seq, to_seq) as a first-class SQL function available at all times — no --with-proofs flag required
• Returns a single row with from_seq, to_seq, entry_count, and merkle_root (64-char BLAKE3 hex); empty range returns 0000…0000
• Privilege: requires admin, operator, or auditor role (can_verify); the readonly role cannot call MERKLE_ROOT
• Uses the same leaf inputs (content_hash per entry) as --with-proofs and vledger audit-package — roots from all three methods are directly comparable
• Files changed: vledger-sql planner/executor/optimizer, vledger-ledger store, vledger-server auth, vledger-pgwire server

v1.0.35 — pgwire --with-proofs flag was silently ignored (fixed)

• Fixed: --with-proofs --pgwire was silently ignored — Merkle root was computed but never sent to PostgreSQL wire-protocol clients
• Root cause: _attach_proofs parameter (underscore prefix) was never consumed; executor always called Executor::new() regardless of the flag
• Three fixes in crates/vledger-pgwire/src/server.rs: parameter renamed and consumed; read plans now route through ReadExecutor on a read lock; Merkle root emitted as a pgwire NoticeResponse after data rows when a proof is present
• Secondary fix: read queries were unnecessarily acquiring the write lock, blocking concurrent reads
• This was a correctness bug — no data was exposed, no integrity guarantee was weakened; the native JSON protocol (port 5433) was unaffected

v1.0.34 — Security & Reliability Hardening: static analysis, mutation testing, formal verification

• Static Analysis (scripts/static-analysis.sh): two-pass cargo clippy — Pass 1 denies unwrap_used, expect_used, panic, cast_possible_truncation, cast_sign_loss, indexing_slicing, and more on financial/crypto packages; Pass 2 denies correctness, suspicious, await_holding_lock across all packages; Amount arithmetic now uses checked_neg/checked_add/checked_sub
• Mutation Testing (scripts/mutation-test.sh): cargo-mutants v27 scoped to 7 financial/crypto packages; vledger-crypto: 57 mutants caught, 20 survived (74% score); surviving mutants documented as test gaps
• Formal Verification (crates/vledger-kani/): 21 Kani proof harnesses exhaustively verifying properties across wal (5), amount (7), hash_chain (5), and hmac (4) modules for all possible inputs within bounded types
• No on-disk format changes; existing databases and backups are fully compatible

v1.0.33 — Security & Reliability Hardening: 498 tests, 6 new fuzz targets, 4 new proptest properties

• 498 tests passing across 11 packages — 245 new tests added across 9 packages (see test suite for full breakdown)
• 4 new proptest properties: reversal+correction nets to correction amount, hash chain valid for random count and amounts, settlement events do not mutate original entry, balance equals sum of lines
• 6 new fuzz targets (12 total): fuzz_replication, fuzz_backup_keysidecar, fuzz_audit_log, fuzz_compliance_report, fuzz_csv_import, fuzz_wal_recovery_multisegment
• No on-disk format changes; existing databases and backups are fully compatible

v1.0.32 — Security & Reliability Hardening: 3 fuzz-found bugs fixed

• WAL reader unbounded allocation (OOM) fixed: payload_len = 0xFFFFFFFF triggered a 4 GiB allocation and killed the process; fixed by capping both payload_len and ct_len at MAX_RECORD_PAYLOAD = 64 MiB before any allocation; found by fuzz_wal_recovery
• SQL planner index-out-of-bounds panic fixed: INSERT with fewer values than columns caused a panic; fixed by replacing vals[idx] with vals.get(idx) returning SqlError::MissingField; found by fuzz_sql_parser
• Fuzz harness bincode allocation cap added: raw arbitrary bytes fed to bincode::serde::decode_from_slice without a limit caused ~1.8 exabyte allocation attempt in the harness (production code path is safe)
• All 6 fuzz targets ran clean after fixes; no on-disk format changes

v1.0.31 — Security & Reliability Hardening: WAL signing, NoSync compile gate, crash recovery tests, 3 new fuzz targets

• SignedCommit::verify() removed: self-consistency method deleted from vledger-crypto; it proved self-consistency (key embedded in commit) but not authenticity; all callers already used the safe verify_against(trusted_key) form; the unsafe method is now a compile error
• WalSyncMode::NoSync is now a compile-time feature gate: the variant does not exist in the type system of a standard release build; requires --features dev-no-sync at compile time; the CLI flag --wal-sync-mode=no_sync returns a hard error in release builds
• 8 new deterministic crash/recovery tests in crates/vledger-ledger/src/deterministic_recovery_tests.rs covering: torn record discard, segment-boundary crash, checkpoint deletion/corruption/future-sequence, concurrent open rejection, and multi-entry batch spanning segment roll
• 3 new fuzz targets: fuzz_backup_restore, fuzz_auth, fuzz_transaction
• No on-disk format changes; existing databases and backups are fully compatible

v1.0.30 — FTS5 metadata index

• Added SQLite FTS5 full-text index over all entry metadata (entries_fts virtual table, unicode61 tokenizer)
• WHERE metadata LIKE '%value%' and WHERE metadata ILIKE '%value%' now use the FTS index — queries that previously took minutes on 17M+ entry ledgers now return in milliseconds
• FTS index is populated at insert time for all new entries
• On first startup after upgrade, existing databases are automatically backfilled (progress logged to nohup.out); subsequent startups skip the step
• Index works with any metadata field name — future CSV imports with different column layouts are automatically searchable

v1.0.29 — Metadata scan OOM fix

• Fixed server crash (OOM) introduced in v1.0.28: replaced entries_scan(entry_count()) with stream_entries(), which iterates SQLite rows one at a time in constant RAM

v1.0.28 — Metadata scan cap fix

• Fixed WHERE metadata LIKE returning 0 rows on ledgers larger than 10,000 entries: scan was incorrectly capped at DEFAULT_SCAN_LIMIT regardless of total ledger size

v1.0.27 — Metadata WHERE filtering

• Added WHERE metadata = 'value' and WHERE metadata LIKE '%value%' / ILIKE support on both ledger and ledger_lines
• Previously metadata was readable in SELECT output but not filterable in WHERE clauses

Built With