58 lines
2.1 KiB
Markdown
58 lines
2.1 KiB
Markdown
# Backtesting and Replay v1 (Backend)
|
|
|
|
## Scope
|
|
Backtesting v1 is an isolated, read-only simulation pipeline under `src/backtest/**`.
|
|
It reuses `ProStrategyEngine` unchanged and is guarded by feature flag plus mode assertion.
|
|
|
|
## Isolation Guarantees
|
|
- Entry path: `POST /api/backtest/run` only.
|
|
- Hard guard: `if (mode !== 'backtest') throw`.
|
|
- No live runtime loop reuse (`src/index.ts` unchanged).
|
|
- No broker order placement (`ReplayExchangeConnector.placeOrder()` throws).
|
|
- No writes to `orders`, `trade_history`, or `capital_ledgers`.
|
|
- In-memory virtual ledger only.
|
|
|
|
## Deterministic Replay Rules
|
|
- Candles are normalized and strictly sorted by timestamp.
|
|
- Timeframes are validated to `15m`, `1h`, `4h`.
|
|
- Symbol processing order is lexicographic and stable.
|
|
- No randomness in fills/slippage/partials/exit ordering.
|
|
- Same input payload produces identical output.
|
|
|
|
## Time-Window Semantics
|
|
- Replay window: `from_date` inclusive to `to_date` inclusive (UTC).
|
|
- Warm-up candles are loaded before `from_date` where available.
|
|
- Trades are evaluated only inside the replay window.
|
|
- Default end-of-window behavior: keep open positions as `OPEN_AT_END`.
|
|
- Optional execution override: `forceCloseAtWindowEnd=true` to close at last candle.
|
|
|
|
## Data Sources
|
|
- CSV upload (required in v1): `symbol,timeframe,timestamp,open,high,low,close,volume`.
|
|
- JSON upload (array rows or nested symbol/timeframe maps).
|
|
- Replay payload adapter (read-only).
|
|
- Kraken historical loader (read-only CCXT OHLC fetch, cached in-memory, no order paths).
|
|
|
|
## API Contract Highlights
|
|
`BacktestResult` includes:
|
|
- `trades`
|
|
- `summary` (`netPnlUsd`, `winRate`, `maxDrawdownPct`, `sharpe`, `totalTrades`)
|
|
- `timeline` (equity and drawdown points)
|
|
- `window` (UTC replay window + `OPEN_AT_END`/`FORCE_CLOSE` policy)
|
|
- `warmup`
|
|
- `openPositionsAtEnd`
|
|
- `assumptions`
|
|
- `diagnostics`
|
|
|
|
## Feature Flags
|
|
- `ENABLE_BACKTEST=true`
|
|
- `BACKTEST_CUSTOMER_ENABLED=false` (when false, only admins can run backtests)
|
|
- `BACKTEST_MAX_CSV_BYTES`
|
|
- `BACKTEST_MAX_ROWS`
|
|
|
|
## Non-Goals
|
|
- Parameter optimization
|
|
- ML tuning
|
|
- Strategy mutation
|
|
- Live/backtest blending
|
|
- Broker execution from backtest mode
|