{ "schema_version": "1.0.0", "bot_id": "2.6", "bot_name": "OrderLifecycleManager", "slug": "orderlifecyclemanager", "layer": "Execution", "layer_key": "exec", "bot_class": "Execution Utility", "authority": [ "Reshape" ], "status": "planned", "readiness": "Spec started", "flagship": true, "is_reference": false, "public_export": false, "identity": { "layer": "Execution", "bot_class": "Execution Utility", "authority": "Reshape", "runs_before": "FillQualityAnalyzer, PartialFillHandler, CancelReplaceOptimizer", "runs_after": "SmartRouter (order signed and submitted to CLOB V2)", "applies_to": "Every live order from submission through terminal state (FILLED, CANCELLED, EXPIRED)", "default_mode": "shadow_only", "user_visible": "yes", "developer_owner": "Polytraders core \u2014 Execution pod" }, "purpose": "OrderLifecycleManager is the single source of truth for every order's state machine, tracking transitions from intent through terminal state. It reconciles local state against the CLOB V2 user-state endpoint, detects stuck-in-flight and orphaned orders, and emits ExecutionReports on every transition.", "why_it_matters": [ { "failure": "Order state out of sync", "consequence": "Strategy layer acts on stale position data, potentially doubling into a filled position or missing a cancellation." }, { "failure": "Stuck-in-flight order not detected", "consequence": "An order that never received an ack occupies position budget indefinitely, blocking new orders." }, { "failure": "Orphaned ack not cancelled", "consequence": "A resting order with no owning strategy leaks capital and may fill at an unintended price." } ], "polymarket_inputs": [ { "input": "CLOB V2 user orders endpoint", "source": "clob_auth", "required": true, "use": "Reconcile local state against exchange state every reconcile_interval_s." }, { "input": "WebSocket user feed \u2014 fill and cancel events", "source": "ws_user", "required": true, "use": "Receive real-time order state transitions (ack, partial fill, full fill, cancel, expire)." } ], "internal_inputs": [ { "input": "Signed order from SmartRouter", "source": "exec.smart_router", "required": true, "use": "Initialise order state record on first submission." }, { "input": "KillSwitch active flag", "source": "risk.kill_switch", "required": true, "use": "Cancel all open orders and halt state updates when active." } ], "raw_params": [ "stuck_order_timeout_s \u00b7 int", "reconcile_interval_s \u00b7 int", "auto_cancel_orphans \u00b7 bool", "publish_audit_log \u00b7 bool" ], "parameters": [ { "name": "stuck_order_timeout_s", "default": 30, "warning": 60, "hard": 120, "controls": "Seconds after submission with no ack before an order is considered stuck-in-flight.", "why_default_matters": "30s covers normal CLOB latency spikes; beyond 60s indicates a system issue.", "threshold_logic": [ { "condition": "age_since_submit_s <= 30", "action": "Normal \u2014 await ack" }, { "condition": "30 < age_since_submit_s <= 60", "action": "WARN \u2014 ORDER_STUCK_WARN emitted" }, { "condition": "age_since_submit_s > 60", "action": "HARD_REJECT \u2014 cancel and emit ORDER_STUCK_HARD" } ], "dev_check": "if now_ms() - order.submit_ms > params.stuck_order_timeout_s * 1000: emit(ORDER_STUCK)", "user_facing": "An order took too long to be acknowledged by the exchange and was cancelled." }, { "name": "reconcile_interval_s", "default": 10, "warning": 30, "hard": 60, "controls": "How often to poll clob_auth for the authoritative user-order list and diff against local state.", "why_default_matters": "10s keeps state drift below one reconcile cycle; polling more often wastes rate-limit budget.", "threshold_logic": [ { "condition": "interval <= 10s", "action": "Normal reconcile cadence" }, { "condition": "interval > 30s", "action": "WARN \u2014 reconciliation lag risk" }, { "condition": "interval > 60s", "action": "Reject config \u2014 PARAMETER_CHANGE_REQUIRES_APPROVAL" } ], "dev_check": "assert params.reconcile_interval_s <= params.hard", "user_facing": "Order status is updated from the exchange every few seconds." }, { "name": "auto_cancel_orphans", "default": true, "warning": "\u2014", "hard": "\u2014", "controls": "Automatically cancel any order found during reconcile that has no owning strategy record.", "why_default_matters": "Orphaned orders must be cancelled to reclaim position budget; leaving them risks unintended fills.", "threshold_logic": [ { "condition": "orphan detected AND auto_cancel_orphans=true", "action": "Cancel order; emit ORDER_ORPHAN_CANCELLED" }, { "condition": "orphan detected AND auto_cancel_orphans=false", "action": "WARN only \u2014 operator must cancel manually" } ], "dev_check": "if orphan and params.auto_cancel_orphans: clob_auth.DELETE('/order/' + order_id)", "user_facing": "An unrecognised order was found and cancelled to protect your account." }, { "name": "publish_audit_log", "default": true, "warning": "\u2014", "hard": "\u2014", "controls": "Emit a full state-transition audit log entry (with builder_code) to the WAL on every order lifecycle event.", "why_default_matters": "Audit logs are required for 7-year retention compliance; disabling is only allowed in isolated test environments.", "threshold_logic": [ { "condition": "publish_audit_log=true", "action": "Every transition emitted to WAL with trace_id and builder_code" }, { "condition": "publish_audit_log=false", "action": "WARN \u2014 audit log disabled; only permitted in test mode" } ], "dev_check": "if params.publish_audit_log: wal.append(transition_record)", "user_facing": "Every change to your order is logged for transparency and record-keeping." } ], "default_config": { "bot_id": "exec.orderlifecyclemanager", "version": "0.1.0", "mode": "shadow_only", "defaults": { "stuck_order_timeout_s": 30, "reconcile_interval_s": 10, "auto_cancel_orphans": true, "publish_audit_log": true }, "locked": { "stuck_order_timeout_s": { "max": 120 }, "reconcile_interval_s": { "max": 60 } } }, "implementation_flow": [ "On receipt of a signed order from SmartRouter, create an order state record: {order_id, market_id, side, price, size_usd, status=PENDING_ACK, submit_ms, builder_code}.", "Subscribe to ws_user feed for fill, cancel, and expire events on this order.", "On CLOB V2 ack received: transition status PENDING_ACK \u2192 OPEN; emit ExecutionReport(status=OPEN).", "On partial fill event: update filled_usd, remaining_usd; emit ExecutionReport(status=PARTIAL); forward to PartialFillHandler.", "On full fill event: transition status \u2192 FILLED; emit ExecutionReport(status=FILLED); forward to FillQualityAnalyzer.", "On cancel/expire event: transition status \u2192 CANCELLED or EXPIRED; emit ExecutionReport.", "Every reconcile_interval_s: fetch clob_auth /orders/open; diff against local state; detect orphans and stuck orders.", "On stuck order (age > stuck_order_timeout_s): cancel via clob_auth DELETE /order/{id}; emit ORDER_STUCK reason code.", "On orphan detected and auto_cancel_orphans=true: cancel via clob_auth; emit ORDER_ORPHAN_CANCELLED.", "On KillSwitch active: cancel all open orders; emit KILL_SWITCH_ACTIVE for each; halt further processing." ], "decision_logic": { "approve": "Order lifecycle event is processed normally; state transitions recorded and ExecutionReport emitted.", "reshape_required": "Reconciliation detects a state discrepancy; local state overwritten with exchange-authoritative state.", "reject": "KillSwitch active or order stuck beyond hard threshold \u2014 cancel order, emit HARD_REJECT reason code.", "warning_only": "Order approaching stuck threshold or reconcile interval exceeds warning level \u2014 emit WARN, continue." }, "decision_output_schema": "ExecutionReport", "decision_output_example": { "report_id": "rep_1a2b3c4d5e6f7a8b", "trace_id": "trc_9f8e7d6c5b4a3f2e", "bot_id": "exec.orderlifecyclemanager", "order_id": "0xaaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666aaaa7777bbbb8888", "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b", "side": "BUY", "status": "PARTIAL", "filled_usd": 150, "remaining_usd": 300, "collateral": "pUSD", "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000", "eip712_domain_version": "2", "evaluated_at_ms": 1746770000000 }, "developer_log": { "report_id": "rep_1a2b3c4d5e6f7a8b", "order_id": "0xaaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666aaaa7777bbbb8888", "status_from": "OPEN", "status_to": "PARTIAL", "filled_usd": 150, "remaining_usd": 300, "reconcile_diff": null, "stuck_age_s": 0, "orphan": false, "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000", "evaluated_at_ms": 1746770000000 }, "user_explanations": [ { "situation": "Order partially filled", "message": "Part of your order was filled. The remaining portion is still open in the market." }, { "situation": "Order stuck \u2014 cancelled", "message": "Your order did not receive a response from the exchange within the expected time and was cancelled for safety." }, { "situation": "Orphaned order cancelled", "message": "An unrecognised order was found on your account and cancelled to protect your balance." } ], "failure_modes": { "main_failure_mode": "ws_user feed disconnects silently, causing fill events to be missed and local state to diverge from exchange state until the next reconcile poll.", "false_positive_risk": "Declaring an order stuck during a legitimate CLOB latency spike, causing a premature cancel and missed fill.", "false_negative_risk": "Reconcile interval too long means orphaned orders linger and consume position budget for up to reconcile_interval_s seconds.", "safe_fallback": "If ws_user feed is unavailable, fall back to polling clob_auth /orders every reconcile_interval_s. If clob_auth is unreachable, hold state and emit WARN; escalate to KillSwitch if unreachable > 60s.", "required_dependencies": [ "ws_user fill/cancel/expire feed", "clob_auth /orders/open endpoint", "KillSwitch active flag" ] }, "acceptance_tests": { "unit": [ { "test": "PENDING_ACK \u2192 OPEN transition on ack", "setup": "Submit order; inject ack event", "expected": "status=OPEN, ExecutionReport emitted" }, { "test": "OPEN \u2192 PARTIAL on partial fill", "setup": "Inject partial fill event; filled=150, size=450", "expected": "remaining_usd=300, status=PARTIAL" }, { "test": "Stuck order cancelled after timeout", "setup": "age_since_submit=90s, stuck_order_timeout_s=30", "expected": "cancel issued, ORDER_STUCK emitted" }, { "test": "Orphan auto-cancelled when auto_cancel_orphans=true", "setup": "Reconcile finds order_id with no local record", "expected": "DELETE /order/{id} issued, ORDER_ORPHAN_CANCELLED emitted" } ], "integration": [ { "test": "Full lifecycle: submit \u2192 ack \u2192 partial fill \u2192 full fill", "expected": "All transitions recorded; final status=FILLED; ExecutionReport emitted to polytraders.reports.execution" }, { "test": "ws_user feed disconnect \u2192 reconcile fallback \u2192 state restored", "expected": "After reconnect, state matches clob_auth; no duplicate events emitted" } ], "property": [ { "property": "Order state always moves forward (no regression from FILLED/CANCELLED to OPEN)", "required": "Always true" }, { "property": "builder_code present on every emitted ExecutionReport", "required": "Always true" } ] }, "checklist_overrides": {}, "legacy_goal": "Single source of truth for every order's state machine, from intent to terminal.", "legacy_pm_signals": [ "Order acks, partial fills, full fills, replaces, cancels, rejects, expirations", "Builder-attribution metadata on every transition", "Reconciliation against CLOB V2 user-state endpoint each tick", "Detected stuck-in-flight orders and orphaned acks" ], "legacy_external_feeds": [], "reporting_groups": [ "execution" ], "network": [ "polygon" ], "api_surface": [ "clob_auth", "ws_user", "internal" ], "version": { "spec": "2.0.0", "implementation": "0.1.0", "schema": "2", "released": null, "planned_release": "Q4-2026" }, "migration_history": [ { "date": "2026-04-28", "from": "n/a", "to": "v2-spec", "reason": "Spec drafted post-CLOB-V2 cutover; bot not yet implemented", "action_taken": "Designed against V2 schema (pUSD, builder codes, V2 EIP-712 domain)" } ], "polymarket_v2_compat": { "clob_version": "v2", "collateral": "pUSD", "eip712_domain_version": "2", "builder_code_aware": true, "negrisk_aware": false, "multichain_ready": false, "sdk_used": "py-clob-client-v2", "settlement_contract": "CTFExchangeV2", "notes": "Every ExecutionReport includes builder_code (bytes32) from the originating signed order for builder attribution on all lifecycle transitions." }, "reference_implementation": { "pseudocode": "FUNCTION manageLifecycle(order):\n // 1. Initialise state\n state = {order_id: order.id, status: 'PENDING_ACK',\n submit_ms: now_ms(), filled_usd: 0,\n builder_code: order.builder_code}\n store.put(order.id, state)\n\n // 2. Subscribe to ws_user events\n ws_user.subscribe('order_update', order.market_id, order.id)\n\n // 3. Process ws_user events\n ON ws_user EVENT e WHERE e.order_id == order.id:\n IF e.type == 'ACK':\n state.status = 'OPEN'\n ELIF e.type == 'PARTIAL_FILL':\n state.filled_usd += e.fill_usd\n state.status = 'PARTIAL'\n FORWARD TO partialfillhandler(state)\n ELIF e.type == 'FILL':\n state.status = 'FILLED'\n FORWARD TO fillqualityanalyzer(state)\n ELIF e.type IN ('CANCEL', 'EXPIRE'):\n state.status = e.type\n EMIT ExecutionReport(state)\n\n // 4. Reconcile loop (every reconcile_interval_s)\n EVERY params.reconcile_interval_s:\n live = FETCH clob_auth.GET('/orders/open')\n FOR order_id IN store.all_open():\n IF order_id NOT IN live AND store.status != 'FILLED':\n state.status = 'RECONCILE_DISCREPANCY'\n EMIT ExecutionReport(state, WARN)\n FOR order_id IN live:\n IF order_id NOT IN store:\n IF params.auto_cancel_orphans:\n clob_auth.DELETE('/order/' + order_id)\n EMIT ExecutionReport(ORDER_ORPHAN_CANCELLED)\n\n // 5. Stuck-order check\n IF state.status == 'PENDING_ACK':\n age_s = (now_ms() - state.submit_ms) / 1000\n IF age_s > params.stuck_order_timeout_s:\n clob_auth.DELETE('/order/' + state.order_id)\n EMIT ExecutionReport(state, HARD_REJECT, ORDER_STUCK)", "sdk_calls": [ "ws_user.subscribe('order_update', market_id, order_id)", "clob_auth.GET('/orders/open')", "clob_auth.DELETE('/order/' + order_id)" ], "complexity": "O(N) per reconcile where N = open orders" }, "wire_examples": { "input": [ { "label": "ws_user partial fill event", "source": "ws_user", "payload": { "order_id": "0xaaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666aaaa7777bbbb8888", "type": "PARTIAL_FILL", "fill_usd": 150, "fill_price": 0.62, "fill_ts_ms": 1746770000000, "collateral": "pUSD" } } ], "output": [ { "label": "ExecutionReport \u2014 PARTIAL status", "payload": { "report_id": "rep_1a2b3c4d5e6f7a8b", "trace_id": "trc_9f8e7d6c5b4a3f2e", "bot_id": "exec.orderlifecyclemanager", "order_id": "0xaaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666aaaa7777bbbb8888", "status": "PARTIAL", "filled_usd": 150, "remaining_usd": 300, "collateral": "pUSD", "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000", "evaluated_at_ms": 1746770000000 } } ] }, "reason_codes": [ { "code": "ORDER_LIFECYCLE_TRANSITION", "severity": "INFO", "meaning": "Normal state transition recorded.", "action": "Emit ExecutionReport; no intervention required.", "user_message": "" }, { "code": "ORDER_STUCK", "severity": "HARD_REJECT", "meaning": "Order has been PENDING_ACK beyond stuck_order_timeout_s.", "action": "Cancel order via clob_auth; emit ExecutionReport.", "user_message": "Your order was cancelled because the exchange did not acknowledge it in time." }, { "code": "ORDER_ORPHAN_CANCELLED", "severity": "WARN", "meaning": "Order found during reconcile with no owning strategy record.", "action": "Cancel order; log warning.", "user_message": "An unrecognised order on your account was cancelled." }, { "code": "KILL_SWITCH_ACTIVE", "severity": "HARD_REJECT", "meaning": "Global kill switch active; cancel all open orders.", "action": "Cancel all open orders; halt processing.", "user_message": "Trading is currently paused." }, { "code": "RECONCILE_DISCREPANCY", "severity": "WARN", "meaning": "Local state does not match exchange state after reconcile poll.", "action": "Overwrite local state with exchange state; emit WARN.", "user_message": "" } ], "metrics": { "emitted": [ { "name": "polytraders_exec_orderlifecyclemanager_transitions_total", "type": "counter", "unit": "count", "labels": [ "status" ], "meaning": "Total order state transitions by terminal or intermediate status." }, { "name": "polytraders_exec_orderlifecyclemanager_stuck_orders_total", "type": "counter", "unit": "count", "labels": [], "meaning": "Total orders cancelled due to stuck-in-flight timeout." }, { "name": "polytraders_exec_orderlifecyclemanager_reconcile_discrepancies_total", "type": "counter", "unit": "count", "labels": [], "meaning": "Total reconcile cycles that found a state discrepancy." }, { "name": "polytraders_exec_orderlifecyclemanager_open_orders", "type": "gauge", "unit": "count", "labels": [], "meaning": "Current number of open orders tracked by the state machine." } ], "alerts": [ { "name": "OLMStuckOrderRate", "condition": "rate(polytraders_exec_orderlifecyclemanager_stuck_orders_total[5m]) > 0.1", "severity": "P2", "runbook": "#runbook-olm-stuck-orders" }, { "name": "OLMReconcileDiscrepancy", "condition": "rate(polytraders_exec_orderlifecyclemanager_reconcile_discrepancies_total[5m]) > 0.05", "severity": "P1", "runbook": "#runbook-olm-reconcile" } ] }, "state": { "store": "redis", "shape": "Hash keyed by order_id; fields: status, filled_usd, remaining_usd, submit_ms, builder_code", "ttl": "72h after terminal state (FILLED/CANCELLED/EXPIRED)", "recovery": "On restart, re-read open order state from clob_auth and rebuild local map.", "size_estimate": "~200 bytes per order; ~1 MB for 5000 concurrent orders" }, "concurrency": { "execution_model": "event-driven single-threaded loop per order", "max_in_flight": 200, "idempotency_key": "order_id + event_type + event_ts_ms", "timeout_ms": 500, "backpressure": "shed oldest pending reconcile if queue > 200", "locking": "per-order_id mutex for state writes" }, "dependencies": { "depends_on": [ { "bot_id": "exec.smart_router", "why": "Provides signed order with builder_code to initialise state.", "contract": "Order state record created only after SmartRouter emits signed order." }, { "bot_id": "risk.kill_switch", "why": "KillSwitch triggers mass cancel of all open orders.", "contract": "No open order survives an active KillSwitch." } ], "emits_to": [ { "bot_id": "exec.partialfillhandler", "why": "Forwards PARTIAL status events for remainder policy decisions.", "contract": "PartialFillHandler receives state with filled_usd and remaining_usd." }, { "bot_id": "exec.fillqualityanalyzer", "why": "Forwards FILLED events for fill quality scoring.", "contract": "FillQualityAnalyzer receives final ExecutionReport with fill price and size." } ], "sibling": [], "external": [ { "service": "CLOB V2 auth API", "endpoint": "https://clob.polymarket.com", "sla": "99.95% / 200ms p99", "failure_mode": "Fall back to ws_user-only state; escalate if unreachable > 60s." }, { "service": "WS user feed", "endpoint": "wss://ws-subscriptions-clob.polymarket.com/ws/user", "sla": "best-effort", "failure_mode": "Fall back to REST reconcile polling." } ] }, "security_surfaces": { "signs_orders": true, "private_key_access": "signing-only", "abuse_vectors": [ "Injecting a fake FILL event to prematurely close an order and suppress further fills", "Flooding the reconcile endpoint to exhaust rate limits and prevent orphan detection" ], "mitigations": [ "ws_user event signatures validated against CLOB V2 HMAC; unsigned events discarded", "Reconcile rate-limit budget tracked; if exhausted, local state is trusted and WARN emitted" ] }, "failure_injection": [ { "scenario": "WS_USER_DISCONNECT", "how_to_inject": "Kill ws_user WebSocket connection", "expected_behaviour": "Bot falls back to clob_auth polling; state restored on reconnect; WARN emitted", "recovery": "WebSocket reconnects; event replay from last seq_id" }, { "scenario": "STUCK_ORDER_TIMEOUT", "how_to_inject": "Block CLOB ack for target order for 90s", "expected_behaviour": "ORDER_STUCK emitted; cancel issued after stuck_order_timeout_s=30s", "recovery": "Automatic; next order proceeds normally" }, { "scenario": "KILL_SWITCH_ON", "how_to_inject": "Set killswitch.active=true with 3 open orders", "expected_behaviour": "All 3 orders cancelled; KILL_SWITCH_ACTIVE emitted per order; no new orders processed", "recovery": "Manual KillSwitch reset required" } ], "runbook": { "summary": "OLM incidents are usually ws_user feed disconnects causing reconcile lag, or a burst of stuck orders during CLOB latency spikes.", "oncall_actions": [ { "alert": "OLMStuckOrderRate", "first_step": "Check CLOB latency dashboard; if elevated, extend stuck_order_timeout_s temporarily.", "diagnosis": "", "mitigation": "", "escalation": "Exec pod lead if stuck rate > 0.5/min sustained" }, { "alert": "OLMReconcileDiscrepancy", "first_step": "Compare local order state dump with clob_auth /orders/open; identify which orders diverged.", "diagnosis": "", "mitigation": "", "escalation": "Exec pod lead + infra if discrepancy persists > 10 min" } ], "manual_overrides": [ { "name": "force_cancel_order", "how": "polytraders bot cancel-order exec.orderlifecyclemanager --order ", "when": "Manual intervention required to cancel a stuck or orphaned order.", "command": "polytraders bot cancel-order exec.orderlifecyclemanager --order ", "effect": "Manual intervention required to cancel a stuck or orphaned order." } ], "healthcheck": "GET /internal/health/orderlifecyclemanager \u2192 green if ws_user feed connected, clob_auth reachable, open_orders gauge stable, reconcile running within interval; red if ws_user disconnected > 30s, clob_auth unreachable, stuck_orders_total spiking" }, "promotion_gates": { "to_shadow": [ { "gate": "All unit tests pass including state-machine invariants", "how_measured": "CI test run", "threshold": "100% pass" } ], "to_limited_live": [ { "gate": "Reconcile discrepancy rate < 0.1% over 48h shadow run", "how_measured": "polytraders_exec_orderlifecyclemanager_reconcile_discrepancies_total", "threshold": "< 0.1%" } ], "to_general_live": [ { "gate": "Zero orphaned orders surviving > 1 reconcile cycle over 7-day limited-live", "how_measured": "Audit log cross-reference", "threshold": "Zero violations" } ] }, "reporting": { "emits_kinds": [ "ExecutionReport" ], "topics": [ "polytraders.reports.execution" ], "partition_key": "trace_id", "cadence": "every-event", "retention_class": "7y", "sampling_rule": "emit-every", "bus_failure_action": "wal-then-retry", "user_visible": "yes", "consumes_kinds": [ "DecisionReport" ] }, "capital_impact": "Direct", "mode_support": [ "quarantine" ], "v3_status": { "phase": 5, "phase_name": "Execution rails", "docs": { "done": 27, "total": 27, "state": "done" }, "impl": { "done": 0, "total": 15, "state": "pending" }, "runtime": { "done": 0, "total": 8, "state": "pending" }, "overall": "pending" } }