# 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

```mermaid
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

```json
{
  "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`