2.4 NonceShepherd

1. Bot Identity

Operational profile

2. Purpose

NonceShepherd manages the on-chain nonce sequence for the Polytraders signing wallet on Polygon, ensuring that every V2 EIP-712 signed order carries a valid, non-colliding nonce. It detects nonce gaps (caused by dropped or reverted transactions), resequences pending orders when a gap is found, and enforces a ceiling on the number of pending signed-but-unposted orders. NonceShepherd also tracks CLOB ClobAuth credential TTLs and triggers re-authentication before they expire.

3. Why This Bot Matters

• Duplicate nonce on two simultaneous orders

  CTFExchangeV2 rejects one of the two orders; fill rate drops and the strategy misses partial execution on fast-moving markets.

• Nonce gap after a reverted transaction

  All orders with nonces above the gap are stuck pending on-chain; they cannot fill until the gap is resolved, potentially leaving open risk positions unhedged.

• Pending order count exceeds threshold

  Signing queue backs up; later orders are assigned nonces that depend on earlier unfilled orders, creating a chain of blocked submissions.

• Expired ClobAuth credential

  CLOB POST /order returns 401; orders cannot be submitted until re-authentication completes, causing submission blackout.

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

{ "pending_orders_threshold": 10 }

if pending_count >= params.hard: raise NonceQueueFullError('NONCE_SHEPHERD_QUEUE_FULL')

{ "resequence_on_gap": true }

if nonce_gap and params.resequence_on_gap: resequence_pending_above(gap_nonce)

{ "refuse_during_gap_s": 30 }

if gap_age_s > params.hard: emit_alert('NONCE_SHEPHERD_GAP_UNRESOLVED')

{ "l2_credential_ttl_h": 24 }

if cred.expires_at - now_ms() < params.l2_credential_ttl_h * 3600 * 1000: schedule_reauth()

8. Default Configuration

{
  "bot_id": "exec.nonce_shepherd",
  "version": "2.1.0",
  "mode": "general_live",
  "defaults": {
    "pending_orders_threshold": 10,
    "resequence_on_gap": true,
    "refuse_during_gap_s": 30,
    "l2_credential_ttl_h": 24
  },
  "locked": {
    "pending_orders_threshold": {
      "max": 20
    }
  }
}

9. Implementation Flow

1. Receive ExecutionPlan from SmartRouter including order parameters and builderCode (bytes32).
2. Check current pending-order count; if >= pending_orders_threshold hard limit, emit HARD_REJECT with NONCE_SHEPHERD_QUEUE_FULL.
3. Fetch current on-chain nonce for signing wallet via onchain RPC eth_getTransactionCount('latest').
4. Compare on-chain nonce to internal sequence table; detect any gap (on-chain nonce > highest unconfirmed internal nonce).
5. If gap detected and resequence_on_gap=true: mark gap, hold new signing for refuse_during_gap_s seconds, re-sign pending orders above gap with corrected nonces.
6. If gap_age_s > refuse_during_gap_s hard limit: emit NONCE_SHEPHERD_GAP_UNRESOLVED alert and pause signing.
7. Assign next available nonce to the incoming order; record assignment in internal sequence table.
8. Check ClobAuth credential TTL; if time_to_expiry < l2_credential_ttl_h: trigger background re-auth.
9. Inject nonce and builderCode (bytes32) into the order payload; forward to wallet adapter for EIP-712 signing.
10. After CLOB POST /order confirms receipt, mark nonce as consumed in sequence table.
11. On fill or cancellation confirmation, remove the nonce entry from the pending table.

10. Reference Implementation

Receives an ExecutionPlan, assigns the next available on-chain nonce, injects the builderCode (bytes32), checks ClobAuth credential TTL, and emits a NonceAssignment for the wallet adapter to sign. Detects and resequences nonce gaps automatically.

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

FUNCTION assignNonce(execution_plan):
  // --- 1. Pending queue gate ---
  pending = FETCH internal.nonce_sequence_table.pending_count()
  IF pending >= params.pending_orders_threshold_hard:
    EMIT HARD_REJECT NONCE_SHEPHERD_QUEUE_FULL
    RETURN

  // --- 2. Fetch on-chain nonce ---
  onchain_nonce = FETCH onchain_rpc.eth_getTransactionCount(wallet_address, 'latest')
  IF onchain_nonce IS NULL:
    EMIT HARD_REJECT NONCE_SHEPHERD_RPC_FAILURE
    RETURN

  // --- 3. Detect nonce gap ---
  seq_head = internal.nonce_sequence_table.highest_pending()
  IF onchain_nonce < seq_head - pending:  // gap exists
    gap_nonce = onchain_nonce
    EMIT WARN NONCE_SHEPHERD_GAP_DETECTED
    IF params.resequence_on_gap:
      resequenced = resequence_pending_above(gap_nonce)
      // re-sign each affected order with corrected nonce
      FOR order IN resequenced:
        order.nonce = order.corrected_nonce
        wallet.sign(buildOrderTypedData(order, { version: '2' }))
    ELSE:
      hold_new_signing(refuse_during_gap_s=params.refuse_during_gap_s)
    gap_age_s = now_s() - gap_detected_at_s
    IF gap_age_s > params.refuse_during_gap_s_hard:
      EMIT ALERT NONCE_SHEPHERD_GAP_UNRESOLVED
      RETURN

  // --- 4. Assign nonce ---
  next_nonce = seq_head + 1
  internal.nonce_sequence_table.reserve(next_nonce, execution_plan.intent_id)

  // --- 5. Inject builderCode (bytes32) ---
  // V2 order field: builder(bytes32) — required for builder attribution
  builder_code = config.builder_code  // 32-byte hex from config

  // --- 6. ClobAuth credential TTL check ---
  cred = FETCH internal.clob_auth_credentials()
  ttl_h = (cred.expires_at - now_ms()) / 3_600_000
  IF ttl_h <= 0:
    EMIT HARD_REJECT NONCE_SHEPHERD_CREDENTIAL_EXPIRED
    RETURN
  IF ttl_h < params.l2_credential_ttl_h:
    schedule_background_reauth()
    EMIT WARN NONCE_SHEPHERD_CREDENTIAL_RENEWING

  // --- 7. Emit NonceAssignment ---
  EMIT NonceAssignment({
    intent_id: execution_plan.intent_id,
    assigned_nonce: next_nonce,
    builder_code: builder_code,       // bytes32
    eip712_domain_version: '2',
    clob_auth_domain_version: '1',
    credential_ttl_remaining_h: ttl_h,
    pending_count_after: pending + 1,
    assigned_at_ms: now_ms()
  })

SDK calls used

• onchain_rpc.eth_getTransactionCount(wallet_address, 'latest')
• buildOrderTypedData(orderParams, { name: 'CTFExchange', version: '2', chainId: 137 })
• clob_auth.POST('/auth/api-key', credentials)
• wallet.sign(typedData)

Complexity: O(N) for resequencing where N = number of pending orders above the gap; O(1) in the normal (no-gap) path

11. Wire Examples

Input — what arrives on the wire

{
  "label": "ExecutionPlan from SmartRouter awaiting nonce assignment",
  "source": "exec.smart_router",
  "payload": {
    "intent_id": "int_9a0b1c2d3e4f5a6b",
    "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "side": "SELL",
    "outcome": "YES",
    "order_type": "GTC",
    "tick_aligned_price": 0.71,
    "size_usd": 300,
    "iceberg": false,
    "eip712_domain_version": "2",
    "generated_at_ms": 1746768990000
  }
}

Output — what the bot emits

{
  "label": "NonceAssignment — nonce assigned, builderCode injected",
  "payload": {
    "shepherd_id": "exec.nonce_shepherd",
    "intent_id": "int_9a0b1c2d3e4f5a6b",
    "assigned_nonce": 1042,
    "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "eip712_domain_version": "2",
    "clob_auth_domain_version": "1",
    "credential_ttl_remaining_h": 22.5,
    "pending_count_after": 7,
    "assigned_at_ms": 1746769000000
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a NonceAssignment object. See NonceAssignment schema.

{
  "shepherd_id": "exec.nonce_shepherd",
  "intent_id": "int_9a0b1c2d3e4f5a6b",
  "assigned_nonce": 1042,
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "eip712_domain_version": "2",
  "clob_auth_domain_version": "1",
  "credential_ttl_remaining_h": 22.5,
  "pending_count_after": 7,
  "assigned_at_ms": 1746769000000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Execution / NonceShepherd
• Grafana — Order signing / nonce gap history and pending queue depth

16. Developer Reporting

{
  "shepherd_id": "exec.nonce_shepherd",
  "intent_id": "int_9a0b1c2d3e4f5a6b",
  "assigned_nonce": 1042,
  "on_chain_nonce": 1040,
  "gap_detected": false,
  "pending_count_before": 6,
  "pending_count_after": 7,
  "credential_ttl_remaining_h": 22.5,
  "resequence_triggered": false,
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "assigned_at_ms": 1746769000000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, Redis nonce table is replayed to reconstruct pending state. Any nonce without on-chain confirmation is treated as potentially gapped and re-verified via RPC.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

2.3

External services

23. Security Surfaces

Abuse vectors considered

• Injecting a crafted nonce into the sequence table to displace a legitimate pending order
• Replaying a stale NonceAssignment with an already-consumed nonce to force a CTFExchangeV2 rejection and DOS the submission pipeline
• Manipulating ClobAuth credential TTL to prevent timely renewal, causing a submission blackout

Mitigations

• Redis nonce table write access restricted to NonceShepherd service account via ACL
• NonceAssignment records are HMAC-signed; consumers reject tampered records
• Nonce deduplication: each nonce can only be in state pending|consumed — duplicate reservation rejected
• ClobAuth re-auth triggered 24h before expiry providing a large retry buffer

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

NonceShepherd incidents are nonce gap events (usually caused by reverted transactions), queue full conditions during high-throughput periods, or ClobAuth credential expiry. All three cause submission blackouts of varying severity.

On-call actions

Manual overrides

• polytraders bot resequence exec.nonce_shepherd --from-nonce <N> — Manually triggers nonce resequencing from nonce N. Use when automatic resequencing fails.
• polytraders bot reauth exec.nonce_shepherd — Forces immediate ClobAuth credential renewal. Use when automatic re-auth has failed or credential is near expiry.

Healthcheck

GET /internal/health/nonceshepherd → 200 if no active gap, pending_count < 15, ClobAuth credential valid > 2h, RPC reachable. RED if active nonce gap > refuse_during_gap_s, pending_count >= 20, credential expired, or RPC unreachable.

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%