Skip to main content

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.

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.