replay_with_avellaneda.py

#!/usr/bin/env python3
"""Replay solver WETH/USDC settlements through an Avellaneda-style backtest."""

from __future__ import annotations

import argparse
import csv
import datetime as dt
import json
import math
import time
import urllib.parse
import urllib.request
from dataclasses import asdict, dataclass
from pathlib import Path


BINANCE_KLINES_URL = "https://api.binance.com/api/v3/klines"


@dataclass
class Candle:
    open_time_ms: int
    open: float
    high: float
    low: float
    close: float
    volume: float


@dataclass
class Trade:
    timestamp: str
    side: str
    price: float
    amount_base: float
    fee_quote: float
    trading_edge_quote: float
    negative_trading_edge_quote: float
    reward_budget_spent_quote: float
    reward_budget_remaining_quote: float
    inventory_risk_reduction_value_quote: float
    base_balance: float
    quote_balance: float
    portfolio_value_quote: float
    base_pct: float


@dataclass
class SettlementEvent:
    """One external inventory movement from a solver settlement.

    base_delta is the WETH amount from the settlement CSV.
    quote_delta is the USDC amount from the settlement CSV.

    Positive delta means the tracked settlement inventory received that token.
    Negative delta means the tracked settlement inventory sent that token.
    """

    timestamp_ms: int
    block_number: int
    tx_hash: str
    solver_address: str
    base_delta: float
    quote_delta: float
    raw_transfer_count: int
    auction_id: int | None
    is_winner: bool | None
    ranking: int | None
    orders_count: int | None
    solver_score_wei: int | None
    reference_score_wei: int | None
    total_winning_score_wei: int | None
    estimated_reward_native: float


def parse_utc_ms(value: str) -> int:
    if value.lower() == "now":
        return int(dt.datetime.now(tz=dt.UTC).timestamp() * 1000)
    if len(value) == 10:
        value = f"{value}T00:00:00"
    parsed = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
    if parsed.tzinfo is None:
        parsed = parsed.replace(tzinfo=dt.UTC)
    return int(parsed.timestamp() * 1000)


def iso_from_ms(timestamp_ms: int) -> str:
    return dt.datetime.fromtimestamp(timestamp_ms / 1000, tz=dt.UTC).isoformat()


def optional_int(value: object) -> int | None:
    if value is None or value == "":
        return None
    return int(value)


def optional_bool(value: object) -> bool | None:
    if value is None or value == "":
        return None
    if isinstance(value, bool):
        return value
    return str(value).lower() in {"1", "true", "yes"}


def interval_to_seconds(interval: str) -> int:
    unit = interval[-1]
    amount = int(interval[:-1])
    if unit == "m":
        return amount * 60
    if unit == "h":
        return amount * 60 * 60
    if unit == "d":
        return amount * 24 * 60 * 60
    raise ValueError(f"Unsupported interval: {interval}")


def fetch_binance_klines(symbol: str, interval: str, start_ms: int, end_ms: int) -> list[Candle]:
    candles: list[Candle] = []
    cursor = start_ms
    while cursor < end_ms:
        params = {
            "symbol": symbol.upper(),
            "interval": interval,
            "startTime": cursor,
            "endTime": end_ms,
            "limit": 1000,
        }
        url = BINANCE_KLINES_URL + "?" + urllib.parse.urlencode(params)
        with urllib.request.urlopen(url, timeout=30) as response:
            payload = json.loads(response.read().decode("utf-8"))
        if not payload:
            break
        for row in payload:
            open_time = int(row[0])
            if open_time >= end_ms:
                continue
            candles.append(
                Candle(
                    open_time_ms=open_time,
                    open=float(row[1]),
                    high=float(row[2]),
                    low=float(row[3]),
                    close=float(row[4]),
                    volume=float(row[5]),
                )
            )
        next_cursor = int(payload[-1][0]) + 1
        if next_cursor <= cursor:
            break
        cursor = next_cursor
        time.sleep(0.12)
    return candles


def load_candles_csv(path: Path) -> list[Candle]:
    candles: list[Candle] = []
    with path.open("r", newline="", encoding="utf-8") as handle:
        for row in csv.DictReader(handle):
            open_time_ms = int(row["open_time_ms"]) if "open_time_ms" in row else parse_utc_ms(row["timestamp"])
            candles.append(
                Candle(
                    open_time_ms=open_time_ms,
                    open=float(row["open"]),
                    high=float(row["high"]),
                    low=float(row["low"]),
                    close=float(row["close"]),
                    volume=float(row.get("volume", 0) or 0),
                )
            )
    return candles


def load_settlement_events(path: Path) -> list[SettlementEvent]:
    """Load solver settlement deltas from CSV.

    The CoW extractor writes weth_delta/usdc_delta. The replay maps those names
    to generic base_delta/quote_delta because Avellaneda thinks in base/quote
    inventory:

    base_delta  = WETH delta
    quote_delta = USDC delta
    """

    events: list[SettlementEvent] = []
    if not path.exists():
        return events
    with path.open("r", newline="", encoding="utf-8") as handle:
        for row in csv.DictReader(handle):
            events.append(
                SettlementEvent(
                    timestamp_ms=parse_utc_ms(row["timestamp"]),
                    block_number=int(row["block_number"]),
                    tx_hash=row["tx_hash"],
                    solver_address=row.get("solver_address", ""),
                    base_delta=float(row.get("weth_delta", row.get("base_delta", 0)) or 0),
                    quote_delta=float(row.get("usdc_delta", row.get("quote_delta", 0)) or 0),
                    raw_transfer_count=int(row.get("raw_transfer_count", 0) or 0),
                    auction_id=optional_int(row.get("auction_id")),
                    is_winner=optional_bool(row.get("is_winner")),
                    ranking=optional_int(row.get("ranking")),
                    orders_count=optional_int(row.get("orders_count")),
                    solver_score_wei=optional_int(row.get("solver_score_wei")),
                    reference_score_wei=optional_int(row.get("reference_score_wei")),
                    total_winning_score_wei=optional_int(row.get("total_winning_score_wei")),
                    estimated_reward_native=float(row.get("estimated_reward_native", 0) or 0),
                )
            )
    events.sort(key=lambda event: (event.timestamp_ms, event.block_number, event.tx_hash))
    return events


def annualized_volatility(candles: list[Candle], lookback: int, interval_seconds: int) -> float:
    if len(candles) < lookback + 1:
        return 0.0
    returns: list[float] = []
    for previous, current in zip(candles[-lookback - 1 :], candles[-lookback:]):
        if previous.close > 0 and current.close > 0:
            returns.append(math.log(current.close / previous.close))
    if len(returns) < 2:
        return 0.0
    mean_return = sum(returns) / len(returns)
    variance = sum((item - mean_return) ** 2 for item in returns) / (len(returns) - 1)
    return math.sqrt(variance * (365 * 24 * 60 * 60 / interval_seconds))


def estimate_liquidity_half_spread(candles: list[Candle], lookback: int) -> float:
    window = candles[-lookback:] if len(candles) >= lookback else candles
    half_ranges = [(candle.high - candle.low) / 2 for candle in window if candle.high >= candle.low]
    return sum(half_ranges) / len(half_ranges) if half_ranges else 0.0


def time_left_fraction(args: argparse.Namespace, candles: list[Candle], index: int) -> float:
    if args.execution_timeframe_mode != "from_date_to_date":
        return 1.0
    if len(candles) <= 1:
        return 0.0
    return max(0.0, min(1.0, (len(candles) - 1 - index) / (len(candles) - 1)))


def quote_state(args: argparse.Namespace, candles: list[Candle], index: int, base: float, quote: float) -> dict:
    """Calculate Avellaneda bid/ask from the current inventory.

    The important input here is the current base/quote balance after applying
    any solver settlement events. If settlements made the portfolio underweight
    WETH, the reservation price moves up to encourage buys. If settlements made
    it overweight WETH, the reservation price moves down to encourage sells.
    """

    candle = candles[index]
    mid = candle.open
    portfolio_value = quote + base * mid
    target_base = (portfolio_value * args.inventory_target_base_pct / 100) / mid
    inventory_error = base - target_base
    normalized_inventory = inventory_error / max(target_base, args.order_amount, 1e-12)

    interval_seconds = interval_to_seconds(args.interval)
    history_start = max(
        0,
        index - max(args.volatility_buffer_size + 1, args.trading_intensity_buffer_size),
    )
    history = candles[history_start : index + 1]
    sigma = annualized_volatility(history, args.volatility_buffer_size, interval_seconds)
    sigma_period = sigma / math.sqrt(365 * 24 * 60 * 60 / interval_seconds) if sigma > 0 else 0.0
    time_fraction = time_left_fraction(args, candles, index)

    min_half_spread = mid * args.min_spread / 100 / 2
    liquidity_half_spread = estimate_liquidity_half_spread(history, args.trading_intensity_buffer_size)
    risk_half_spread = 0.5 * args.risk_factor * sigma_period * mid * time_fraction
    half_spread = max(min_half_spread, liquidity_half_spread + risk_half_spread)

    theoretical_shift = inventory_error * args.risk_factor * (sigma_period**2) * mid * time_fraction
    candle_inventory_shift = normalized_inventory * half_spread * args.risk_factor * time_fraction
    reservation_price = mid - theoretical_shift - candle_inventory_shift
    bid = reservation_price - half_spread
    ask = reservation_price + half_spread
    if args.add_transaction_costs:
        bid *= 1 - args.maker_fee
        ask *= 1 + args.maker_fee

    return {
        "inventory_error": inventory_error,
        "annualized_volatility": sigma,
        "time_left_fraction": time_fraction,
        "reservation_price": reservation_price,
        "bid": bid,
        "ask": ask,
    }


def inventory_error_base(base: float, quote: float, mid: float, target_base_pct: float) -> float:
    portfolio_value = quote + base * mid
    if portfolio_value <= 0 or mid <= 0:
        return 0.0
    target_base = (portfolio_value * target_base_pct / 100) / mid
    return base - target_base


def write_csv(path: Path, rows: list[dict]) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    if not rows:
        path.write_text("", encoding="utf-8")
        return
    with path.open("w", newline="", encoding="utf-8") as handle:
        writer = csv.DictWriter(handle, fieldnames=list(rows[0].keys()))
        writer.writeheader()
        writer.writerows(rows)


def simulate(args: argparse.Namespace, candles: list[Candle], settlements: list[SettlementEvent]) -> tuple[dict, list[Trade], list[dict], list[dict]]:
    """Replay three portfolio paths over the same candle window.

    1. Hold-only:
       keep the initial WETH/USDC balances unchanged and mark them at the final
       price. This is calculated at the end as buy_and_hold_value.

    2. Settlement-only:
       apply solver WETH/USDC deltas, but do not let Avellaneda trade. These
       balances live in settlement_only_base / settlement_only_quote.

    3. Settlement + Avellaneda:
       apply the same solver deltas, then let Avellaneda quote and trade after
       the inventory has moved. These balances live in base / quote.
    """

    # Full path: solver settlements plus Avellaneda trades.
    base = args.initial_base
    quote = args.initial_quote

    # Baseline path: solver settlements only, no Avellaneda trades.
    settlement_only_base = args.initial_base
    settlement_only_quote = args.initial_quote
    trades: list[Trade] = []
    equity_curve: list[dict] = []
    applied_settlements: list[dict] = []
    settlement_index = 0
    total_external_base_delta = 0.0
    total_external_quote_delta = 0.0
    total_solver_reward_native = 0.0
    total_solver_reward_quote = 0.0
    cumulative_reward_budget_quote = 0.0
    reward_budget_spent_quote = 0.0
    reward_aware_skipped_trades = 0
    reward_aware_accepted_negative_edge_trades = 0
    total_negative_trading_edge_quote = 0.0
    total_inventory_risk_reduction_value_quote = 0.0
    solver_addresses = sorted({event.solver_address for event in settlements if event.solver_address})

    for index, candle in enumerate(candles):
        # Apply all solver settlement events whose timestamp is before or equal
        # to the current candle timestamp. With 1m candles, a settlement at
        # 12:34:20 is reflected when the replay reaches the next candle boundary.
        while settlement_index < len(settlements) and settlements[settlement_index].timestamp_ms <= candle.open_time_ms:
            event = settlements[settlement_index]

            # event.base_delta is the WETH movement from the settlement CSV.
            # event.quote_delta is the USDC movement from the settlement CSV.
            #
            # These lines manually move the simulated inventory exactly as the
            # solver settlement moved WETH/USDC.
            base += event.base_delta
            quote += event.quote_delta

            # Apply the same external movement to the settlement-only baseline.
            # This path lets us later answer: what if Avellaneda did nothing
            # after the solver moved inventory?
            settlement_only_base += event.base_delta
            settlement_only_quote += event.quote_delta

            reward_quote = event.estimated_reward_native * candle.open
            total_solver_reward_native += event.estimated_reward_native
            total_solver_reward_quote += reward_quote
            cumulative_reward_budget_quote += reward_quote

            total_external_base_delta += event.base_delta
            total_external_quote_delta += event.quote_delta
            applied_settlements.append(
                {
                    "timestamp": iso_from_ms(event.timestamp_ms),
                    "block_number": event.block_number,
                    "tx_hash": event.tx_hash,
                    "solver_address": event.solver_address,
                    "base_delta": event.base_delta,
                    "quote_delta": event.quote_delta,
                    "auction_id": event.auction_id,
                    "is_winner": event.is_winner,
                    "ranking": event.ranking,
                    "orders_count": event.orders_count,
                    "solver_score_wei": event.solver_score_wei,
                    "reference_score_wei": event.reference_score_wei,
                    "total_winning_score_wei": event.total_winning_score_wei,
                    "estimated_reward_native": event.estimated_reward_native,
                    "estimated_reward_quote": reward_quote,
                    "mark_price": candle.open,
                    "mark_value_quote": event.quote_delta + event.base_delta * candle.open,
                    "base_balance_after": base,
                    "quote_balance_after": quote,
                }
            )
            settlement_index += 1

        # After external settlement deltas are applied, Avellaneda sees the new
        # inventory and computes quotes around its reservation price.
        state = quote_state(args, candles, index, base, quote)
        bid = state["bid"]
        ask = state["ask"]
        amount = args.order_amount
        touched_bid = candle.low <= bid
        touched_ask = candle.high >= ask

        # Candle data only tells us high/low, not the exact intraminute path. If
        # both bid and ask were touched, take the side that reduces inventory
        # error first.
        if touched_bid and touched_ask:
            sides = ["buy", "sell"] if state["inventory_error"] < 0 else ["sell", "buy"]
        elif touched_bid:
            sides = ["buy"]
        elif touched_ask:
            sides = ["sell"]
        else:
            sides = []

        for side in sides:
            if side == "buy":
                # Avellaneda buys WETH at the bid: WETH balance increases,
                # USDC balance decreases by cost plus fee.
                price = bid
                cost = price * amount
                fee = cost * args.maker_fee
                if quote < cost + fee:
                    continue
                trading_edge = (candle.open - price) * amount - fee
                base_after = base + amount
                quote_after = quote - cost - fee
                before_error = abs(inventory_error_base(base, quote, candle.open, args.inventory_target_base_pct))
                after_error = abs(inventory_error_base(base_after, quote_after, candle.open, args.inventory_target_base_pct))
                inventory_risk_reduction_value = max(before_error - after_error, 0.0) * candle.open * args.inventory_risk_reduction_weight
                negative_edge = max(-trading_edge, 0.0)
                reward_needed = max(negative_edge - inventory_risk_reduction_value, 0.0)
                if args.reward_aware and reward_needed > max(cumulative_reward_budget_quote - reward_budget_spent_quote - args.reward_budget_safety_margin, 0.0):
                    reward_aware_skipped_trades += 1
                    continue
                if negative_edge > 0:
                    total_negative_trading_edge_quote += negative_edge
                    total_inventory_risk_reduction_value_quote += inventory_risk_reduction_value
                    if args.reward_aware:
                        reward_budget_spent_quote += reward_needed
                        reward_aware_accepted_negative_edge_trades += 1
                quote -= cost + fee
                base += amount
            else:
                # Avellaneda sells WETH at the ask: WETH balance decreases,
                # USDC balance increases by proceeds minus fee.
                price = ask
                if base < amount:
                    continue
                proceeds = price * amount
                fee = proceeds * args.maker_fee
                trading_edge = (price - candle.open) * amount - fee
                base_after = base - amount
                quote_after = quote + proceeds - fee
                before_error = abs(inventory_error_base(base, quote, candle.open, args.inventory_target_base_pct))
                after_error = abs(inventory_error_base(base_after, quote_after, candle.open, args.inventory_target_base_pct))
                inventory_risk_reduction_value = max(before_error - after_error, 0.0) * candle.open * args.inventory_risk_reduction_weight
                negative_edge = max(-trading_edge, 0.0)
                reward_needed = max(negative_edge - inventory_risk_reduction_value, 0.0)
                if args.reward_aware and reward_needed > max(cumulative_reward_budget_quote - reward_budget_spent_quote - args.reward_budget_safety_margin, 0.0):
                    reward_aware_skipped_trades += 1
                    continue
                if negative_edge > 0:
                    total_negative_trading_edge_quote += negative_edge
                    total_inventory_risk_reduction_value_quote += inventory_risk_reduction_value
                    if args.reward_aware:
                        reward_budget_spent_quote += reward_needed
                        reward_aware_accepted_negative_edge_trades += 1
                base -= amount
                quote += proceeds - fee

            value = quote + base * candle.close
            trades.append(
                Trade(
                    timestamp=iso_from_ms(candle.open_time_ms),
                    side=side,
                    price=price,
                    amount_base=amount,
                    fee_quote=fee,
                    trading_edge_quote=trading_edge,
                    negative_trading_edge_quote=negative_edge,
                    reward_budget_spent_quote=reward_needed if args.reward_aware else 0.0,
                    reward_budget_remaining_quote=max(cumulative_reward_budget_quote - reward_budget_spent_quote, 0.0),
                    inventory_risk_reduction_value_quote=inventory_risk_reduction_value,
                    base_balance=base,
                    quote_balance=quote,
                    portfolio_value_quote=value,
                    base_pct=(base * candle.close / value * 100) if value > 0 else 0.0,
                )
            )

        value = quote + base * candle.close
        settlement_only_value = settlement_only_quote + settlement_only_base * candle.close
        equity_curve.append(
            {
                "timestamp": iso_from_ms(candle.open_time_ms),
                "close": candle.close,
                "base_balance": base,
                "quote_balance": quote,
                "portfolio_value_quote": value,
                "base_pct": (base * candle.close / value * 100) if value > 0 else 0.0,
                "settlement_only_base_balance": settlement_only_base,
                "settlement_only_quote_balance": settlement_only_quote,
                "settlement_only_value_quote": settlement_only_value,
                "settlement_only_base_pct": (settlement_only_base * candle.close / settlement_only_value * 100) if settlement_only_value > 0 else 0.0,
                "inventory_target_base_pct": args.inventory_target_base_pct,
                "inventory_error_base": state["inventory_error"],
                "reservation_price": state["reservation_price"],
                "bid": state["bid"],
                "ask": state["ask"],
                "time_left_fraction": state["time_left_fraction"],
                "cumulative_solver_reward_quote": total_solver_reward_quote,
                "reward_budget_remaining_quote": max(cumulative_reward_budget_quote - reward_budget_spent_quote, 0.0),
            }
        )

    initial_mid = candles[0].open
    final_mid = candles[-1].close

    # Hold-only path: no solver settlement deltas and no Avellaneda trades.
    initial_value = args.initial_quote + args.initial_base * initial_mid
    initial_base_pct = (args.initial_base * initial_mid / initial_value * 100) if initial_value > 0 else 0.0
    buy_and_hold_value = args.initial_quote + args.initial_base * final_mid

    # Full path and settlement-only path, both marked at the final price.
    final_value = quote + base * final_mid
    settlement_only_value = settlement_only_quote + settlement_only_base * final_mid
    buy_and_hold_pnl = buy_and_hold_value - initial_value
    settlement_only_pnl = settlement_only_value - initial_value
    final_base_pct = (base * final_mid / final_value * 100) if final_value > 0 else 0.0
    settlement_only_base_pct = (settlement_only_base * final_mid / settlement_only_value * 100) if settlement_only_value > 0 else 0.0
    reward_adjusted_final_value = final_value + total_solver_reward_quote
    reward_adjusted_settlement_only_value = settlement_only_value + total_solver_reward_quote
    avellaneda_delta = final_value - settlement_only_value
    reward_budget_after_avellaneda = total_solver_reward_quote + avellaneda_delta

    summary = {
        "summary_schema_version": 2,
        "symbol": args.symbol.upper(),
        "interval": args.interval,
        "candles": len(candles),
        "start": iso_from_ms(candles[0].open_time_ms),
        "end": iso_from_ms(candles[-1].open_time_ms),
        "settlement_events_loaded": len(settlements),
        "settlement_events_applied": len(applied_settlements),
        "solver_address": solver_addresses[0] if len(solver_addresses) == 1 else "",
        "solver_addresses": solver_addresses,
        "initial_value_quote": initial_value,
        "initial_base_balance": args.initial_base,
        "initial_quote_balance": args.initial_quote,
        "initial_base_pct": initial_base_pct,
        "buy_and_hold_value_quote": buy_and_hold_value,
        "settlement_only_value_quote": settlement_only_value,
        "final_value_quote": final_value,
        "pnl_quote": final_value - initial_value,
        "pnl_pct": (final_value / initial_value - 1) * 100 if initial_value > 0 else 0.0,
        "hold_only_pnl_pct": (buy_and_hold_pnl / initial_value * 100) if initial_value > 0 else 0.0,
        "buy_and_hold_pnl_quote": buy_and_hold_pnl,
        "buy_and_hold_pnl_pct": (buy_and_hold_pnl / initial_value * 100) if initial_value > 0 else 0.0,
        "settlement_only_pnl_quote": settlement_only_pnl,
        "settlement_only_pnl_pct": (settlement_only_pnl / initial_value * 100) if initial_value > 0 else 0.0,
        "avellaneda_vs_settlement_only_quote": avellaneda_delta,
        "avellaneda_vs_settlement_only_pct": (avellaneda_delta / initial_value * 100) if initial_value > 0 else 0.0,
        "avellaneda_vs_settlement_only_result": (
            "better" if final_value > settlement_only_value else "worse" if final_value < settlement_only_value else "same"
        ),
        "trades": len(trades),
        "final_base_balance": base,
        "final_quote_balance": quote,
        "final_base_pct": final_base_pct,
        "adjusted_base_pct": settlement_only_base_pct,
        "settlement_only_base_pct": settlement_only_base_pct,
        "inventory_target_base_pct": args.inventory_target_base_pct,
        "base_pct_error": final_base_pct - args.inventory_target_base_pct,
        "total_external_base_delta": total_external_base_delta,
        "total_external_quote_delta": total_external_quote_delta,
        "solver_reward_native": total_solver_reward_native,
        "solver_reward_quote": total_solver_reward_quote,
        "reward_estimate_mode": "cow_api_uncapped_performance_reward" if total_solver_reward_native else "none",
        "reward_adjusted_final_value_quote": reward_adjusted_final_value,
        "reward_adjusted_settlement_only_value_quote": reward_adjusted_settlement_only_value,
        "reward_adjusted_pnl_quote": reward_adjusted_final_value - initial_value,
        "reward_adjusted_pnl_pct": ((reward_adjusted_final_value - initial_value) / initial_value * 100) if initial_value > 0 else 0.0,
        "reward_adjusted_settlement_only_pnl_quote": reward_adjusted_settlement_only_value - initial_value,
        "reward_adjusted_settlement_only_pnl_pct": ((reward_adjusted_settlement_only_value - initial_value) / initial_value * 100) if initial_value > 0 else 0.0,
        "reward_budget_after_avellaneda_quote": reward_budget_after_avellaneda,
        "reward_budget_covers_avellaneda_loss": reward_budget_after_avellaneda >= 0,
        "reward_coverage_ratio": (
            total_solver_reward_quote / abs(avellaneda_delta)
            if avellaneda_delta < 0
            else None
        ),
        "reward_aware_enabled": args.reward_aware,
        "reward_budget_safety_margin": args.reward_budget_safety_margin,
        "reward_budget_spent_quote": reward_budget_spent_quote,
        "reward_budget_remaining_quote": max(cumulative_reward_budget_quote - reward_budget_spent_quote, 0.0),
        "reward_aware_skipped_trades": reward_aware_skipped_trades,
        "reward_aware_accepted_negative_edge_trades": reward_aware_accepted_negative_edge_trades,
        "total_negative_trading_edge_quote": total_negative_trading_edge_quote,
        "inventory_risk_reduction_value_quote": total_inventory_risk_reduction_value_quote,
        "config": {
            "settlements": str(args.settlements),
            "initial_base": args.initial_base,
            "initial_quote": args.initial_quote,
            "order_amount": args.order_amount,
            "risk_factor": args.risk_factor,
            "order_amount_shape_factor": args.order_amount_shape_factor,
            "min_spread": args.min_spread,
            "inventory_target_base_pct": args.inventory_target_base_pct,
            "execution_timeframe_mode": args.execution_timeframe_mode,
            "add_transaction_costs": args.add_transaction_costs,
            "volatility_buffer_size": args.volatility_buffer_size,
            "trading_intensity_buffer_size": args.trading_intensity_buffer_size,
            "maker_fee": args.maker_fee,
            "reward_aware": args.reward_aware,
            "reward_budget_safety_margin": args.reward_budget_safety_margin,
            "inventory_risk_reduction_weight": args.inventory_risk_reduction_weight,
        },
    }
    return summary, trades, equity_curve, applied_settlements


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Replay solver WETH/USDC settlements through Avellaneda inventory rebalancing.")
    parser.add_argument("--settlements", type=Path, required=True, help="CSV from fetch_cow_settlement_deltas.py.")
    parser.add_argument("--symbol", default="ETHUSDC", help="Binance candle symbol used as WETH/USDC mark price.")
    parser.add_argument("--interval", default="1m")
    parser.add_argument("--start", help="UTC start date/time.")
    parser.add_argument("--end", help="UTC end date/time, or now.")
    parser.add_argument("--candles-csv", type=Path)
    parser.add_argument("--initial-base", type=float, required=True, help="Initial WETH balance.")
    parser.add_argument("--initial-quote", type=float, required=True, help="Initial USDC balance.")
    parser.add_argument("--order-amount", type=float, default=0.01)
    parser.add_argument("--risk-factor", type=float, default=1.0)
    parser.add_argument("--order-amount-shape-factor", type=float, default=0.0)
    parser.add_argument("--min-spread", type=float, default=0.0)
    parser.add_argument("--inventory-target-base-pct", type=float, default=50.0)
    parser.add_argument("--execution-timeframe-mode", choices=("infinite", "from_date_to_date"), default="infinite")
    parser.add_argument("--add-transaction-costs", action="store_true")
    parser.add_argument("--reward-aware", action="store_true", help="Use solver reward estimates as budget for locally negative rebalancing trades.")
    parser.add_argument("--reward-budget-safety-margin", type=float, default=0.0, help="USDC amount to keep unused when spending reward budget.")
    parser.add_argument(
        "--inventory-risk-reduction-weight",
        type=float,
        default=0.0,
        help="USDC value multiplier for each WETH of inventory error reduction when approving negative-edge trades.",
    )
    parser.add_argument("--volatility-buffer-size", type=int, default=200)
    parser.add_argument("--trading-intensity-buffer-size", type=int, default=200)
    parser.add_argument("--maker-fee", type=float, default=0.0001)
    parser.add_argument("--out-dir", type=Path, default=Path("results/replay"))
    return parser


def main() -> None:
    args = build_parser().parse_args()
    if args.candles_csv:
        candles = load_candles_csv(args.candles_csv)
    else:
        if not args.start or not args.end:
            raise SystemExit("--start and --end are required unless --candles-csv is used")
        candles = fetch_binance_klines(args.symbol, args.interval, parse_utc_ms(args.start), parse_utc_ms(args.end))
    if len(candles) < args.volatility_buffer_size + 2:
        raise SystemExit(f"Only loaded {len(candles)} candles; use a longer range or smaller --volatility-buffer-size.")

    settlements = load_settlement_events(args.settlements)
    summary, trades, equity_curve, applied_settlements = simulate(args, candles, settlements)

    args.out_dir.mkdir(parents=True, exist_ok=True)
    (args.out_dir / "summary.json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
    write_csv(args.out_dir / "trades.csv", [asdict(trade) for trade in trades])
    write_csv(args.out_dir / "equity_curve.csv", equity_curve)
    write_csv(args.out_dir / "applied_settlements.csv", applied_settlements)
    write_csv(args.out_dir / "candles.csv", [asdict(candle) for candle in candles])

    print(json.dumps(summary, indent=2))
    print(f"\nWrote {args.out_dir / 'summary.json'}")
    print(f"Wrote {args.out_dir / 'trades.csv'}")
    print(f"Wrote {args.out_dir / 'equity_curve.csv'}")
    print(f"Wrote {args.out_dir / 'applied_settlements.csv'}")


if __name__ == "__main__":
    main()