{ "schema_version": "1.0.0", "bot_id": "3.18", "bot_name": "Dispute-Risk Pricing", "slug": "dispute-risk-pricing", "layer": "Strategy", "layer_key": "strat", "bot_class": "Alpha Strategy", "authority": [ "Trade" ], "status": "planned", "readiness": "Spec started", "flagship": false, "is_reference": false, "public_export": false, "identity": { "layer": "Strategy", "bot_class": "Alpha Strategy", "authority": "Trade", "runs_before": "Risk guardrail pipeline", "runs_after": "Observation bus / internal analytics", "applies_to": "Polymarket binary markets currently under UMA dispute where the rule parser confidence is at maximum and the current CLOB price underestimates the true resolution probability", "default_mode": "shadow_only", "user_visible": "Advanced details only", "developer_owner": "Polytraders core \u2014 Strategy pod" }, "purpose": "Dispute-Risk Pricing identifies Polymarket markets affected by UMA dispute uncertainty where the current price does not reflect the true resolution probability given the dispute risk. The bot buys positions that appear mispriced due to dispute-inflated uncertainty, but only when the resolution-rule reading is unambiguous and the parser confidence is at maximum.", "why_it_matters": [ { "failure": "Rule reading changes during dispute window", "consequence": "If the resolution rule interpretation changes after entry, the position is now directionally wrong and cannot be safely exited at the original thesis." }, { "failure": "Stale input data", "consequence": "Acting on stale signals for Dispute-Risk Pricing produces trades based on outdated market conditions, generating adverse fills." }, { "failure": "KillSwitch not respected", "consequence": "Emitting OrderIntents while KillSwitch is active bypasses risk controls." } ], "polymarket_inputs": [ { "input": "CLOB book (mid, depth, spread)", "source": "ws_market", "required": true, "use": "Read current market price and available depth for order sizing." }, { "input": "Market status (open/closed/resolved)", "source": "clob_public", "required": true, "use": "Skip closed or resolved markets." } ], "internal_inputs": [ { "input": "KillSwitch active flag", "source": "KillSwitch", "required": true, "use": "Abort all intent emission if KillSwitch active." }, { "input": "Dispute-Risk Pricing analytics signal", "source": "internal (analytics engine)", "required": true, "use": "Provides the core Dispute-Risk Pricing signal that drives trade decisions." }, { "input": "Builder code bytes32", "source": "internal config", "required": true, "use": "Injected into builder field on every signed V2 OrderIntent." } ], "raw_params": [ "min_parser_confidence \u00b7 0\u20131", "max_position_per_market \u00b7 int", "require_human_signoff \u00b7 bool", "halt_on_contradiction \u00b7 bool" ], "parameters": [ { "name": "min_parser_confidence", "default": 0.9, "warning": 0.8, "hard": 0.7, "controls": "Minimum resolution rule parsing confidence (0\u20131) required before the bot considers a dispute-risk trade.", "why_default_matters": "0.90 ensures the resolution rule is effectively unambiguous; lower confidence creates risk of trading on incorrect rule interpretation.", "threshold_logic": [ { "condition": ">= 0.90", "action": "Allow dispute-risk evaluation" }, { "condition": "0.80\u20130.90", "action": "WARN DRP_LOW_CONFIDENCE; halve size" }, { "condition": "< 0.70", "action": "HARD_REJECT DRP_CONFIDENCE_BELOW_FLOOR" } ], "dev_check": "if parser_confidence < params.hard: return skip('DRP_CONFIDENCE_BELOW_FLOOR')", "user_facing": "The resolution rule reading was not clear enough for a dispute-risk trade." }, { "name": "max_position_per_market", "default": 300, "warning": 500, "hard": 700, "controls": "Maximum pUSD exposure per market under dispute.", "why_default_matters": "300 pUSD limits single-market dispute exposure.", "threshold_logic": [ { "condition": "<= 300 pUSD", "action": "Normal sizing" }, { "condition": "> 700 pUSD", "action": "Reject config \u2014 PARAMETER_CHANGE_REQUIRES_APPROVAL" } ], "dev_check": "if params.max_position_per_market > params.hard: raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')", "user_facing": "Position size capped at per-market maximum." }, { "name": "require_human_signoff", "default": true, "warning": null, "hard": null, "controls": "If true, each new dispute-risk pair requires one-time human approval before automatic trading.", "why_default_matters": "Prevents automated trading on novel dispute types without human review.", "threshold_logic": [ { "condition": "not approved", "action": "HARD_REJECT DRP_NOT_APPROVED" } ], "dev_check": "if require_human_signoff and not approved: return skip('DRP_NOT_APPROVED')", "user_facing": "This market dispute has not been manually approved for automated trading." }, { "name": "halt_on_contradiction", "default": true, "warning": null, "hard": null, "controls": "If true, halt all trading on a market if a new oracle signal contradicts the current rule reading.", "why_default_matters": "Prevents compounding losses when the resolution reading changes during a dispute.", "threshold_logic": [ { "condition": "contradiction detected", "action": "HARD_REJECT DRP_CONTRADICTION_HALT" } ], "dev_check": "if contradiction_detected: return skip('DRP_CONTRADICTION_HALT')", "user_facing": "A conflicting resolution signal was detected; trading was halted for safety." } ], "default_config": { "bot_id": "strat.dispute_risk_pricing", "version": "0.1.0", "mode": "shadow_only", "defaults": { "min_parser_confidence": 0.9, "max_position_per_market": 300, "require_human_signoff": true, "halt_on_contradiction": true }, "locked": { "min_parser_confidence": { "min": 0.7 }, "max_position_per_market": { "min": 700 } } }, "implementation_flow": [ "Check KillSwitch; if active, emit no OrderIntents.", "FETCH Dispute-Risk Pricing analytics signal from internal engine.", "IF signal below hard floor: SKIP, emit sampled DecisionReport DRP_NO_EDGE.", "FETCH clob_public market status; skip if closed or resolved.", "FETCH ws_market book; compute current mid and available depth.", "IF signal < warning threshold: WARN DRP_MARGINAL; reduce size 50%.", "Compute order size = min(max_size_param, available_depth).", "EMIT IOC OrderIntent with builder code.", "EMIT DecisionReport with intent_emitted=true, reason=DRP_TRADE." ], "decision_logic": { "approve": "All gates passed, KillSwitch inactive, market open. Emit IOC OrderIntent.", "reshape_required": "Not applicable \u2014 reshaping handled by downstream Risk guardrail.", "reject": "Signal below hard floor; stale data; market closed; KillSwitch active.", "warning_only": "Signal in warning zone triggers 50% size reduction." }, "decision_output_schema": "OrderIntent", "decision_output_example": { "intent_id": "oi_01HDRP0000001A", "trace_id": "tr_01HDRP000TR001", "market_id": "0xdisputer000000000000000000000000000000000000000000000000000000000001", "outcome": "YES", "side": "buy", "price": "0.540", "size_pUSD": "200.00", "tif": "IOC", "post_only": false, "builder": { "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000", "fee_bps": 25 }, "negrisk_aware": false, "decision": { "signal_score": 0.75, "reasons": [ "DRP_TRADE" ] }, "comment": "fees are operator-set at match time in V2 \u2014 feeRateBps is NOT on the signed order" }, "developer_log": { "bot_id": "strat.dispute_risk_pricing", "market_id": "0xdisputer000000000000000000000000000000000000000000000000000000000001", "signal_score": 0.75, "intent_emitted": true, "reason": "DRP_TRADE", "emitted_at_ms": 1746790800000 }, "user_explanations": [ { "situation": "Dispute-Risk Pricing trade placed", "message": "The Dispute-Risk Pricing strategy detected a suitable opportunity and placed a trade." }, { "situation": "Edge too small \u2014 no trade", "message": "The signal was below the minimum threshold. No trade was placed." }, { "situation": "Safety gate active \u2014 no trade", "message": "A safety condition (stale data, kill switch, or parameter limit) blocked the trade." } ], "failure_modes": { "main_failure_mode": "If the resolution rule interpretation changes after entry, the position is now directionally wrong and cannot be safely exited at the original thesis.", "false_positive_risk": "Signal mis-fires when market conditions change rapidly, producing trades that quickly move against the Dispute-Risk Pricing thesis.", "false_negative_risk": "Hard floor set too conservatively misses genuine opportunities.", "safe_fallback": "If ws_market feed stale or analytics signal unavailable, skip without emitting any OrderIntent.", "required_dependencies": [ "ws_market", "clob_public", "internal Dispute-Risk Pricing analytics engine", "KillSwitch", "internal builder code" ] }, "acceptance_tests": { "unit": [ { "test": "Emit IOC when signal=0.75 and all gates pass", "setup": "standard config", "expected": "IOC OrderIntent; reason=DRP_TRADE" }, { "test": "Skip when signal below hard floor", "setup": "signal=below_hard", "expected": "No OrderIntent; sampled reason=DRP_NO_EDGE" }, { "test": "Skip when KillSwitch active", "setup": "killswitch.active=true", "expected": "No OrderIntents emitted" } ], "integration": [ { "test": "Full cycle: signal \u2192 computation \u2192 IOC OrderIntent on Polygon testnet", "expected": "Order has builder.code, no feeRateBps, EIP-712 domain v2" } ], "property": [ { "property": "Bot never emits OrderIntent when KillSwitch is active", "required": "Always true" }, { "property": "feeRateBps never present on any signed OrderIntent", "required": "Always true" } ] }, "checklist_overrides": {}, "legacy_goal": "Buy positions that are mispriced because of UMA dispute uncertainty \u2014 only when the resolution-rule reading is unambiguous.", "legacy_pm_signals": [ "Markets in proposal/dispute with mid pulled away from a clean source-of-truth read", "ResolutionRuleParser (4.8) confidence score and contradiction flags", "Historical dispute-resolution outcomes for the rule template" ], "legacy_external_feeds": [ "UMA on-chain dispute state" ], "reporting_groups": [ "strategy_decision" ], "reason_codes": [ { "code": "DRP_TRADE", "severity": "INFO", "meaning": "All gates passed. IOC OrderIntent emitted for Dispute-Risk Pricing.", "action": "Emit IOC OrderIntent.", "user_message": "A Dispute-Risk Pricing trade was placed." }, { "code": "DRP_MARGINAL", "severity": "WARN", "meaning": "Edge is within the warning threshold; size reduced 50%.", "action": "Emit at 50% size; log warning.", "user_message": "A small edge was found; a reduced-size Dispute-Risk Pricing trade was placed." }, { "code": "DRP_NO_EDGE", "severity": "INFO", "meaning": "Edge below hard floor. Skipping.", "action": "Skip; emit sampled DecisionReport.", "user_message": "The edge was too small to justify a trade." }, { "code": "DRP_CONFIDENCE_BELOW_FLOOR", "severity": "HARD_REJECT", "meaning": "Parser confidence below 0.70 hard floor.", "action": "Skip; no OrderIntent.", "user_message": "The resolution rule was not clear enough for a dispute-risk trade." }, { "code": "DRP_CONTRADICTION_HALT", "severity": "HARD_REJECT", "meaning": "Oracle signal contradicts current rule reading. All trading on market halted.", "action": "Skip; no OrderIntent; log alert.", "user_message": "A conflicting resolution signal was detected; trading halted for safety." }, { "code": "DRP_HARD_REJECT", "severity": "HARD_REJECT", "meaning": "A critical gate condition blocked the trade (stale data, kill switch, or hard parameter breach).", "action": "Skip; no OrderIntent.", "user_message": "A safety condition blocked the trade." }, { "code": "KILL_SWITCH_ACTIVE", "severity": "HARD_REJECT", "meaning": "Global kill switch is active.", "action": "Skip all markets; no OrderIntents emitted.", "user_message": "Trading is currently paused." } ], "metrics": { "emitted": [ { "name": "polytraders_strat_disputeriskpricing_decisions_total", "type": "counter", "unit": "count", "labels": [ "verdict", "reason_code" ], "meaning": "Total evaluation cycles by verdict and reason code." }, { "name": "polytraders_strat_disputeriskpricing_signal_score", "type": "histogram", "unit": "score", "labels": [], "meaning": "Distribution of analytics signal scores at evaluation." }, { "name": "polytraders_strat_disputeriskpricing_intents_emitted_total", "type": "counter", "unit": "count", "labels": [ "outcome" ], "meaning": "Total IOC OrderIntents emitted." }, { "name": "polytraders_strat_disputeriskpricing_eval_latency_ms", "type": "histogram", "unit": "milliseconds", "labels": [], "meaning": "Latency from signal receipt to OrderIntent emit." } ], "alerts": [ { "name": "DisputeRiskPricingStaleFeed", "condition": "rate(polytraders_strat_disputeriskpricing_decisions_total{reason_code='STALE_MARKET_DATA'}[5m]) > 0.1", "severity": "warn", "runbook": "#runbook-dispute-risk-pricing-stale" }, { "name": "DisputeRiskPricingKillSwitch", "condition": "rate(polytraders_strat_disputeriskpricing_decisions_total{reason_code='KILL_SWITCH_ACTIVE'}[1m]) > 0", "severity": "page", "runbook": "#runbook-killswitch" }, { "name": "DisputeRiskPricingNoEdge", "condition": "rate(polytraders_strat_disputeriskpricing_decisions_total{verdict='skip',reason_code='DRP_NO_EDGE'}[10m]) / rate(polytraders_strat_disputeriskpricing_decisions_total[10m]) > 0.95", "severity": "warn", "runbook": "#runbook-dispute-risk-pricing-edge" } ] }, "state": { "store": "redis", "shape": "Per market: last signal score, last evaluated timestamp; keyed by market_id", "ttl": "60s per signal snapshot", "recovery": "On cold start, signals rebuilt from next analytics engine poll.", "size_estimate": "~150 bytes per tracked market; < 500 KB total" }, "concurrency": { "execution_model": "actor-per-market", "max_in_flight": 25, "idempotency_key": "intent_id", "timeout_ms": 300, "backpressure": "drop oldest signal per market_id when queue > 2", "locking": "per-market_id mutex for signal state" }, "dependencies": { "depends_on": [ { "bot_id": "risk.kill_switch", "why": "Checked first; blocks all intent emission when active." } ], "emits_to": [ { "bot_id": "risk.portfolio_guard", "what": "IOC OrderIntents for risk guardrail evaluation." }, { "bot_id": "gov.builder_attribution", "what": "builder.code bytes32 on every OrderIntent." } ], "sibling": [], "external": [ { "service": "Polymarket CLOB WebSocket (ws_market)", "sla": "best-effort", "fallback": "Skip all OrderIntent emission on disconnect." }, { "service": "Internal Dispute-Risk Pricing analytics engine", "sla": "internal SLA", "fallback": "If signal unavailable, treat as below hard floor and skip." } ] }, "security_surfaces": { "signs_orders": true, "private_key_access": "signing-only", "abuse_vectors": [ "Signal injection to produce false Dispute-Risk Pricing trades", "Order sizing parameter manipulation to exceed position limits" ], "mitigations": [ "Dispute-Risk Pricing analytics signals sourced from authenticated internal engine only", "Hard limits on position size enforced before OrderIntent emission", "Builder code injected from secure internal config" ] }, "failure_injection": [ { "scenario": "SIGNAL_UNAVAILABLE", "how_to_inject": "Cut internal analytics engine connection", "expected_behaviour": "No entries; DecisionReport with reason=DRP_HARD_REJECT emitted", "recovery": "Automatic when engine reconnects." }, { "scenario": "HARD_FLOOR_BREACH", "how_to_inject": "Inject signal below hard floor", "expected_behaviour": "DRP_NO_EDGE; no OrderIntent", "recovery": "Automatic on next valid signal." }, { "scenario": "KILL_SWITCH_ON", "how_to_inject": "Set killswitch.active=true", "expected_behaviour": "No OrderIntents emitted for any market", "recovery": "Automatic on manual KillSwitch reset." } ], "runbook": { "summary": "Dispute-Risk Pricing incidents are typically stale analytics feeds or kill-switch activations. Hard-floor skips are normal.", "oncall_actions": [ { "alert": "DisputeRiskPricingStaleFeed", "first_action": "Check internal Dispute-Risk Pricing analytics engine connectivity and feed health.", "escalate_to": "Infra on-call if feed lag > 5 min." }, { "alert": "DisputeRiskPricingKillSwitch", "first_action": "Confirm KillSwitch activation was intentional.", "escalate_to": "Risk pod lead immediately." }, { "alert": "DisputeRiskPricingNoEdge", "first_action": "Review signal calibration; check if market conditions have changed.", "escalate_to": "Strategy pod lead if prolonged." } ], "manual_overrides": [ { "name": "exclude_market", "how": "Add market_id to config.excluded_markets", "when": "Market is showing anomalous conditions that invalidate the Dispute-Risk Pricing signal." } ], "healthcheck": "GET /internal/health/dispute-risk-pricing -> 200 if Analytics engine active; signal age < 60s; KillSwitch inactive.. Red: Analytics engine down or KillSwitch active.." }, "promotion_gates": { "to_shadow": [ { "gate": "Unit tests pass including hard-floor skip and kill-switch block", "how_measured": "CI test run", "threshold": "100% pass" } ], "to_limited_live": [ { "gate": "p99 eval latency < 300ms over 24h shadow run", "how_measured": "polytraders_strat_disputeriskpricing_eval_latency_ms histogram", "threshold": "p99 < 300ms" } ], "to_general_live": [ { "gate": "E2E: signal \u2192 computation \u2192 IOC OrderIntent on Polygon testnet with builder.code and no feeRateBps", "how_measured": "E2E test", "threshold": "Pass" } ] }, "wire_examples": { "input": [ { "label": "Dispute-Risk Pricing analytics signal", "source": "internal (analytics engine)", "payload": { "market_id": "0xdisputer000000000000000000000000000000000000000000000000000000000001", "signal_score": "0.75", "received_at_ms": 1746790800000 } } ], "output": [ { "label": "OrderIntent \u2014 Dispute-Risk Pricing IOC buy YES", "payload": { "intent_id": "oi_01HDRP0000001A", "market_id": "0xdisputer000000000000000000000000000000000000000000000000000000000001", "outcome": "YES", "side": "buy", "price": "0.540", "size_pUSD": "200.00", "tif": "IOC", "builder": { "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000", "fee_bps": 25 }, "decision": { "signal_score": 0.75, "reasons": [ "DRP_TRADE" ] } } } ] }, "reference_implementation": { "pseudocode": "FUNCTION onSignalUpdate(market_id, signal):\n ks = FETCH internal.killswitch.status\n IF ks.active: RETURN\n\n // Hard floor gate\n IF signal.score < params.min_parser_confidence_hard:\n IF random() < 0.01:\n EMIT DecisionReport(intent_emitted=false, reason='DRP_NO_EDGE')\n RETURN\n\n mkt = FETCH clob_public.GET('/markets/' + market_id)\n IF mkt.closed OR mkt.resolved: RETURN\n\n // Warning threshold check\n sizeMultiplier = 0.5 IF signal.score < params.min_parser_confidence_warn ELSE 1.0\n IF sizeMultiplier < 1.0: WARN('DRP_MARGINAL')\n\n // Book snapshot\n book = FETCH ws_market.book(market_id)\n mid = (book.best_bid + book.best_ask) / 2\n depth = FETCH clob_public.depth(market_id)\n\n // Size computation\n orderSize = toPusdUnits(min(params.max_position_per_market * sizeMultiplier, depth.available))\n\n EMIT OrderIntent(market=market_id, outcome='YES', side='buy', price=mid,\n size_pUSD=orderSize, tif='IOC', builder=internalBuilderCode)\n EMIT DecisionReport(intent_emitted=true, signal_score=signal.score,\n reason='DRP_TRADE')", "sdk_calls": [ "ws_market.subscribe('book', [market_id])", "fetchClobPublic('/markets/' + market_id)", "internal.analyticsEngine.signal(market_id)", "buildOrderTypedData(orderParams, {name:'CTFExchange', version:'2', chainId:137})", "internal.builder_code" ], "complexity": "O(1) per signal update per market" }, "api_surface": [ "clob_public", "clob_auth", "ws_market", "onchain", "internal" ], "network": [ "polygon" ], "version": { "spec": "2.0.0", "implementation": "0.1.0", "schema": "2", "released": null, "planned_release": "Q3-2026" }, "migration_history": [ { "date": "2026-04-28", "from": "n/a", "to": "v2-spec", "reason": "Spec drafted post-CLOB-V2 cutover; bot not yet implemented", "action_taken": "Designed against V2 schema (pUSD, builder codes, V2 EIP-712 domain)" } ], "polymarket_v2_compat": { "clob_version": "v2", "collateral": "pUSD", "eip712_domain_version": "2", "builder_code_aware": true, "negrisk_aware": false, "multichain_ready": false, "sdk_used": "py-clob-client-v2", "settlement_contract": "CTFExchangeV2", "notes": "Bot not yet implemented; designed against V2 schema (pUSD, builder codes, V2 EIP-712 domain). feeRateBps not present on any signed OrderIntent." }, "reporting": { "emits_kinds": [ "DecisionReport" ], "topics": [ "polytraders.reports.decision" ], "cadence": "every-event", "retention_class": "2y", "sampling_rule": "emit-every", "bus_failure_action": "fail-closed", "user_visible": "yes", "consumes_kinds": [ "ObservationReport", "RiskVote" ] }, "capital_impact": "Direct", "v3_status": { "phase": 8, "phase_name": "Additional strategies", "docs": { "done": 27, "total": 27, "state": "done" }, "impl": { "done": 0, "total": 15, "state": "pending" }, "runtime": { "done": 0, "total": 8, "state": "pending" }, "overall": "pending" } }