Polytraders Dev Guide
internal
v3 spine Phase 1 · Shared contracts 9 demo-wired · 0 shadow-ready · 0 production-live · 100 pending · 109 total 15/33 infra tasks the plan status board

Order flow

From signal to on-chain order, every step. Every box is a real bot; every arrow is a typed schema. The order is fixed: Discovery → Intel → Strategy emits OrderIntent → Risk → Execution → Security → Lifecycle → Governance. Risk has no input until Strategy decides.

Pipeline rule: Risk evaluates OrderIntents. There is no path from a market observation to a signed order that bypasses Strategy. Reordering this is forbidden — see forbidden patterns.

  1. Signal (Intel) — Intelligence bots emit typed signals (MarketSnapshot, OrderBookSnapshot, news, sports feeds). All freshness-stamped.
  2. Discoverydisc.marketscanner filters the signal space down to candidate markets that pass the eligibility rules.
  3. Strategy emits OrderIntent — Exactly one Alpha Strategy bot evaluates the candidate and either emits an OrderIntent or returns STRAT_NO_EDGE. Risk does nothing until this step completes.
  4. Risk pipeline — The OrderIntent passes through every Risk bot in declared order. Each emits a RiskVote. Any single REJECT halts the pipeline.
  5. Execution shaping — If approved, exec.fee_slippage_estimator, exec.smart_router and (if needed) exec.order_shaper turn the intent into an ExecutionPlan.
  6. Signing — The signer service produces a SignedOrderRequest using EIP-712 v2 and the configured builderCode.
  7. Submission — The signed request is posted to the CLOB v2 endpoint. The Order Lifecycle Manager owns the order from this point on.
  8. Lifecycleexec.order_lifecycle_manager handles fills, partials, amends, cancels and timeouts. Every event emits a ReportEnvelope.
  9. Reconciliationgov.reconciler matches on-chain state to internal state on a heartbeat. Any mismatch fires GOV_RECONCILE_MISMATCH and may trigger the kill switch.
  10. Audit — Every step is recorded by gov.audit_log with the correlation ID. The full trail is replayable by gov.replay_simulator.

Latency budgets along the path

HopTargetHard cap
Signal → MarketSnapshot< 100 ms250 ms
Strategy decide()< 50 ms200 ms
Full Risk pipeline< 50 ms150 ms
Execution shaping< 100 ms300 ms
Signingimpl-dependent500 ms
Full intent → on-chain< 500 ms1500 ms (kill switch arms beyond this)

What can short-circuit