4.17 MarketResolutionWatcher

1. Bot Identity

Operational profile

2. Purpose

Watches the on-chain resolution state of every active Polymarket market. As a market approaches resolution, it emits typed warnings (T-24h, T-1h, finalising, resolved) so downstream bots can stop opening new positions and start unwinding. Pure observer — never blocks; the actual blocking is done by Risk's PreResolutionFreeze guardrail downstream.

3. Why This Bot Matters

• Trading into resolution

  Once a market is in its finalising window, prices can become extremely sticky and orders can sit unfilled until expiry; opening fresh exposure here is high regret.

• Missing the unwind window

  Without an explicit signal, strategies do not know when to switch from open-mode to unwind-mode.

• Resolution-driven losses

  Bots that hold a position through a resolution event with the wrong outcome lose 100% of that position; the unwind window must be respected.

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

{ "t_minus_warn_hours": 24 }

if (hoursToResolve <= p.t_minus_warn_hours) emit('WARN', hoursToResolve);

{ "t_minus_freeze_hours": 1 }

if (hoursToResolve <= p.t_minus_freeze_hours) emit('FREEZE', hoursToResolve);

8. Default Configuration

{
  "t_minus_warn_hours": 24,
  "t_minus_freeze_hours": 1
}

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.

for each market in active_markets():
  meta = polymarket.metadata(market.id)
  hours = (meta.scheduled_ts_ms - now_ms())/3_600_000
  tier = pick_tier(hours, p)
  emit('resolution_warning', market.id, tier, hours)
subscribe('ConditionResolved', lambda e: emit('resolution_warning', e.market_id, 'RESOLVED', 0))

11. Wire Examples

Input — what arrives on the wire

{
  "market_id": "0xabc",
  "scheduled_ts_ms": 1715263600000,
  "now_ms": 1715260000000
}

Output — what the bot emits

{
  "kind": "resolution_warning",
  "tier": "FREEZE",
  "hours_to_resolve": 0.42
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "kind": "resolution_warning",
  "market_id": "0xabc",
  "tier": "FREEZE",
  "hours_to_resolve": 0.42,
  "ts_ms": 1715260000000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Dashboards

• 4.17 overview dashboard

16. Developer Reporting

"Per emission: market_id, tier, hours_to_resolve, scheduled_ts_ms, on_chain_event (if any)."

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Per-market last-emitted tier (latched). Persisted to durable KV.

State stores

Cold-start recovery

Cold-start hydrates from fast KV; missing keys default to safe fallback.

On restart

All in-flight decisions are re-evaluated; no bot decision is trusted across restart without re-emit.

21. Concurrency & Idempotency

22. Dependencies

Emits to (downstream consumers)

Required before (graph.required_before)

risk.pre_resolution_freeze

23. Security Surfaces

Reads Polymarket REST + Ethereum logs. No write surface.

Signing surface

None — bot does not sign or submit.

Mitigations

• Rate-limit per source
• Audit-log every override
• Require role-based authz on admin paths

24. Polymarket V2 Compatibility

25. Versioning & Migration

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

If signals stop emitting: check Polymarket REST credentials and chain RPC health.

On-call actions

Manual overrides

• polytraders bot pause 4.17 — Disables the bot's enforcement layer; downstream consumers fall back to safe defaults.

Healthcheck

GET /healthz/market_resolution_watcher → 200 if last successful evaluation < 60s ago.

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%