Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
275
docs/specs/mempool/fee-oracle.md
Normal file
275
docs/specs/mempool/fee-oracle.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# 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`
|
||||
|
||||
Reference in New Issue
Block a user