4.2 OracleWatcher

1. Bot Identity

2. Purpose

OracleWatcher streams the UMA Optimistic Oracle on-chain, detecting assertion proposals, dispute filings, DVM debate escalations, and final vote outcomes for every Polymarket condition ID. It emits an ObservationReport on every state change. OracleWatcher is strictly read-only — it never submits or signs anything. Output is the primary feed for oracleriskmonitor, which uses it to gate positions during contested resolutions.

3. Why This Bot Matters

• Proposal missed before 2-hour challenge window closes

  Position held through unchallenged incorrect resolution; full collateral loss on the wrong outcome.

• Dispute state not detected

  oracleriskmonitor is unaware that a market is in a 24–72-hour DVM debate; strategies continue trading as if resolution is certain.

• DVM vote outcome not propagated

  Settlement logic based on outdated oracle state; payout mismatch or duplicate claim.

• Stale UMA state cached during RPC outage

  Old proposal treated as current; oracleriskmonitor computes wrong time-to-resolution, potentially permitting over-leveraged entry.

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

{ "poll_interval_s": 12 }

if (p.poll_interval_s > p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "challenge_window_alert_s": 3600 }

if (p.challenge_window_alert_s < p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "alert_on_state_change": true }

// not yet authored

8. Default Configuration

{
  "bot_id": "intel.oraclewatcher",
  "version": "2.1.0",
  "mode": "general_live",
  "defaults": {
    "poll_interval_s": 12,
    "challenge_window_alert_s": 3600,
    "alert_on_state_change": true
  },
  "locked": {
    "poll_interval_s": {
      "max": 60
    },
    "challenge_window_alert_s": {
      "min": 600
    }
  }
}

9. Implementation Flow

1. On startup, subscribe to Polygon RPC event log for UMA OptimisticOracle ProposePrice, DisputePrice, and Settle events filtered to Polymarket ancillary data prefixes.
2. On each block (poll_interval_s), fetch new events since last processed block number.
3. For each event: resolve assertion_id → condition_id via Gamma API / internal registry.
4. Determine oracle_state: PROPOSED | CHALLENGED | DVM_DEBATE | DVM_VOTE | SETTLED.
5. Compute time_to_deadline_s: for PROPOSED, time until 2-hour challenge window closes; for DVM_DEBATE, estimated 24–48 h; for DVM_VOTE, estimated 48 h.
6. If oracle_state is PROPOSED and time_to_deadline_s ≤ challenge_window_alert_s, emit WARN ORACLEWATCHER_CHALLENGE_WINDOW_CLOSING.
7. Check KillSwitch; if active, continue watching but suppress emissions.
8. If alert_on_state_change is true (or state = PROPOSED | SETTLED), emit ObservationReport with: report_id, condition_id, assertion_id, oracle_state, bond_pusd, time_to_deadline_s, proposed_price, disputer (if any), dvm_question_id (if any), block_number.
9. Log per-event summary: condition_id, state transition, bond_pusd, time_to_deadline_s.

10. Reference Implementation

Subscribes to Polygon RPC event log for UMA oracle events, maps assertion_ids to condition_ids, tracks the full proposal→dispute→DVM→settle lifecycle, and emits an ObservationReport on every state change.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output.

FUNCTION watchBlock(block_number):
  // --- 0. RPC health check ---
  IF rpc.last_block_age_s > 2 * params.poll_interval_s:
    EMIT WARN 'STALE_DATA — RPC unresponsive'
    RETURN

  // --- 1. Fetch new UMA events since last_processed_block ---
  events = rpc.getLogs(
    address   = UMA_OPTIMISTIC_ORACLE_ADDR,
    topics    = [PROPOSE_PRICE_SIG, DISPUTE_PRICE_SIG, SETTLE_SIG],
    fromBlock = last_processed_block + 1,
    toBlock   = block_number
  )

  // --- 2. KillSwitch gate ---
  ks = FETCH internal.killswitch.status

  FOR event IN events:
    // --- 3. Ancillary data prefix filter ---
    IF NOT event.ancillaryData.startsWith(POLYMARKET_PREFIX):
      CONTINUE

    // --- 4. Resolve assertion_id → condition_id ---
    condition_id = gamma_api.GET('/assertion/' + event.assertionId + '/condition')
    IF condition_id IS NULL:
      condition_id = internal.registry.lookup(event.assertionId)
    IF condition_id IS NULL OR condition_id NOT IN watched_condition_ids:
      CONTINUE

    // --- 5. Determine oracle state ---
    state = SWITCH event.topic:
      PROPOSE_PRICE_SIG  -> 'PROPOSED'
      DISPUTE_PRICE_SIG  -> 'CHALLENGED'
      SETTLE_SIG         -> 'SETTLED'

    // --- 6. Compute deadline ---
    IF state == 'PROPOSED':
      challenge_deadline_ms = event.timestamp_ms + 2*60*60*1000   // +2h
      time_to_deadline_s    = (challenge_deadline_ms - now_ms()) / 1000
    ELSE IF state == 'CHALLENGED':
      time_to_deadline_s    = 24*60*60  // DVM: 24–48h
    ELSE:
      time_to_deadline_s    = None

    // --- 7. Challenge window alert ---
    warnings = []
    IF state == 'PROPOSED' AND time_to_deadline_s <= params.challenge_window_alert_s:
      warnings.append('ORACLEWATCHER_CHALLENGE_WINDOW_CLOSING')

    // --- 8. KillSwitch suppress ---
    IF ks.active:
      LOG INFO 'KILL_SWITCH_ACTIVE — suppressing ObservationReport'
      CONTINUE

    // --- 9. Emit ---
    IF params.alert_on_state_change OR state IN ('PROPOSED', 'SETTLED'):
      report = ObservationReport(
        report_id         = 'rep_ow_' + condition_id[:6] + '_' + now_ms(),
        trace_id          = newTraceId(),
        bot_id            = 'intel.oraclewatcher',
        kind              = 'ObservationReport',
        condition_id      = condition_id,
        assertion_id      = event.assertionId,
        oracle_state      = state,
        bond_pusd         = 750,
        time_to_deadline_s= time_to_deadline_s,
        proposed_price    = event.price,
        disputer          = event.disputer IF state == 'CHALLENGED' ELSE null,
        dvm_question_id   = event.dvmQuestionId IF state IN ('CHALLENGED','DVM_VOTE') ELSE null,
        block_number      = block_number,
        warnings          = warnings,
        emitted_at_ms     = now_ms()
      )
      EMIT internal.bus.observations <- report

  last_processed_block = block_number

SDK calls used

• rpc.getLogs(address=UMA_OPTIMISTIC_ORACLE_ADDR, topics=[...], fromBlock, toBlock)
• gamma_api.GET('/assertion/<assertionId>/condition')
• internal.registry.lookup(assertionId)

Complexity: O(E) per block where E = UMA oracle events in that block; typically O(1) in steady state

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Polygon RPC ProposePrice event",
  "source": "onchain",
  "payload": {
    "event": "ProposePrice",
    "assertionId": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
    "ancillaryData": "0x706f6c796d61726b65743a313233",
    "price": 1,
    "timestamp_ms": 1746700900000,
    "block_number": 72345678
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — PROPOSED state",
  "payload": {
    "report_id": "rep_ow_0xdef5_1746700900000",
    "trace_id": "trc_0xfeed000102030405060708",
    "bot_id": "intel.oraclewatcher",
    "kind": "ObservationReport",
    "condition_id": "0xdef5670000000000000000000000000000000000000000000000000000000000",
    "assertion_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
    "oracle_state": "PROPOSED",
    "bond_pusd": 750,
    "time_to_deadline_s": 7198,
    "proposed_price": 1,
    "disputer": null,
    "dvm_question_id": null,
    "block_number": 72345678,
    "warnings": [],
    "emitted_at_ms": 1746700900120
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "rep_ow_0xdef5_1746700900000",
  "trace_id": "trc_0xfeed000102030405",
  "bot_id": "intel.oraclewatcher",
  "kind": "ObservationReport",
  "condition_id": "0xdef5670000000000000000000000000000000000000000000000000000000000",
  "assertion_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "oracle_state": "CHALLENGED",
  "bond_pusd": 750,
  "time_to_deadline_s": null,
  "proposed_price": 1,
  "disputer": "0xABCDEF1234567890ABCDEF1234567890ABCDEF12",
  "dvm_question_id": "0x9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e",
  "block_number": 72345678,
  "warnings": [
    "ORACLEWATCHER_CHALLENGE_WINDOW_CLOSING"
  ],
  "emitted_at_ms": 1746700900120
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / OracleWatcher dispute lifecycle
• Grafana — Intelligence / challenge deadline countdown

16. Developer Reporting

{
  "bot_id": "intel.oraclewatcher",
  "block_number": 72345678,
  "events_detected": 2,
  "events_emitted": 2,
  "killswitch_active": false,
  "condition_ids_watched": 14,
  "pending_proposals": 3,
  "active_disputes": 1,
  "dvm_votes_pending": 0
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, reload oracle_states from Postgres and resume watching from last_block_number. Any missed events since last_block_number are re-fetched from RPC.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Malicious ancillary data in a non-Polymarket UMA assertion crafted to match Polymarket prefix, injecting a spurious ObservationReport
• RPC provider substitution attack returning crafted event logs to fake a settlement

Mitigations

• Ancillary data prefix validated against a hardcoded Polymarket prefix byte sequence
• Assertion IDs cross-checked against Gamma API and internal registry before emission
• All ObservationReports are informational only — settlement decisions require independent on-chain confirmation

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

OracleWatcher incidents are most commonly RPC outages or unexpected dispute spikes. Because UMA disputes can prevent settlement and have legal standing, page immediately on RPC outage or imminent challenge deadline.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/oraclewatcher -> 200 if rpc_block_lag_s < 24 AND Postgres reachable AND last ObservationReport emitted within 10 min of last on-chain UMA event. RED if rpc_block_lag_s > 60 OR Postgres unreachable OR any PROPOSED assertion has time_to_deadline_s < 600 with no alert fired.

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%