### Hyperliquid Bot System Design

## Executive Summary

This design specifies a production-grade, single-process Rust trading system for Hyperliquid focused on short-to-medium intraday swing opportunities triggered by rapid bursts of volume and liquidity. The recommended design center is a deterministic event engine driven primarily by `trades` and `bbo`, with `activeAssetCtx` and user/account streams as contextual and authoritative state inputs, and optional shallow `l2Book` features only if staging proves incremental value.

The alpha architecture should not be a generic indicator bot. It should be a microstructure-gated two-branch strategy: **breakout continuation** when one-sided aggressive flow is persistent and price acceptance holds, and **sweep reversion** when a liquidity-taking burst appears exhausted and the swept level is rapidly reclaimed. Traditional EMA/ATR/VWAP/RSI/HHV/LLV features remain useful as normalization, regime, and exit controls, but should not be primary event triggers for this use case.

The survival objective dominates the design: all new risk must stop on stale market state, stale user state, reconnect uncertainty, queue saturation, signer/nonce anomalies, or unresolved execution ambiguity. Re-entry to trading must occur only after authoritative reconciliation by snapshots and queries confirms coherent orders, fills, and positions.

## System Goals / Non-Goals

### Goals
- Single-process Rust binary with strict hot-path/cold-path separation.
- Deterministic, replayable strategy/risk hot loop over normalized internal events.
- Current-data-only intraday alpha using rapid volume/liquidity shock detection, continuation confirmation, and failed-sweep reversion.
- Authoritative reconnect recovery using snapshots plus `/info` backfill and cloid-based ambiguity resolution.
- Bounded-memory, bounded-queue, low-allocation runtime with reserved capacity for risk-off traffic.

### Non-Goals
- No full deep-book reconstruction engine in MVP. Hyperliquid public `l2Book` is snapshot-based and `/info` returns at most 20 levels per side, so full diff-sequenced L2/L3 logic is not the default baseline.
- No multi-process shared signer topology. One API wallet per trading process is the safe design.
- No heavy online model fitting, clustering, or adaptive meta-labeling in the hot path. Those belong in replay research and cold-path calibration.

## Architecture

### Process Model
Run one process with four temperature zones:
1. **Hot path**: deterministic event consumer thread for state mutation, feature updates, signal branching, risk admission, and compact intent emission. 
2. **Warm path**: network I/O runtime for WebSocket read/write, JSON decode/encode, signing, nonce allocation, batching, and heartbeat timers. 
3. **Cold path**: reconciliation queries, journaling flush, metrics export, admin control plane, configuration reload, and diagnostics.
4. **Operator safety plane**: manual mode toggles, SAFE/LOCKED unlock policy, session arming/disarming, and emergency flatten authorization.

### Task Model

| Task | Thread / runtime | Responsibility | Hot? |
| --- | --- | --- | --- |
| MD socket reader | Tokio | Read WS frames, decode JSON, timestamp receipt, push raw msgs | No |
| MD normalizer | Tokio or dedicated warm thread | Map strings to ids, parse decimals to fixed-point, dedupe trades | No |
| Strategy/risk loop | Dedicated thread | Apply events in total local order, update state, emit intents | Yes |
| Execution gateway | Tokio + warm worker | Batch intents, allocate nonces, sign, send post requests, track req ids | No |
| Reconciliation supervisor | Tokio/cold | Reconnect, resubscribe, query snapshots, resolve ambiguous orders | No |
| Observability | Cold workers | Metrics export, log writing, journal flush, admin API | No |

### Hot Path Rules
**Must be in hot path:** normalized event application, rolling feature updates, state-machine transitions, risk checks, signal branching, order intent creation, timer-wheel consumption.

**Must not be in hot path:** JSON parsing, websocket framing, signature generation, HTTP fallbacks, file I/O, formatted logging, dynamic plugin dispatch, heap-growing string-keyed maps, model fitting, and exchange query retries.

## Crate / Module Layout

| Crate | Purpose | Hotness | Key modules |
| --- | --- | --- | --- |
| `bot-types` | Core ids, enums, fixed-point wrappers, event structs | Hot | `ids`, `fp`, `event`, `state` |
| `bot-math` | Streaming stats, MAD, ring buffers, rolling extrema | Hot | `rolling_sum`, `robust_scale`, `vpin`, `deque_extrema` |
| `bot-state` | Per-symbol and portfolio state stores | Hot | `symbol_state`, `order_state`, `position_state`, `account_state` |
| `bot-strategy` | Shock detectors, regime filters, continuation/reversion modules | Hot | `detectors`, `regime`, `continuation`, `sweep_reversion`, `lifecycle` |
| `bot-risk` | Invariants, limits, kill-switches, state transitions | Hot | `pretrade`, `posttrade`, `state_gate`, `kill_switch` |
| `bot-hl-md` | Hyperliquid market-data adapters | Warm | `ws_client`, `parser`, `normalize`, `subscriptions` |
| `bot-hl-exec` | Signing, nonces, batching, outbound envelopes, response correlation | Warm | `nonce`, `sign`, `post`, `batcher`, `shadow_orders` |
| `bot-runtime` | Bootstrap, queue wiring, timers, mode control | Warm | `bootstrap`, `scheduler`, `heartbeat`, `recovery` |
| `bot-obs` | Journal, tracing, metrics, admin API | Cold | `journal`, `metrics`, `logging`, `admin` |
| `bot-config` | Static config, symbol metadata, limits | Cold | `defaults`, `schema`, `validation` |
| `bot-replay` | Event-driven backtest/replay harness | Cold | `loader`, `exchange_sim`, `latency`, `slippage`, `faults` |
| `bot-main` | Thin binary entrypoint | Mixed | `main.rs` |