zeekayandHanzo Dev
8cc08f3b69
Three things claimed to be this repo's trading API and no two agreed. pkg/trading carried its own Venue interface, its own V4/native/V2/V3 and broker venues, its own constant-product math and its own eth_call client — a copy of what pkg/gateway already had — and nothing mounted it: grep for the import outside that directory returns empty. api/openapi.yaml documented it anyway, so the one published contract in the repo described the one package no binary served. Meanwhile the binary answered at /v1/* and again at /trading/* in Uniswap's shapes: two contracts for one API, reachable by both names, free to drift. Deleted, both of them, rather than picked between and left beside. Everything answers under /v1/trade now. api.lux.cloud carries the chain at /v1/chain, the C-chain at the root and other services besides, so /v1/quote was a generic name claimed on a shared host; one prefix is one namespace with one owner, and the edge rule that publishes it collapses from a nine-clause allowlist to a prefix. Server.routes() is the surface written once, and TestTheDocumentIsTheSurface reads api/openapi.yaml and holds the two to each other in both directions. /v1/trade/venues is new. It is the question a screen asks before it asks anything else — which chains this deployment can price, and from what — grouped by chain, because a venue is a contract on a chain and the same name means a different pool on each. Without it a client learns a chain is unquotable by quoting on it and reading an error. The allowance is read rather than assumed. approval/check and permit2/check answered allowance 0 and needsApproval on every request, under a comment saying the gateway had no way to reach a chain; it has one per chain, one field away — the same endpoint the pool is quoted from. Measured against 96369: LUSD to the position manager reads 6000000000000000000000000, which is what eth_call returns for that pair, and the approve tx now rides along only when it is needed. Handed back beside "you already approved" it is a transaction somebody sends, and the user pays gas for a state change that changes nothing before every swap. Permit2 reads the expiration too, because a grant that has run out is not a grant. Nothing here invents a number any more. /v1/history/prices and /v1/history/tvl returned a random walk seeded from hardcoded base prices — LUX at 2.47, WBTC at 96420, 12.5M of TVL on a chain whose pools were seeded hours ago — and both were routed to the public internet, where a chart drawn from them is indistinguishable from a chart of the market. History belongs to the indexer, which reads the chain. /v1/tokens/search answered 501 on a TODO, a route lying about the surface in the other direction. Gone, with a test that keeps them gone. 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++ (CPU default build), plus a GPU-native per-book matcher (CGO_ENABLED=1, unified
lux-gpubackend, parity-verified GPU==CPU) — see "GPU matching" - 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. The default (CGO-off) build matches on CPU; a GPU-native per-book matcher also exists — see "GPU matching" 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).
GPU matching
The live default (CGO-off) build matches on CPU (11.88M ord/s C++, 169
ns/match): a single hot-book match is smaller than the dispatch overhead of
handing one book to an integrated GPU, so the CPU wins for the single-book hot
path. A GPU-native deterministic per-book matcher — byte-identical to the CPU
oracle (MatchOrderCPU) and parity-verified (pkg/lxgpu/orderbook_parity_test.go,
three_mode_parity_test.go) — is available with CGO_ENABLED=1 via the unified
lux-gpu backend (runtime-select CUDA/HIP/Metal), where it wins at planet scale
by running one thread per book across millions of books. Kernels ship prebuilt
from luxcpp/dex. Measured throughput (deterministic per-book, GPU==CPU parity):
| Device | Orders/sec |
|---|---|
| AMD Radeon 8060S | 12.76B |
| NVIDIA GB10 | 9.13B |
| Apple M4 Max | 5.60B |
| Apple M1 Max | 2.80B |
| Two-node fabric | 21.9B |
The GPU also drives the FHE layer: the Metal NTT kernel is 23.6× 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 — stale, not re-verified this session)
These are FIX wire encode/decode message rates (a separate axis from order matching) and have not been re-measured; treat as historical, not current.
| 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 — the lux-gpu backend runtime-selects CUDA; no CUDA make var
CGO_ENABLED=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.