5.3 SignaturePreviewer

1. Bot Identity

Operational profile

2. Purpose

Render a plain-English summary of every EIP-712 signature before the wallet shows the modal.

3. Why This Bot Matters

• User signs a phishing or misrouted order without understanding it

  Funds transferred to an unintended address or contract under user signature.

• Domain separator not validated before display

  A forged domain could cause a user to unknowingly sign for a different chain or contract.

• Strategy deviates from declared envelope

  User signs an order outside the parameters they approved at strategy setup.

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_preview_for": ["all"] }

if (p.require_preview_for.includes('all') || p.require_preview_for.includes(order.type)) generatePreview(order);

{ "block_on_envelope_mismatch": true }

if (p.block_on_envelope_mismatch && deviation > 0.20) return reject('SIGNATURE_ENVELOPE_BREACH');

8. Default Configuration

{
  "bot_id": "sec.signature_previewer",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "require_preview_for": [
      "all"
    ],
    "min_detail_level": "standard",
    "block_on_envelope_mismatch": true,
    "retain_log_days": 30
  }
}

9. Implementation Flow

1. Receive EIP-712 typed data for pending signing request.
2. Check KillSwitch; if active, REJECT(KILL_SWITCH_ACTIVE).
3. Verify domain separator version == '2' and verifyingContract in V2 allow-list.
4. Resolve token IDs to market names via Gamma API.
5. Compute diff between order fields and strategy declared envelope.
6. If deviation > 20% and block_on_envelope_mismatch: REJECT(SIGNATURE_ENVELOPE_BREACH).
7. Render plain-English preview: market name, side, size in pUSD, price, expiry, contract.
8. Emit preview to wallet UI; await user acknowledgement.
9. Emit RiskVote(APPROVE) after acknowledgement; log to 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.

// SignaturePreviewer
FUNCTION previewSignature(typedData, strategyEnvelope):
  IF FETCH(internal.killswitch).active:
    EMIT RiskVote(DENY, KILL_SWITCH_ACTIVE); RETURN
  // Domain check
  IF typedData.domain.version != '2':
    EMIT RiskVote(DENY, CONTRACT_GUARD_DOMAIN_MISMATCH); RETURN
  // Resolve market name
  meta = FETCH(gamma.markets[typedData.message.tokenId])
  marketName = meta ? meta.question : '(unresolved)'
  // Envelope diff
  deviation = ABS(typedData.message.size_usd - strategyEnvelope.size_usd)
               / strategyEnvelope.size_usd
  IF deviation > 0.20 AND params.block_on_envelope_mismatch:
    EMIT RiskVote(DENY, SIGNATURE_ENVELOPE_BREACH); RETURN
  // Render preview
  preview = {
    market: marketName,
    side: typedData.message.side,
    size_pusd: typedData.message.size_usd,
    price: typedData.message.price,
    contract: typedData.domain.verifyingContract
  }
  EMIT preview TO wallet_ui
  AWAIT user.acknowledge()
  EMIT RiskVote(APPROVE)
  LOG(governance.audit, {preview, decision: 'APPROVE'})

SDK calls used

• gamma.get_market(token_id)
• clob_auth.get_typed_data(intent_id)
• internal.killswitch.status()

Complexity: O(1) per signing request — single Gamma API call

11. Wire Examples

Input — what arrives on the wire

EIP-712 typed data for BUY order — clob_auth

{
  "intent_id": "int_3c4d5e6f7a8b9c0d",
  "domain": {
    "name": "CTFExchange",
    "version": "2",
    "chainId": 137,
    "verifyingContract": "0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E"
  },
  "message": {
    "side": "BUY",
    "tokenId": "0x5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
    "size_usd": 400,
    "price": 0.55,
    "timestamp_ms": 1746768672000
  }
}

Output — what the bot emits

RiskVote — APPROVE with preview

{
  "vote_id": "sec.signature_previewer.20260509T140000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "preview": {
    "market": "US Election — Winner",
    "side": "BUY",
    "size_pusd": 400,
    "price": 0.55
  },
  "checked_at": "2026-05-09T14:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "vote_id": "sec.signature_previewer.20260509T140000Z",
  "decision": "APPROVE",
  "reason_code": null,
  "evidence": {
    "market": "US Election \u2014 Winner",
    "side": "BUY",
    "size_pusd": 400,
    "price": 0.55,
    "domain_ok": true,
    "envelope_deviation_pct": 2.0,
    "user_acknowledged": true
  },
  "checked_at": "2026-05-09T14:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "sec.signature_previewer",
  "decision": "APPROVE",
  "inputs_used": [
    "eip712.typed_data",
    "gamma.market_metadata",
    "strategy.envelope"
  ],
  "checked_at": "2026-05-09T14:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Preview log rebuilt from audit trail on restart.

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

• Phishing payload with misleading market name in typed data
• Forged domain separator to redirect signing to different chain

Mitigations

• Market names resolved from trusted Gamma API, not from order payload
• Domain separator validated against V2 allow-list before display

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

Domain mismatch and envelope breach alerts are P0/P1 security events requiring immediate investigation.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/signaturepreviewer → green if Gamma API reachable; last preview rendered within 30s.; red if Gamma API unreachable for > 60s or domain mismatch alert firing.

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%