1. System Overview

Verity replaces traditional mutable‑balance databases with a Merkle‑proofed, TLA+‑verified double‑entry ledger and replaces role‑based access control with compile‑time capability security. The platform runs on bare‑metal Linux servers with hardware‑enforced Trusted Execution Environments (Intel TDX or AMD SEV‑SNP) for production. Evaluation deployments may use simulation mode with reduced security guarantees.

Deployment architecture — two binaries, one system:

Binary	Role	Network Binding	Licence Check
verity	Core banking engine (ledger, BIAN domains, AI agents, Merkle proofs, TLA+ model checking)	127.0.0.1:9000 (localhost only — never exposed to the internet)	Offline Ed25519 signature verification against embedded vendor public key
verity-gateway	API gateway, TLS termination, rate limiting, capability token routing, CORS	0.0.0.0:443 (public interface)	Offline Ed25519 signature verification against embedded vendor public key

Key architectural properties:

• Both binaries are statically linked — no system libraries beyond Linux kernel 5.15+ required.
• The licence is hardware‑bound on first install. Moving the binaries to different hardware requires a new licence key.
• All data is stored in a Merkle‑proofed, append‑only ledger. No transaction can be modified or deleted after commit.
• The gateway handles all external traffic; the core engine never faces the public internet.
• AI agents run inside the core engine, governed by capability tokens enforced at the VM level.

2. Prerequisites

2.1 Hardware Requirements

Environment	CPU	RAM	Storage	TEE
Production	16 cores (Intel Xeon Scalable or AMD EPYC 9005)	64 GB ECC	1 TB NVMe SSD (RAID‑1 recommended)	Intel TDX or AMD SEV‑SNP required
Evaluation / Pilot	8 cores	32 GB	512 GB SSD	Optional (simulation mode)
Edge (branch / ATM)	4 cores (Intel Atom or ARM Cortex‑A78AE)	4 GB	32 GB eMMC	Optional

2.2 Software Requirements

Component	Version / Notes
Operating System	Linux kernel 5.15 or later. Ubuntu 22.04/24.04 LTS, RHEL 9, or Debian 12 recommended.
Database	PostgreSQL 17+ (production) or SQLite 3 (single‑node evaluation only).
TLS Certificate	A valid X.509 certificate for the API gateway. Self‑signed acceptable for initial setup.
NTP	Accurate time synchronisation mandatory. The platform refuses to start if the clock is wrong.
Network	Outbound access to payment rails (FedNow, SWIFT) as required. Inbound access on port 443 (gateway). Port 9000 (core) must be blocked from all external access.

2.3 Licence Key

A licence key must be obtained from Intellectica AI LLC before installation. The key is a long string beginning with VERITY- and contains a cryptographically‑signed payload. It is bound to the first server it is installed on. A single licence key covers both the core engine and the API gateway.

3. Installation

3.1 Obtain the Binaries

1. Navigate to the download portal: https://verity-core-banking.pages.dev/download.
2. Paste your licence key into the input field.
3. Select the binary from the dropdown:
   verity (Core Banking Engine) — download first.
   verity-gateway (API Gateway) — download second.
4. Click Download. The portal validates your licence against the Supabase Edge Function and returns a signed, time‑limited download URL.
5. Repeat for the second binary.
6. Save both files to your server (e.g. verity-0.1.0.bin and verity-gateway-0.1.0.bin).

3.2 Verify Integrity

SHA‑256 checksums are displayed on the download page after successful licence validation. Verify each binary before execution:

sha256sum verity-*.bin
# Compare the output with the checksums shown on the download page

3.3 Create a Dedicated System User

sudo useradd -r -s /bin/false -d /var/lib/verity verity
sudo mkdir -p /var/lib/verity/data
sudo chown -R verity:verity /var/lib/verity /etc/verity 2>/dev/null || true

3.4 Install the Binaries

sudo cp verity-*.bin /usr/local/bin/verity
sudo cp verity-gateway-*.bin /usr/local/bin/verity-gateway
sudo chmod 755 /usr/local/bin/verity /usr/local/bin/verity-gateway

3.5 Run the Installer

Run the built‑in licence validator on each binary. The validator performs offline Ed25519 signature verification, expiration check, and hardware‑fingerprint binding.

sudo verity install --license "VERITY-..."
sudo verity-gateway install --license "VERITY-..."

The installer performs the following steps automatically:

• Licence validation — cryptographically verifies the licence key signature against the vendor's public key (embedded in each binary).
• Hardware binding — captures a hardware fingerprint (CPU serial, motherboard UUID, disk serial, MAC address) and stores it in /etc/verity/machine_id.
• Environment detection — checks for TEE support (Intel TDX / AMD SEV‑SNP). If no TEE is found, the platform runs in simulation mode with a warning.
• Configuration generation — writes /etc/verity/config.toml (core) and /etc/verity/gateway.toml (gateway) with default settings.
• Ledger initialisation — creates the Merkle ledger directory at /var/lib/verity/data.

Expected output:

✅ Verity installed successfully.
   Organisation: First Interstate Bank
   Licence expires: 2027-06-01T00:00:00Z

Start the core engine with:   verity serve
Start the gateway with:       verity-gateway serve

If the licence check fails, the installer prints a specific error:

• Licence signature invalid — the key was tampered with or generated with a different vendor key.
• Licence expired — request a renewal from your account manager.
• Licence is bound to different hardware — the key was already activated on another machine. Request a new licence.

3.6 Create systemd Services

The recommended way to run Verity in production is via systemd. Create two unit files.

Core engine unit — /etc/systemd/system/verity.service:

sudo tee /etc/systemd/system/verity.service << 'EOF'
[Unit]
Description=Verity Core Banking Engine
After=network.target postgresql.service

[Service]
Type=simple
ExecStart=/usr/local/bin/verity serve
Restart=on-failure
RestartSec=5
User=verity
Group=verity
Environment="RUST_LOG=info"
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

Gateway unit — /etc/systemd/system/verity-gateway.service:

sudo tee /etc/systemd/system/verity-gateway.service << 'EOF'
[Unit]
Description=Verity API Gateway
After=verity.service

[Service]
Type=simple
ExecStart=/usr/local/bin/verity-gateway serve
Restart=on-failure
RestartSec=5
User=verity
Group=verity
Environment="RUST_LOG=info"
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable verity verity-gateway
sudo systemctl start verity verity-gateway

3.7 Verify the Installation

# Check service status for both
sudo systemctl status verity verity-gateway

# Check licence status
verity license status

# Check the gateway health endpoint
curl -k https://localhost/health

Expected licence status output:

Organisation: First Interstate Bank
Expiry:       2027-06-01T00:00:00Z
Hardware match: 100%
Signature:    ✅ valid

Expected health endpoint response:

{"status":"ok","version":"0.1.0","core":"connected"}

3.8 Smoke Tests

Verify the full pipeline by creating a test account and posting a transaction:

# Create a test account
curl -k -X POST https://localhost/api/accounts \
  -H "Content-Type: application/json" \
  -d '{"account_id":"test-001","currency":"USD"}'

# Post a balanced transaction
curl -k -X POST https://localhost/api/ledger/transaction \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id":"tx-001",
    "entries":[
      {"account_id":"test-001","amount":"100.00","type":"credit"},
      {"account_id":"test-002","amount":"-100.00","type":"debit"}
    ]
  }'

# Verify the conservation invariant (Σ = 0)
curl -k https://localhost/api/ledger/health
# Expected: {"conservation":"Σ=0.00","merkle_root":"def456...","entry_count":2}

4. Configuration

4.1 Core Engine Configuration (/etc/verity/config.toml)

The main configuration file for the core banking engine is generated by the installer and may be edited manually.

[platform]
org = "First Interstate Bank"

[ledger]
# Use "sqlite" for single-node, "postgres" for HA
storage = "sqlite"
path = "/var/lib/verity/data/ledger.db"

[api]
bind = "127.0.0.1:9000"    # NEVER expose this port publicly

[tee]
enabled = true
mode = "auto"               # "auto", "production", or "simulation"

[telemetry]
prometheus_port = 9090
log_level = "info"

[agents]
max_concurrent = 10

4.2 Gateway Configuration (/etc/verity/gateway.toml)

The gateway configuration file controls TLS termination, rate limiting, and proxy forwarding to the core engine.

[server]
bind = "0.0.0.0:443"
tls_cert = "/etc/verity/certs/fullchain.pem"
tls_key = "/etc/verity/certs/privkey.pem"

[proxy]
core_url = "http://127.0.0.1:9000"
timeout_seconds = 30

[rate_limit]
requests_per_second = 1000
burst = 2000

If you do not yet have a TLS certificate, you can start in plain‑HTTP mode for testing by setting bind = "0.0.0.0:8080" and commenting out the tls_* lines.

4.3 Key Configuration Options (Core)

Setting	Default	Description
ledger.path	/var/lib/verity/data/ledger.db	Path to the Merkle ledger event store. Must be on persistent, high‑performance storage.
ledger.storage	sqlite	sqlite for single‑node or postgres for high‑availability.
api.bind	127.0.0.1:9000	Internal bind address. Must remain localhost; the gateway is the only client.
tee.mode	auto	One of auto, production, simulation. In production mode the binary refuses to start without valid TEE attestation.
telemetry.prometheus_port	9090	Prometheus metrics endpoint (restrict to monitoring subnet).

4.4 Key Configuration Options (Gateway)

Setting	Default	Description
server.bind	0.0.0.0:443	Public HTTPS bind address.
server.tls_cert	(none)	Path to TLS certificate file. Required for production.
server.tls_key	(none)	Path to TLS private key file. Required for production.
proxy.core_url	http://127.0.0.1:9000	URL of the core engine (must be localhost).
rate_limit.requests_per_second	1000	Maximum sustained requests per second.

4.5 Environment Variables

Variable	Purpose	Default
DATABASE_URL	PostgreSQL connection string (when using storage = "postgres")	postgresql://verity:verity@localhost:5432/verity
VERITY_VENDOR_PUBKEY	Embedded at build time	(compiled in)

5. Operations

5.1 Daily Operations

# Start both services
sudo systemctl start verity verity-gateway

# Stop both services
sudo systemctl stop verity verity-gateway

# Restart both services (gateway restarts gracefully, core unaffected)
sudo systemctl restart verity-gateway
sudo systemctl restart verity

# View core engine logs
sudo journalctl -u verity -f

# View gateway logs
sudo journalctl -u verity-gateway -f

5.2 Licence Management

Both binaries share the same licence. Check status with either:

# Check licence status
verity license status

# Check version of each binary
verity version
verity-gateway version

5.3 Backup and Recovery

The Merkle ledger is an append‑only event store. Backups must include:

• The ledger directory (/var/lib/verity/data by default).
• The configuration files (/etc/verity/config.toml and /etc/verity/gateway.toml).
• The licence file (/etc/verity/license). This file is plain text and hardware‑bound; it cannot be used on different hardware.
• TLS certificate and key (/etc/verity/certs/).

Example daily cron job:

#!/bin/bash
tar -czf /backup/verity-$(date +%Y%m%d).tgz /etc/verity /var/lib/verity/data

Data	Frequency	Retention
Ledger	Continuous (PostgreSQL WAL archiving)	7 years (regulatory minimum)
Configuration	After every change	Indefinite
Licence file	After initial install	Indefinite

5.4 Monitoring

Verity emits OpenTelemetry traces, metrics, and structured logs. Point the OTLP exporter to your observability backend:

[observability]
otlp_endpoint = "http://otel-collector:4317"

Key metrics to monitor:

Metric	Description	Alert Threshold
ledger.append_latency_ms	P99 latency of ledger appends	> 50 ms
capability.validation_count	Capability token validations per second	Sudden drop may indicate attack
fraud.alerts_generated	Fraud alerts per hour	Spike warrants investigation
license.hardware_match	Hardware fingerprint match percentage	< 100% = possible tampering
gateway.requests_per_second	Inbound requests handled by the gateway	Approaching configured rate limit
gateway.core_latency_ms	Latency from gateway to core	> 10 ms on loopback

5.5 Log Levels

Level	Purpose
error	Licence validation failures, ledger corruption, TEE attestation failures, gateway-core disconnection
warn	VM/container detection, clock anomalies, circuit breaker trips, rate limit warnings
info	Normal operations: transaction commits, agent actions, payment processing, request routing
debug	Detailed tracing for support investigations
trace	Full execution traces (high volume, not recommended for production)

6. Troubleshooting

6.1 Common Issues

Symptom	Likely Cause	Resolution
"Licence signature invalid"	The licence key was generated with a different vendor key, or the key has been corrupted.	Obtain a new licence key from Intellectica AI LLC.
"Licence is bound to different hardware"	The binaries were moved to a different server, or the server underwent major hardware changes.	Request a licence re‑issue from Intellectica AI LLC.
"System clock appears to have been rolled back"	NTP is not running or the system clock is incorrect.	Enable NTP (sudo timedatectl set-ntp true). Ensure the clock is synchronised before restarting Verity.
"Virtualised/container environment detected"	The platform is running inside a VM or container without TEE support.	This is a warning only. The platform will start in simulation mode. For production, deploy on bare‑metal with TEE.
Gateway returns 502 Bad Gateway	Core engine is not running or not listening on 127.0.0.1:9000.	Check sudo systemctl status verity. Verify the core API bind address in /etc/verity/config.toml.
Gateway returns "Service Unavailable"	Core engine is starting up or experiencing high load.	Wait a few seconds; check core logs for errors.
Health endpoint unreachable	Gateway is not running, or firewall blocks port 443.	sudo systemctl status verity-gateway. Verify firewall allows inbound 443/tcp.
Ledger append latency is high	Storage I/O is saturated, or the database connection pool is exhausted.	Check disk I/O (iostat). Increase the database connection pool size in core config.

6.2 Diagnostic Commands

# Check both service statuses
sudo systemctl status verity verity-gateway

# View the last 100 log lines (core)
sudo journalctl -u verity -n 100 --no-pager

# View the last 100 log lines (gateway)
sudo journalctl -u verity-gateway -n 100 --no-pager

# Check licence validity
verity license status

# Test the gateway health endpoint
curl -k https://localhost/health

# Check disk space on the ledger volume
df -h /var/lib/verity/data

# Check NTP synchronisation
timedatectl show-timesync

6.3 Emergency Shutdown

In the event of a security incident, both services can be immediately halted:

sudo systemctl stop verity verity-gateway

For hardware‑grade termination, the platform supports a Non‑Maskable Interrupt (NMI) on TEE‑enabled hardware. This is triggered via the IPMI/BMC interface and is specific to your server hardware. Consult your server documentation for NMI invocation.

After an emergency shutdown, the ledger remains consistent because all writes are append‑only. No data corruption occurs from a hard stop.

7. Security

7.1 Licence Enforcement

The licence is cryptographically bound to the server's hardware fingerprint. The binaries will not start if:

• The licence file is missing or tampered with.
• The hardware fingerprint has changed (different CPU, motherboard, or disk).
• The system clock has been rolled back.
• The licence has expired.

7.2 Network Security Architecture

The core engine (verity) binds exclusively to 127.0.0.1:9000. It has no exposure to the public network. All external traffic is handled by the gateway (verity-gateway), which provides:

• TLS termination — certificates configured in /etc/verity/gateway.toml.
• Capability‑based access control — every request must carry a valid capability token; ambient authority is denied.
• Rate limiting — protects the core from excessive requests.
• Request routing — proxies valid requests to the core over the loopback interface.

7.3 TEE Attestation

In production mode, the core binary performs remote attestation on every startup. The TEE (Intel TDX or AMD SEV‑SNP) proves to the binary that it is running on genuine, untampered hardware. If attestation fails, the core refuses to start, and the gateway will report the core as unavailable.

7.4 Capability‑Based Security

All operations—including those initiated by human operators—are governed by capability tokens. No ambient authority exists. The four‑eyes principle is enforced at the virtual‑machine level for high‑value operations (wire transfers above $10,000, loan approvals, general‑ledger postings).

7.5 Audit Trail

Every transaction, agent action, and configuration change produces a cryptographically‑signed provenance record. These records are Merkle‑chained and may be anchored to a public transparency service (SCITT). Regulators can verify the integrity of the audit trail independently without access to the bank's systems.

8. Maintenance

8.1 Upgrading Verity

1. Download the new binaries from the download portal (same licence key).
2. Stop both services: sudo systemctl stop verity-gateway verity
3. Replace the core binary: sudo cp verity-<new-version>.bin /usr/local/bin/verity
4. Replace the gateway binary: sudo cp verity-gateway-<new-version>.bin /usr/local/bin/verity-gateway
5. Re‑validate the licence (on the new core binary): sudo verity install --license "$(cat /etc/verity/license)"
6. Re‑validate the licence (on the new gateway binary): sudo verity-gateway install --license "$(cat /etc/verity/license)"
7. Start both services: sudo systemctl start verity verity-gateway
8. Verify: verity version, verity-gateway version, and curl -k https://localhost/health

The licence file and ledger are compatible across versions. No data migration is required.

8.2 Licence Renewal

When a licence approaches expiry, contact Intellectica AI LLC for a renewal key. Apply the new key to both binaries:

sudo verity install --license "VERITY-<new-key>"
sudo verity-gateway install --license "VERITY-<new-key>"

This updates the licence file while preserving the existing ledger and configuration. No service restart is required; the new licence takes effect immediately.

8.3 Database Maintenance

For PostgreSQL deployments, standard maintenance practices apply:

• Regular VACUUM operations
• WAL archiving for point‑in‑time recovery
• Connection pool monitoring

Verity uses SQLx for database access. The connection pool size defaults to 10 and may be tuned in the core configuration file.

9. Network & Firewall Requirements

Source	Destination	Port	Protocol	Purpose
External clients (operator workstations, agents)	Verity gateway server	443	HTTPS	All API and dashboard access
Verity gateway server	Verity core server (same machine)	9000	HTTP (loopback)	Internal proxy to core engine
Verity core server	FedNow endpoint	443	HTTPS	Instant payment processing
Verity core server	SWIFT endpoint	443	HTTPS	Cross‑border payment processing
Verity core server	PostgreSQL server	5432	TCP	Ledger database (if not localhost)
Verity core server	NTP server	123	UDP	Time synchronisation
Verity core server	OTLP collector	4317	gRPC	Observability telemetry

Critical: Port 9000 (core engine) must never be exposed to any network except the local loopback interface. Use a host‑based firewall (e.g., iptables or nftables) to enforce this.

10. Support

For technical support, contact Intellectica AI LLC:
Email: support@verity.io
Emergency: [phone number provided with licence]

When reporting an issue, please include:

• Verity version from both binaries (verity version and verity-gateway version)
• Licence status (verity license status)
• The last 100 lines of the systemd journal for both services
• The server's hardware specifications and operating system version
• A description of the expected behaviour and the observed behaviour

# Install both binaries
sudo cp verity-*.bin /usr/local/bin/verity
sudo cp verity-gateway-*.bin /usr/local/bin/verity-gateway
sudo chmod 755 /usr/local/bin/verity /usr/local/bin/verity-gateway

# Activate licence
sudo verity install --license "VERITY-..."
sudo verity-gateway install --license "VERITY-..."

# Service management
sudo systemctl start verity verity-gateway
sudo systemctl stop verity verity-gateway
sudo systemctl restart verity-gateway
sudo systemctl status verity verity-gateway

# Logs
sudo journalctl -u verity -f
sudo journalctl -u verity-gateway -f

# Licence & version
verity license status
verity version
verity-gateway version

# Health check
curl -k https://localhost/health

# Smoke test
curl -k -X POST https://localhost/api/accounts -H "Content-Type: application/json" -d '{"account_id":"test","currency":"USD"}'
curl -k https://localhost/api/ledger/health

/etc/verity/
├── config.toml          # Core engine configuration
├── gateway.toml         # Gateway configuration
├── license              # Plain‑text licence key
├── machine_id           # Hardware fingerprint
└── certs/
    ├── fullchain.pem    # TLS certificate
    └── privkey.pem      # TLS private key

/var/lib/verity/data/
└── ledger.db            # SQLite event store (default; may be PostgreSQL)

/usr/local/bin/
├── verity               # Core banking engine (static binary)
└── verity-gateway       # API gateway (static binary)