explorer-monorepo/docs/specs/mempool/fee-oracle.md

Fee Oracle Specification

Overview

This document specifies the fee estimation service that calculates and predicts transaction fees based on historical data and current mempool conditions.

Architecture

flowchart TB
    subgraph Data[Data Sources]
        Blocks[Recent Blocks]
        Mempool[Current Mempool]
        History[Historical Data]
    end
    
    subgraph Analysis[Analysis]
        Percentile[Percentile Calculator]
        Prediction[Prediction Model]
        Adjust[Market Adjuster]
    end
    
    subgraph Output[Output]
        Estimates[Fee Estimates]
        API[API Endpoint]
        Cache[Cache]
    end
    
    Blocks --> Percentile
    Mempool --> Percentile
    History --> Prediction
    Percentile --> Adjust
    Prediction --> Adjust
    Adjust --> Estimates
    Estimates --> API
    Estimates --> Cache

Fee Calculation Methods

Method 1: Percentile-Based (Primary)

Algorithm:

1. Collect gas prices from recent N blocks (e.g., 100 blocks)
2. Calculate percentiles: 25th, 50th, 75th, 95th
3. Use percentiles as fee estimates

Percentile Mapping:

• Slow: 25th percentile
• Standard: 50th percentile (median)
• Fast: 75th percentile
• Urgent: 95th percentile

Update Frequency: Every new block

Method 2: Mempool-Based Adjustment

Algorithm:

1. Start with percentile-based estimates
2. Analyze current mempool:
   • Average gas price of pending transactions
   • Pending transaction count
   • Mempool pressure (pending / recent block capacity)
3. Adjust estimates based on mempool conditions

Adjustment Factors:

• High mempool pressure → Increase estimates
• Low mempool pressure → Decrease estimates
• Recent confirmed gas prices → Weight recent data more

Method 3: Time-Based Prediction

Algorithm:

• Predict fees for different confirmation times
• Example: "To be confirmed in 1 block, use X gas price"
• Use historical data to train model

Prediction Targets:

• 1 block (next block)
• 3 blocks (within 3 blocks)
• 10 blocks (within 10 blocks)

Fee Estimate Structure

Standard Estimates

{
  "chain_id": 138,
  "block_number": 12345,
  "estimates": {
    "slow": {
      "gas_price": "20000000000",
      "max_fee_per_gas": "20000000000",
      "max_priority_fee_per_gas": "1000000000",
      "confidence": 0.95,
      "estimated_confirmation_time": "5 minutes"
    },
    "standard": {
      "gas_price": "30000000000",
      "max_fee_per_gas": "30000000000",
      "max_priority_fee_per_gas": "2000000000",
      "confidence": 0.90,
      "estimated_confirmation_time": "2 minutes"
    },
    "fast": {
      "gas_price": "50000000000",
      "max_fee_per_gas": "50000000000",
      "max_priority_fee_per_gas": "3000000000",
      "confidence": 0.85,
      "estimated_confirmation_time": "30 seconds"
    },
    "urgent": {
      "gas_price": "100000000000",
      "max_fee_per_gas": "100000000000",
      "max_priority_fee_per_gas": "5000000000",
      "confidence": 0.80,
      "estimated_confirmation_time": "next block"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

EIP-1559 Support

For EIP-1559 Chains:

• Provide max_fee_per_gas and max_priority_fee_per_gas
• Calculate base fee prediction
• Estimate priority fee needed for desired speed

Historical Fee Analysis

Data Collection

Sources:

• Recent blocks (last 100-1000 blocks)
• Historical fee data (time-series database)

Metrics Tracked:

• Min, max, average gas price per block
• Percentiles (25th, 50th, 75th, 95th, 99th)
• Gas price distribution
• Confirmation time by gas price

Analysis Windows

Short-term (Last 10 blocks):

• Most recent trends
• Quick response to market changes

Medium-term (Last 100 blocks):

• Stable baseline
• Primary estimate source

Long-term (Last 1000 blocks):

• Historical patterns
• Anomaly detection

Prediction Models

Simple Moving Average

Algorithm: Average of recent N blocks

Pros: Simple, fast Cons: Slow to adapt to changes

Weighted Moving Average

Algorithm: Weight recent blocks more heavily

Pros: Faster adaptation Cons: More volatile

Machine Learning Models (Future)

Potential Models:

• Linear regression
• Time series forecasting (ARIMA, LSTM)
• Classification (predict confirmation time)

Features:

• Historical gas prices
• Mempool metrics
• Block time
• Network activity

API Endpoint

Get Fee Estimates

GET /api/v1/mempool/{chain_id}/fees

Query Parameters:

• block_target (integer): Target confirmation block (optional)

Response: Fee estimates object (see structure above)

Get Fee History

GET /api/v1/mempool/{chain_id}/fees/history

Query Parameters:

• period (string): Time period (1h, 24h, 7d, 30d)
• interval (string): Aggregation interval (1m, 5m, 1h)

Response: Historical fee data with timestamps

Caching Strategy

Cache Duration

• Fee Estimates: 10 seconds (update every block)
• Fee History: 5 minutes (less frequently updated)

Cache Invalidation

• Invalidate on new block
• Invalidate on significant mempool changes

Performance Considerations

Calculation Performance

Target: Calculate estimates in < 100ms

Optimization:

• Pre-calculate percentiles
• Cache historical data
• Use efficient algorithms

Update Frequency

Block-based: Update on every new block Time-based: Update every 10 seconds (fallback)

Accuracy Metrics

Tracking Accuracy

Metrics:

• Predicted vs actual confirmation time
• Predicted vs actual gas price used
• Estimate accuracy by tier (slow/standard/fast/urgent)

Confidence Scores

Calculation:

• Based on historical accuracy
• Variance in recent data
• Mempool stability

Display: Include confidence score in estimates

Monitoring

Metrics

• Fee estimate accuracy
• Update latency
• Calculation time
• Cache hit rate

Alerts

• High prediction error (> 50% off)
• Calculation timeout
• Cache miss rate spike

References

• Mempool Service: See mempool-service.md
• Time-Series Schema: See ../database/timeseries-schema.md