> ## 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.

# FeeMarket Types

<Card title="Try it Live" icon="play" href="https://playground.tevm.sh?example=primitives/fee-market.ts">
  Run FeeMarket examples in the interactive playground
</Card>

# FeeMarket Types

TypeScript types for fee market state and calculations.

## State

```typescript theme={null}
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:**

```typescript theme={null}
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

```typescript theme={null}
type Eip1559State = {
  gasUsed: bigint;
  gasLimit: bigint;
  baseFee: bigint;
}
```

EIP-1559 base fee state subset.

**Example:**

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

## Eip4844State

```typescript theme={null}
type Eip4844State = {
  excessBlobGas: bigint;
  blobGasUsed: bigint;
}
```

EIP-4844 blob fee state subset.

**Example:**

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

## TxFeeParams

```typescript theme={null}
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:**

```typescript theme={null}
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

```typescript theme={null}
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:**

```typescript theme={null}
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

```typescript theme={null}
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:**

```typescript theme={null}
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

```typescript theme={null}
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:**

```typescript theme={null}
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.

```typescript theme={null}
// 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:

```typescript theme={null}
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:

```typescript theme={null}
// 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](./utilities.mdx) for validation functions.