5.2 AllowanceMonitor

1. Bot Identity

Operational profile

2. Purpose

Track ERC-20 allowances per token and contract; alert and shrink to a tight ceiling on idle.

3. Why This Bot Matters

• Unbounded ERC-20 allowance left idle

  A compromised or malicious contract can drain the wallet's pUSD balance at any future time.

• Allowance not shrunk after idle period

  Unlimited approvals compound risk; industry incidents show dormant allowances are frequently exploited.

• No alert on unbounded approval

  Operators remain unaware of excessive exposure until an incident occurs.

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

{ "max_allowance_usd": 500 }

if (allowance > p.max_allowance_usd && !p.auto_shrink) return reject('ALLOWANCE_EXCEEDS_CEILING');

{ "auto_shrink": true }

if (p.auto_shrink && allowance > needed) await shrinkAllowance(token, spender, needed);

8. Default Configuration

{
  "bot_id": "sec.allowance_monitor",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "max_allowance_usd": 500,
    "idle_revoke_h": 48,
    "auto_shrink": true,
    "alert_on_unbounded": true
  }
}

9. Implementation Flow

1. Receive order intent before submission.
2. Check KillSwitch; if active, REJECT(KILL_SWITCH_ACTIVE).
3. FETCH current pUSD allowance for (CTFExchangeV2, wallet) from Polygon RPC.
4. If allowance > max_allowance_usd and auto_shrink=true: submit shrink tx, wait for confirmation.
5. If allowance > max_allowance_usd and auto_shrink=false: REJECT(ALLOWANCE_EXCEEDS_CEILING).
6. Check idle duration; if > idle_revoke_h: trigger revoke allowance for idle spenders.
7. Emit RiskVote(APPROVE) with current allowance snapshot.
8. Log result to governance audit trail.

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.

// AllowanceMonitor
FUNCTION checkAllowance(pendingOrder, wallet):
  IF FETCH(internal.killswitch).active:
    EMIT RiskVote(DENY, KILL_SWITCH_ACTIVE); RETURN
  spender = pendingOrder.contract_address  // CTFExchangeV2
  allowance = FETCH(onchain.erc20.allowance(pUSD, wallet, spender))
  IF allowance == null:  // RPC failure
    EMIT RiskVote(DENY, STALE_DATA); RETURN
  IF allowance > params.max_allowance_usd:
    IF params.auto_shrink:
      AWAIT onchain.approve(pUSD, spender, pendingOrder.size_usd)
      allowance = pendingOrder.size_usd  // now safe
    ELSE:
      EMIT RiskVote(DENY, ALLOWANCE_EXCEEDS_CEILING); RETURN
  // Idle revoke check
  last_use = FETCH(onchain.last_transfer_event(spender))
  idle_h = (NOW() - last_use) / 3600
  IF idle_h > params.idle_revoke_h:
    AWAIT onchain.approve(pUSD, spender, 0)  // revoke
    EMIT RiskVote(DENY, ALLOWANCE_EXCEEDS_CEILING); RETURN
  EMIT RiskVote(APPROVE)
  LOG(governance.audit, {allowance, spender, wallet})

SDK calls used

• onchain.erc20.allowance(pUSD_ADDRESS, wallet, CTFExchangeV2_ADDRESS)
• onchain.approve(pUSD_ADDRESS, spender, amount)

Complexity: O(1) per order — single RPC read

11. Wire Examples

Input — what arrives on the wire

Order with safe allowance — internal

{
  "intent_id": "int_2b3c4d5e6f7a8b9c",
  "contract_address": "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
  "size_usd": 200,
  "timestamp_ms": 1746768672000
}

Output — what the bot emits

RiskVote — APPROVE

{
  "vote_id": "sec.allowance_monitor.20260509T130000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "evidence": {
    "allowance_usd": 400,
    "ceiling_usd": 500,
    "shrunk": false
  },
  "checked_at": "2026-05-09T13:00:00Z"
}

RiskVote — DENY (exceeds ceiling, auto_shrink off)

{
  "vote_id": "sec.allowance_monitor.20260509T130100Z",
  "decision": "DENY",
  "reason_code": "ALLOWANCE_EXCEEDS_CEILING",
  "checked_at": "2026-05-09T13:01:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "vote_id": "sec.allowance_monitor.20260509T130000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "evidence": {
    "token": "pUSD",
    "spender": "CTFExchangeV2",
    "allowance_usd": 400,
    "ceiling_usd": 500,
    "shrunk": false
  },
  "checked_at": "2026-05-09T13:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "sec.allowance_monitor",
  "decision": "APPROVE",
  "inputs_used": [
    "onchain.allowance",
    "config.max_allowance_usd"
  ],
  "checked_at": "2026-05-09T13:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Re-read from Polygon RPC on restart; fail-closed if RPC 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

• RPC returning stale allowance to prevent shrink from firing
• Rapid allowance inflation between check and order submission

Mitigations

• Allowance re-read immediately before every signing action
• auto_shrink submits tx and waits for confirmation before approving

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

AllowanceExceedsCeiling alerts require immediate review — check auto_shrink status and RPC health.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/allowancemonitor → green if All allowances at or below max_allowance_usd; last check within 60s.; red if Any allowance above ceiling for more than 120s.

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%