2.6 OrderLifecycleManager

1. Bot Identity

Operational profile

2. 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.

3. Why This Bot Matters

• Order state out of sync

  Strategy layer acts on stale position data, potentially doubling into a filled position or missing a cancellation.

• Stuck-in-flight order not detected

  An order that never received an ack occupies position budget indefinitely, blocking new orders.

• Orphaned ack not cancelled

  A resting order with no owning strategy leaks capital and may fill at an unintended price.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "stuck_order_timeout_s": 30 }

if now_ms() - order.submit_ms > params.stuck_order_timeout_s * 1000: emit(ORDER_STUCK)

{ "reconcile_interval_s": 10 }

assert params.reconcile_interval_s <= params.hard

{ "auto_cancel_orphans": true }

if orphan and params.auto_cancel_orphans: clob_auth.DELETE('/order/' + order_id)

{ "publish_audit_log": true }

if params.publish_audit_log: wal.append(transition_record)

8. Default Configuration

{
  "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
    }
  }
}

9. Implementation Flow

1. 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}.
2. Subscribe to ws_user feed for fill, cancel, and expire events on this order.
3. On CLOB V2 ack received: transition status PENDING_ACK → OPEN; emit ExecutionReport(status=OPEN).
4. On partial fill event: update filled_usd, remaining_usd; emit ExecutionReport(status=PARTIAL); forward to PartialFillHandler.
5. On full fill event: transition status → FILLED; emit ExecutionReport(status=FILLED); forward to FillQualityAnalyzer.
6. On cancel/expire event: transition status → CANCELLED or EXPIRED; emit ExecutionReport.
7. Every reconcile_interval_s: fetch clob_auth /orders/open; diff against local state; detect orphans and stuck orders.
8. On stuck order (age > stuck_order_timeout_s): cancel via clob_auth DELETE /order/{id}; emit ORDER_STUCK reason code.
9. On orphan detected and auto_cancel_orphans=true: cancel via clob_auth; emit ORDER_ORPHAN_CANCELLED.
10. On KillSwitch active: cancel all open orders; emit KILL_SWITCH_ACTIVE for each; halt further processing.

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

FUNCTION manageLifecycle(order):
  // 1. Initialise state
  state = {order_id: order.id, status: 'PENDING_ACK',
           submit_ms: now_ms(), filled_usd: 0,
           builder_code: order.builder_code}
  store.put(order.id, state)

  // 2. Subscribe to ws_user events
  ws_user.subscribe('order_update', order.market_id, order.id)

  // 3. Process ws_user events
  ON ws_user EVENT e WHERE e.order_id == order.id:
    IF e.type == 'ACK':
      state.status = 'OPEN'
    ELIF e.type == 'PARTIAL_FILL':
      state.filled_usd += e.fill_usd
      state.status = 'PARTIAL'
      FORWARD TO partialfillhandler(state)
    ELIF e.type == 'FILL':
      state.status = 'FILLED'
      FORWARD TO fillqualityanalyzer(state)
    ELIF e.type IN ('CANCEL', 'EXPIRE'):
      state.status = e.type
    EMIT ExecutionReport(state)

  // 4. Reconcile loop (every reconcile_interval_s)
  EVERY params.reconcile_interval_s:
    live = FETCH clob_auth.GET('/orders/open')
    FOR order_id IN store.all_open():
      IF order_id NOT IN live AND store.status != 'FILLED':
        state.status = 'RECONCILE_DISCREPANCY'
        EMIT ExecutionReport(state, WARN)
    FOR order_id IN live:
      IF order_id NOT IN store:
        IF params.auto_cancel_orphans:
          clob_auth.DELETE('/order/' + order_id)
          EMIT ExecutionReport(ORDER_ORPHAN_CANCELLED)

  // 5. Stuck-order check
  IF state.status == 'PENDING_ACK':
    age_s = (now_ms() - state.submit_ms) / 1000
    IF age_s > params.stuck_order_timeout_s:
      clob_auth.DELETE('/order/' + state.order_id)
      EMIT ExecutionReport(state, HARD_REJECT, ORDER_STUCK)

SDK calls used

• 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

11. Wire Examples

Input — what arrives on the wire

ws_user partial fill event — ws_user

{
  "order_id": "0xaaaa1111bbbb2222cccc3333dddd4444eeee5555ffff6666aaaa7777bbbb8888",
  "type": "PARTIAL_FILL",
  "fill_usd": 150,
  "fill_price": 0.62,
  "fill_ts_ms": 1746770000000,
  "collateral": "pUSD"
}

Output — what the bot emits

ExecutionReport — PARTIAL status

{
  "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
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ExecutionReport object. See ExecutionReport schema.

{
  "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
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "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
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, re-read open order state from clob_auth and rebuild local map.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

2.11 2.15 2.7 2.8 6.16 4.16 1.19 5.9

External services

23. Security Surfaces

Abuse vectors considered

• 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

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

OLM incidents are usually ws_user feed disconnects causing reconcile lag, or a burst of stuck orders during CLOB latency spikes.

On-call actions

Manual overrides

• polytraders bot cancel-order exec.orderlifecyclemanager --order <order_id> — Manual intervention required to cancel a stuck or orphaned order.

Healthcheck

GET /internal/health/orderlifecyclemanager → 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

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%