4.8 ResolutionRuleParser

1. Bot Identity

2. Purpose

Convert each market's resolution rule into a structured representation: source-of-truth, condition, ambiguity score.

3. Why This Bot Matters

• Free-text rule treated as if structured

  Resolution rules are written in English and parsed by humans. Without a structured representation, every downstream consumer — ContradictionDetector, RuleChangeMonitor, SourceOfTruthVerifier — re-parses the same string and gets subtly different answers.

• Ambiguity score not surfaced to strategies

  A resolution rule with high ambiguity carries non-trivial settlement risk. Without an explicit score, strategy bots cannot down-size or skip those markets.

• Source-of-truth field unused

  A structured 'source-of-truth' field lets SourceOfTruthVerifier check whether the cited source actually publishes the data needed to resolve. The parser is the upstream that makes that check possible.

• Rule changes hard to diff

  RuleChangeMonitor needs to detect post-listing edits. Diffing structured representations catches semantic changes; diffing raw strings flags every cosmetic edit and misses meaningful ones.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "poll_interval_s": 300 }

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

{ "staleness_threshold_s": 600 }

if (cache_age_s > p.staleness_threshold_s.hard) emit('STALE_DATA');

8. Default Configuration

{
  "bot_id": "intel.resolutionruleparser",
  "version": "0.1.0",
  "mode": "planned",
  "defaults": {
    "poll_interval_s": 300,
    "staleness_threshold_s": 600
  },
  "locked": {
    "poll_interval_s": {
      "max": 3600
    },
    "staleness_threshold_s": {
      "max": 7200
    }
  }
}

9. Implementation Flow

— not yet authored —

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.

FUNCTION parseResolutionRules(condition_id):
  // 0. KillSwitch check
  IF FETCH internal.killswitch.status == ACTIVE:
    RETURN

  // 1. Fetch market metadata from Gamma
  market = FETCH gamma.GET('/markets/' + condition_id)
  IF market IS NULL:
    EMIT WARN 'STALE_DATA'
    RETURN

  // 2. Extract resolution source and rules
  rules = market.resolution_rules
  source = market.resolution_source
  oracle_bond_pusd = 750  // UMA $750 pUSD bond

  // 3. Validate rule completeness
  IF rules IS NULL OR len(rules) == 0:
    EMIT WARN 'RESOLUTIONRULEPARSER_MISSING_RULES'
    RETURN

  // 4. Check negRisk flag
  neg_risk = market.get('negRisk', False)

  // 5. Emit ObservationReport
  EMIT ObservationReport {
    report_id: gen_id(),
    kind: 'ObservationReport',
    condition_id: condition_id,
    resolution_source: source,
    resolution_rules_hash: hash(rules),
    oracle_bond_pusd: oracle_bond_pusd,
    neg_risk: neg_risk,
    emitted_at_ms: now_ms()
  }

SDK calls used

• gamma.GET('/markets/<condition_id>')
• data.GET('/markets/<condition_id>/resolution')
• internal.killswitch.status

Complexity: O(1) per market; O(M) for bulk pre-load

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Gamma market metadata fetch for resolution rule parsing",
  "source": "gamma",
  "payload": {
    "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
    "question": "Will BTC close above $100k on Dec 31, 2026?",
    "resolution_source": "UMA Optimistic Oracle",
    "resolution_rules": "Resolves YES if Coinbase BTC/USD close price on Dec 31 2026 is >= 100000.",
    "negRisk": false,
    "timestamp_ms": 1746703000000
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — resolution rules parsed",
  "payload": {
    "report_id": "rep_rrp_0xf1a2_1746703000000",
    "trace_id": "trc_0xbeef0102030405060709",
    "bot_id": "intel.resolutionruleparser",
    "kind": "ObservationReport",
    "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
    "resolution_source": "UMA Optimistic Oracle",
    "resolution_rules_hash": "0xabcd1234",
    "oracle_bond_pusd": 750,
    "neg_risk": false,
    "emitted_at_ms": 1746703005000
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "report_id": "rep_rrp_0xf1a2_1746703000000",
  "trace_id": "trc_0xbeef0102030405060709",
  "bot_id": "intel.resolutionruleparser",
  "kind": "ObservationReport",
  "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
  "resolution_source": "UMA Optimistic Oracle",
  "resolution_rules_hash": "0xabcd1234",
  "oracle_bond_pusd": 750,
  "neg_risk": false,
  "change_detected": false,
  "emitted_at_ms": 1746703005000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / ResolutionRuleParser parse rate and source change events

16. Developer Reporting

{
  "bot_id": "intel.resolutionruleparser",
  "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
  "rules_hash": "0xabcd1234",
  "change_detected": false,
  "gamma_response_ms": 120,
  "killswitch_active": false,
  "emitted_at_ms": 1746703005000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, reload last known state from Postgres; re-parse all active markets.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

Used by (auto-aggregated)

4.9

External services

23. Security Surfaces

Abuse vectors considered

• Adversary modifies resolution rules in Gamma to manipulate downstream strategy behaviour
• Source change spoofing to trigger false RESOLUTIONRULEPARSER_SOURCE_CHANGE alerts

Mitigations

• Rules hash comparison detects any rule text changes between parses
• ObservationReports are informational only — strategies independently verify before acting

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

ResolutionRuleParser incidents are typically Gamma API outages or unexpected rule changes. Rule changes require prompt strategy notification.

On-call actions

Manual overrides

• force_reparse_all — POST /internal/resolutionruleparser/reparse to trigger bulk re-parse of all active markets — After Gamma API recovery from extended outage

Healthcheck

Endpoint: /internal/health/resolutionruleparser | Green: Last parse < 60 min ago AND Postgres reachable AND Gamma API returning 200 | Red: No parse for > 2 h OR Postgres unreachable OR Gamma API down > 15 min

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%