5.7 ChainStateVerifier

1. Bot Identity

Operational profile

2. Purpose

Cross-check every order’s chain-derived inputs (nonce, balance, allowance) against multiple sources before signing.

3. Why This Bot Matters

• Single RPC source used for nonce/balance without cross-checking

  A stale or compromised RPC causes double-spend attempts or orders built on wrong nonce.

• Reorg not detected before signing

  An order signed on top of a reorged block may reference a state that no longer exists, causing failed settlement.

• Balance check skipped

  Orders submitted without sufficient pUSD collateral fail at settlement, wasting gas and degrading UX.

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

{ "require_quorum": 2 }

if (agreeing.count < p.require_quorum) return reject('CHAIN_STATE_MISMATCH');

{ "halt_on_mismatch": true }

if (p.halt_on_mismatch && !quorumAgreesOnBlockHash()) return reject('CHAIN_STATE_MISMATCH');

8. Default Configuration

{
  "bot_id": "sec.chain_state_verifier",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "require_quorum": 2,
    "halt_on_mismatch": true,
    "reorg_depth_alert": 2,
    "publish_to": [
      "governance_audit",
      "risk_compliance"
    ]
  }
}

9. Implementation Flow

1. Receive order before signing.
2. Check KillSwitch; if active, REJECT(KILL_SWITCH_ACTIVE).
3. FETCH primary provider from RPCFailoverManager.
4. FETCH block_number and block_hash from primary and at least one secondary provider.
5. Compare block hashes at same block_number across providers.
6. If mismatch detected and halt_on_mismatch=true: REJECT(CHAIN_STATE_MISMATCH).
7. Check reorg depth; if > reorg_depth_alert blocks, emit WARN.
8. FETCH pUSD balance of trading wallet from primary provider.
9. If balance < order.size_usd: REJECT(CHAIN_STATE_MISMATCH) — insufficient collateral.
10. Emit RiskVote(APPROVE) with block_hash, block_number, and balance snapshot.

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.

// ChainStateVerifier
FUNCTION verifyChainState(pendingOrder, providers):
  IF FETCH(internal.killswitch).active:
    EMIT RiskVote(DENY, KILL_SWITCH_ACTIVE); RETURN
  // Fetch block state from multiple providers
  blockStates = []
  FOR provider IN providers:
    state = FETCH(provider.eth_getBlockByNumber('latest'))
    IF state != null: blockStates.append({provider, block_number: state.number, hash: state.hash})
  // Quorum check on block hash
  hashCounts = COUNT_BY(blockStates, x => x.hash)
  topHash = hashCounts.max_count_hash
  agreeing = blockStates.filter(x => x.hash == topHash)
  IF agreeing.count < params.require_quorum:
    EMIT RiskVote(DENY, CHAIN_STATE_MISMATCH); RETURN
  // Balance check
  balance = FETCH(primary.erc20.balanceOf(pUSD, pendingOrder.wallet))
  IF balance < pendingOrder.size_usd:
    EMIT RiskVote(DENY, CHAIN_STATE_MISMATCH); RETURN
  EMIT RiskVote(APPROVE, {block_number: topHash.block_number, balance})
  LOG(governance.audit, {block_number, balance, quorum_count: agreeing.count})

SDK calls used

• provider.eth_getBlockByNumber('latest')
• provider.erc20.balanceOf(pUSD_ADDRESS, wallet)
• internal.killswitch.status()

Complexity: O(p) where p = provider count; single block per provider

11. Wire Examples

Input — what arrives on the wire

Pending order requiring chain state check — internal

{
  "intent_id": "int_6f7a8b9c0d1e2f3a",
  "wallet": "0xUserWallet123",
  "size_usd": 400,
  "contract_address": "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
  "timestamp_ms": 1746768672000
}

Output — what the bot emits

RiskVote — APPROVE

{
  "vote_id": "sec.chain_state_verifier.20260509T180000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "evidence": {
    "block_number": 58420100,
    "quorum_count": 3,
    "balance_pusd": 1200
  },
  "checked_at": "2026-05-09T18:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "vote_id": "sec.chain_state_verifier.20260509T180000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "evidence": {
    "block_number": 58420100,
    "block_hash": "0xabc123def456",
    "quorum_count": 3,
    "balance_pusd": 1200,
    "order_size_pusd": 400
  },
  "checked_at": "2026-05-09T18:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "sec.chain_state_verifier",
  "decision": "APPROVE",
  "inputs_used": [
    "onchain.block_hash",
    "onchain.pusd_balance",
    "rpc_failover.primary"
  ],
  "checked_at": "2026-05-09T18:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Re-fetch from all providers on restart; fail-closed if quorum unavailable.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Colluding RPC providers presenting a forged fork to pass quorum check
• Stale balance read causing order submission despite insufficient pUSD

Mitigations

• Quorum requires agreement across independently configured providers
• Balance checked immediately before signing; no caching of positive balance

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

ChainStateMismatch is a P0 event. Investigate provider disagreement immediately — could indicate network attack or RPC failure.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/chainstateverifier → green if Quorum met; last successful verification within 10s.; red if Quorum < require_quorum or no successful verification in 60s.

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%