PIP-0004: Bitcoin Core-Style Fee Estimation Oracle

[andrepatta]

PIP-0004: Bitcoin Core-Style Fee Estimation Oracle

Description: Replace the percentile-based gas price oracle with a confirmation-tracking fee estimator modeled after Bitcoin Core's estimatesmartfee algorithm.
Author: Parallax Protocol Team
Status: Scheduled for v1.1.2
Type: Standards Track
Category: Core
Created: 2026-04-01

Abstract

This PIP replaces the existing gas price oracle, which estimates fees by sampling a fixed number of transactions from recent blocks and returning a percentile of their gas prices, with a fee estimation algorithm modeled after Bitcoin Core's estimatesmartfee. The new oracle tracks how long transactions at various fee levels take to confirm, groups them into exponentially-spaced fee-rate buckets, and uses exponential decay across three time horizons to recommend the lowest fee rate that historically achieved a high confirmation success rate within a requested number of blocks.

Motivation

The existing gas price oracle samples 3 transactions from each of the last 20 blocks and returns the 60th percentile of their effective tips. This approach has a fundamental flaw: it does not account for block fullness. When blocks are far from full, there is little competition for block space, and even the minimum gas price should suffice for prompt confirmation. However, the percentile-based approach continues to report elevated fees as long as recent transactions happened to pay high prices, regardless of whether those high prices were necessary.

This leads to users overpaying for gas during periods of low network activity. Conversely, during sudden spikes in demand, the oracle's backward-looking percentile may underestimate the fee needed for timely confirmation.

Bitcoin Core's fee estimation algorithm solves these problems by directly measuring confirmation outcomes: it tracks what percentage of transactions at each fee level were confirmed within N blocks, and uses that empirical data to recommend fees. Since Parallax shares the same ~10-minute block target as Bitcoin, the algorithm's parameters and time horizons can be applied directly.

Specification

Fee-Rate Buckets

Transactions are grouped into N exponentially-spaced fee-rate buckets (default: 40 buckets with a 1.1x multiplier starting at 1 GWei). Bucket i covers gas prices in the range [MinBucketFee * BucketMultiplier^i, MinBucketFee * BucketMultiplier^(i+1)).

Three Time Horizons

The oracle maintains three independent sets of tracking data, each with its own exponential decay rate:

Horizon	Decay Factor	Half-Life	Confirmation Targets
Short	0.962	~18 blocks (~3h)	1 - 12 blocks
Medium	0.9952	~144 blocks (~1d)	1 - 48 blocks
Long	0.99931	~1008 blocks (~1w)	1 - 1008 blocks

Per-Bucket Tracking

For each fee-rate bucket and each time horizon, the oracle maintains:

• confirmed[t]: The decayed count of transactions at this fee rate that were confirmed within t blocks of entering the mempool.
• inMempool[t]: The decayed count of transactions at this fee rate that remained unconfirmed after t blocks.
• totalSeen: The decayed count of all transactions ever observed at this fee rate.

Block Processing

When a new block is received:

1. Decay: All counters in all buckets across all horizons are multiplied by their respective decay factors.
2. Confirmation Resolution: For each transaction in the block that was previously tracked in the mempool, compute blocksWaited = currentBlock - entryBlock + 1. For all confirmation targets t >= blocksWaited, increment confirmed[t] in the corresponding bucket across all horizons.
3. Failure Tracking: For each transaction still pending in the mempool beyond target t blocks, increment inMempool[t] in the corresponding bucket.
4. Cleanup: Remove mempool entries older than 2 * MaxConfTarget blocks.

Mempool Transaction Processing

When a new transaction enters the mempool:

1. Compute its fee-rate bucket from its gas price.
2. Record its entry block number and bucket index.
3. Increment totalSeen for the bucket across all horizons.

Fee Estimation (eth_estimateSmartFee)

Given a confirmation target confTarget:

1. Clamp confTarget to [1, MaxConfTarget].
2. For each applicable time horizon (based on confTarget range):
   a. Scan buckets from highest fee to lowest.
   b. For each bucket with sufficient data, compute successRate = confirmed[confTarget] / (confirmed[confTarget] + inMempool[confTarget]).
   c. Find the lowest bucket where successRate >= SuccessThreshold (default: 0.95).
3. Return the maximum (most conservative) estimate across all applicable horizons.
4. If no horizon has sufficient data, return the configured default gas price.
5. Clamp the result to [DefaultGasPrice, MaxPrice], where DefaultGasPrice is the miner's minimum gas price (default: 1 GWei, configurable via --miner.gasprice).

Backward-Compatible eth_gasPrice

The existing eth_gasPrice RPC method is implemented as EstimateSmartFee(confTarget=2), providing a "confirm in ~2 blocks" recommendation. This maintains full backward compatibility with MetaMask and other wallets that call eth_gasPrice.

New RPC Method

A new RPC method eth_estimateSmartFee is introduced:

Parameters:

• confTarget (integer): The desired number of blocks within which the transaction should confirm.

Returns:

{
  "gasPrice": "0x...",
  "confTarget": 2,
  "successRate": 0.97
}

Configuration Parameters

Parameter	Default	Description
NumBuckets	40	Number of fee-rate buckets
BucketMultiplier	1.1	Spacing between bucket boundaries
MinBucketFee	1 GWei	Lowest bucket boundary
MaxConfTarget	1008	Maximum supported confirmation target
SuccessThreshold	0.95	Required success rate to recommend a bucket
ShortDecay	0.962	Per-block decay for short horizon
MediumDecay	0.9952	Per-block decay for medium horizon
LongDecay	0.99931	Per-block decay for long horizon

Rationale

Why Bitcoin Core's Algorithm?

Bitcoin Core's fee estimation is battle-tested over a decade of production use on a network with the same ~10-minute block time as Parallax. Its key insight is that fee estimation should be based on empirical confirmation outcomes, not on sampling recent transaction prices. This naturally accounts for block fullness: when blocks are not full, even low-fee transactions confirm quickly, driving down the recommended fee. When blocks are congested, low-fee transactions fail to confirm, driving up the recommendation.

Why Three Time Horizons?

Different horizons serve different purposes:

• The short horizon (3-hour half-life) responds quickly to sudden changes in demand, suitable for urgent transactions targeting 1-12 block confirmation.
• The medium horizon (1-day half-life) smooths out short-term fluctuations, suitable for targets of 1-48 blocks.
• The long horizon (1-week half-life) provides stable estimates for patient transactions (up to 1008 blocks).

Taking the maximum across applicable horizons ensures conservative estimates that protect against sudden fee spikes.

Why Not Include Mempool State?

Bitcoin Core's algorithm intentionally does not incorporate current mempool state into its estimates. This is a deliberate design choice: mempool state is highly volatile, node-specific (different nodes see different mempools), and can be manipulated. The history-based approach provides more stable and reliable estimates.

Minimum Gas Price Floor

The estimate is never allowed to go below the miner's configured minimum gas price (default 1 GWei). Transactions below this floor will not be picked up by miners, so recommending them would be misleading.

Backwards Compatibility

• eth_gasPrice continues to work and returns the same type of response. Its implementation changes from percentile sampling to EstimateSmartFee(confTarget=2).
• eth_maxPriorityFeePerGas continues to work identically (delegates to the same path as eth_gasPrice).
• eth_feeHistory is unchanged and continues to return historical block data.
• eth_estimateGas (gas unit estimation, not price) is unchanged.
• MetaMask and other wallets that use eth_gasPrice will automatically benefit from the improved estimation without any client-side changes.

The new eth_estimateSmartFee method is purely additive and does not affect existing functionality.

Test Cases

1. Cold Start: With no historical data, all estimates return the configured default gas price.
2. Clamping: Estimates are always within [defaultGasPrice, maxPrice].
3. Bucket Assignment: Gas prices are correctly mapped to exponentially-spaced buckets.
4. Confirmation Tracking: After processing blocks with known transactions, the oracle produces estimates reflecting the observed confirmation patterns.
5. Target Clamping: Confirmation targets below 1 are clamped to 1; targets above MaxConfTarget are clamped to MaxConfTarget.

Reference Implementation

The reference implementation modifies the following files:

• prl/gasprice/gasprice.go — Core oracle rewrite with bucket tracking, decay, and estimation
• prl/prlconfig/config.go — Configuration defaults
• internal/prlapi/backend.go — Backend interface extension
• internal/prlapi/api.go — New RPC handler
• prl/api_backend.go — Backend implementation
• prl/backend.go — Oracle initialization wiring
• les/api_backend.go — Light client backend implementation
• les/client.go — Light client oracle initialization

Security Considerations

• Data Starvation: During periods of very low transaction volume, the oracle may lack sufficient data to make estimates. In this case, it falls back to the configured default gas price, which is a safe minimum.
• Manipulation Resistance: The exponential decay and multi-horizon design make it costly to manipulate estimates. An attacker would need to sustain artificial transaction patterns across multiple time horizons.
• Memory Usage: The oracle tracks pending mempool transactions in memory. Entries older than 2 * MaxConfTarget blocks are automatically cleaned up to prevent unbounded growth.
• Cold Start: After a node restart, all tracking state is lost and the oracle returns default prices until sufficient data accumulates (approximately 3 hours for the short horizon). This is consistent with Bitcoin Core's behavior.

Copyright

Copyright and related rights waived via CC0.