zeekayandHanzo Dev
3925b347f1
Fixes the fail-safe liveness edge the Byzantine suite found: a self-cross-heavy stream could wedge one later submit at BuildBlock with "resting order missing full settlement identity (orderuser)" / "insufficient locked balance" (seed 42, ~step 153; same class as seed-4242). Root cause: pkg/lx/orderbook.go tryMatchImmediateLocked's self-trade skip removed the self-crossed maker from the IN-MEMORY book (removeOrder + delete Orders + ordersMap.Delete) without a matching consensus state write. The in-memory book feeds the execution root via BookToRows(ob), but the durable order:/orderuser:/ reserve rows were left untouched — so the two diverged, and a later cross tripped the settle-time invariants. Fix (one and one way — route through the existing cancel-persist path): - pkg/lx/orderbook.go: the matcher RECORDS each self-cancelled maker id (ob.selfCanceled, reset per match) and exposes DrainSelfCanceled(). No fill is produced; self-trade prevention is unchanged. - pkg/dchain/execute.go: applySubmit drains the self-cancelled ids into applyResult.SelfCanceled. - pkg/dchain/block.go: extract releaseOrderReserve() — the single canonical cancel-persist primitive (release reserve locked->available, delete reserve + orderuser: rows, fail-closed on missing identity). TxCancel now calls it; a submit's self-cancelled makers call it too, and execute deletes their order: rows in lockstep. In-memory and durable state now move together within the block. Properties preserved: - Determinism: the self-cross block's execRoot is UNCHANGED (BookToRows already excluded the maker); every validator drops the same maker + releases the same reserve. No fork. - Conservation-exact: the released reserve moves locked->available; sum unchanged, no mint/burn. - Self-trade prevention: self-crosses still never trade (zero fills). - Anti-theft: owner resolved exclusively via the orderuser: index, fail-closed. TDD (CGO_ENABLED=0 GOWORK=off GOFLAGS=-mod=mod): - TestByzantineConservation_AdversarialMatcherStream: 1280 ops, 10 -> 0 fail-safe refusals (now asserts zero as a regression guard); I=A+L + no-fork every op. - TestByzantineMatcher_SelfCrossCancelsRestingMakerConsistently: new pin — the partial-fill -> self-cross -> external-cross wedge shape now cancels the maker (8 locked base -> available), later crosses run clean, collateral withdrawable. - Full pkg/lx, pkg/dchain, pkg/consensus suites green; chains/dexvm unaffected. Co-authored-by: Hanzo Dev <[email protected]>
LX
Lux DEX — pure-Go matching engine, order book, oracle aggregator, and JSON-RPC / WebSocket / gRPC SDKs.
Open core
This repository is the public, pure-Go reference implementation of the Lux DEX matching engine. It is fully functional, runs standalone, and underpins every Lux DEX deployment.
For commercial deployments that need hardware acceleration (NUMA-aware
C++ order book, CUDA / Metal batched verification, FPGA fast paths)
the same Go interfaces are implemented by lux-private/dex and
selected at build time via the dex_gpu build tag. The accelerated
backend fails closed unless the operator's environment carries a Lux
commercial license token whose scope list includes dex. Contact
[email protected] for commercial licensing.
Features
- High performance (measured, Apple M1 Max): 11.88M orders/sec (C++ engine, 10 threads), 2.2M orders/sec (pure Go)
- Low latency: 169 ns avg match (p50 125 ns, p99 292 ns) on the C++ engine; 381 ns/order in pure Go
- Multi-engine architecture: pure Go and NUMA-aware C++ — order matching runs on CPU
- Quantum-resistant consensus: DAG with post-quantum signatures
- Cross-platform: Linux, macOS (Intel & Apple Silicon), Windows
- Professional Market Data: Real-time oracle integration with multiple sources
- Cross-Chain Support: Universal bridge for all major blockchains
- 100% Test Coverage: All critical paths tested and verified
Quick Start
# Install dependencies
go mod download
# Build all binaries
make build
# Run tests
make test
# Run demo
./bin/demo
# Run benchmarks
make bench
Installation
From Source
git clone https://github.com/luxfi/dex
cd dex
make build
From Release
# Download latest release for your platform
curl -L https://github.com/luxfi/dex/releases/latest/download/lx-dex-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) -o lx-dex
chmod +x lx-dex
./lx-dex
Performance
Measured first-hand on Apple M1 Max. Order matching runs on CPU — see "Why matching stays on CPU" below.
| Engine | Avg match | p50 / p99 | Throughput |
|---|---|---|---|
| C++ (10 threads) | — | — | 11.88M orders/sec |
| C++ (single thread) | 169 ns | 125 ns / 292 ns | 5.91M orders/sec |
Pure Go (pkg/lx) |
381 ns | — | 2.2M orders/sec |
C++ order cancel: 49 ns. Pure-Go matching does 1–2 allocs/op (not zero-alloc).
Why matching stays on CPU
GPU order matching exists only as a CUDA path on Linux (commercial
lux-private/dex); there is no Apple/Metal matching path. A single match is
~169 ns — smaller than the dispatch overhead of handing a batch to an
integrated GPU — so the CPU wins for matching. The GPU pays off in the FHE
layer instead: the Metal NTT kernel is 23× faster than the CPU NTT at
N=4096, batch=128, where batched polynomial decomposition dominates.
Architecture
On-chain settlement follows D matches · C settles: the D-Chain (dexvm)
matches and BLS-signs a DFillReceipt; the C-Chain receipt-settlement precompile
0x9999 (Uniswap-V4 PoolManager ABI) verifies the certificate inline and settles
under Block-STM. See docs/ARCHITECTURE.md
and the normative spec LP-9999.
The DEX uses a multi-engine architecture; order matching runs on CPU:
- Pure Go engine (
pkg/lx): portable reference, 2.2M orders/sec, 381 ns/order - C++ engine: 11.88M orders/sec (10 threads), 5.91M single-thread, 169 ns avg match
FIX Protocol Performance (December 2024)
| Engine | NewOrderSingle | ExecutionReport | MarketDataSnapshot |
|---|---|---|---|
| Pure Go | 163K/sec | 124K/sec | 332K/sec |
| Hybrid Go/C++ | 167K/sec | 378K/sec | 616K/sec |
| Pure C++ | 444K/sec | 804K/sec | 1.08M/sec |
| Rust | 484K/sec | 232K/sec | 586K/sec |
See docs/ for detailed documentation.
Development
Requirements
- Go 1.21+
- macOS or Linux
- Optional: Apple Silicon Mac for Metal-accelerated FHE (NTT)
- Optional: NVIDIA GPU for CUDA acceleration
Building with GPU Support
# Apple Silicon (Metal)
CGO_ENABLED=1 make build
# Linux with CUDA
CGO_ENABLED=1 CUDA=1 make build
Running Tests
# Unit tests
make test
# Benchmarks
make bench
# All tests including integration
go test ./...
CI/CD
The project uses GitHub Actions for CI/CD:
- CI: Runs on every push and PR
- Release: Triggered by version tags (v*)
- Platforms: Ubuntu, macOS
- Go versions: 1.21, 1.22
See .github/workflows/ for workflow definitions.
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing) - Open a Pull Request
License
Copyright (C) 2020-2025, Lux Industries Inc.