# Simulation Tools Enhancement Plan

## Goal
Align the profitability replay harness and embedded simulation helpers with production requirements: real historical data, accurate fee/slippage modelling, and automated validation in CI.

## Tasks

1. **Historical Data Ingestion**
   - [ ] Define vector schema for real opportunities (timestamp, DEX, expected vs. realized profit, route data).
   - [ ] Build extraction pipeline from historical archive/DB to `tools/simulation/vectors/` (with sanitised examples).
   - [ ] Add versioning/checksums for vectors used in CI.

2. **Simulation Accuracy**
   - [ ] Replace hard-coded fees/reserves (`tools/simulation/main.go`) with per-exchange metadata.
   - [ ] Model slippage, gas costs, and failed trades using observed distributions.
   - [ ] Introduce configuration for latency, backrunning competition, gas spikes.

3. **Integration with Arbitrage Pipeline**
   - [ ] Provide CLI option to replay directly against `ArbitrageService` / executor in dry-run mode.
   - [ ] Emit metrics for hit rate and net profit and compare against Prometheus data.

4. **CI Automation**
   - [ ] Add `make simulate-profit` to staging/audit workflows with artifact retention.
   - [ ] Set thresholds (e.g., net profit >0, hit rate >50%) to fail CI when regressions occur.

5. **Documentation & Runbooks**
   - [ ] Update `docs/5_development/TESTING_BENCHMARKING.md` and `docs/6_operations/DEPLOYMENT_GUIDE.md` with guidance on capturing vectors and interpreting reports.
   - [ ] Provide runbook entry for simulation dashboards and alerting.

## References
- `tools/simulation/main.go`
- `scripts/run_profit_simulation.sh`
- `pkg/arbitrage` simulation helper functions