VectorLedger Docs

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.

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.

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.

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. When vledger start is running, the CLI automatically detects it and connects over TLS. Use --server to point at a non-default address.

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.

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. Verifies every file's BLAKE3 hash against the manifest before completing. --force is required to overwrite an existing data directory.

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.

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:

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

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

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

Amounts are displayed as decimals (e.g. 1.00) rather than minor units. The cap applies to the number of entries before line expansion — a cap of 10,000 entries yields up to 20,000 rows for a standard two-line transaction.

Example output:

accounts — chart of accounts

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

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:

Financial Functions

Aggregates & Window Functions

Joins

Supports INNER JOIN and LEFT OUTER JOIN.

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.

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 vectorguardlabs.com/pricing — 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 sales@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 sales@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

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

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.

Built With