5.8 ContractAddressGuard

1. Bot Identity

Operational profile

2. Purpose

ContractAddressGuard refuses to allow a signature or on-chain submission against any contract address that is not present on the committed CLOB V2 allow-list. It enforces the EIP-712 domain separator match against the expected V2 domain and rejects any order that targets a V1 Exchange address. This is a hard security control for the V1-to-V2 migration and must not be loosened without an explicit signed-off admin change. It cannot modify orders — it only approves or rejects.

3. Why This Bot Matters

• Order signed against V1 contract after migration

  Funds are sent to a deprecated contract that may not be monitored, potentially locking or losing assets that cannot be recovered through normal settlement.

• Unknown contract address accepted

  Signing an order against an unrecognised contract is the primary vector for phishing and malicious contract substitution attacks in decentralised trading environments.

• Domain separator mismatch not detected

  A forged or misconfigured EIP-712 domain separator could cause a valid-looking signature to be replayed on a different contract or chain, leading to unintended asset transfers.

• No alert on block

  Without an alert every time a suspicious address is blocked, security incidents may not be noticed until significant damage has occurred.

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

{ "v2_addresses": "[]" }

if (!p.v2_addresses.some(a => a.address === order.contract_address && a.chainId === order.chainId)) return reject('CONTRACT_ADDRESS_NOT_ALLOWED');

{ "block_v1_signing": true }

if (p.block_v1_signing && V1_ADDRESSES.has(order.contract_address)) return reject('CONTRACT_ADDRESS_NOT_ALLOWED');

{ "require_domain_match": true }

if (p.require_domain_match && order.domainSeparator !== EXPECTED_V2_DOMAIN) return reject('CONTRACT_ADDRESS_NOT_ALLOWED');

{ "alert_on_block": true }

if (p.alert_on_block && decision === 'REJECT') alerting.emit('SECURITY_BLOCK', { order, reason });

8. Default Configuration

{
  "bot_id": "sec.contract_address_guard",
  "version": "1.0.0",
  "mode": "hard_guard",
  "defaults": {
    "v2_addresses": [],
    "block_v1_signing": true,
    "require_domain_match": true,
    "alert_on_block": true
  },
  "locked": {
    "block_v1_signing": {
      "immutable": true
    },
    "require_domain_match": {
      "immutable": true
    },
    "alert_on_block": {
      "immutable": true
    },
    "v2_addresses": {
      "change_requires_signed_admin_action": true
    }
  }
}

9. Implementation Flow

1. Receive a pending order or OrderIntent before it reaches the signing step.
2. Check KillSwitch active flag; if active, return REJECT immediately with KILL_SWITCH_ACTIVE.
3. Check whether v2_addresses is non-empty; if empty, return REJECT with CONTRACT_ADDRESS_NOT_ALLOWED and log a configuration alert.
4. If block_v1_signing=true, check whether order.contract_address matches any known V1 Exchange address; if matched, return REJECT with CONTRACT_ADDRESS_NOT_ALLOWED.
5. Check order.contract_address and order.chainId against the v2_addresses allow-list; if not found, return REJECT with CONTRACT_ADDRESS_NOT_ALLOWED.
6. If require_domain_match=true, compute the expected EIP-712 domain separator for the V2 contract on the target chain and compare with order.domainSeparator; if mismatch, return REJECT with CONTRACT_ADDRESS_NOT_ALLOWED.
7. Validate order schema against the V2 order specification; if the order uses V1 schema fields, return REJECT with CONTRACT_ADDRESS_NOT_ALLOWED.
8. If alert_on_block=true and any reject was issued, emit a security alert to the monitoring stack with full order metadata.
9. Log the decision (approve or reject), the checked address, chain ID, and timestamp to the governance audit trail via BuilderAttribution.
10. Return APPROVE with inputs_used and checked_at timestamp if all checks pass.

10. Reference Implementation

Validates every pending order against a hardcoded V2 allow-list (CTFExchangeV2, NegRiskAdapter, pUSD ERC-20 on Polygon), verifies the EIP-712 domain separator version is '2', and rejects any order targeting a V1 address.

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

// V2 allow-list — chain ID 137 (Polygon)
CONST V2_ALLOW_LIST = [
  { address: '0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E', label: 'CTFExchangeV2' },
  { address: '0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296', label: 'NegRiskAdapter' },
  { address: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', label: 'pUSD ERC-20' }
]
CONST V1_DENY_LIST = [ '0xC5d563A36AE78145C45a50134d48A1A61A3A4Dc7' ]  // old CTFExchange
CONST EXPECTED_EIP712_DOMAIN_VERSION = '2'

FUNCTION checkContractAddress(pendingOrder):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active:
    EMIT SecurityCheck(decision=DENY, reason=KILL_SWITCH_ACTIVE)
    alerting.emit('SECURITY_BLOCK', { pendingOrder, reason: KILL_SWITCH_ACTIVE })
    RETURN

  // --- 1. V2 allow-list non-empty check ---
  IF V2_ALLOW_LIST.isEmpty():
    EMIT SecurityCheck(decision=DENY, reason=CONTRACT_ADDRESS_NOT_ALLOWED)
    alerting.emit('SECURITY_BLOCK', { pendingOrder, reason: 'allow_list_empty' })
    RETURN

  // --- 2. V1 deny-list check ---
  IF V1_DENY_LIST.includes(pendingOrder.contract_address):
    EMIT SecurityCheck(decision=DENY, reason=CONTRACT_ADDRESS_NOT_ALLOWED)
    alerting.emit('SECURITY_BLOCK', { pendingOrder, reason: 'v1_address_detected' })
    RETURN

  // --- 3. V2 allow-list membership check ---
  matched = V2_ALLOW_LIST.find(
    a => a.address == pendingOrder.contract_address
         AND pendingOrder.chain_id == 137
  )
  IF NOT matched:
    EMIT SecurityCheck(decision=DENY, reason=CONTRACT_ADDRESS_NOT_ALLOWED)
    alerting.emit('SECURITY_BLOCK', { pendingOrder, reason: 'not_in_allow_list' })
    RETURN

  // --- 4. EIP-712 domain separator check ---
  // Domain version must be '2'; ClobAuth domain stays '1'
  IF pendingOrder.eip712_domain_version != EXPECTED_EIP712_DOMAIN_VERSION:
    EMIT SecurityCheck(decision=DENY, reason=CONTRACT_ADDRESS_NOT_ALLOWED)
    alerting.emit('SECURITY_BLOCK', { pendingOrder, reason: 'domain_version_mismatch' })
    RETURN

  // --- 5. V2 order schema check ---
  // V2 schema: timestamp + metadata(bytes32) + builder(bytes32)
  // V1 fields nonce/feeRateBps/taker must be absent
  IF pendingOrder.nonce IS NOT NULL OR pendingOrder.feeRateBps IS NOT NULL:
    EMIT SecurityCheck(decision=DENY, reason=CONTRACT_ADDRESS_NOT_ALLOWED)
    alerting.emit('SECURITY_BLOCK', { pendingOrder, reason: 'v1_schema_fields_present' })
    RETURN

  // --- 6. Log to governance audit trail ---
  EMIT GovernanceLog(event=SECURITY_CHECK_PASSED, order=pendingOrder, allow_list_label=matched.label)

  // --- 7. Happy path ---
  EMIT SecurityCheck(decision=ALLOW, checked_at=now_iso())

Helpers used

SDK calls used

• buildOrderTypedData(pendingOrder, { name: 'CTFExchange', version: '2', chainId: 137, verifyingContract: '0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E' })
• fetchClobPublic('/markets/' + pendingOrder.market_id)
• internal.killswitch.status()
• alerting.emit('SECURITY_BLOCK', metadata)

Complexity: O(1) per order — allow-list lookup is a constant-size set

11. Wire Examples

Input — what arrives on the wire

Pending order targeting CTFExchangeV2 (valid) — internal

{
  "intent_id": "int_5e6f7a8b9c0d1e2f",
  "contract_address": "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
  "chain_id": 137,
  "eip712_domain_version": "2",
  "market_id": "0x5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
  "side": "BUY",
  "size_usd": 400,
  "timestamp_ms": 1746768672000,
  "metadata": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "builder": "0x706f6c7974726164657273000000000000000000000000000000000000000000"
}

Pending order targeting V1 address (should DENY) — internal

{
  "intent_id": "int_3c4d5e6f7a8b9c0d",
  "contract_address": "0xC5d563A36AE78145C45a50134d48A1A61A3A4Dc7",
  "chain_id": 137,
  "eip712_domain_version": "1",
  "nonce": "12345"
}

Output — what the bot emits

SecurityCheck — ALLOW (V2 address, valid schema)

{
  "check_id": "sec.contract_address_guard.20260509T100000Z",
  "scope": "contract",
  "decision": "ALLOW",
  "reason_code": null,
  "evidence": {
    "submitted_address": "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
    "chain_id": 137,
    "allow_list_version": "v2.2026-04-28",
    "allow_list_label": "CTFExchangeV2",
    "allow_list_match": true,
    "domain_version_ok": true,
    "v2_schema_ok": true,
    "alert_raised": false
  },
  "checked_at": "2026-05-09T10:00:00Z"
}

SecurityCheck — DENY (V1 address detected)

{
  "check_id": "sec.contract_address_guard.20260509T100500Z",
  "scope": "contract",
  "decision": "DENY",
  "reason_code": "CONTRACT_ADDRESS_NOT_ALLOWED",
  "evidence": {
    "submitted_address": "0xC5d563A36AE78145C45a50134d48A1A61A3A4Dc7",
    "chain_id": 137,
    "allow_list_version": "v2.2026-04-28",
    "allow_list_match": false,
    "v1_address_detected": true,
    "alert_raised": true
  },
  "checked_at": "2026-05-09T10:05:00Z"
}

Reproduce locally

curl 'https://clob.polymarket.com/markets/0x5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e'

12. Decision Logic

13. Standard Decision Output

This bot returns a SecurityCheck object. See SecurityCheck schema.

{
  "check_id": "sec.contract_address_guard.20260509T100000Z",
  "scope": "contract",
  "decision": "DENY",
  "reason_code": "CONTRACT_ADDRESS_NOT_ALLOWED",
  "evidence": {
    "submitted_address": "0xDEAD1234",
    "chain_id": 137,
    "allow_list_version": "v2.2026-05-08",
    "allow_list_match": false,
    "alert_raised": true
  },
  "checked_at": "2026-05-09T10:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Security / ContractAddressGuard
• Grafana — V1 to V2 migration / address block history

Log levels

16. Developer Reporting

{
  "bot_id": "sec.contract_address_guard",
  "decision": "DENY",
  "reason_code": "CONTRACT_ADDRESS_NOT_ALLOWED",
  "inputs_used": [
    "clob.order_schema",
    "admin_ui.v2_allow_list"
  ],
  "metrics": {
    "submitted_address": "0xDEAD1234",
    "allow_list_size": 4,
    "match": false
  },
  "checked_at": "2026-05-09T10:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Stateless per evaluation. The V2 allow-list is loaded from Admin UI configuration at startup and is immutable until a signed admin change.

Cold-start recovery

On cold start, allow-list is loaded from Admin UI config. If config is unreachable, fail-closed: treat allow-list as empty and return DENY on all orders.

On restart

Allow-list is re-loaded from Admin UI on startup. If the last known config is cached locally, that cache is used until Admin UI is reachable.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

2.1 5.3

External services

23. Security Surfaces

ContractAddressGuard is the primary defence against phishing, V1 replay, and malicious contract substitution. Every block emits a security alert. The allow-list is change-controlled.

Signing surface

This bot does NOT sign anything. It runs before signing to prevent signing against unapproved contracts.

On-chain contract calls

Abuse vectors considered

• Injecting an unknown contract address into an order payload to redirect funds
• Replaying a V1 signed order by substituting the V1 CTFExchange address
• EIP-712 domain separator forgery to redirect signing to a different chain or contract
• Modifying the allow-list by bypassing the signed admin action requirement

Mitigations

• V2 allow-list is hardcoded for Polygon chain_id=137; any other chain_id is rejected
• V1 deny-list check runs before the allow-list check
• EIP-712 domain version must exactly equal '2' — mismatches are blocked and alerted
• V1 schema fields (nonce, feeRateBps, taker) trigger immediate DENY
• Every DENY emits a security alert regardless of alert_on_block setting (it is locked true)

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

Every ContractAddressGuard block is a P0 security event. On-call must treat every block as a potential attack until proven otherwise.

On-call actions

Manual overrides

• polytraders admin add-address sec.contract_address_guard --address <addr> --chain-id 137 — Adds an address to the V2 allow-list. Requires signed admin action and is audit-logged.
• polytraders bot status sec.contract_address_guard — Prints current allow-list, deny-list, and last block event.

Healthcheck

GET /health → 200 if allow-list contains at least 3 addresses and no DENY alert has fired in the last 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%