Architecture Reference
A thorough, code-grounded description of the Lorenz system as it exists today. One chapter per crate, the on-chain program, end-to-end flows, safety invariants, and the roadmap seams.
A thorough, code-grounded description of the Lorenz system as it exists today. Every statement here is meant to be checkable against the source; where a piece is unfinished it is labelled roadmap / seam, never described as working.
Lorenz Protocol is an experimental, unaudited reference architecture for atomic, flash-loan-funded arbitrage on Solana. It does not trade live yet and makes no profitability claims. See the Disclaimer.
How this set relates to the other docs
The root Architecture overview, Invariants, and Security pages are the high-level documents. This architecture reference is the deep reference that expands them:
| Doc | Relationship |
|---|---|
| Architecture overview | Executive summary of the two-plane split. Expanded by chapters 01, 04, 05, 08. |
| Invariants | Canonical list of guarantees. Cross-referenced and explained in chapter 09. |
| Security | Threat model + disclosure. Cross-referenced in chapters 06 and 09. |
Reading guide
Start at 01 for the mental model, then read by interest:
| # | Chapter | What it covers |
|---|---|---|
| 01 | System Overview | What Lorenz is, the data/control plane model, design principles, status legend |
| 02 | Crate Topology | Workspace layout, dependency graph, why the on-chain program is excluded |
| 03 | Core Domain Model | lorenz-core: newtypes, typed config, errors, telemetry records |
| 04 | Data Plane | lorenz-amm, lorenz-graph, lorenz-dex, lorenz-stream: detect → size pipeline |
| 05 | Control Plane | lorenz-agent: risk manager, tuner, ledger, LLM boundary, orchestrator |
| 06 | On-chain Program | programs/executor: instructions, accounts, the five on-chain invariants |
| 07 | Backtester | lorenz-backtest: cost model, replay loop, the runnable binary |
| 08 | End-to-End Flows | Sequence diagrams for detection, backtest, and a (roadmap) live trade |
| 09 | Safety & Invariants | Where each guarantee is enforced and how it is verified |
| 10 | Roadmap & Seams | Every NotImplemented boundary and what a production build adds |
| 11 | Glossary | Terms: notional, CPMM/CLMM, Geyser, flash loan, Jito tip, … |
The system in one paragraph
A deterministic data plane ingests pool state, models the market as a token graph, detects profitable cycles (negative-cycle Bellman-Ford), and prices them with exact integer AMM math. An off-hot-path control plane consumes telemetry and may only tighten limits; an LLM, if present, can return only one action from a closed, clamped set. The final backstop is a custom on-chain program that refuses to settle any trade that loses money or exceeds its spend cap. Safety is a property of the runtime and the type system, not a promise in a README.
Status legend
Used consistently across all chapters:
- ✅ Implemented + tested: real code with unit/property tests.
- 🟡 Seam: a typed, documented integration point that compiles and returns
an explicit
NotImplemented, so the surrounding logic is reviewable. - 🔭 Roadmap: described and scoped, not present in code yet.
Conventions
- File paths are relative to the repository root (
lorenz/). - Symbols are written as
module::Typeand map to the crate of the same prefix (risk::RuleBasedRiskManagerlives incrates/lorenz-agent/src/risk.rs). - "Base units" always means the integer smallest unit of a token (lamports for SOL). No floating-point value ever settles.
Quickstart
What actually works today in Lorenz, how to run the off-chain workspace and backtester, the production requirements, and the repository layout.
Architecture Overview
The executive summary of the Lorenz two-plane split. Data plane vs control plane, the data flow, where each crate fits, and the economics-first build phasing.