FeeMarket Types

Try it Live

Run FeeMarket examples in the interactive playground

FeeMarket Types

TypeScript types for fee market state and calculations.

State

type State = {
  gasUsed: bigint;
  gasLimit: bigint;
  baseFee: bigint;
  excessBlobGas: bigint;
  blobGasUsed: bigint;
}

Complete fee market state for a block. Combines EIP-1559 and EIP-4844 state.

Properties:

• gasUsed - Gas used in block (0 to gasLimit)
• gasLimit - Maximum gas per block
• baseFee - Base fee per gas (wei), minimum 7
• excessBlobGas - Accumulated excess blob gas
• blobGasUsed - Blob gas used in block (0 to 786432)

Example:

const state: FeeMarket.State = {
  gasUsed: 15_000_000n,
  gasLimit: 30_000_000n,
  baseFee: 1_000_000_000n, // 1 gwei
  excessBlobGas: 0n,
  blobGasUsed: 262144n // 2 blobs
};

Eip1559State

type Eip1559State = {
  gasUsed: bigint;
  gasLimit: bigint;
  baseFee: bigint;
}

EIP-1559 base fee state subset.

Example:

const eip1559: FeeMarket.Eip1559State = {
  gasUsed: 20_000_000n,
  gasLimit: 30_000_000n,
  baseFee: 1_000_000_000n
};

Eip4844State

type Eip4844State = {
  excessBlobGas: bigint;
  blobGasUsed: bigint;
}

EIP-4844 blob fee state subset.

Example:

const eip4844: FeeMarket.Eip4844State = {
  excessBlobGas: 393216n, // 3 blobs worth
  blobGasUsed: 524288n    // 4 blobs used
};

TxFeeParams

type TxFeeParams = {
  maxFeePerGas: bigint;
  maxPriorityFeePerGas: bigint;
  baseFee: bigint;
}

EIP-1559 transaction fee parameters.

Properties:

• maxFeePerGas - Maximum total fee per gas (wei)
• maxPriorityFeePerGas - Maximum priority fee/tip (wei)
• baseFee - Current block base fee (wei)

Constraints:

• maxFeePerGas >= baseFee (or tx cannot be included)
• maxPriorityFeePerGas <= maxFeePerGas

Example:

const params: FeeMarket.TxFeeParams = {
  maxFeePerGas: 2_000_000_000n,        // 2 gwei max
  maxPriorityFeePerGas: 1_000_000_000n, // 1 gwei tip
  baseFee: 800_000_000n                 // 0.8 gwei base
};

BlobTxFeeParams

type BlobTxFeeParams = TxFeeParams & {
  maxFeePerBlobGas: bigint;
  blobBaseFee: bigint;
  blobCount: bigint;
}

EIP-4844 blob transaction fee parameters. Extends TxFeeParams.

Additional Properties:

• maxFeePerBlobGas - Maximum fee per blob gas (wei)
• blobBaseFee - Current blob base fee (wei)
• blobCount - Number of blobs (1-6)

Constraints:

• maxFeePerBlobGas >= blobBaseFee (or tx cannot be included)
• 1 <= blobCount <= 6

Example:

const params: FeeMarket.BlobTxFeeParams = {
  maxFeePerGas: 2_000_000_000n,
  maxPriorityFeePerGas: 1_000_000_000n,
  baseFee: 1_000_000_000n,
  maxFeePerBlobGas: 10_000_000n, // 10 wei/gas
  blobBaseFee: 5_000_000n,       // 5 wei/gas
  blobCount: 3n
};

TxFee

type TxFee = {
  effectiveGasPrice: bigint;
  priorityFee: bigint;
  baseFee: bigint;
}

Calculated transaction fee breakdown.

Properties:

• effectiveGasPrice - Actual price per gas paid (wei)
• priorityFee - Priority fee per gas paid (wei)
• baseFee - Base fee per gas (wei)

Formula:

• effectiveGasPrice = min(maxFeePerGas, baseFee + maxPriorityFeePerGas)
• priorityFee = effectiveGasPrice - baseFee

Example:

const fee: FeeMarket.TxFee = {
  effectiveGasPrice: 1_800_000_000n, // 1.8 gwei
  priorityFee: 1_000_000_000n,       // 1 gwei tip
  baseFee: 800_000_000n              // 0.8 gwei base
};

// Total cost for 21000 gas transfer
const cost = fee.effectiveGasPrice * 21_000n; // 37,800,000,000,000 wei

BlobTxFee

type BlobTxFee = TxFee & {
  blobGasPrice: bigint;
  totalBlobFee: bigint;
}

Calculated blob transaction fee breakdown. Extends TxFee.

Additional Properties:

• blobGasPrice - Actual blob gas price paid (wei per blob gas)
• totalBlobFee - Total fee for all blobs (wei)

Formula:

• blobGasPrice = min(maxFeePerBlobGas, blobBaseFee)
• totalBlobFee = blobGasPrice * BLOB_GAS_PER_BLOB * blobCount

Example:

const fee: FeeMarket.BlobTxFee = {
  effectiveGasPrice: 1_800_000_000n,
  priorityFee: 1_000_000_000n,
  baseFee: 800_000_000n,
  blobGasPrice: 5_000_000n,          // 5 wei/gas
  totalBlobFee: 1_966_080_000_000n   // 3 blobs * 131072 * 5
};

// Total cost
const executionCost = fee.effectiveGasPrice * 100_000n; // execution gas
const totalCost = executionCost + fee.totalBlobFee;

Type Guards

All types are plain TypeScript interfaces. No runtime type guards provided.

Type Relationships

State
├── Eip1559State (subset)
└── Eip4844State (subset)

TxFeeParams
└── BlobTxFeeParams (extends)

TxFee
└── BlobTxFee (extends)

Branded Types

Types in BrandedState.ts are identical to main types. No phantom branding used.

// BrandedState === State (same structure)
import type { BrandedState } from './BrandedState.js';
import type { State } from './State.js';

Usage with Namespace Functions

All functions operate on these plain data types:

import * as FeeMarket from './FeeMarket.js';

// State operations
const state: FeeMarket.State = { /* ... */ };
const next = FeeMarket.nextState(state);

// Fee calculations
const params: FeeMarket.TxFeeParams = { /* ... */ };
const fee = FeeMarket.calculateTxFee(params);

// Blob fees
const blobParams: FeeMarket.BlobTxFeeParams = { /* ... */ };
const blobFee = FeeMarket.calculateBlobTxFee(blobParams);

Validation

Use validation functions for runtime checks:

// Validate state
const stateErrors = FeeMarket.validateState(state);
if (stateErrors.length > 0) {
  throw new Error(`Invalid state: ${stateErrors.join(', ')}`);
}

// Validate transaction parameters
const paramErrors = FeeMarket.validateTxFeeParams(params);
if (paramErrors.length > 0) {
  throw new Error(`Invalid params: ${paramErrors.join(', ')}`);
}

See utilities.mdx for validation functions.