How chrislernunes/hydrax. works
1) Overall shape
HydraExchange is a C++20 exchange-simulation codebase organized around a central matching core, with three main usage modes: offline simulation, benchmarking, and live market-data ingestion from Binance. The architecture is not a traditional service/app stack; it is a low-latency in-process system where most subsystems are compiled into the same executable via an include-based single-translation-unit pattern.
2) Entry points and modes
main.cpp is the CLI entry for the simulator/engine, while examples/live_binance.cpp builds the live feed demo. The README indicates runtime modes for example matching, execution-model experiments, agent simulation, and throughput benchmarking. These modes are thin wrappers over the same underlying engine and analytics components.
3) Core trading engine
The heart of the repo is engine/matching_engine/ plus engine/orderbook/. Orders enter the matching engine, are stored in the limit order book, matched with price-time priority, and generate execution reports/trade events. The engine supports common order types such as limit, market, IOC, FOK, and post-only.
4) Order lifecycle boundary
engine/gateway/order_gateway.cpp and engine/gateway/risk_checks.cpp form the ingress boundary before orders reach the book. This is where validation/risk checks happen, separating “submit intent” from “engine acceptance.” The matching engine owns order allocation and lifecycle management, while the gateway constrains what is allowed to reach it.
5) Limit order book internals
engine/orderbook/limit_order_book.cpp and price_level.cpp implement the book data structure. The README describes a std::map<Price, PriceLevel> with intrusive linked-list queues, enabling fast best-price lookup and O(1)-style insertion/cancel behavior in the hot path. This is the primary stateful component of the exchange.
6) Market data fanout
engine/market_data/feed_publisher.cpp publishes book/trade updates from the engine to downstream consumers. This is the key outbound data path from matching events to analytics, simulations, or live dashboards. In architecture diagrams, this should sit beside the engine as the primary event dissemination layer.
7) Shared domain model
include/hydra/types.hpp and include/hydra/order.hpp define the core domain types: prices, quantities, order IDs, sides, and the order struct itself. These types are shared across engine, agents, simulation, analytics, and Binance integration, which makes them the main cross-cutting contract in the repo.
8) Simulation and microstructure models
The simulation/ tree adds models that sit on top of the engine rather than replacing it. latency_model/ simulates network, queueing, engine processing, and cancel-race effects; execution_model/ simulates queue position, fill probability, and market impact; replay/ generates synthetic order flow. These components feed the same matching engine but represent different research assumptions.
9) Agent layer
agents/market_maker.cpp contains strategy agents used in simulation. The README describes multiple strategy behaviors—market making, noise trading, momentum, and latency arbitrage—implemented as active participants that submit orders into the engine through the public API. In diagrams, agents should be shown as producers of order flow, not as part of the matching core.
10) Analytics subsystem
analytics/orderflow_metrics.cpp computes online metrics such as order-flow imbalance, Kyle’s lambda, spread, realized volatility, and alpha decay. These analytics consume market data/trade streams from the engine or live Binance feed and produce derived signals for dashboards and strategy evaluation. This subsystem is read-mostly and downstream of the trading/matching path.
11) Live Binance integration
The binance/ directory is a separate live-data subsystem built around ws_client.hpp (TLS WebSocket client), binance_stream.hpp (stream parsing and local order-book reconstruction), and live_analytics.hpp (real-time metrics/dashboard). Data flow is Binance public WebSocket streams → local book reconstruction → analytics/output. OpenSSL is the only external runtime dependency, and the live path is distinct from the simulator path.
12) Infrastructure and performance primitives
infrastructure/ provides low-level building blocks: lock-free queues, a ring buffer, a memory pool, and timestamp utilities. These are not business logic; they support the engine’s low-latency execution and avoid heap churn or locking on the hot path. They are fundamental to the system’s performance claims and should appear as shared infrastructure beneath the engine, simulation, and live-feed layers.
13) Benchmarks and research artifacts
benchmarks/throughput_benchmark.cpp measures engine and data-structure throughput. HydraExchange_SSRN.pdf and the README position the project as research-oriented microstructure infrastructure, so benchmarks are first-class artifacts rather than incidental tests. They validate the engine, memory pool, and order-book design.
14) Practical architecture note
Because many .cpp files are included directly rather than compiled as separate translation units, the repo behaves like a tightly composed codebase with explicit compile-time wiring. That means the architecture diagram should emphasize module boundaries and data flow, not process boundaries or distributed services.
Main entry points: matching_engine.cpp Matching core · memory_pool.hpp Infra primitives · order_gateway.cpp Order gateway · limit_order_book.cpp Limit book
Components 22
Entry points
CLI and demo executables that wire the same core modules into different runtime modes.
Core engine
Matching, order book, gateway, and market-data emission.
- Order gateway · Validates and forwards order intent into the engine.
engine/gateway/order_gateway.cpp - Risk checks · Pre-engine checks and acceptance constraints.
engine/gateway/risk_checks.cpp - Matching core · Price-time matching, order lifecycle, and execution handling.
engine/matching_engine/matching_engine.cpp - Trade event · Trade and execution-report representation emitted by the engine.
engine/matching_engine/trade_event.cpp - Limit book · Primary stateful order book structure and best-price management.
engine/orderbook/limit_order_book.cpp - Price level · Per-price queue and level bookkeeping for the book hot path.
engine/orderbook/price_level.cpp - Feed publisher · Broadcasts book and trade updates to downstream consumers.
engine/market_data/feed_publisher.cpp
Shared models
Domain contracts used across engine, simulation, analytics, and live feeds.
- Strategy API · Public submission surface used by agents and simulations.
api/strategy_api.hpp - Core types · Prices, quantities, sides, IDs, and shared order contracts.
include/hydra/types.hpp - Order model · Order structure and lifecycle-facing order fields.
include/hydra/order.hpp
Simulation
Research models that generate flow, latency, and execution assumptions.
- Market maker · Representative strategy agent that submits orders into the engine.
agents/market_maker.cpp - Latency model · Network, queueing, processing, and cancel-race delay simulation.
simulation/latency_model/network_delay.cpp - Execution model · Queue position, fill probability, and market-impact assumptions.
simulation/execution_model/queue_position.cpp - Synthetic flow · Synthetic order-flow generation for replay and experiments.
simulation/replay/synthetic_orderflow.cpp
Live feed
Binance ingestion and local reconstruction path.
- Binance stream · WebSocket stream parsing and local book reconstruction.
binance/binance_stream.hpp - WS client · TLS WebSocket transport used by the live Binance path.
binance/ws_client.hpp - Live analytics · Real-time metrics and dashboard logic for live market data.
binance/live_analytics.hpp
Support
Infrastructure and measurement utilities.
- Orderflow metrics · Online market-quality and alpha-style metrics from feeds.
analytics/orderflow_metrics.cpp - Infra primitives · Lock-free queues, ring buffer, memory pool, and timestamp utilities.
infrastructure/memory_pool.hpp - Throughput bench · Measures engine and data-structure throughput.
benchmarks/throughput_benchmark.cpp
Connections 26
- Main CLI → Order gateway: submit orders · CLI-driven modes exercise the order ingress path.
- Main CLI → Matching core: drive engine · Runs the central exchange simulation and matching loop.
- Main CLI → Orderflow metrics: measure flow · Offline modes consume engine output for analysis.
- Live demo → WS client: connect · Live demo opens the Binance transport.
- Live demo → Binance stream: reconstruct · Parses public streams into local book state.
- Order gateway → Risk checks: validate · Orders are checked before acceptance.
- Order gateway → Matching core: forward · Accepted orders enter the matching core.
- Strategy API → Order gateway: submit · Strategies and simulations use the public API boundary.
- Strategy API → Market maker: used by · Strategy agents submit through the same interface.
- Matching core → Limit book: mutate · Matching updates the limit order book state.
- Limit book → Price level: manage levels · Price levels implement the book’s queue structure.
- Matching core → Trade event: emit · Matches generate execution and trade events.
- Matching core → Feed publisher: publish · Book and trade updates fan out to consumers.
- Feed publisher → Orderflow metrics: feed · Analytics consume book and trade streams.
- Feed publisher → Live analytics: feed · Live metrics subscribe to the same outbound stream.
- Latency model → Matching core: simulate · Latency effects are applied against engine interaction.
- Execution model → Limit book: estimate fills · Execution assumptions depend on queue position and book state.
- Synthetic flow → Market maker: generate inputs · Synthetic replay and flow models drive agents.
- Market maker → Strategy API: submit orders · Agent orders enter through the shared boundary.
- Binance stream → Live analytics: derive signals · Reconstructed live data feeds downstream metrics.
- WS client → Binance stream: transport · WebSocket transport carries Binance public data.
- Infra primitives → Matching core: support · Low-latency primitives back hot-path execution.
- Infra primitives → Limit book: support · Book operations rely on shared memory and queue primitives.
- Infra primitives → Binance stream: support · Live ingestion uses common buffering and timing utilities.
- Throughput bench → Matching core: measure · Benchmarks exercise the engine core.
- Throughput bench → Infra primitives: measure · Throughput tests also cover infrastructure primitives.