> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perpsagent.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# System flow

> End-to-end request and execution flow.

A single user action — "launch this grid" — fans out across the stack like this.

## Launch flow

<Steps>
  <Step title="User confirms in Telegram">
    The bot has shown the AI-proposed config plus expected risk metrics. User taps confirm.
  </Step>

  <Step title="Pre-trade validation">
    Backend validates that the user's Bybit key is alive, trade-only, and has the required market access. Risk caps are sanity-checked against account size.
  </Step>

  <Step title="Commit on Mantle">
    `CommitRegistry.commit(runId, configHash, capsHash, marketId, timestamp)` is sent. Backend waits for inclusion.
  </Step>

  <Step title="Engine handoff">
    On commit confirmation, the grid engine is allocated the `runId`, loads the config, and subscribes to fills from the Bybit adapter.
  </Step>

  <Step title="Ladder placement">
    Engine places the initial ladder of orders through the adapter. Each intent passes through cap enforcement.
  </Step>

  <Step title="Live state">
    Fills stream in over WebSocket. PnL, drawdown, and risk metrics update in real time. Telegram pushes status updates and alerts.
  </Step>

  <Step title="End of run">
    Triggered by target, stop, or user. Engine cancels open orders, snapshots the verified outcome, and hands it to the proof layer.
  </Step>

  <Step title="Attest on Mantle">
    `AttestationRegistry.attest(runId, outcomeHash, pnl, maxDrawdown, riskScore, status)` is sent and confirmed. Telegram shows the user a link to the attestation.
  </Step>
</Steps>

## Stop flow

* User sends `/stop` in Telegram.
* Engine cancels open orders.
* Outcome is snapshotted and attested on Mantle.
* Run is closed in the operational store; track record lives on-chain.

## Failure modes

* **Venue outage:** adapter surfaces the error, engine pauses placement, user is notified. Existing positions remain on Bybit under user control.
* **Mantle slow:** launch waits on commit inclusion before any order goes out. No silent trading.
* **Cap breach attempt:** rejected at the cap-enforcement layer; engine logs the rejection and alerts the user.