NonceShepherd
NonceShepherd manages the on-chain nonce sequence for the Polytraders signing wallet on Polygon, ensuring that every V2 EIP-712 signed order carries a
What it does
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.
Pipeline placement
Applies to: Every order that will be signed with the Polytraders wallet and submitted via CLOB V2
Why it matters
| If this fails | Consequence |
|---|---|
| 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. |
Inputs
Polymarket inputs
| Input | Source | Required | Use |
|---|---|---|---|
| ClobAuth credential (L2 API key + secret + passphrase) | CLOB V2 auth endpoint | required | Authenticate order submissions to the Polymarket CLOB V2. ClobAuth domain version is '1' (unchanged in V2). |
Internal inputs
| Input | Source | Required | Use |
|---|---|---|---|
| On-chain nonce for signing wallet from Polygon state | onchain RPC (eth_getTransactionCount) | required | Determine the next valid nonce for the pending order; detect gaps by comparing on-chain nonce to internal sequence. |
| Internal pending-order sequence table | internal Redis store | required | Track which nonces have been assigned to signed-but-unposted orders to detect gaps and collisions. |
| ExecutionPlan from SmartRouter | exec.smart_router | required | Receive the order to be signed; assign nonce and inject builderCode (bytes32) before handing off to wallet adapter. |
Authority
What this bot is permitted to do
State
Readiness
General live
Status
live
Class
Execution Utility
Default mode
general_live
Developer owner
Polytraders core
Capital impact
Direct
Reason codes emitted
| Code | Severity | Meaning | Action |
|---|---|---|---|
| NONCE_SHEPHERD_OK | INFO | Nonce assigned successfully; no gap detected; queue healthy. | Emit NonceAssignment; proceed to wallet adapter. |
| NONCE_SHEPHERD_QUEUE_FULL | HARD_REJECT | Pending signed-but-unposted order count has reached the hard ceiling. | Block new signing requests until pending count drops below threshold. |
| NONCE_SHEPHERD_GAP_DETECTED | WARN | A gap in the nonce sequence was detected, indicating a reverted or dropped transaction. | Hold new signing for refuse_during_gap_s; trigger resequencing if resequence_on_gap=true. |
| NONCE_SHEPHERD_GAP_UNRESOLVED | HARD_REJECT | Nonce gap has not resolved within refuse_during_gap_s hard limit. | Pause all new signing; emit alert to on-call; await operator action. |
| NONCE_SHEPHERD_CREDENTIAL_RENEWING | WARN | ClobAuth credential TTL is within l2_credential_ttl_h hours of expiry; background re-auth triggered. | Schedule background re-auth. Continue processing with current credential. |
| NONCE_SHEPHERD_CREDENTIAL_EXPIRED | HARD_REJECT | ClobAuth credential has expired; CLOB submissions will fail with 401. | Block all order submissions until re-auth completes. |
| NONCE_SHEPHERD_RPC_FAILURE | HARD_REJECT | Cannot fetch on-chain nonce from Polygon RPC. | Block new signing. Emit alert. Resume once RPC recovers. |
| KILL_SWITCH_ACTIVE | HARD_REJECT | Global kill switch active; no new nonces assigned. | Block all signing requests. |
Related bots in Execution
Used by
Reverse index — strategies that currently reference exec.nonceshepherd. If you change this bot's authority or reason codes, these strategies must re-pass shadow.
| Strategy | State | Activity |
|---|---|---|
| Crypto Q2 — basket rebalance | frozen | last triggered 20m ago |
| US Elect — book-builder | demo-wired | last triggered 27m ago |
| NBA H2H — moneyline market-make | demo-wired | last triggered 34m ago |
Showing 3 of 3 · demo-wired ≠ production-live
Why this matters
Execution bots does NOT propose new positions; only routes and shapes approved intents. Understanding the authority boundary prevents misuse and makes promotion-gate reviews faster and more reliable. View raw spec JSON →