4.10 ContradictionDetector

1. Bot Identity

2. Purpose

Surface markets whose resolution rule contradicts itself, the title, or a parent neg-risk constraint.

3. Why This Bot Matters

• Self-contradicting market traded as if resolvable

  A market whose resolution rule contradicts its title or a parent neg-risk constraint may never resolve cleanly. Strategies that trade it can be left holding positions through ambiguous or court-overturned outcomes.

• Neg-risk parent constraint silently violated

  Polymarket's neg-risk markets share a constraint that exactly one outcome must resolve YES across the set. A child market whose rule allows two simultaneous YES resolutions breaks that invariant; without detection, sizing and hedging logic on those markets is wrong.

• Operators surprised at resolution time

  Discovery of a contradiction at resolution is the worst possible time. Catching it at listing time lets Discovery exclude the market or Governance flag it for human review days before any trade is placed.

• No structured reason for excluding a market

  Without this signal, MarketScanner has no defensible reason to filter out a malformed market beyond an operator's gut call. The contradiction record provides the audit trail.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "contradiction_threshold": 1.05 }

if (total_yes < p.contradiction_threshold.hard) return;

{ "poll_interval_s": 30 }

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

8. Default Configuration

{
  "bot_id": "intel.contradictiondetector",
  "version": "0.1.0",
  "mode": "planned",
  "defaults": {
    "contradiction_threshold": 1.05,
    "poll_interval_s": 30
  },
  "locked": {
    "contradiction_threshold": {
      "min": 1.0
    },
    "poll_interval_s": {
      "max": 300
    }
  }
}

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 detectContradictions(market_group):
  // 0. KillSwitch check
  IF FETCH internal.killswitch.status == ACTIVE:
    RETURN

  // 1. Fetch prices for all markets in group
  prices = {}
  FOR cid IN market_group.condition_ids:
    p = FETCH data.GET('/prices/' + cid)
    IF p IS NULL:
      EMIT WARN 'STALE_DATA'
      CONTINUE
    prices[cid] = p

  // 2. Check mutual-exclusivity constraint
  total_yes = sum(prices[c].yes for c in prices)
  IF total_yes > contradiction_threshold:
    EMIT WARN 'CONTRADICTIONDETECTOR_PRICE_CONTRADICTION'
    contradiction_detected = True
  ELSE:
    contradiction_detected = False

  // 3. Emit ObservationReport
  EMIT ObservationReport {
    report_id: gen_id(),
    kind: 'ObservationReport',
    market_group_id: market_group.id,
    contradiction_detected: contradiction_detected,
    total_yes_sum: total_yes,
    emitted_at_ms: now_ms()
  }

SDK calls used

• data.GET('/prices/<condition_id>')
• gamma.GET('/market-groups/<group_id>')
• internal.killswitch.status

Complexity: O(M) per market group where M = markets in group

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Contradiction check for a mutually-exclusive market group",
  "source": "internal",
  "payload": {
    "market_group_id": "grp_uselection2026",
    "condition_ids": [
      "0xabc1000000000000000000000000000000000000000000000000000000000000",
      "0xabc2000000000000000000000000000000000000000000000000000000000000"
    ],
    "timestamp_ms": 1746703000000
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — contradiction detected",
  "payload": {
    "report_id": "rep_cd_grp_uselection_1746703000000",
    "trace_id": "trc_0xbeef0102030405060711",
    "bot_id": "intel.contradictiondetector",
    "kind": "ObservationReport",
    "market_group_id": "grp_uselection2026",
    "contradiction_detected": true,
    "total_yes_sum": 1.18,
    "emitted_at_ms": 1746703005000
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "report_id": "rep_cd_grp_uselection_1746703000000",
  "trace_id": "trc_0xbeef0102030405060711",
  "bot_id": "intel.contradictiondetector",
  "kind": "ObservationReport",
  "market_group_id": "grp_uselection2026",
  "contradiction_detected": true,
  "total_yes_sum": 1.18,
  "warnings": [],
  "emitted_at_ms": 1746703005000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / ContradictionDetector YES-sum by market group

16. Developer Reporting

{
  "bot_id": "intel.contradictiondetector",
  "market_group_id": "grp_uselection2026",
  "total_yes_sum": 1.18,
  "contradiction_detected": true,
  "prices_fetched": 2,
  "prices_missing": 0,
  "killswitch_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, re-fetch all active group prices on first poll cycle.

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

• Adversary places thin orders to artificially inflate YES-sum and trigger false contradiction signals
• Data API returns stale prices during low-liquidity periods, causing spurious contradictions

Mitigations

• contradiction_threshold parameter tuned above normal spread noise to reduce false positives
• ObservationReports are informational only — strategies independently validate 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

ContradictionDetector incidents are either Data API outages or genuine price contradictions. Contradictions are signals for strategies, not errors.

On-call actions

Manual overrides

• adjust_contradiction_threshold — Update config.contradiction_threshold; requires approval gate if threshold < 1.02 — When market spreads widen due to low liquidity causing false positives

Healthcheck

Endpoint: /internal/health/contradictiondetector | Green: Last check < 2x poll_interval_s AND Redis reachable AND Data API returning 200 | Red: No check for > 10 min OR Redis unreachable

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%