2.5 GasOracle

1. Bot Identity

Operational profile

2. 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.

3. Why This Bot Matters

• Submitting during a gas spike

  Transaction costs erode trade profitability; maker rebates (paid in pUSD) can be wiped out by gas fees on low-edge positions.

• Deferring a risk-critical cancellation

  A resting order that should be pulled stays live during adverse market movement, accumulating unintended exposure.

• Using a stale 24h gas baseline

  The percentile thresholds are miscalibrated, causing GasOracle to defer operations during normal conditions or approve during actual spikes.

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

Legacy signals migrated from the v1 catalogue. Re-classify into the four-column form before this bot ships.

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "max_gas_percentile_for_ops": 75 }

if pct > params.hard and not op.never_defer: return defer('GAS_ORACLE_SPIKE_BLOCK')

{ "conversion_min_ev_usd": 0.1 }

ev_net = ev_gross - gas_cost_pusd; if ev_net < params.hard: return defer('GAS_ORACLE_EV_BELOW_FLOOR')

{ "defer_non_urgent": true }

if not params.defer_non_urgent: skip_gas_check()

{ "never_defer_risk": true }

assert params.never_defer_risk == True  # locked; config change requires approval

8. Default Configuration

{
  "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
    }
  }
}

9. Implementation Flow

1. Fetch current Polygon gas price (gwei) via onchain RPC (eth_feeHistory or eth_gasPrice).
2. Retrieve the rolling 24h gas-price baseline from the internal time-series store; compute percentile rank of current gas price.
3. For each pending on-chain operation in the execution scheduler queue, read its urgency flag (risk_critical vs. non_urgent).
4. If op.risk_critical=true (never_defer_risk=true locked): approve unconditionally — emit GasDecision.PASS.
5. If current gas percentile <= max_gas_percentile_for_ops: approve non-urgent op — emit GasDecision.PASS.
6. If percentile is in the WARN band (max_gas_percentile..+10): approve with a WARN annotation on the GasDecision.
7. 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).
8. 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.
9. Emit GasDecision record to internal execution scheduler with verdict, reason_code, gas_gwei_current, gas_percentile, and retry_after_s.
10. Append data point to rolling 24h baseline.

10. Reference Implementation

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.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

FUNCTION evaluateGas(pending_ops):
  // --- 1. Fetch current gas price ---
  gas_gwei = FETCH onchain_rpc.eth_gasPrice()  // gwei
  IF gas_gwei IS NULL:
    FOR op IN pending_ops:
      IF NOT op.risk_critical:
        EMIT GasDecision(op, DEFER, GAS_ORACLE_RPC_FAILURE)
    RETURN

  // --- 2. Compute percentile rank from 24h baseline ---
  baseline = FETCH internal.gas_baseline_24h()  // sorted list of gwei samples
  IF baseline IS NULL OR isStale(baseline, 300):
    cap_gwei = 100  // static fallback cap
    pct = 99 IF gas_gwei > cap_gwei ELSE 50
    EMIT WARN GAS_ORACLE_BASELINE_UNAVAILABLE
  ELSE:
    pct = percentile_rank(gas_gwei, baseline)  // 0..100

  // --- 3. For each pending operation ---
  FOR op IN pending_ops:
    // --- 3a. Risk-critical bypass ---
    IF op.risk_critical AND params.never_defer_risk:
      EMIT GasDecision(op, PASS, GAS_ORACLE_RISK_BYPASS,
                       gas_gwei=gas_gwei, pct=pct)
      CONTINUE

    // --- 3b. Neg-risk conversion EV check ---
    IF op.kind == 'negrisk_conversion':
      gas_cost_pusd = estimate_gas_cost_pusd(gas_gwei, op.gas_limit)
      ev_net = op.ev_gross_pusd - gas_cost_pusd
      IF ev_net < params.conversion_min_ev_usd:
        EMIT GasDecision(op, DEFER, GAS_ORACLE_EV_BELOW_FLOOR,
                         ev_net=ev_net, gas_cost_pusd=gas_cost_pusd)
        CONTINUE

    // --- 3c. Gas percentile gate ---
    IF pct > params.max_gas_percentile_for_ops:
      IF NOT params.defer_non_urgent:
        EMIT GasDecision(op, PASS, GAS_ORACLE_ELEVATED)
      ELSE:
        retry_after_s = estimate_gas_dip_s(baseline, params.max_gas_percentile_for_ops)
        EMIT GasDecision(op, DEFER, GAS_ORACLE_SPIKE_BLOCK,
                          retry_after_s=retry_after_s, gas_percentile=pct)
    ELSE IF pct > params.max_gas_percentile_for_ops - 10:
      EMIT GasDecision(op, PASS, GAS_ORACLE_ELEVATED, warn=true, gas_percentile=pct)
    ELSE:
      EMIT GasDecision(op, PASS, GAS_ORACLE_OK, gas_percentile=pct)

  // --- 4. Append current sample to baseline ---
  internal.gas_baseline_24h.append(gas_gwei, now_ms())

SDK calls used

• 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

11. Wire Examples

Input — what arrives on the wire

{
  "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 — what the bot emits

{
  "label": "GasDecision — 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
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a GasDecision object. See GasDecision schema.

{
  "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
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Execution / GasOracle
• Grafana — Polygon Gas / 24h baseline and current percentile

16. Developer Reporting

{
  "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
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, baseline is re-hydrated from Redis. First evaluation cycle uses stored baseline immediately. Deferred ops resume from queue.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

2.4

External services

23. Security Surfaces

Abuse vectors considered

• 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 — cannot be set by external callers
• GasDecision records signed with internal HMAC; tampering detected by consumer bots

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

GasOracle incidents are typically elevated gas causing large defer-queue buildup, or RPC connectivity failures. Neither condition directly causes trading losses — risk-critical ops are always approved — but sustained deferral may cause order management lag.

On-call actions

Manual overrides

• polytraders bot config exec.gas_oracle defer_non_urgent=false --ttl 60 — Disables non-urgent op deferral for 60 seconds. Use only during pre-approved maintenance windows.
• polytraders bot flush-queue exec.gas_oracle — Force-drains the rate-deferred operation queue after a gas spike resolves.

Healthcheck

GET /internal/health/gasoracle → 200 if RPC reachable, baseline updated within 60s, no consecutive RPC errors. RED if RPC unreachable > 3 polls or baseline stale > 300s.

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%