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

> EIP-1559 and EIP-4844 fee market calculations for Ethereum transactions

## Overview

FeeMarket implements Ethereum's dynamic fee mechanisms: EIP-1559 for base fees and EIP-4844 for blob fees. Use it to calculate next block fees, validate transactions, project fee trends, and estimate costs.

```typescript theme={null}
import * as FeeMarket from '@voltaire/FeeMarket';

// Calculate next base fee
const nextBaseFee = FeeMarket.BaseFee(
  15_000_000n,    // parent gas used
  30_000_000n,    // parent gas limit
  1_000_000_000n  // parent base fee (1 gwei)
);

// Calculate blob base fee
const blobFee = FeeMarket.BlobBaseFee(393216n); // excess blob gas
```

## Types

### State

Complete fee market state for a block:

```typescript theme={null}
type FeeMarketType = {
  gasUsed: bigint;        // Gas used in block
  gasLimit: bigint;       // Gas limit of block
  baseFee: bigint;        // Base fee per gas (wei)
  excessBlobGas: bigint;  // Excess blob gas accumulated
  blobGasUsed: bigint;    // Blob gas used in block
};
```

### TxFeeParams

Transaction fee parameters for EIP-1559:

```typescript theme={null}
type TxFeeParams = {
  maxFeePerGas: bigint;         // Maximum fee per gas (wei)
  maxPriorityFeePerGas: bigint; // Priority fee tip (wei)
  baseFee: bigint;              // Current block base fee (wei)
};
```

### BlobTxFeeParams

Extended parameters for blob transactions (EIP-4844):

```typescript theme={null}
type BlobTxFeeParams = TxFeeParams & {
  maxFeePerBlobGas: bigint; // Maximum fee per blob gas (wei)
  blobBaseFee: bigint;      // Current blob base fee (wei)
  blobCount: bigint;        // Number of blobs in transaction
};
```

### TxFee

Calculated transaction fee breakdown:

```typescript theme={null}
type TxFee = {
  effectiveGasPrice: bigint; // Effective gas price paid (wei/gas)
  priorityFee: bigint;       // Priority fee paid (wei/gas)
  baseFee: bigint;           // Base fee paid (wei/gas)
};
```

### BlobTxFee

Extended fee breakdown for blob transactions:

```typescript theme={null}
type BlobTxFee = TxFee & {
  blobGasPrice: bigint;  // Blob gas price paid (wei/blob gas)
  totalBlobFee: bigint;  // Total blob fee (wei)
};
```

## EIP-1559 Methods

### BaseFee

Calculate next block's base fee using the EIP-1559 formula.

```typescript theme={null}
const nextBaseFee = FeeMarket.BaseFee(
  parentGasUsed,   // bigint
  parentGasLimit,  // bigint
  parentBaseFee    // bigint
);
```

**Formula:**

* `gasTarget = gasLimit / 2`
* If `gasUsed > gasTarget`: base fee increases (up to 12.5%)
* If `gasUsed < gasTarget`: base fee decreases (up to 12.5%)
* If `gasUsed == gasTarget`: base fee unchanged
* Minimum base fee: 7 wei

```typescript theme={null}
// Block at target (50% full): unchanged
const fee1 = FeeMarket.BaseFee(15_000_000n, 30_000_000n, 1_000_000_000n);
// fee1 === 1_000_000_000n

// Block full: increases ~12.5%
const fee2 = FeeMarket.BaseFee(30_000_000n, 30_000_000n, 1_000_000_000n);
// fee2 === 1_125_000_000n

// Empty block: decreases ~12.5%
const fee3 = FeeMarket.BaseFee(0n, 30_000_000n, 1_000_000_000n);
// fee3 === 1_000_000_000n (empty blocks maintain fee)
```

### calculateTxFee

Calculate effective transaction fee breakdown.

```typescript theme={null}
const fee = FeeMarket.calculateTxFee({
  maxFeePerGas: 2_000_000_000n,
  maxPriorityFeePerGas: 1_000_000_000n,
  baseFee: 800_000_000n
});

// fee.effectiveGasPrice === 1_800_000_000n (baseFee + priority)
// fee.priorityFee === 1_000_000_000n
// fee.baseFee === 800_000_000n
```

**Formula:**

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

### canIncludeTx

Check if transaction meets minimum fee requirements.

```typescript theme={null}
const canInclude = FeeMarket.canIncludeTx({
  maxFeePerGas: 1_000_000_000n,
  maxPriorityFeePerGas: 100_000_000n,
  baseFee: 900_000_000n
});
// canInclude === true (maxFeePerGas >= baseFee)
```

For blob transactions, also checks `maxFeePerBlobGas >= blobBaseFee`.

### validateTxFeeParams

Validate transaction fee parameters.

```typescript theme={null}
const errors = FeeMarket.validateTxFeeParams({
  maxFeePerGas: 2_000_000_000n,
  maxPriorityFeePerGas: 1_000_000_000n,
  baseFee: 800_000_000n
});
// errors === [] (empty array = valid)
```

**Validates:**

* `maxFeePerGas >= 0`
* `maxPriorityFeePerGas >= 0`
* `maxPriorityFeePerGas <= maxFeePerGas`
* `baseFee >= 0`
* For blob txs: `blobCount` between 1 and 6

## EIP-4844 Methods

### BlobBaseFee

Calculate blob base fee using EIP-4844 exponential formula.

```typescript theme={null}
const blobFee = FeeMarket.BlobBaseFee(excessBlobGas);
```

**Formula:** Uses Taylor series approximation of `MIN_BLOB_BASE_FEE * e^(excessBlobGas / UPDATE_FRACTION)`

```typescript theme={null}
// No excess: minimum fee (1 wei)
const fee1 = FeeMarket.BlobBaseFee(0n);
// fee1 === 1n

// With excess: exponentially increasing
const fee2 = FeeMarket.BlobBaseFee(393216n);
// fee2 > 1n (increases with excess)
```

### calculateExcessBlobGas

Calculate excess blob gas for next block.

```typescript theme={null}
const excess = FeeMarket.calculateExcessBlobGas(
  parentExcessBlobGas,  // bigint
  parentBlobGasUsed     // bigint
);
```

**Formula:** `max(0, parentExcess + parentBlobGasUsed - TARGET_BLOB_GAS_PER_BLOCK)`

```typescript theme={null}
// Below target: no excess
const excess1 = FeeMarket.calculateExcessBlobGas(0n, 131072n);
// excess1 === 0n (1 blob < 3 blob target)

// Above target: accumulates
const excess2 = FeeMarket.calculateExcessBlobGas(0n, 524288n);
// excess2 === 131072n (4 blobs - 3 blob target = 1 blob excess)
```

### calculateBlobTxFee

Calculate complete blob transaction fee breakdown.

```typescript theme={null}
const fee = FeeMarket.calculateBlobTxFee({
  maxFeePerGas: 2_000_000_000n,
  maxPriorityFeePerGas: 1_000_000_000n,
  baseFee: 800_000_000n,
  maxFeePerBlobGas: 10_000_000n,
  blobBaseFee: 5_000_000n,
  blobCount: 3n
});

// Includes all TxFee fields plus:
// fee.blobGasPrice === 5_000_000n
// fee.totalBlobFee === 5_000_000n * 131072n * 3n
```

## State Methods

### nextState

Calculate next block's complete fee market state.

```typescript theme={null}
const currentState = {
  gasUsed: 20_000_000n,
  gasLimit: 30_000_000n,
  baseFee: 1_000_000_000n,
  excessBlobGas: 0n,
  blobGasUsed: 262144n  // 2 blobs
};

const next = FeeMarket.nextState(currentState);
// next.gasUsed === 0n (reset)
// next.baseFee === calculated new base fee
// next.excessBlobGas === calculated new excess
// next.blobGasUsed === 0n (reset)
```

### validateState

Validate block state parameters.

```typescript theme={null}
const errors = FeeMarket.validateState({
  gasUsed: 0n,
  gasLimit: 30_000_000n,
  baseFee: 1_000_000_000n,
  excessBlobGas: 0n,
  blobGasUsed: 0n
});
// errors === []
```

**Validates:**

* `gasUsed >= 0` and `<= gasLimit`
* `gasLimit > 0`
* `baseFee >= MIN_BASE_FEE` (7 wei)
* `excessBlobGas >= 0`
* `blobGasUsed >= 0` and `<= MAX_BLOB_GAS_PER_BLOCK`

### projectBaseFees

Project base fees over multiple blocks.

```typescript theme={null}
const fees = FeeMarket.projectBaseFees(
  initialState,     // FeeMarketType
  10,               // number of blocks
  25_000_000n,      // average gas used per block
  262144n           // average blob gas used (optional)
);
// fees === [baseFee1, baseFee2, ..., baseFee10]
```

Useful for fee trend analysis and gas price estimation.

## Utility Functions

### gweiToWei

Convert gwei to wei.

```typescript theme={null}
const wei = FeeMarket.gweiToWei(1.5);
// wei === 1_500_000_000n
```

### weiToGwei

Convert wei to gwei for display.

```typescript theme={null}
const gwei = FeeMarket.weiToGwei(1_500_000_000n);
// gwei === "1.500000000"
```

## Constants

### EIP-1559 Constants

```typescript theme={null}
FeeMarket.Eip1559.MIN_BASE_FEE              // 7n (wei)
FeeMarket.Eip1559.BASE_FEE_CHANGE_DENOMINATOR // 8n (12.5% = 1/8)
FeeMarket.Eip1559.ELASTICITY_MULTIPLIER     // 2n (limit = target * 2)
```

### EIP-4844 Constants

```typescript theme={null}
FeeMarket.Eip4844.MIN_BLOB_BASE_FEE          // 1n (wei)
FeeMarket.Eip4844.BLOB_BASE_FEE_UPDATE_FRACTION // 3338477n
FeeMarket.Eip4844.TARGET_BLOB_GAS_PER_BLOCK  // 393216n (3 blobs)
FeeMarket.Eip4844.BLOB_GAS_PER_BLOB          // 131072n (128 KiB)
FeeMarket.Eip4844.MAX_BLOBS_PER_BLOCK        // 6n
FeeMarket.Eip4844.MAX_BLOB_GAS_PER_BLOCK     // 786432n (6 * 131072)
```

## Usage Examples

### Estimate Transaction Cost

```typescript theme={null}
import * as FeeMarket from '@voltaire/FeeMarket';

async function estimateTransactionCost(
  gasEstimate: bigint,
  currentBaseFee: bigint,
  priorityFee: bigint = 1_000_000_000n
): { maxFee: bigint; estimatedCost: bigint } {
  // Add 20% buffer for base fee volatility
  const maxFeePerGas = currentBaseFee * 120n / 100n + priorityFee;

  const fee = FeeMarket.calculateTxFee({
    maxFeePerGas,
    maxPriorityFeePerGas: priorityFee,
    baseFee: currentBaseFee
  });

  return {
    maxFee: maxFeePerGas,
    estimatedCost: fee.effectiveGasPrice * gasEstimate
  };
}
```

### Monitor Fee Trends

```typescript theme={null}
import * as FeeMarket from '@voltaire/FeeMarket';

function analyzeFeeTrends(state: FeeMarket.FeeMarketType) {
  // Project fees for next 10 blocks at current usage
  const optimistic = FeeMarket.projectBaseFees(state, 10, state.gasLimit / 4n);
  const average = FeeMarket.projectBaseFees(state, 10, state.gasLimit / 2n);
  const congested = FeeMarket.projectBaseFees(state, 10, state.gasLimit * 3n / 4n);

  return {
    low: optimistic[9],
    medium: average[9],
    high: congested[9]
  };
}
```

### Validate Before Submission

```typescript theme={null}
import * as FeeMarket from '@voltaire/FeeMarket';

function validateTransaction(
  params: FeeMarket.TxFeeParams | FeeMarket.BlobTxFeeParams
): { valid: boolean; errors: string[] } {
  const errors = FeeMarket.validateTxFeeParams(params);

  if (errors.length === 0 && !FeeMarket.canIncludeTx(params)) {
    errors.push('Transaction fee too low for current base fee');
  }

  return { valid: errors.length === 0, errors };
}
```

## Related

* [Gas](/primitives/gas/index) - Gas limits and usage
* [Transaction](/primitives/transaction) - Transaction types
* [KZG](/crypto/kzg) - Blob commitment cryptography
* [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) - Fee market specification
* [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) - Blob transaction specification