Documentation

Blazil

Open-core financial and AI infrastructure built in Rust for the throughput requirements of modern payment systems and inference workloads.

Blazil is infrastructure — not a payment gateway, not a SaaS dashboard. It is the ledger and settlement engine that financial systems are built on top of.

Quick Start

Clone the repo and run one script — the cluster starts itself.

bash

git clone https://github.com/Kolerr-Lab/BLAZIL
cd BLAZIL
./scripts/demo.sh

Starts a single-node cluster with all services on localhost.

Prerequisites

bash

# Prerequisites: Docker, Rust 1.88+, Go 1.25+
./scripts/setup.sh
docker compose -f infra/docker/docker-compose.dev.yml up -d
cargo build --workspace
cd services && go build ./...

Single Node Configuration

The demo script starts all services on localhost with no external dependencies.

3-Node Production Cluster

bash

# On node-1:
BLAZIL_NODE_ID=node-1 ./scripts/do-start.sh 10.0.0.1 10.0.0.2 10.0.0.3
# On node-2:
BLAZIL_NODE_ID=node-2 ./scripts/do-start.sh 10.0.0.1 10.0.0.2 10.0.0.3
# On node-3:
BLAZIL_NODE_ID=node-3 ./scripts/do-start.sh 10.0.0.1 10.0.0.2 10.0.0.3

Grafana → http://<node-1-ip>:3001 (admin / blazil)

Environment Variables

BLAZIL_NODE_ID: Node identifier (node-1, node-2, node-3)
BLAZIL_CLUSTER_IPS: Comma-separated list of cluster node IPs
BLAZIL_GRPC_PORT: gRPC service port (default: 50051)
BLAZIL_METRICS_PORT: Prometheus metrics port (default: 9090)

Zero-Copy Stack

Each layer removes a specific bottleneck.

1
TRANSPORT
Aeron IPC (local, 1.2M TPS peak) / TCP for cluster — 37.5× faster than TCP baseline
2
RING BUFFER
Rust LMAX Disruptor — 262K capacity/shard, P99 42ns (single shard, in-memory)
3
PIPELINE
2 shards/node, 131K in-flight window per shard — near-linear horizontal scaling
4
CONSENSUS
TigerBeetle 0.16.78 VSR — 3-node cluster, quorum 2/3, survives 1-node failure
5
STORAGE
O_DIRECT + fsync (TigerBeetle) — primary bottleneck on DO NVMe (100–127 MB/s fio randwrite)

How a Transaction Flows

1
Client sends events via Aeron IPC transport (local) or TCP (cluster)
2
Engine enqueues onto the LMAX Disruptor ring buffer (lock-free, single producer per shard)
3
Two shards per node process in parallel — 131K in-flight window per shard, 262K total per node
4
Each shard accumulates batches and commits to its local TigerBeetle instance
5
TigerBeetle VSR consensus (quorum 2/3) commits with O_DIRECT + fsync — primary latency source on cloud NVMe (~1–2s on DO)
6
Aggregate throughput across 3 nodes: 436,351 TPS (sharded) · 130,998 TPS (VSR 3-replica)

Performance factors

Multi-Shard Pipeline

2 shards/node with 131K in-flight window each — 97.7% efficiency at 2 shards, near-linear horizontal scaling.

Aeron IPC Transport

1.2M TPS local peak. 37.5× faster than TCP. Zero-copy in-process messaging eliminates kernel overhead.

Lock-free Ring Buffer

LMAX Disruptor with 262K capacity/shard. P99 42ns single shard in-memory. Single-producer, eliminates contention.

Architecture vs. Infrastructure

Bottleneck on DO is disk I/O (100–127 MB/s NVMe). On bare-metal Gen4 NVMe: estimated 5–10M TPS sharded, 1–2M VSR.

v0.2 DO Cluster Results

Infrastructure: 3× DigitalOcean s-4vcpu-8gb-amd · Ubuntu 24.04 LTS · TigerBeetle 0.16.78 · SGP1 · $252/month · April 13, 2026

Option B — Sharded (Max Throughput)

436,351 TPS

3 independent nodes · 3,000,000 events · 0% error rate

node-1130,118 TPS · p99 3,007ms

node-2146,028 TPS · p99 2,542ms

node-3160,205 TPS · p99 2,333ms

18× Visa peak (24K) · 436× Mojaloop (1K). No fault tolerance — independent TB instances.

Raw report

Option A — VSR Consensus (Fault-Tolerant)

130,998 TPS

1 cluster · 3 replicas · 1,000,000 events · 0% error rate

P501,774ms

P952,559ms

P992,747ms

P99.92,827ms

5.5× Visa peak · 131× Mojaloop. Quorum 2/3 — survives 1-node failure. 3.33× lower than sharded.

Raw report

Bottleneck: disk I/O, not architecture. DO NVMe throttles at 100–127 MB/s (fio 4k randwrite). Latency dominated by TigerBeetle O_DIRECT + fsync (1–2s). On bare-metal NVMe Gen4: estimated 5–10M TPS (sharded) and 1–2M TPS (VSR) with <100ms latency.

Running Benchmarks Locally

bash

# v0.2 local micro-benchmarks (MacBook Air M4)
cargo run -p blazil-bench --release

# Aeron IPC E2E (requires Aeron feature flag)
cargo run -p blazil-bench --release --features aeron

Runs the in-memory pipeline benchmark. Single shard: ~20M TPS P99 42ns. 4 shards: ~61M TPS.

Cluster Stress Test

bash

# Provision nodes with Ansible
ansible-playbook -i inventory.ini playbooks/provision.yml

# Run sharded benchmark (Option B)
ansible-playbook -i inventory.ini playbooks/run-bench.yml \
  -e 'scenario=sharded-tb shards=2 events=1000000'

# Run VSR consensus benchmark (Option A)
ansible-playbook -i inventory.ini playbooks/run-bench.yml \
  -e 'scenario=vsr-consensus events=1000000'

# Raw report links (April 13, 2026):
# Option B: docs/runs/2026-04-13_option-b-sharded-aggregate.md
# Option A: docs/runs/2026-04-13_option-a-vsr-consensus-summary.md

Reproduces the April 13 2026 v0.2 DO cluster results. Requires 3 provisioned nodes.

AI Infrastructure Overview

Blazil reuses its transport, observability, and operational model for AI workloads: Tract ONNX inference, io_uring data loading, and a distributed Qwen2.5-7B pipeline.

Pure Rust inference

Tract ONNX + io_uring dataloader remove Python and GPU assumptions from the serving path.

Shared transport layer

The same zero-copy discipline used for 233,894 TPS fintech traffic is reused for AI sample movement and orchestration.

Operator-ready stack

Observability, mTLS, policy, and signed artifacts are shared across fintech and AI instead of maintained as two platforms.

Verified distributed LLM path

Qwen2.5-7B-Instruct has already run through a 3-stage Aeron IPC pipeline with multi-token generation verified on Apple M4 CPU.

Dataset Coverage

Dataset	Use Cases	Format	Status
Text / NLP	Sentiment, embeddings, semantic search	CSV, directory	7 tests
Time Series	Forecasting, stock prediction, sensors	CSV with windowing	4 tests
Features	Fraud, anomaly, intrusion detection	CSV + normalization	6 tests
Audio	Voice commands, speaker ID, event detection	WAV	2 tests
Object Detection	Document verification, KYC, product detection	YOLO	2 tests

Text / NLP

Sentiment, embeddings, semantic search

CSV, directory

7 tests

Time Series

Forecasting, stock prediction, sensors

CSV with windowing

4 tests

Features

Fraud, anomaly, intrusion detection

CSV + normalization

6 tests

Audio

Voice commands, speaker ID, event detection

WAV

2 tests

Object Detection

Document verification, KYC, product detection

YOLO

2 tests

Distributed LLM Pipeline

Qwen2.5-7B-Instruct has already been verified on a 3-stage distributed pipeline with token feedback, KV cache continuity, and correct position propagation across decode steps.

Stage 1

Layers 0-10

Prefill orchestration, request state tracking, Aeron media driver

Stage 2

Layers 10-20

Middle layer compute and activation forwarding

Stage 3

Layers 20-28 + LM head

Sampling, token feedback, final decode output

Verified result: 32 tokens in 19.7s on Apple M4 CPU. Recent fixes covered KV cache lifecycle, Language Drift, decode orchestration, and termination logic.

Security & Hardening

Cross-shard 2PC

TigerBeetle pending, post, and void flows provide atomic reserve, commit, and abort semantics across shards.

mTLS automation

Kubernetes ingress and cert-manager handle certificate issuance and rotation across services.

Identity and policy

Vault, Keycloak, and OPA cover secrets, authentication, and policy enforcement.

Supply chain

Syft SBOM generation and Cosign keyless signing add provenance to container builds in CI.

Runbooks & ADRs

The platform has moved beyond benchmark claims into operator-facing documentation: runbooks, ADRs, and recovery guides.

ADR 0004

Auth strategy: JWT + mTLS

Open on GitHub

ADR 0005

Transport selection across gRPC, TCP + MessagePack, and Aeron

Open on GitHub

ADR 0006

Sharding design and cross-shard 2PC

Open on GitHub

Runbooks

Blue-green deployment, scaling, backup, corruption response, alerts, upgrades

Open on GitHub

Stack Reference

The complete Blazil-Beetle stack.

Layer	Technology	Purpose
Engine	Rust + LMAX Disruptor	Lock-free ring buffer · 262K capacity/shard · 42ns P99
Services	Go + gRPC bidirectional streaming	Persistent ingress · 256 in-flight window · zero RTT
Pipeline	2 shards/node · 131K in-flight	131K in-flight window per shard · near-linear scale
Transport	Aeron IPC · TCP + MessagePack · io_uring	1.2M TPS local · 37.5× TCP baseline · zero-copy hot path
Ledger	TigerBeetle 0.16.78	VSR consensus, O_DIRECT + fsync disk writes
2PC	pending / post / void	Atomic cross-shard reserve, commit, and abort flow
Priority	Multi-stream Aeron	Critical <1ms · High <5ms · Normal <50ms
AI / ML	Tract ONNX + 5 datasets + Qwen2.5-7B	Pure Rust inference · distributed LLM pipeline
Security	Vault + Keycloak + OPA + cert-manager	Secrets, auth, policy, and mTLS auto-rotation
Supply Chain	Syft SBOM + Cosign	Container provenance and CI-attested signing
Observability	Prometheus + Grafana + OTel	Real-time metrics, dashboards, distributed tracing

Engine

Rust + LMAX Disruptor

Lock-free ring buffer · 262K capacity/shard · 42ns P99

Services

Go + gRPC bidirectional streaming

Persistent ingress · 256 in-flight window · zero RTT

Pipeline

2 shards/node · 131K in-flight

131K in-flight window per shard · near-linear scale

Transport

Aeron IPC · TCP + MessagePack · io_uring

1.2M TPS local · 37.5× TCP baseline · zero-copy hot path

Ledger

TigerBeetle 0.16.78

VSR consensus, O_DIRECT + fsync disk writes

2PC

pending / post / void

Atomic cross-shard reserve, commit, and abort flow

Priority

Multi-stream Aeron

Critical <1ms · High <5ms · Normal <50ms

AI / ML

Tract ONNX + 5 datasets + Qwen2.5-7B

Pure Rust inference · distributed LLM pipeline

Security

Vault + Keycloak + OPA + cert-manager

Secrets, auth, policy, and mTLS auto-rotation

Supply Chain

Syft SBOM + Cosign

Container provenance and CI-attested signing

Observability

Prometheus + Grafana + OTel

Real-time metrics, dashboards, distributed tracing