1.3 OracleRiskMonitor

1. Bot Identity

Operational profile

2. Purpose

OracleRiskMonitor watches the UMA Optimistic Oracle queue for proposals and active disputes on markets where open positions exist. When a market enters a resolution proposal or a dispute window, the bot can block new orders on that market, require reduced size, or flag a position for review. It protects against the scenario where a trade is submitted into a market moments before a contested resolution flips the outcome. It never overrides the strategy intent or changes the direction of an order — it only controls whether and how much the order is permitted to proceed.

3. Why This Bot Matters

• Trading into an active oracle dispute

  A position opened after a dispute was filed may be immediately underwater if the dispute resolves against the expected outcome; the resolution risk was not priced in.

• Holding a full position through the proposal window

  Markets entering their proposal phase have uncertain resolution timing. Holding full size through this window increases exposure to a binary outcome that cannot be hedged once the proposal is live.

• Stale oracle status

  If the oracle queue feed is unavailable, a strategy could open or increase a position without knowing a dispute is already active. The safe behaviour is to block, not to approve on missing data.

• Neg-risk market definition shift during proposal

  On neg-risk markets, the 'Other' outcome definition can shift if a proposal is disputed, potentially invalidating the expected payout structure.

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

{ "reduce_at_proposal_pct": 50 }

if (proposalActive && orderSize > limit * (p.default / 100)) return reshape({ max_size_usd: limit * (p.default / 100) });

{ "block_disputed": true }

if (p.block_disputed && disputeActive) return reject('ORACLE_DISPUTE_ACTIVE');

{ "max_dispute_window_h": 48 }

const ageH = (Date.now() - disputeStartMs) / 3600000; if (ageH > p.hard) escalate('DISPUTE_OVERDUE');

{ "downgrade_size_by_confidence": true }

if (p.downgrade_size_by_confidence) cap = cap * (1 - proposalFraction * 0.5);

8. Default Configuration

{
  "bot_id": "risk.oracle_risk_monitor",
  "version": "1.0.0",
  "mode": "hard_guard",
  "defaults": {
    "reduce_at_proposal_pct": 50,
    "block_disputed": true,
    "max_dispute_window_h": 48,
    "downgrade_size_by_confidence": true
  },
  "locked": {
    "block_disputed": {
      "immutable": true
    },
    "max_dispute_window_h": {
      "max": 168
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent from Strategy layer including market_id, side, and size_usd.
2. Check KillSwitch active flag; if active, return REJECT with KILL_SWITCH_ACTIVE immediately.
3. Fetch market resolution-source metadata from Gamma API for the target market_id to confirm UMA oracle is used.
4. Subscribe to or poll UMA Optimistic Oracle on-chain events to detect any active proposal or dispute for this market.
5. If a dispute is active and block_disputed=true, return REJECT with reason_code=ORACLE_DISPUTE_ACTIVE.
6. If a proposal is active (but no dispute), retrieve the current position size for this market from PortfolioGuard.
7. Apply reduce_at_proposal_pct to compute the maximum allowed size. If downgrade_size_by_confidence=true, further reduce the cap based on elapsed fraction of the proposal window.
8. If order.size_usd > computed cap, return RESHAPE_REQUIRED with constraints.max_size_usd set to the computed cap.
9. If the market is neg-risk, apply a 20% additional reduction to the cap due to potential definition-shift risk.
10. Return APPROVE if all checks pass, with inputs_used and checked_at timestamp.

10. Reference Implementation

Polls the UMA Optimistic Oracle for active proposals and disputes on the target market, then applies proposal-window size caps or hard rejects, depending on dispute status and the elapsed fraction of the proposal window.

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

FUNCTION evaluateOracleRisk(intent):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active:
    EMIT RiskVote(decision=HARD_REJECT, reason=KILL_SWITCH_ACTIVE)
    RETURN

  // --- 1. Fetch market resolution metadata ---
  marketMeta = fetchClobPublic('/markets/' + intent.market_id)
  IF marketMeta IS NULL OR isStale(marketMeta, params.stale_top_seconds):
    EMIT RiskVote(decision=HARD_REJECT, reason=STALE_MARKET_DATA)
    RETURN

  IF marketMeta.resolution_source != 'UMA':
    // Non-UMA markets pass through without oracle checks
    EMIT RiskVote(decision=APPROVE)
    RETURN

  // --- 2. Fetch UMA oracle state ---
  oracleState = FETCH onchain.uma.proposal_status(intent.market_id)
  // oracleState: { proposalActive, disputeActive, proposalStartMs, challengeWindowMs }
  // $750 pUSD proposer bond; 2h challenge window; disputed → DVM 24-48h

  // --- 3. Hard reject on active dispute ---
  IF oracleState.disputeActive AND params.block_disputed:
    EMIT RiskVote(decision=HARD_REJECT, reason=ORACLE_DISPUTE_ACTIVE)
    RETURN

  // --- 4. Proposal window size cap ---
  IF oracleState.proposalActive:
    position = FETCH internal.portfolio_guard.market_position(intent.market_id)
    proposalFraction = (now_ms() - oracleState.proposalStartMs)
                       / oracleState.challengeWindowMs
    cap = position.per_market_limit * (params.reduce_at_proposal_pct / 100)
    IF params.downgrade_size_by_confidence AND proposalFraction >= 0.5:
      cap = cap * (1 - proposalFraction * 0.5)
    // NegRisk: apply extra 20% reduction
    IF marketMeta.neg_risk:
      cap = cap * 0.80
    cap = toUsdcUnits(cap)
    IF intent.size_usd > cap:
      EMIT RiskVote(decision=RESHAPE_REQUIRED,
                    reason=ORACLE_RESOLUTION_PENDING,
                    constraints={ max_size_usd: cap })
      RETURN

  // --- 5. Bond check ---
  IF oracleState.proposerBondPUsd < 750:
    EMIT RiskVote(decision=HARD_REJECT, reason=ORACLE_PROPOSER_BOND_BELOW_MIN)
    RETURN

  // --- 6. Happy path ---
  EMIT RiskVote(decision=APPROVE, checked_at=now_iso())

Helpers used

SDK calls used

• fetchClobPublic('/markets/0xabc123...')
• fetchClobPublic('/book?market=0xabc123...')
• onchain.uma.proposal_status('0xabc123...')
• internal.killswitch.status()
• internal.portfolio_guard.market_position('0xabc123...')

Complexity: O(1) per intent — single market oracle state lookup

11. Wire Examples

Input — what arrives on the wire

OrderIntent on UMA-resolved market in active dispute — internal

{
  "intent_id": "int_9c2e4d6f8a0b1c3e",
  "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "side": "BUY",
  "outcome": "YES",
  "size_usd": 600,
  "neg_risk": false,
  "generated_at": "2026-05-09T07:00:00Z"
}

UMA oracle state (on-chain) — clob_public

{
  "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "resolution_source": "UMA",
  "proposal_active": true,
  "dispute_active": true,
  "proposal_start_ms": 1746770400000,
  "challenge_window_ms": 7200000,
  "proposer_bond_pusd": 750,
  "dispute_filed_at": "2026-05-09T07:00:00Z",
  "neg_risk": false
}

Output — what the bot emits

RiskVote — HARD_REJECT (active dispute)

{
  "guard_id": "risk.oracle_risk_monitor",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "ORACLE_DISPUTE_ACTIVE",
  "message": "Market 0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b has an active UMA resolution dispute filed at 2026-05-09T07:00:00Z. New orders are blocked until the dispute resolves.",
  "constraints": {},
  "inputs_used": [
    "gamma_api.market.resolution_source",
    "onchain.uma.dispute_events",
    "internal.killswitch.status"
  ],
  "checked_at": "2026-05-09T07:02:00Z"
}

RiskVote — RESHAPE_REQUIRED (proposal window, no dispute)

{
  "guard_id": "risk.oracle_risk_monitor",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "ORACLE_RESOLUTION_PENDING",
  "message": "Market is in UMA proposal window (fraction=0.40). Max size capped to 1000 pUSD.",
  "constraints": {
    "max_size_usd": 1000,
    "passive_only": false,
    "close_only": false
  },
  "inputs_used": [
    "gamma_api.market.resolution_source",
    "onchain.uma.proposal_events",
    "internal.portfolio_guard.position"
  ],
  "checked_at": "2026-05-09T08:00:00Z"
}

Reproduce locally

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

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.oracle_risk_monitor",
  "decision": "REJECT",
  "severity": "HARD",
  "reason_code": "ORACLE_DISPUTE_ACTIVE",
  "message": "Market CLOB:0xabc123 has an active UMA resolution dispute filed at 2026-05-08T14:00:00Z. New orders are blocked until the dispute resolves.",
  "constraints": {},
  "inputs_used": [
    "gamma_api.market.resolution_source",
    "uma.oracle.dispute_events",
    "internal.killswitch.status"
  ],
  "checked_at": "2026-05-09T07:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Risk overview / OracleRiskMonitor
• Grafana — UMA oracle status / proposal and dispute tracker

Log levels

16. Developer Reporting

{
  "bot_id": "risk.oracle_risk_monitor",
  "decision": "REJECT",
  "reason_code": "ORACLE_DISPUTE_ACTIVE",
  "inputs_used": [
    "gamma_api.market.resolution_source",
    "uma.oracle.dispute_events"
  ],
  "metrics": {
    "market_id": "CLOB:0xabc123",
    "dispute_filed_at": "2026-05-08T14:00:00Z",
    "dispute_age_h": 17.0,
    "block_disputed": true,
    "proposal_active": true,
    "proposal_fraction_elapsed": 0.63
  },
  "checked_at": "2026-05-09T07:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Maintains a short-lived in-memory cache of oracle state per market_id to avoid redundant on-chain calls within the same evaluation window.

State stores

Cold-start recovery

On cold start, the cache is empty. The first evaluation for each market triggers a fresh on-chain fetch.

On restart

Oracle state is re-fetched on first evaluation; no durable state is loaded.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

3.11

External services

23. Security Surfaces

OracleRiskMonitor is read-only. It never signs orders or holds private keys.

Signing surface

This bot does NOT sign anything.

Abuse vectors considered

• Feeding a stale or forged oracle state to bypass dispute detection
• Manipulating proposalFraction to reduce the size cap during a proposal window

Mitigations

• Oracle state has a 30s TTL; stale data triggers HARD_REJECT rather than pass-through
• proposalFraction is computed from on-chain timestamps, not from any mutable local state

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

OracleRiskMonitor incidents are driven by active UMA disputes or stale oracle feed. Disputes are expected events; on-call must validate the dispute is legitimate before considering any override.

On-call actions

Manual overrides

• polytraders bot pause risk.oracle_risk_monitor — Stops emitting RiskVotes. Use only during a known feed outage with explicit Risk pod lead sign-off.
• polytraders bot flush-cache risk.oracle_risk_monitor --market <market_id> — Evicts the oracle state cache for a specific market, forcing a fresh on-chain fetch.

Healthcheck

GET /health → 200 if on-chain oracle state fetch latency < 500ms and no market has been in dispute for > max_dispute_window_h.

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%