# Bot State Machine (v1 / v2)

## States (per pool)

- **IDLE** — Within band; no action.
- **ABOVE_BAND** — P_pool > P_oracle + band; trigger sell T.
- **BELOW_BAND** — P_pool < P_oracle - band; trigger buy T.
- **INVENTORY_ADJUST** — Re-center single-sided liquidity or bridge.
- **COOLDOWN** — Post-intervention cooldown; no trade.
- **CIRCUIT_BREAK** — Deviation > circuit break threshold; pause.

## Transitions

- IDLE → ABOVE_BAND when δ > normalBand.
- IDLE → BELOW_BAND when δ < -normalBand.
- ABOVE_BAND / BELOW_BAND → IDLE after successful trade and δ back in band.
- Any → INVENTORY_ADJUST when inventory imbalance exceeds threshold.
- After any trade → COOLDOWN for configured time or blocks.
- Any → CIRCUIT_BREAK when |δ| > circuitBreakBps; require manual or automated reset.

## v1

- Deviation watcher; simple buy/sell to compress δ; inventory thresholds; no cross-quote routing.

## v2

- Cross-quote routing (best edge by slippage + fee); bridge-aware mint/burn; circuit-break risk controls; HUB-first priority; global per-token trade budget.

See [../config/peg-bands.json](../config/peg-bands.json) and [bot-pseudo-code.md](bot-pseudo-code.md).