Recording and Replay

The Hydra includes a powerful recording and replay system designed for high-fidelity backtesting. By capturing real-time events and replaying them in a controlled environment, you can validate strategy changes and performance with absolute determinism.

Overview

The workflow consists of two primary stages:

1. Recording: Capturing live events from Polymarket and reference price feeds into a structured data file.
2. Replaying: Running the bot against the recorded data file using a simulated clock to evaluate strategy behavior.

This system ensures that the exact same market conditions—including network latency artifacts and price fluctuations—are reproduced during testing.

Recording Market Data

The recorder subscribes to the EventBus and serializes specific market events into a JSONL (JSON Lines) file.

Entry Point

To start a recording session, run the following command:

bun run record

How it Works

1. Initialization: The bot loads the configuration and connects to the Polymarket and Binance data feeds.
2. Market Discovery: Based on your markets.coins configuration, the bot identifies and subscribes to relevant prediction markets.
3. Event Capture: The recorder captures all MarketDataUpdated and ReferencePriceEvent events.
4. Persistence: Events are written in real-time to a dedicated recording file.

Output Location

Recordings are stored in a timestamped subdirectory within the configured output directory (default is ./runs):

persistence.outDir/record_<timestamp>/recording.jsonl

Stopping

To finish recording, press Ctrl+C. The bot will perform a clean shutdown, close the recording file, and display final statistics including the total number of records captured and file size.

Replaying a Recording

Replay mode allows you to execute the bot’s trading logic against historical data as if it were happening in real-time.

Entry Point

To execute a replay, use the replay script:

bun run replay

Configuration

To use replay mode, you must update your config.yaml (or the file pointed to by BOT_CONFIG):

# Set the operation mode to replay
mode: "replay"

# Specify the input recording file
replay:
  input: "./runs/record_1736531200000/recording.jsonl"

Simulated Time (SimClock)

During replay, the bot does not use the system clock. Instead, it uses a SimClock that advances time precisely to the timestamp of each recorded event. This means:

• Time “jumps” between events, allowing large recordings to be replayed much faster than real-time.
• Interval-based logic (like risk checks or snapshots) remains consistent with the original event timeline.

Determinism and Backtesting

The core value of the recording system is determinism.

Determinism Guarantee

Because the SimClock and the replay runner process events in the exact order and at the exact relative time they occurred, the bot’s internal state transitions will be identical across multiple runs of the same recording. This allows you to:

• Debug specific strategy decisions by re-running the same market scenario.
• Compare the performance of different strategy parameters on the same data set.
• Verify bug fixes by ensuring they resolve issues observed in a specific recording.

Backtesting Workflow

1. Record: Capture data during volatile market periods or specific events (e.g., a scheduled crypto announcement).
2. Develop: Modify your strategy in src/engine/strategies/.
3. Replay: Run the replay script to see the impact of your changes.
4. Evaluate:
   • Review Events: Analyze the events.jsonl produced during the replay to understand internal state transitions.
   • Trade Ledger: Use the hydra trades command to view the resulting trades and performance summary.

     hydra trades --mode replay --summary