Skip to main content

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

Calculation Formula

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