4.9 SourceOfTruthVerifier

1. Bot Identity

2. Purpose

Sanity-check that the source listed in a market's rule actually publishes what's needed for resolution.

3. Why This Bot Matters

• Cited source does not actually publish what's needed

  A market that cites 'team-website.com' as its source-of-truth resolves on whatever that site publishes. If the site stops publishing, publishes only behind a paywall, or publishes too coarsely (winner only, no margin), the market cannot be resolved cleanly. Catching that at listing prevents the trade.

• Rule change to a worse source goes undetected

  A post-listing edit can swap the cited source for a less reliable one. Pairing this verifier with RuleChangeMonitor catches the moment the cited source becomes unsuitable.

• Operators have no defensible exclusion reason

  MarketScanner needs a structured reason to exclude a market with a broken source-of-truth. The verifier produces that reason in a form Discovery and Governance can both consume.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "poll_interval_s": 120 }

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

{ "staleness_threshold_s": 300 }

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

8. Default Configuration

{
  "bot_id": "intel.sourceoftruthverifier",
  "version": "0.1.0",
  "mode": "planned",
  "defaults": {
    "poll_interval_s": 120,
    "staleness_threshold_s": 300
  },
  "locked": {
    "poll_interval_s": {
      "max": 1800
    },
    "staleness_threshold_s": {
      "max": 3600
    }
  }
}

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

  // 1. Fetch from all three sources
  gamma_state = FETCH gamma.GET('/markets/' + condition_id)
  data_state = FETCH data.GET('/markets/' + condition_id)
  chain_state = FETCH onchain.CTFExchangeV2.getCondition(condition_id)

  // 2. Compare resolution status
  IF gamma_state.status != data_state.status:
    EMIT WARN 'SOURCEOFTRUTH_GAMMA_DATA_MISMATCH'

  // 3. Compare on-chain vs data API
  IF chain_state.resolved != data_state.resolved:
    EMIT WARN 'SOURCEOFTRUTH_CHAIN_API_MISMATCH'

  // 4. Staleness check
  IF now() - gamma_state.updated_at > staleness_threshold_s:
    EMIT WARN 'STALE_DATA'

  // 5. Emit ObservationReport
  EMIT ObservationReport {
    report_id: gen_id(),
    kind: 'ObservationReport',
    condition_id: condition_id,
    verified: all_agree(gamma_state, data_state, chain_state),
    discrepancies: collect_discrepancies(),
    emitted_at_ms: now_ms()
  }

SDK calls used

• gamma.GET('/markets/<condition_id>')
• data.GET('/markets/<condition_id>')
• onchain.CTFExchangeV2.getCondition(condition_id)

Complexity: O(1) per market; 3 parallel API calls per verification

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Source-of-truth verification request for a condition",
  "source": "internal",
  "payload": {
    "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
    "trigger": "pre-strategy-entry",
    "timestamp_ms": 1746703000000
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — sources agree",
  "payload": {
    "report_id": "rep_sotv_0xf1a2_1746703000000",
    "trace_id": "trc_0xbeef0102030405060710",
    "bot_id": "intel.sourceoftruthverifier",
    "kind": "ObservationReport",
    "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
    "verified": true,
    "discrepancies": [],
    "emitted_at_ms": 1746703003000
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "report_id": "rep_sotv_0xf1a2_1746703000000",
  "trace_id": "trc_0xbeef0102030405060710",
  "bot_id": "intel.sourceoftruthverifier",
  "kind": "ObservationReport",
  "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
  "verified": true,
  "discrepancies": [],
  "emitted_at_ms": 1746703003000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / SourceOfTruthVerifier discrepancy rate and verification latency

16. Developer Reporting

{
  "bot_id": "intel.sourceoftruthverifier",
  "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
  "verified": true,
  "discrepancies": [],
  "gamma_response_ms": 95,
  "data_response_ms": 110,
  "chain_response_ms": 180,
  "killswitch_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, reload from Postgres; re-verify all active markets on first 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

• Attacker causes deliberate Gamma/chain mismatch to trigger strategy pauses via alert flooding
• Stale on-chain state during fast resolution causes spurious CHAIN_API_MISMATCH alerts

Mitigations

• Alert thresholds require multiple mismatches before paging to reduce noise
• ObservationReports informational only — strategies verify independently before pausing

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

SourceOfTruthVerifier incidents are most critical when chain/API mismatch is detected — this may indicate a resolution propagation delay. Page immediately on chain mismatch.

On-call actions

Manual overrides

• force_reverify_all — POST /internal/sourceoftruthverifier/reverify-all to force fresh three-source check on all active markets — After known Gamma or Data API outage recovery

Healthcheck

Endpoint: /internal/health/sourceoftruthverifier | Green: Last verification < 5 min ago AND Postgres reachable AND Gamma + RPC returning 200 | Red: No verification for > 15 min OR Postgres unreachable OR chain/API mismatch unresolved > 10 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%