{ "schema_version": "1.0.0", "bot_id": "2.5", "bot_name": "GasOracle", "slug": "gasoracle", "layer": "Execution", "layer_key": "exec", "bot_class": "Execution Utility", "authority": [ "Reshape" ], "status": "live", "readiness": "General live", "flagship": false, "is_reference": false, "public_export": false, "identity": { "layer": "Execution", "bot_class": "Execution Utility", "authority": "Reshape", "runs_before": "Order signing and on-chain submission", "runs_after": "ExecutionPlan assembly (SmartRouter)", "applies_to": "Every on-chain operation that can be deferred without breaching a risk constraint", "default_mode": "general_live", "user_visible": "Advanced details only", "developer_owner": "Polytraders core" }, "purpose": "GasOracle continuously monitors the Polygon network gas-price environment and advises the execution layer on whether on-chain operations (order submission, cancel-and-replace, neg-risk conversions) are economically viable at the current gas price. It defers non-urgent operations when gas is above the rolling percentile threshold, and never defers risk-critical operations such as emergency cancellations.", "why_it_matters": [ { "failure": "Submitting during a gas spike", "consequence": "Transaction costs erode trade profitability; maker rebates (paid in pUSD) can be wiped out by gas fees on low-edge positions." }, { "failure": "Deferring a risk-critical cancellation", "consequence": "A resting order that should be pulled stays live during adverse market movement, accumulating unintended exposure." }, { "failure": "Using a stale 24h gas baseline", "consequence": "The percentile thresholds are miscalibrated, causing GasOracle to defer operations during normal conditions or approve during actual spikes." } ], "polymarket_inputs": [], "internal_inputs": [ { "input": "Polygon mempool gas-price snapshot (gwei)", "source": "onchain RPC (eth_gasPrice / fee history)", "required": true, "use": "Current gas price evaluated against the rolling 24h percentile baseline." }, { "input": "Rolling 24h gas-price baseline", "source": "internal time-series store", "required": true, "use": "Compute the max_gas_percentile_for_ops threshold from historical distribution." }, { "input": "Pending operation queue with urgency flags", "source": "internal execution scheduler", "required": true, "use": "Identify whether each pending op is risk-critical (never_defer) or deferrable." } ], "raw_params": [ "max_gas_percentile_for_ops \u00b7 0\u2013100", "conversion_min_ev_usd \u00b7 float", "defer_non_urgent \u00b7 bool", "never_defer_risk \u00b7 bool (locked true)" ], "parameters": [ { "name": "max_gas_percentile_for_ops", "default": 75, "warning": 85, "hard": 95, "controls": "Maximum historical gas-price percentile (0\u2013100) at which non-urgent on-chain operations are approved. Operations are deferred when the current gas price exceeds this percentile of the rolling 24h distribution.", "why_default_matters": "Setting the gate at the 75th percentile ensures operations are deferred during the top quarter of daily gas-price spikes, keeping transaction costs within budget without causing excessive deferrals.", "threshold_logic": [ { "condition": "current_gas <= p75", "action": "APPROVE \u2014 submit operation" }, { "condition": "p75 < current_gas <= p85", "action": "WARN \u2014 elevated gas; proceed for non-urgent ops" }, { "condition": "p85 < current_gas <= p95", "action": "RESHAPE \u2014 defer all non-urgent ops" }, { "condition": "current_gas > p95", "action": "Hard block \u2014 defer unless never_defer_risk=true" } ], "dev_check": "if pct > params.hard and not op.never_defer: return defer('GAS_ORACLE_SPIKE_BLOCK')", "user_facing": "On-chain operations are paused temporarily because network fees are unusually high right now." }, { "name": "conversion_min_ev_usd", "default": 0.1, "warning": 0.05, "hard": 0.0, "controls": "Minimum expected value (pUSD) that a neg-risk conversion must generate after gas costs before GasOracle approves the on-chain conversion call.", "why_default_matters": "Requiring at least $0.10 net EV prevents marginal conversions from being triggered when gas costs consume the arb spread.", "threshold_logic": [ { "condition": "ev_after_gas >= 0.10", "action": "APPROVE conversion" }, { "condition": "0.05 <= ev_after_gas < 0.10", "action": "WARN \u2014 margin thin" }, { "condition": "ev_after_gas < 0.05", "action": "RESHAPE \u2014 defer conversion" } ], "dev_check": "ev_net = ev_gross - gas_cost_pusd; if ev_net < params.hard: return defer('GAS_ORACLE_EV_BELOW_FLOOR')", "user_facing": "" }, { "name": "defer_non_urgent", "default": true, "warning": "\u2014", "hard": "\u2014", "controls": "When true, non-urgent on-chain operations (routine cancel-replace, post-fill bookkeeping) are deferred when gas exceeds max_gas_percentile_for_ops.", "why_default_matters": "Deferring non-urgent operations by default limits gas spend during spikes without impacting trading outcomes.", "threshold_logic": [ { "condition": "defer_non_urgent=true AND gas > threshold", "action": "Queue op for retry in next evaluation cycle" }, { "condition": "defer_non_urgent=false", "action": "Submit regardless of gas price (not recommended except for testing)" } ], "dev_check": "if not params.defer_non_urgent: skip_gas_check()", "user_facing": "" }, { "name": "never_defer_risk", "default": true, "warning": "\u2014", "hard": "\u2014", "controls": "Locked true. Risk-critical on-chain operations (emergency order cancellations, kill-switch triggered burns) always bypass gas deferral logic.", "why_default_matters": "A gas spike must never prevent the system from executing an emergency cancellation. Risk safety is unconditional.", "threshold_logic": [ { "condition": "op.risk_critical=true AND never_defer_risk=true", "action": "APPROVE unconditionally \u2014 bypass gas check" } ], "dev_check": "assert params.never_defer_risk == True # locked; config change requires approval", "user_facing": "" } ], "default_config": { "bot_id": "exec.gas_oracle", "version": "2.1.0", "mode": "general_live", "defaults": { "max_gas_percentile_for_ops": 75, "conversion_min_ev_usd": 0.1, "defer_non_urgent": true, "never_defer_risk": true }, "locked": { "never_defer_risk": { "value": true } } }, "implementation_flow": [ "Fetch current Polygon gas price (gwei) via onchain RPC (eth_feeHistory or eth_gasPrice).", "Retrieve the rolling 24h gas-price baseline from the internal time-series store; compute percentile rank of current gas price.", "For each pending on-chain operation in the execution scheduler queue, read its urgency flag (risk_critical vs. non_urgent).", "If op.risk_critical=true (never_defer_risk=true locked): approve unconditionally \u2014 emit GasDecision.PASS.", "If current gas percentile <= max_gas_percentile_for_ops: approve non-urgent op \u2014 emit GasDecision.PASS.", "If percentile is in the WARN band (max_gas_percentile..+10): approve with a WARN annotation on the GasDecision.", "If percentile exceeds max_gas_percentile_for_ops and defer_non_urgent=true: emit GasDecision.DEFER with retry_after_s set to next expected dip (estimated from baseline).", "For neg-risk conversion ops: additionally compute ev_after_gas = ev_gross - gas_cost_pusd; if below conversion_min_ev_usd, emit GasDecision.DEFER with GAS_ORACLE_EV_BELOW_FLOOR.", "Emit GasDecision record to internal execution scheduler with verdict, reason_code, gas_gwei_current, gas_percentile, and retry_after_s.", "Append data point to rolling 24h baseline." ], "decision_logic": { "approve": "Current gas price falls at or below max_gas_percentile_for_ops of the rolling 24h baseline, or the operation is marked risk_critical.", "reshape_required": "Non-urgent operation deferred to a lower-gas window. The operation is queued with a retry_after_s estimate derived from the baseline distribution.", "reject": "Conversion op net EV falls below conversion_min_ev_usd hard floor (0.0); GasOracle cancels the conversion entirely.", "warning_only": "Gas is in the 75th\u201385th percentile band; GasDecision.PASS is emitted with a WARN annotation for monitoring." }, "decision_output_schema": "GasDecision", "decision_output_example": { "oracle_id": "exec.gas_oracle", "op_id": "op_3c4d5e6f7a8b9c0d", "verdict": "DEFER", "reason_code": "GAS_ORACLE_SPIKE_BLOCK", "gas_gwei_current": 142.7, "gas_percentile": 88, "threshold_percentile": 75, "retry_after_s": 180, "never_defer_risk": true, "evaluated_at_ms": 1746768900000 }, "developer_log": { "oracle_id": "exec.gas_oracle", "op_id": "op_3c4d5e6f7a8b9c0d", "op_kind": "cancel_replace", "risk_critical": false, "gas_gwei_current": 142.7, "gas_percentile": 88, "max_gas_percentile_for_ops": 75, "defer_non_urgent": true, "verdict": "DEFER", "reason_code": "GAS_ORACLE_SPIKE_BLOCK", "retry_after_s": 180, "baseline_window_h": 24, "evaluated_at_ms": 1746768900000 }, "user_explanations": [ { "situation": "On-chain operation deferred due to gas spike", "message": "A routine order update was postponed briefly because network fees are currently elevated. It will be retried automatically when fees return to normal levels." }, { "situation": "Neg-risk conversion blocked \u2014 margin too thin after gas", "message": "A conversion operation was not submitted because the expected gain after network fees did not meet the minimum threshold." }, { "situation": "Risk-critical cancellation approved despite high gas", "message": "An emergency order cancellation was submitted immediately despite elevated network fees because risk safety overrides gas cost constraints." } ], "failure_modes": { "main_failure_mode": "Stale 24h baseline causing the percentile rank to be computed incorrectly \u2014 GasOracle may approve operations during genuine spikes or block during normal conditions.", "false_positive_risk": "Deferring a non-urgent operation unnecessarily during a brief transient spike, causing minor latency in order management.", "false_negative_risk": "Approving an operation at a gas price that turns out to be a spike because the baseline has not yet captured recent price history.", "safe_fallback": "If the rolling baseline store is unreachable, fall back to a hard static cap of 100 gwei. If the RPC gas feed is unreachable, defer all non-urgent ops and surface GAS_ORACLE_RPC_FAILURE.", "required_dependencies": [ "Polygon onchain RPC (gas price feed)", "Internal time-series store (24h baseline)", "Execution scheduler (pending operation queue)" ] }, "acceptance_tests": { "unit": [ { "test": "Approve operation when gas is at 60th percentile (below 75th threshold)", "setup": "current_gas=p60, max_gas_percentile_for_ops=75, op.risk_critical=false", "expected": "GasDecision.verdict=PASS" }, { "test": "Defer non-urgent operation when gas is at 88th percentile", "setup": "current_gas=p88, max_gas_percentile_for_ops=75, defer_non_urgent=true", "expected": "GasDecision.verdict=DEFER, reason_code=GAS_ORACLE_SPIKE_BLOCK" }, { "test": "Approve risk-critical op unconditionally at 98th percentile", "setup": "current_gas=p98, op.risk_critical=true, never_defer_risk=true (locked)", "expected": "GasDecision.verdict=PASS \u2014 gas check bypassed" }, { "test": "Block conversion when ev_after_gas < 0.0 (hard floor)", "setup": "ev_gross=0.08, gas_cost_pusd=0.12, conversion_min_ev_usd=0.10", "expected": "GasDecision.verdict=DEFER, reason_code=GAS_ORACLE_EV_BELOW_FLOOR" }, { "test": "Emit WARN annotation when gas is in 75th\u201385th percentile band", "setup": "current_gas=p80, max_gas_percentile_for_ops=75", "expected": "GasDecision.verdict=PASS with warn_annotation=GAS_ORACLE_ELEVATED" } ], "integration": [ { "test": "End-to-end: deferred op is retried after gas normalises", "expected": "Op queued with retry_after_s; re-evaluated next cycle; approved once gas drops below threshold" }, { "test": "Baseline store outage causes static-cap fallback", "expected": "GasOracle falls back to 100 gwei hard cap; emits GAS_ORACLE_BASELINE_UNAVAILABLE" } ], "property": [ { "property": "never_defer_risk=true (locked) \u2014 risk-critical ops always receive PASS regardless of gas", "required": "Always true" }, { "property": "GasDecision always includes gas_gwei_current, gas_percentile, and evaluated_at_ms", "required": "Always true" } ] }, "checklist_overrides": {}, "legacy_goal": "Decide when on-chain operations are economical.", "legacy_pm_signals": [ "Pending neg-risk conversion EV vs. expected gas cost" ], "legacy_external_feeds": [ "Polygon gas-price oracles", "24h gas baseline (rolling)" ], "reporting_groups": [ "execution" ], "network": [ "polygon" ], "api_surface": [ "onchain", "internal" ], "version": { "spec": "2.0.0", "implementation": "2.1.0", "schema": "2", "released": "2026-04-28" }, "migration_history": [ { "date": "2026-04-28", "from": "v1", "to": "v2", "reason": "CLOB V2 cutover; collateral renamed from USDC.e to pUSD", "action_taken": "Removed all USDC.e references from gas-cost calculation helpers; gas-cost estimates now expressed in pUSD. No CLOB order fields touched by this bot \u2014 GasOracle is purely internal/onchain and has no EIP-712 surface." } ], "polymarket_v2_compat": { "clob_version": "v2", "collateral": "pUSD", "eip712_domain_version": "2", "builder_code_aware": false, "negrisk_aware": false, "multichain_ready": false, "sdk_used": "py-clob-client-v2 (no direct CLOB calls; only onchain RPC)", "settlement_contract": "CTFExchangeV2", "notes": "GasOracle is internal-only and does not call Polymarket V2 APIs directly. It monitors the Polygon gas environment and gates on-chain operations. Gas costs are expressed in pUSD (USDC-backed ERC-20) for consistency with V2 fee accounting." }, "reference_implementation": { "summary": "Fetches the current Polygon gas price, computes its percentile rank against the rolling 24h baseline, and emits a GasDecision (PASS/DEFER) for each pending on-chain operation. Risk-critical operations always bypass the gas gate.", "language_note": "Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.", "pseudocode": "FUNCTION evaluateGas(pending_ops):\n // --- 1. Fetch current gas price ---\n gas_gwei = FETCH onchain_rpc.eth_gasPrice() // gwei\n IF gas_gwei IS NULL:\n FOR op IN pending_ops:\n IF NOT op.risk_critical:\n EMIT GasDecision(op, DEFER, GAS_ORACLE_RPC_FAILURE)\n RETURN\n\n // --- 2. Compute percentile rank from 24h baseline ---\n baseline = FETCH internal.gas_baseline_24h() // sorted list of gwei samples\n IF baseline IS NULL OR isStale(baseline, 300):\n cap_gwei = 100 // static fallback cap\n pct = 99 IF gas_gwei > cap_gwei ELSE 50\n EMIT WARN GAS_ORACLE_BASELINE_UNAVAILABLE\n ELSE:\n pct = percentile_rank(gas_gwei, baseline) // 0..100\n\n // --- 3. For each pending operation ---\n FOR op IN pending_ops:\n // --- 3a. Risk-critical bypass ---\n IF op.risk_critical AND params.never_defer_risk:\n EMIT GasDecision(op, PASS, GAS_ORACLE_RISK_BYPASS,\n gas_gwei=gas_gwei, pct=pct)\n CONTINUE\n\n // --- 3b. Neg-risk conversion EV check ---\n IF op.kind == 'negrisk_conversion':\n gas_cost_pusd = estimate_gas_cost_pusd(gas_gwei, op.gas_limit)\n ev_net = op.ev_gross_pusd - gas_cost_pusd\n IF ev_net < params.conversion_min_ev_usd:\n EMIT GasDecision(op, DEFER, GAS_ORACLE_EV_BELOW_FLOOR,\n ev_net=ev_net, gas_cost_pusd=gas_cost_pusd)\n CONTINUE\n\n // --- 3c. Gas percentile gate ---\n IF pct > params.max_gas_percentile_for_ops:\n IF NOT params.defer_non_urgent:\n EMIT GasDecision(op, PASS, GAS_ORACLE_ELEVATED)\n ELSE:\n retry_after_s = estimate_gas_dip_s(baseline, params.max_gas_percentile_for_ops)\n EMIT GasDecision(op, DEFER, GAS_ORACLE_SPIKE_BLOCK,\n retry_after_s=retry_after_s, gas_percentile=pct)\n ELSE IF pct > params.max_gas_percentile_for_ops - 10:\n EMIT GasDecision(op, PASS, GAS_ORACLE_ELEVATED, warn=true, gas_percentile=pct)\n ELSE:\n EMIT GasDecision(op, PASS, GAS_ORACLE_OK, gas_percentile=pct)\n\n // --- 4. Append current sample to baseline ---\n internal.gas_baseline_24h.append(gas_gwei, now_ms())\n", "sdk_calls": [ "onchain_rpc.eth_gasPrice()", "onchain_rpc.eth_feeHistory(blockCount=20, newestBlock='latest')", "internal.gas_baseline_24h.fetch()", "internal.gas_baseline_24h.append(sample)", "estimate_gas_cost_pusd(gas_gwei, gas_limit)" ], "complexity": "O(P) where P = number of pending on-chain operations per evaluation cycle" }, "wire_examples": { "input": { "label": "Pending non-urgent cancel-replace operation", "source": "internal execution scheduler", "payload": { "op_id": "op_3c4d5e6f7a8b9c0d", "kind": "cancel_replace", "risk_critical": false, "gas_limit": 80000, "ev_gross_pusd": null, "enqueued_at_ms": 1746768840000 } }, "output": { "label": "GasDecision \u2014 deferred due to gas spike", "payload": { "oracle_id": "exec.gas_oracle", "op_id": "op_3c4d5e6f7a8b9c0d", "verdict": "DEFER", "reason_code": "GAS_ORACLE_SPIKE_BLOCK", "gas_gwei_current": 142.7, "gas_percentile": 88, "threshold_percentile": 75, "retry_after_s": 180, "never_defer_risk": true, "evaluated_at_ms": 1746768900000 } } }, "reason_codes": [ { "code": "GAS_ORACLE_OK", "severity": "INFO", "meaning": "Current gas price is below max_gas_percentile_for_ops; operation approved.", "action": "Emit GasDecision.PASS. Operation proceeds normally.", "user_message": "" }, { "code": "GAS_ORACLE_ELEVATED", "severity": "WARN", "meaning": "Gas price is in the warning band (within 10 percentile points above threshold). Operation approved with annotation.", "action": "Emit GasDecision.PASS with warn=true; monitor for further elevation.", "user_message": "Network fees are slightly elevated. Operations are continuing but costs may be higher than usual." }, { "code": "GAS_ORACLE_SPIKE_BLOCK", "severity": "RESHAPE", "meaning": "Gas price exceeds max_gas_percentile_for_ops; non-urgent operation deferred.", "action": "Emit GasDecision.DEFER with retry_after_s. Operation queued for next lower-gas window.", "user_message": "An on-chain operation was postponed temporarily because network fees are unusually high." }, { "code": "GAS_ORACLE_EV_BELOW_FLOOR", "severity": "RESHAPE", "meaning": "Neg-risk conversion net EV (after gas cost) is below conversion_min_ev_usd threshold.", "action": "Emit GasDecision.DEFER. Conversion not submitted.", "user_message": "" }, { "code": "GAS_ORACLE_RISK_BYPASS", "severity": "INFO", "meaning": "Risk-critical operation approved unconditionally despite elevated gas (never_defer_risk=true locked).", "action": "Emit GasDecision.PASS. Gas check bypassed. Log gas_gwei for audit.", "user_message": "" }, { "code": "GAS_ORACLE_RPC_FAILURE", "severity": "HARD_REJECT", "meaning": "Polygon RPC gas feed is unreachable; current gas price cannot be determined.", "action": "Defer all non-urgent ops. Emit GAS_ORACLE_RPC_FAILURE. Risk-critical ops still approved.", "user_message": "On-chain operations are paused briefly due to a network connectivity issue." }, { "code": "GAS_ORACLE_BASELINE_UNAVAILABLE", "severity": "WARN", "meaning": "Rolling 24h gas baseline store is unreachable or stale; falling back to hard static cap.", "action": "Use static 100 gwei cap. Emit WARN annotation on all GasDecision records this cycle.", "user_message": "" }, { "code": "KILL_SWITCH_ACTIVE", "severity": "HARD_REJECT", "meaning": "Global kill switch is active; all on-chain operations except emergency cancellations are halted.", "action": "Defer all non-risk-critical ops. No GasDecision.PASS emitted.", "user_message": "Trading is currently paused." } ], "metrics": { "emitted": [ { "name": "polytraders_exec_gasoracle_decisions_total", "type": "counter", "unit": "count", "labels": [ "verdict", "reason_code" ], "meaning": "Total GasDecision records emitted per verdict/reason_code." }, { "name": "polytraders_exec_gasoracle_gas_gwei", "type": "gauge", "unit": "gwei", "labels": [], "meaning": "Current Polygon gas price at the last evaluation cycle." }, { "name": "polytraders_exec_gasoracle_gas_percentile", "type": "gauge", "unit": "percentile", "labels": [], "meaning": "Percentile rank of current gas price against 24h baseline; >75 triggers deferral." }, { "name": "polytraders_exec_gasoracle_defer_queue_depth", "type": "gauge", "unit": "count", "labels": [ "op_kind" ], "meaning": "Number of non-urgent operations currently queued awaiting a lower-gas window." }, { "name": "polytraders_exec_gasoracle_rpc_errors_total", "type": "counter", "unit": "count", "labels": [], "meaning": "Consecutive RPC fetch failures; sustained > 3 triggers a page alert." }, { "name": "polytraders_exec_gasoracle_eval_latency_ms", "type": "histogram", "unit": "ms", "labels": [], "meaning": "Wall-clock time to complete one full evaluation cycle." } ], "alerts": [ { "name": "GasOracleSpikeBlock", "condition": "rate(polytraders_exec_gasoracle_decisions_total{verdict='DEFER',reason_code='GAS_ORACLE_SPIKE_BLOCK'}[10m]) > 0.5", "severity": "warn", "runbook": "#runbook-gasoracle-spike-block" }, { "name": "GasOracleRpcDown", "condition": "polytraders_exec_gasoracle_rpc_errors_total > 3", "severity": "page", "runbook": "#runbook-gasoracle-rpc-failure" }, { "name": "GasOracleDeferQueueDeep", "condition": "polytraders_exec_gasoracle_defer_queue_depth > 50", "severity": "warn", "runbook": "#runbook-gasoracle-defer-queue" }, { "name": "GasOracleBaselineStale", "condition": "time() - polytraders_exec_gasoracle_baseline_updated_at > 600", "severity": "warn", "runbook": "#runbook-gasoracle-baseline-stale" } ], "dashboards": [ "Grafana \u2014 Execution / GasOracle", "Grafana \u2014 Polygon Gas / 24h baseline and current percentile" ], "log_level": "info" }, "state": { "store": "redis", "shape": "Rolling 24h gas-price time-series (gwei samples with ms timestamps); deferred-operation queue keyed by op_id.", "ttl": "24h for gas baseline samples; deferred ops expire after 3600s if never re-evaluated", "recovery": "On restart, baseline is re-hydrated from Redis. First evaluation cycle uses stored baseline immediately. Deferred ops resume from queue.", "size_estimate": "~2 KB for 24h baseline at 1 sample/10s; <1 KB per deferred op entry" }, "concurrency": { "execution_model": "single-threaded event loop", "max_in_flight": 1, "idempotency_key": "op_id", "timeout_ms": 500, "backpressure": "Evaluation deferred until current cycle completes; ops queue in Redis", "locking": "none \u2014 single event loop; Redis SETNX for deferred-op deduplication" }, "dependencies": { "depends_on": [ { "bot_id": "risk.kill_switch", "why": "KillSwitch active flag overrides all GasOracle approvals for non-risk-critical ops.", "contract": "GasDecision.PASS not emitted for any non-risk-critical op when KillSwitch is active." } ], "emits_to": [ { "bot_id": "exec.smart_router", "what": "GasDecision records controlling whether on-chain submission proceeds.", "contract": "SmartRouter must receive GasDecision.PASS before submitting a signed order on-chain." }, { "bot_id": "exec.nonce_shepherd", "what": "Deferred-op signals so NonceShepherd can pause nonce increments for queued ops.", "contract": "NonceShepherd holds nonce reservation when GasOracle emits DEFER." } ], "sibling": [], "external": [ { "service": "Polygon RPC (gas feed)", "endpoint": "https://polygon-rpc.com (or internal RPC node)", "sla": "best-effort / internal node target 99.9%", "fallback": "Static 100 gwei hard cap; all non-urgent ops deferred." } ] }, "security_surfaces": { "signs_orders": false, "private_key_access": "none", "abuse_vectors": [ "Manipulating the rolling baseline store to artificially lower the perceived percentile, causing GasOracle to approve submissions during genuine gas spikes", "Injecting false risk_critical=true flags on non-risk ops to bypass the gas gate" ], "mitigations": [ "Baseline store (Redis) access restricted to GasOracle service account only", "risk_critical flag validated against the KillSwitch and Risk pipeline authority \u2014 cannot be set by external callers", "GasDecision records signed with internal HMAC; tampering detected by consumer bots" ], "contract_calls": [] }, "failure_injection": [ { "scenario": "RPC_DOWN", "how_to_inject": "Block outbound TCP to the Polygon RPC endpoint", "expected_behaviour": "GasOracle emits GAS_ORACLE_RPC_FAILURE; all non-urgent ops deferred; risk-critical ops still approved", "recovery": "Reconnects on next evaluation cycle when RPC is restored" }, { "scenario": "BASELINE_STALE", "how_to_inject": "Set Redis baseline last-updated timestamp to now()-600s without updating samples", "expected_behaviour": "GasOracle falls back to 100 gwei static cap; emits GAS_ORACLE_BASELINE_UNAVAILABLE WARN", "recovery": "Baseline self-heals as samples accumulate after Redis reconnect" }, { "scenario": "GAS_SPIKE_SUSTAINED", "how_to_inject": "Inject synthetic gas samples at p98 into the baseline for 30 minutes", "expected_behaviour": "All non-urgent ops accumulate in defer queue; GasOracleDeferQueueDeep alert fires at depth > 50", "recovery": "Ops re-evaluated and flushed once gas normalises below threshold" }, { "scenario": "NEVER_DEFER_RISK_TAMPER", "how_to_inject": "Attempt to set never_defer_risk=false via config API", "expected_behaviour": "Config change rejected with PARAMETER_CHANGE_REQUIRES_APPROVAL; locked value preserved", "recovery": "No action needed; lock enforced at config validation layer" }, { "scenario": "KILL_SWITCH_ON", "how_to_inject": "Activate global KillSwitch", "expected_behaviour": "All non-risk-critical GasDecision records emit DEFER with KILL_SWITCH_ACTIVE", "recovery": "Resumes on manual KillSwitch reset" } ], "runbook": { "summary": "GasOracle incidents are typically elevated gas causing large defer-queue buildup, or RPC connectivity failures. Neither condition directly causes trading losses \u2014 risk-critical ops are always approved \u2014 but sustained deferral may cause order management lag.", "oncall_actions": [ { "alert": "GasOracleRpcDown", "first_step": "Verify Polygon RPC endpoint is reachable from service host. Check internal RPC node health.", "diagnosis": "If RPC is unreachable, all non-urgent ops are deferred and static cap fallback is active.", "mitigation": "Switch to fallback RPC node if primary is down.", "escalation": "Infra on-call if RPC down > 5 minutes" }, { "alert": "GasOracleDeferQueueDeep", "first_step": "Check current gas percentile in Grafana. If gas has normalised but queue is not draining, check Redis connectivity.", "diagnosis": "Sustained high gas or Redis connectivity issue preventing queue drain.", "mitigation": "If Redis is down, restart Redis. If gas is genuinely high, notify strategy team.", "escalation": "Exec pod lead if queue depth > 200" }, { "alert": "GasOracleBaselineStale", "first_step": "Check Redis connectivity and GasOracle process health. Baseline should update every 10s.", "diagnosis": "GasOracle process may be down or Redis write is failing.", "mitigation": "Restart GasOracle process. Verify Redis write permissions.", "escalation": "Exec pod lead after 10 minutes of staleness" }, { "alert": "GasOracleSpikeBlock", "first_step": "Monitor gas in Grafana. If spike is genuine and prolonged, notify strategy team of order management latency.", "diagnosis": "Market gas spike causing all non-urgent ops to defer.", "mitigation": "No immediate action needed; ops auto-resume when gas normalises.", "escalation": "Strategy pod lead if non-urgent ops deferred > 30 minutes" } ], "manual_overrides": [ { "command": "polytraders bot config exec.gas_oracle defer_non_urgent=false --ttl 60", "effect": "Disables non-urgent op deferral for 60 seconds. Use only during pre-approved maintenance windows." }, { "command": "polytraders bot flush-queue exec.gas_oracle", "effect": "Force-drains the rate-deferred operation queue after a gas spike resolves." } ], "healthcheck": "GET /internal/health/gasoracle \u2192 200 if RPC reachable, baseline updated within 60s, no consecutive RPC errors. RED if RPC unreachable > 3 polls or baseline stale > 300s." }, "promotion_gates": { "to_shadow": [ { "gate": "Unit tests pass: all 5 acceptance_tests.unit cases", "how_measured": "CI test run", "threshold": "100% pass" }, { "gate": "never_defer_risk lock enforced by config validator", "how_measured": "Unit test: attempt to set never_defer_risk=false \u2192 ConfigError", "threshold": "Pass" } ], "to_limited_live": [ { "gate": "p99 eval latency < 500ms over 24h", "how_measured": "polytraders_exec_gasoracle_eval_latency_ms histogram", "threshold": "p99 < 500ms" }, { "gate": "Defer-queue drains within 5 minutes of gas normalising in integration test", "how_measured": "Integration test", "threshold": "Pass" } ], "to_general_live": [ { "gate": "Baseline store failover to static cap tested in staging", "how_measured": "Failure injection: BASELINE_STALE scenario", "threshold": "Pass \u2014 static cap applied correctly" }, { "gate": "7-day production shadow confirms no false deferral of risk-critical ops", "how_measured": "Audit log review", "threshold": "Zero risk-critical ops deferred" } ] }, "reporting": { "emits_kinds": [ "ExecutionReport" ], "topics": [ "polytraders.reports.exec" ], "cadence": "every-event", "retention_class": "7y", "sampling_rule": "emit-every", "bus_failure_action": "wal-then-retry", "user_visible": "summary-only", "consumes_kinds": [] }, "capital_impact": "Direct", "mode_support": [ "quarantine" ], "v3_status": { "phase": 5, "phase_name": "Execution rails", "docs": { "done": 27, "total": 27, "state": "done" }, "impl": { "done": 0, "total": 15, "state": "pending" }, "runtime": { "done": 0, "total": 8, "state": "pending" }, "overall": "pending" } }