Quickstart

Lorenz Protocol is a reference architecture and engineering framework, published to demonstrate how a serious Solana arbitrage stack is designed and built. It is deliberately not a turnkey money machine, and we are honest about why.

What actually works today (verifiable)

These are implemented and covered by tests (cargo test):

• lorenz-amm: constant-product AMM math in integer arithmetic, with property tests for the invariants any correct AMM must satisfy.
• lorenz-graph: arbitrage detection as negative-cycle Bellman-Ford over a token graph, with cycle reconstruction.
• lorenz-dex: pool model + quoting + real account decoders. SPL token accounts and the Raydium AMM v4 / CP-Swap pool layouts are decoded with real on-chain offsets (fixture-tested); concentrated-liquidity venues are honestly left unimplemented because their math is not constant-product.
• lorenz-stream: transport-agnostic pool-update streaming. A deterministic ReplaySource drives the detector end-to-end; the Geyser/Yellowstone transport is a typed, documented production seam.
• lorenz-backtest: a deterministic replay/backtester with a full cost model (flash-loan fee, priority fee, Jito tip, slippage). Runnable on a bundled sample market: cargo run -p lorenz-backtest.
• lorenz-agent: control-plane primitives plus an LLM orchestrator: the model may only return one action from a closed set, and every value is clamped against hard ceilings before it is applied (a hallucination cannot widen a cap or raise a fee). Includes a rule-based risk manager with a kill-switch, an append-only decision ledger, and a deterministic parameter tuner.
• lorenz-core: shared domain types, strict typed config, observability.
• programs/executor: the on-chain guard/fee/accounting logic (Anchor), with pure unit-tested arithmetic and a documented Kamino flash-loan seam.

Quick start

# Off-chain workspace (no Solana toolchain needed)
cargo test --workspace
cargo run -p lorenz-backtest

# On-chain program (requires anchor-cli + cargo build-sbf)
anchor build

Production requirements (what a live deployment additionally needs)

These are explicitly not done in this reference framework. They are labelled as such in code and docs, never faked, and together they constitute the scope of a production build:

• Decoders for concentrated-liquidity venues (Whirlpool, Raydium CLMM, Meteora DLMM), which need a tick/sqrt-price pricing model rather than constant-product.
• The flash-loan borrow/repay CPI and multi-DEX swap route in the on-chain program (mod flash_loan, mod route return NotImplemented).
• The live Geyser/Yellowstone transport behind lorenz-stream's documented seam, and the tx submission path, on co-located low-latency infrastructure.
• An external audit of the on-chain program before any use with real capital.
• The LLM-backed agent on top of the control-plane primitives.
• Multi-tenant onboarding and the non-custodial vault UX.

See the phased plan in the Architecture overview and Roadmap & Seams.

Two reasonable ways to use it

• (A) Self-serve, at your own risk. Fork it, implement the roadmap pieces for your own infrastructure, and operate it yourself. MIT-licensed; you own the outcome.
• (B) Custom build. If you want a production-grade, low-latency deployment, this architecture is the starting point and the production requirements above are the scope of work. Open an issue to discuss a custom implementation.

Repository layout

crates/
  lorenz-core/       domain types, typed config, telemetry
  lorenz-amm/        AMM math (tested, property-based)
  lorenz-graph/      negative-cycle arbitrage detection
  lorenz-dex/        pool model, quoting, real account decoders
  lorenz-stream/     transport-agnostic streaming -> detector (+ Geyser seam)
  lorenz-backtest/   deterministic replay + cost model (+ runnable bin)
  lorenz-agent/      risk manager, kill-switch, ledger, tuner, LLM orchestrator
programs/
  executor/        on-chain atomic executor (Anchor), invariants enforced
docs/
  ARCHITECTURE.md  system design and data/control plane split
  INVARIANTS.md    the guarantees and where each is enforced
  adr/             architecture decision records
  SECURITY.md      threat model and disclosure

License

MIT. See LICENSE.