RSX v0

Origin Story

RSX started with a simple question: what if you wrote all the specs before any code?

Key insight: The spec-first approach meant we discovered protocol mismatches at spec review time, not integration time. The CRITIQUE.md identified 36 design gaps. All 36 were resolved before writing code.

Architecture Overview

Six process types. Nine Rust crates. One wire format.

                    Internet
                       |
                   [WebSocket]
                       |
                  +----------+
                  | Gateway  |  auth, rate limit, validation
                  +----+-----+
                       |
                  [CMP/UDP]
                       |
                  +----------+
                  |   Risk   |  margin, positions, liquidation
                  |  (shard) |  per user_id hash
                  +----+-----+
                       |
                  [CMP/UDP]
                       |
          +------------+------------+
          |            |            |
     +----+----+  +----+----+  +---+-----+
     | ME: BTC |  | ME: ETH |  | ME: ... |
     +---------+  +---------+  +---------+

The Crates

rsx-types — Price, Qty, Side, SymbolConfig. Fixed-point i64 newtypes. Zero-cost abstractions. #[repr(transparent)] wrappers.

rsx-book — Orderbook with slab allocator. CompressionMap turns 20M price levels into 617K slots. #[repr(C, align(64))] cache-line alignment. PriceLevel linked lists with OrderSlot indices.

rsx-matching — Single-threaded matching engine. FIFO price-time priority. GTC, IOC, FOK, post-only, reduce-only. DedupTracker for idempotent replay. CPU-pinned via core_affinity.

rsx-risk — Portfolio margin. Position tracking. Liquidation triggers. Funding payments. Per-user shard, hash-based routing.

rsx-dxs — WAL writer/reader. CMP protocol (Aeron-inspired, UDP with NACK/heartbeat). DXS replay service. Fixed-record format: 16B header + #[repr(C, align(64))] payload. CRC32 validation. 10ms flush guarantee. No Kafka, no NATS.

rsx-gateway — WebSocket ingress. JWT auth. Rate limiting. Circuit breaker. CMP bridge to risk. monoio (io_uring) for async I/O.

rsx-marketdata — Shadow book for public consumption. L2/BBO/trades WebSocket. monoio runtime.

rsx-mark — Mark price aggregator from external feeds. Separate process, CMP to risk.

rsx-recorder — Archival DXS consumer. tokio-based. Postgres sink (tokio-postgres).

Communication

CMP/UDP — hot path, <10μs latency. Aeron-inspired protocol with gap detection, NACK, heartbeat. Flow control via control messages. C structs over UDP.

WAL/TCP — cold path, replay, archival. Fixed records over TCP. Optional TLS. Disk format = wire format = memory (zero transformation).

SPSC Rings (rtrb) — intra-process tile communication, 50-170ns per hop. Busy-spin on dedicated cores.

monoio — io_uring-based async runtime for Gateway and MarketData tiles. Batches kernel submissions vs epoll.

tokio — async runtime for cold path (recorder, DXS replay, Postgres). Not on hot path.

Design Principles

Zero Heap on Hot Path — Slab allocators for orders. CompressionMap for price levels. Pre-allocated event buffers. No malloc during matching. The matching engine sees 100-500ns per order.

Fixed-Point Everywhere — All values are i64 in smallest units. No floats, anywhere. Deterministic across architectures. Type-safe newtypes prevent mixing Price and Qty at compile time.

One Wire Format — WAL bytes = disk bytes = wire bytes = memory bytes. No serialization layer. No protobuf. No FlatBuffers. Just #[repr(C, align(64))] and CRC32.

Backpressure, Not Drops — When a buffer fills, the producer stalls. Never drop data silently. A delayed fill is acceptable. A lost fill means incorrect positions.

Asymmetric Durability — Fills: 0ms loss (fsync before send). Orders: ephemeral (user retries on crash). Positions: derived (replay fills to rebuild).

Current Progress

v0 / Spec Phase — RSX is a design study, not a production system. The architecture is validated through specs and unit tests. No E2E integration. No load testing. No security audit. This is research-grade code exploring exchange architecture patterns.

What Works (in isolation)

• Full order lifecycle: submit, match, fill, position update
• GTC, IOC, FOK, post-only, reduce-only orders
• Cross-margin with liquidation triggers
• Mark price aggregation from external feeds
• WAL-based crash recovery
• Playground dev dashboard with process control
• Trading UI (Bybit-style)

Technical Details from Codebase

Data Structures:

• Fixed-point i64: Price(i64) ticks, Qty(i64) lots — no floats anywhere
• Slab allocator: pre-allocated OrderSlot arena, bump allocator with freelist
• CompressionMap: zone-based price compression (5 zones, varying ticks-per-slot: 1, 10, 100, 1000, 1)
• PriceLevel linked lists with OrderSlot slab indices — no heap on hot path
• #[repr(C, align(64))] on hot-path structs for cache-line alignment

Benchmarks (Criterion):

• rsx-types: type conversions
• rsx-book: slab alloc/free, compression, insert/cancel operations
• rsx-matching: dedup, matching latency
• rsx-dxs: WAL persistence, encoding, CMP protocol
• rsx-gateway, rsx-risk, rsx-marketdata, rsx-mark: component-level benchmarks

Testing:

• 895+ Rust unit tests
• testcontainers (Postgres integration)
• Playwright E2E suite in rsx-playground
• make wal WAL correctness tests (<10s)
• Property tests (proptest for order sequences, future)

What's Next

1. Full E2E smoke test — The complete pipeline: WS client → Gateway → Risk → ME → back. Individual components tested. Now the full loop.

2. Stress testing — Target: 1M fills/sec sustained. Criterion benchmarks exist. Sustained load testing pending.

3. V2 features — Market orders. Variable tick sizes. Multi-datacenter replication. Each a spec-first effort.

RSX v0 aims to be the smallest exchange design that is correct. The specs and unit tests validate the architecture. Production deployment is a different project entirely.