lls

Overview

lls maintains a correct, real-time local order book for one or more Binance Spot symbols by combining a REST snapshot with the diff-depth WebSocket stream, and serves a web dashboard showing the live book plus per-symbol health. It is the canonical order-book-reconstruction problem — the one quant connectivity interviews keep coming back to — built to be defensible from first principles.

Architecture

Two execution domains share no mutable state and no locks, joined only by a lock-free ArcSwap. The hot path runs synchronous tungstenite + ureq on a core_affinity-pinned thread per symbol — no async scheduler. Live frames parse zero-copy with sonic-rs and a custom allocation-free fixed-point string parser; prices and quantities are i64 scaled by 1e8, giving exact ordering with no float hazards. A separate Tokio + axum server reads the published snapshots at a fixed cadence and pushes JSON over WebSocket, keeping serde_json off the hot path.

Sequence Correctness

The reconciliation logic is a set of pure, unit-tested functions implementing Binance's exact procedure: drop u ≤ lastUpdateId; require the first event to satisfy U ≤ lastUpdateId+1 ≤ u; then enforce strict U == prev_u + 1; any gap triggers a full resync. 20 unit tests cover the parser, the book, and the sync rules.

Resilience

A monotonic-clock staleness check (immune to NTP steps) plus an active ping/pong heartbeat that runs only when the stream is idle catches a half-open socket independently of market activity. Reconnects use exponential backoff with jitter; any gap, stale tick, missed pong, or close triggers a full resync from a fresh snapshot.

Measured Performance

On an Apple Silicon dev box: parse_event ≈ 0.6 µs, parse_and_apply ≈ 0.8 µs, book_update on a 5000-level book ≈ 17 ns. Parsing dominates the book by ~35×, which is exactly why the optimization budget went to SIMD parsing rather than an exotic book structure.