2.3 QueueWarden

1. Bot Identity

Operational profile

2. Purpose

QueueWarden polices the rate at which orders and cancel-replace operations are sent to the Polymarket CLOB V2 and manages the maker queue position of resting orders. It enforces a cap on cancel-replace operations per minute to avoid CLOB rate-limit rejections, monitors drift between the resting quote price and the best bid/ask, and cancels stale resting orders that have not been filled within the stale_ttl_s window. QueueWarden also injects builderCode (bytes32) into cancel-replace messages to maintain builder attribution continuity across order lifecycle events.

3. Why This Bot Matters

• Excessive cancel-replace rate

  Polymarket CLOB V2 enforces per-API-key rate limits. Exceeding them causes 429 rejections, breaking the order submission pipeline and potentially leaving the strategy with unintended open positions.

• Quote drift not corrected

  A resting order priced more than drift_ticks_threshold ticks away from the current best bid/ask is no longer competitive; it accumulates adverse-selection risk without filling.

• Stale resting order not cancelled

  An order sitting in the book beyond stale_ttl_s may fill at a price that no longer reflects the strategy's current view, creating unintended exposure.

• builderCode absent from cancel-replace message

  Builder attribution is broken for the replacement order; maker rebates may not be correctly attributed.

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

Legacy signals migrated from the v1 catalogue. Re-classify into the four-column form before this bot ships.

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "drift_ticks_threshold": 2 }

if drift > params.hard: force_cancel_replace(order_id)

{ "stale_ttl_s": 300 }

if order.resting_s > params.hard: force_cancel(order_id)

{ "cancel_replace_per_min_cap": 30 }

if sliding_window_count(60) >= params.hard: defer_to_next_slot(op)

{ "min_queue_position": 5 }

if queue_pos > params.hard: force_cancel_replace(order_id)

8. Default Configuration

{
  "bot_id": "exec.queue_warden",
  "version": "2.1.0",
  "mode": "general_live",
  "defaults": {
    "drift_ticks_threshold": 2,
    "stale_ttl_s": 300,
    "cancel_replace_per_min_cap": 30,
    "min_queue_position": 5
  },
  "locked": {
    "cancel_replace_per_min_cap": {
      "max": 30
    },
    "stale_ttl_s": {
      "max": 600
    }
  }
}

9. Implementation Flow

1. On each evaluation tick (configurable, default 5s), load the active resting order registry from internal state.
2. For each resting order, fetch the current best bid/ask from the CLOB V2 authenticated book endpoint.
3. Compute price drift in ticks: drift = abs(order.price - best_bid_or_ask) / tick_size.
4. Compute resting time: resting_s = (now_ms() - order.placed_at_ms) / 1000.
5. Fetch queue position for the order from the CLOB V2 order status endpoint.
6. Apply stale TTL check: if resting_s > stale_ttl_s (or > hard limit), mark order for cancellation.
7. Apply drift check: if drift > drift_ticks_threshold (or > hard limit), mark order for cancel-replace.
8. Apply queue position check: if queue_position > min_queue_position (or > hard limit), mark order for cancel-replace.
9. For each marked order: check sliding-window cancel-replace rate counter; if < cancel_replace_per_min_cap, execute cancel-replace immediately.
10. If rate cap reached: queue excess cancel-replace ops for the next available slot; emit WARN QUEUE_WARDEN_RATE_CAP_HIT.
11. On cancel-replace execution: inject builderCode (bytes32) into the replacement order payload before forwarding to NonceShepherd.
12. Update internal order registry with new order_id, price, placed_at_ms after successful cancel-replace.
13. Emit QueueDecision record for each evaluated order with verdict (HOLD / CANCEL_REPLACE / CANCEL_STALE) and reason_code.

10. Reference Implementation

On each evaluation tick, QueueWarden inspects every resting order in the internal registry, computes drift and resting time, and emits a QueueDecision (HOLD / CANCEL_REPLACE / CANCEL_STALE). Cancel-replace ops inject builderCode (bytes32) and are rate-limited by a sliding window counter.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

FUNCTION evaluateOrders():
  // --- 0. Load active orders ---
  orders = FETCH internal.order_registry.all_resting()
  IF orders IS NULL:
    EMIT WARN QUEUE_WARDEN_STATE_UNAVAILABLE
    RETURN

  // --- 1. Fetch rate counter ---
  rate_1m = FETCH internal.rate_counter.sliding_window_count(60)  // ops in last 60s

  FOR order IN orders:
    // --- 2. Fetch best bid/ask from CLOB V2 ---
    book = FETCH clob_auth.GET('/book?token_id=' + order.token_id)
    IF book IS NULL:
      // Safe fallback: cancel rather than leave resting with unknown drift
      EMIT QueueDecision(order, CANCEL_STALE, QUEUE_WARDEN_BOOK_UNAVAILABLE)
      CONTINUE

    best_price = book.best_ask IF order.side == 'BUY' ELSE book.best_bid
    drift_ticks = abs(order.price - best_price) / order.tick_size
    resting_s = (now_ms() - order.placed_at_ms) / 1000

    // --- 3. Queue position check ---
    queue_pos = FETCH clob_auth.GET('/order/' + order.order_id + '/queue_position')

    // --- 4. Determine action ---
    force = (drift_ticks > params.drift_ticks_threshold_hard
             OR resting_s > params.stale_ttl_s_hard
             OR queue_pos > params.min_queue_position_hard)

    IF resting_s > params.stale_ttl_s:
      action = 'CANCEL_STALE'; reason = 'QUEUE_WARDEN_STALE_ORDER'
    ELSE IF drift_ticks > params.drift_ticks_threshold:
      action = 'CANCEL_REPLACE'; reason = 'QUEUE_WARDEN_DRIFT_EXCEEDED'
    ELSE IF queue_pos > params.min_queue_position:
      action = 'CANCEL_REPLACE'; reason = 'QUEUE_WARDEN_QUEUE_DEGRADED'
    ELSE:
      // HOLD — possibly with WARN annotation
      warn = (drift_ticks > params.drift_ticks_threshold - 1
              OR resting_s > params.stale_ttl_s * 0.8)
      EMIT QueueDecision(order, HOLD, None, warn=warn)
      CONTINUE

    // --- 5. Rate-cap check ---
    IF action == 'CANCEL_REPLACE' AND rate_1m >= params.cancel_replace_per_min_cap AND NOT force:
      internal.rate_queue.enqueue(order.order_id, action)
      EMIT WARN QUEUE_WARDEN_RATE_CAP_HIT
      CONTINUE

    // --- 6. Execute cancel ---
    clob_auth.DELETE('/order/' + order.order_id)
    internal.order_registry.remove(order.order_id)

    IF action == 'CANCEL_REPLACE':
      // --- 7. Build replacement with V2 fields + builderCode ---
      replacement = {
        market_id: order.market_id,
        side: order.side,
        price: best_price,  // refreshed to current best
        size_usd: order.size_usd,
        builder_code: config.builder_code,  // bytes32
        eip712_domain_version: '2'
      }
      // Nonce assigned by NonceShepherd before signing
      EMIT NonceAssignmentRequest(replacement)
      internal.rate_counter.increment()

    EMIT QueueDecision(order, action, reason,
                       drift_ticks=drift_ticks, resting_s=resting_s,
                       queue_position=queue_pos,
                       builder_code=config.builder_code,
                       evaluated_at_ms=now_ms())

SDK calls used

• clob_auth.GET('/book?token_id=' + order.token_id)
• clob_auth.GET('/order/' + order.order_id + '/queue_position')
• clob_auth.DELETE('/order/' + order.order_id)
• clob_auth.POST('/order', signed_replacement_order)
• buildOrderTypedData(replacementParams, { name: 'CTFExchange', version: '2', chainId: 137 })

Complexity: O(R) where R = number of resting orders in the registry per evaluation tick

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Resting order evaluated for drift",
  "source": "internal order registry + CLOB V2 book snapshot",
  "payload": {
    "order_id": "0xb2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
    "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "side": "BUY",
    "outcome": "YES",
    "price": 0.65,
    "tick_size": 0.01,
    "size_usd": 200,
    "placed_at_ms": 1746769153000,
    "best_ask_at_eval": 0.68,
    "queue_position": 4
  }
}

Output — what the bot emits

{
  "label": "QueueDecision — CANCEL_REPLACE due to drift",
  "payload": {
    "warden_id": "exec.queue_warden",
    "order_id": "0xb2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
    "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "verdict": "CANCEL_REPLACE",
    "reason_code": "QUEUE_WARDEN_DRIFT_EXCEEDED",
    "drift_ticks": 3,
    "resting_s": 47,
    "queue_position": 4,
    "replacement_price": 0.68,
    "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "eip712_domain_version": "2",
    "evaluated_at_ms": 1746769200000
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a QueueDecision object. See QueueDecision schema.

{
  "warden_id": "exec.queue_warden",
  "order_id": "0xb2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
  "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
  "verdict": "CANCEL_REPLACE",
  "reason_code": "QUEUE_WARDEN_DRIFT_EXCEEDED",
  "drift_ticks": 3,
  "resting_s": 47,
  "queue_position": 4,
  "replacement_price": 0.68,
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "eip712_domain_version": "2",
  "evaluated_at_ms": 1746769200000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Execution / QueueWarden
• Grafana — Order quality / drift distribution and stale order rate

16. Developer Reporting

{
  "warden_id": "exec.queue_warden",
  "order_id": "0xb2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
  "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
  "order_price": 0.65,
  "best_ask": 0.68,
  "drift_ticks": 3,
  "drift_ticks_threshold": 2,
  "resting_s": 47,
  "stale_ttl_s": 300,
  "queue_position": 4,
  "min_queue_position": 5,
  "cancel_replace_rate_1m": 12,
  "cancel_replace_per_min_cap": 30,
  "verdict": "CANCEL_REPLACE",
  "reason_code": "QUEUE_WARDEN_DRIFT_EXCEEDED",
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "evaluated_at_ms": 1746769200000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, order registry is replayed from Redis. Any entry older than stale_ttl_s_hard is immediately cancelled. Rate counter resets on restart.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Manipulating the internal order registry to falsely report high queue positions, triggering excessive cancel-replace churn and burning through the rate cap
• Injecting a false book snapshot to inflate apparent drift and cause unnecessary order refresh operations
• Rate cap exhaustion attack: flooding QueueWarden with resting orders to exhaust cancel_replace_per_min_cap before legitimate orders can be managed

Mitigations

• Order registry write access restricted to QueueWarden and NonceShepherd service accounts via Redis ACL
• Book snapshots fetched directly from Polymarket CLOB V2 authenticated endpoint — not from an internal cache that could be tampered with
• Rate counter enforced per-key sliding window; max 30 ops/min per API key is a hard constraint on the CLOB side as well
• QueueDecision records HMAC-signed; consumers reject tampered records

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

QueueWarden incidents are typically rate-cap exhaustion during volatile markets, CLOB book endpoint degradation causing precautionary mass cancellations, or KillSwitch-triggered mass cancellations. All require coordination with the Strategy pod.

On-call actions

Manual overrides

• polytraders bot cancel-all exec.queue_warden — Immediately cancels all resting orders without waiting for the next evaluation tick. Use in emergencies.
• polytraders bot flush-queue exec.queue_warden --rate — Force-drains the rate-deferred cancel-replace queue after the rate cap is raised or market calms.

Healthcheck

GET /internal/health/queuewarden → 200 if CLOB book endpoint reachable, cancel_replace_rate_1m < 24, rate queue depth < 10, state store connected. RED if CLOB unreachable, rate_1m >= 30, or state store disconnected.

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%