Documentation Index
Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
Use this file to discover all available pages before exploring further.
EffectiveGasPrice
EIP-1559 effective gas price representing the actual gas price paid for a transaction. Calculated from base fee and effective priority fee, capped by maxFeePerGas.
Overview
Branded bigint type representing effective price in Wei. Determines actual transaction cost: cost = effectiveGasPrice * gasUsed.
Quick Start
import * as EffectiveGasPrice from './primitives/EffectiveGasPrice/index.js';
import * as BaseFeePerGas from './primitives/BaseFeePerGas/index.js';
import * as MaxFeePerGas from './primitives/MaxFeePerGas/index.js';
import * as MaxPriorityFeePerGas from './primitives/MaxPriorityFeePerGas/index.js';
// Calculate effective price
const baseFee = BaseFeePerGas.fromGwei(25n);
const maxFee = MaxFeePerGas.fromGwei(100n);
const maxPriorityFee = MaxPriorityFeePerGas.fromGwei(2n);
const effective = EffectiveGasPrice.calculate(baseFee, maxFee, maxPriorityFee);
console.log(EffectiveGasPrice.toGwei(effective)); // 27n (25 + 2)
Type Definition
type EffectiveGasPriceType = bigint & { readonly [brand]: "EffectiveGasPrice" };
Branded bigint preventing confusion with other fee types. All values in Wei.
API
Construction
from(value)
Create from bigint, number, or hex string.
const price1 = EffectiveGasPrice.from(27000000000n);
const price2 = EffectiveGasPrice.from("0x64da46800");
const price3 = EffectiveGasPrice.from(27000000000);
calculate(baseFee, maxFee, maxPriorityFee)
Calculate from EIP-1559 fee parameters.
const baseFee = 25000000000n; // 25 Gwei
const maxFee = 100000000000n; // 100 Gwei
const maxPriorityFee = 2000000000n; // 2 Gwei
const effective = EffectiveGasPrice.calculate(baseFee, maxFee, maxPriorityFee);
// Returns 27000000000n (25 + 2 Gwei)
fromGwei(gwei)
Create from Gwei value.
const price = EffectiveGasPrice.fromGwei(27n); // 27000000000n Wei
fromWei(wei)
Create from Wei value (alias for from).
const price = EffectiveGasPrice.fromWei(27000000000n);
Conversion
toGwei(effectivePrice)
Convert to Gwei.
const price = EffectiveGasPrice.from(27000000000n);
EffectiveGasPrice.toGwei(price); // 27n
toWei(effectivePrice)
Convert to Wei (identity).
EffectiveGasPrice.toWei(price); // 27000000000n
toNumber(effectivePrice)
Convert to number. Warning: precision loss on large values.
EffectiveGasPrice.toNumber(price); // 27000000000
toBigInt(effectivePrice)
Convert to bigint (identity).
EffectiveGasPrice.toBigInt(price); // 27000000000n
Comparison
equals(price1, price2)
Check equality.
const price1 = EffectiveGasPrice.from(27000000000n);
const price2 = EffectiveGasPrice.from(27000000000n);
EffectiveGasPrice.equals(price1, price2); // true
compare(price1, price2)
Compare values. Returns -1, 0, or 1.
const price1 = EffectiveGasPrice.from(27000000000n);
const price2 = EffectiveGasPrice.from(30000000000n);
EffectiveGasPrice.compare(price1, price2); // -1
effectivePriorityFee = min(maxPriorityFeePerGas, maxFeePerGas - baseFeePerGas)
effectiveGasPrice = baseFeePerGas + effectivePriorityFee
Capped at maxFeePerGas for safety.
Calculation Examples
Within Budget
const baseFee = 25000000000n; // 25 Gwei
const maxFee = 100000000000n; // 100 Gwei
const maxPriorityFee = 2000000000n; // 2 Gwei
const effective = EffectiveGasPrice.calculate(baseFee, maxFee, maxPriorityFee);
// 25 + 2 = 27 Gwei
Priority Fee Capped
const baseFee = 25000000000n; // 25 Gwei
const maxFee = 26000000000n; // 26 Gwei (only 1 Gwei room)
const maxPriorityFee = 2000000000n; // 2 Gwei requested
const effective = EffectiveGasPrice.calculate(baseFee, maxFee, maxPriorityFee);
// 25 + 1 = 26 Gwei (priority capped at available budget)
Zero Priority Fee
const baseFee = 25000000000n; // 25 Gwei
const maxFee = 100000000000n; // 100 Gwei
const maxPriorityFee = 0n; // No tip
const effective = EffectiveGasPrice.calculate(baseFee, maxFee, maxPriorityFee);
// 25 + 0 = 25 Gwei
MaxFee Equal to BaseFee
const baseFee = 25000000000n; // 25 Gwei
const maxFee = 25000000000n; // 25 Gwei
const maxPriorityFee = 2000000000n; // 2 Gwei requested
const effective = EffectiveGasPrice.calculate(baseFee, maxFee, maxPriorityFee);
// 25 + 0 = 25 Gwei (no room for tip)
Real-world Examples
Transaction Cost
// Calculate actual transaction cost
const effective = EffectiveGasPrice.calculate(
25000000000n, // baseFee
100000000000n, // maxFee
2000000000n // maxPriorityFee
);
const gasUsed = 21000n; // Standard transfer
// Cost in Wei
const cost = effective * gasUsed; // 567000000000000n
// Cost in ETH
const ethCost = Number(cost) / 1e18; // 0.000567 ETH
Receipt Verification
// Verify transaction receipt
const receipt = await provider.getTransactionReceipt(txHash);
const effectivePrice = EffectiveGasPrice.from(receipt.effectiveGasPrice);
console.log(`Paid: ${EffectiveGasPrice.toGwei(effectivePrice)} Gwei`);
console.log(`Gas used: ${receipt.gasUsed}`);
console.log(`Total cost: ${effectivePrice * receipt.gasUsed} Wei`);
Refund Calculation
const maxFee = MaxFeePerGas.fromGwei(100n);
const effectivePrice = EffectiveGasPrice.fromGwei(27n);
const gasUsed = 21000n;
// What user authorized
const authorized = maxFee * gasUsed; // 2100000000000000n
// What user actually paid
const paid = effectivePrice * gasUsed; // 567000000000000n
// Refund
const refund = authorized - paid; // 1533000000000000n (0.001533 ETH)
Fee Breakdown
Miner vs Burned
const baseFee = BaseFeePerGas.fromGwei(25n);
const effectivePrice = EffectiveGasPrice.fromGwei(27n);
const gasUsed = 21000n;
// Total cost
const totalCost = effectivePrice * gasUsed; // 567000000000000n
// Burned (base fee)
const burned = baseFee * gasUsed; // 525000000000000n
// To miner (priority fee)
const toMiner = (effectivePrice - baseFee) * gasUsed; // 42000000000000n
Historical Analysis
Track Effective Prices
const history: bigint[] = [];
async function trackEffectivePrices() {
const block = await provider.getBlock('latest');
for (const txHash of block.transactions) {
const receipt = await provider.getTransactionReceipt(txHash);
const effective = EffectiveGasPrice.from(receipt.effectiveGasPrice);
history.push(effective);
}
// Calculate average
const sum = history.reduce((a, b) => a + b, 0n);
const avg = sum / BigInt(history.length);
console.log(`Average effective price: ${EffectiveGasPrice.toGwei(avg)} Gwei`);
}
Compare Networks
// Mainnet
const mainnetEffective = EffectiveGasPrice.fromGwei(27n);
const mainnetCost = mainnetEffective * 21000n; // 567000000000000n
// Polygon
const polygonEffective = EffectiveGasPrice.fromGwei(100n); // Higher Gwei, lower ETH value
const polygonCost = polygonEffective * 21000n; // Much cheaper in USD
// L2 (Arbitrum)
const arbitrumEffective = EffectiveGasPrice.fromGwei(1n);
const arbitrumCost = arbitrumEffective * 21000n; // 21000000000000n (very cheap)
Fee Estimation
Predict Effective Price
async function estimateEffectivePrice(
provider,
priorityLevel: 'low' | 'normal' | 'high'
): Promise<bigint> {
const block = await provider.getBlock('latest');
const baseFee = BaseFeePerGas.from(block.baseFeePerGas);
const priorityFees = {
low: MaxPriorityFeePerGas.fromGwei(1n),
normal: MaxPriorityFeePerGas.fromGwei(2n),
high: MaxPriorityFeePerGas.fromGwei(5n),
};
const priorityFee = priorityFees[priorityLevel];
const maxFee = MaxFeePerGas.fromGwei(
BaseFeePerGas.toGwei(baseFee) * 2n
);
return EffectiveGasPrice.calculate(baseFee, maxFee, priorityFee);
}
Common Patterns
Validate Transaction
// Before submission
function validateFees(baseFee: bigint, maxFee: bigint, priorityFee: bigint) {
const effective = EffectiveGasPrice.calculate(baseFee, maxFee, priorityFee);
// Check if effective price is reasonable
const maxExpected = baseFee * 2n;
if (effective > maxExpected) {
console.warn('Effective price higher than expected');
}
// Check if user gets full priority fee
const fullTip = baseFee + priorityFee;
if (effective < fullTip) {
console.warn('Priority fee capped by maxFee');
}
return effective;
}
Cost Comparison
// Compare scenarios
const scenarios = [
{ baseFee: 15n, priorityFee: 1n },
{ baseFee: 25n, priorityFee: 2n },
{ baseFee: 50n, priorityFee: 3n },
];
const maxFee = 100n;
for (const { baseFee, priorityFee } of scenarios) {
const effective = EffectiveGasPrice.calculate(
BaseFeePerGas.fromGwei(baseFee),
MaxFeePerGas.fromGwei(maxFee),
MaxPriorityFeePerGas.fromGwei(priorityFee)
);
const cost = effective * 21000n;
console.log(`Base ${baseFee} + Tip ${priorityFee} = ${EffectiveGasPrice.toGwei(effective)} Gwei (${cost} Wei)`);
}
Specification