5.1 WalletPermissionGuard

1. Bot Identity

Operational profile

2. Purpose

Enforce that each strategy can only call the wallet methods the user has explicitly granted, scoped per session.

3. Why This Bot Matters

• Strategy calls an unauthorized wallet method

  Unexpected asset movement or signing actions outside the user-granted scope, undermining non-custodial guarantees.

• Method whitelist not enforced

  A compromised strategy could sign arbitrary orders, draining pUSD balances.

• Permission scope not session-bound

  Stale grants from a previous session silently persist, violating least-privilege.

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

{ "method_whitelist": "[]" }

if (!p.method_whitelist.includes(order.method)) return reject('WALLET_PERMISSION_DENIED');

{ "max_per_call_size_usd": 1000 }

if (order.size_usd > p.max_per_call_size_usd) return reject('WALLET_PERMISSION_DENIED');

8. Default Configuration

{
  "bot_id": "sec.wallet_permission_guard",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "method_whitelist": [],
    "contract_allowlist": [],
    "max_per_call_size_usd": 1000,
    "require_reapproval_h": 24
  }
}

9. Implementation Flow

1. Receive pending order before signing.
2. Check KillSwitch; if active, REJECT(KILL_SWITCH_ACTIVE).
3. Check session expiry; if expired, REJECT(SESSION_KEY_EXPIRED).
4. Verify order.method is in method_whitelist; if not, REJECT(WALLET_PERMISSION_DENIED).
5. Verify order.contract_address is in contract_allowlist; if not, REJECT(WALLET_PERMISSION_DENIED).
6. Verify order.size_usd <= max_per_call_size_usd; if exceeded, REJECT(WALLET_PERMISSION_DENIED).
7. Emit RiskVote(APPROVE) with inputs_used and checked_at.
8. Log decision 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.

// WalletPermissionGuard
FUNCTION checkWalletPermission(pendingOrder, session):
  // 0. KillSwitch
  IF FETCH(internal.killswitch).active:
    EMIT RiskVote(DENY, KILL_SWITCH_ACTIVE); RETURN
  // 1. Session expiry
  IF session.expires_at < NOW():
    EMIT RiskVote(DENY, SESSION_KEY_EXPIRED); RETURN
  // 2. Method whitelist
  IF pendingOrder.method NOT IN session.method_whitelist:
    EMIT RiskVote(DENY, WALLET_PERMISSION_DENIED); RETURN
  // 3. Contract allowlist
  IF pendingOrder.contract_address NOT IN session.contract_allowlist:
    EMIT RiskVote(DENY, WALLET_PERMISSION_DENIED); RETURN
  // 4. Size cap
  IF pendingOrder.size_usd > params.max_per_call_size_usd:
    EMIT RiskVote(DENY, WALLET_PERMISSION_DENIED); RETURN
  // 5. Approve
  EMIT RiskVote(APPROVE)
  LOG(governance.audit, {decision, intent_id, method, session_id})

SDK calls used

• clob_auth.get_session(user_id)
• internal.killswitch.status()

Complexity: O(n) where n = whitelist size (small constant)

11. Wire Examples

Input — what arrives on the wire

Permitted matchOrders call — internal

{
  "intent_id": "int_1a2b3c4d5e6f7a8b",
  "method": "matchOrders",
  "contract_address": "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
  "size_usd": 400,
  "timestamp_ms": 1746768672000
}

Output — what the bot emits

RiskVote — APPROVE

{
  "vote_id": "sec.wallet_permission_guard.20260509T120000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "checked_at": "2026-05-09T12:00:00Z"
}

RiskVote — DENY (method not in whitelist)

{
  "vote_id": "sec.wallet_permission_guard.20260509T120100Z",
  "decision": "DENY",
  "reason_code": "WALLET_PERMISSION_DENIED",
  "checked_at": "2026-05-09T12:01:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "vote_id": "sec.wallet_permission_guard.20260509T120000Z",
  "decision": "DENY",
  "reason_code": "WALLET_PERMISSION_DENIED",
  "evidence": {
    "method": "transfer",
    "in_whitelist": false
  },
  "checked_at": "2026-05-09T12:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "sec.wallet_permission_guard",
  "decision": "DENY",
  "reason_code": "WALLET_PERMISSION_DENIED",
  "inputs_used": [
    "session.whitelist",
    "order.method"
  ],
  "checked_at": "2026-05-09T12:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Reload whitelist from Admin UI on restart; fail-closed if 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

• Strategy attempting to call an unauthorized method to bypass fee caps
• Session token replay after expiry

Mitigations

• Whitelist checked on every call; no caching of positive decisions
• Session expiry enforced by monotonic clock comparison

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 WALLET_PERMISSION_DENIED is a security event. Investigate whether the strategy is misconfigured or attempting scope escalation.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/walletpermissionguard → green if Session store reachable; whitelist non-empty for active strategies.; red if Session store unreachable or all whitelists empty.

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%