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

# EffectiveGasPrice

> EIP-1559 effective gas price - actual gas price paid in transaction

# 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

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

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

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

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

```typescript theme={null}
const price = EffectiveGasPrice.fromGwei(27n); // 27000000000n Wei
```

#### `fromWei(wei)`

Create from Wei value (alias for `from`).

```typescript theme={null}
const price = EffectiveGasPrice.fromWei(27000000000n);
```

### Conversion

#### `toGwei(effectivePrice)`

Convert to Gwei.

```typescript theme={null}
const price = EffectiveGasPrice.from(27000000000n);
EffectiveGasPrice.toGwei(price); // 27n
```

#### `toWei(effectivePrice)`

Convert to Wei (identity).

```typescript theme={null}
EffectiveGasPrice.toWei(price); // 27000000000n
```

#### `toNumber(effectivePrice)`

Convert to number. Warning: precision loss on large values.

```typescript theme={null}
EffectiveGasPrice.toNumber(price); // 27000000000
```

#### `toBigInt(effectivePrice)`

Convert to bigint (identity).

```typescript theme={null}
EffectiveGasPrice.toBigInt(price); // 27000000000n
```

### Comparison

#### `equals(price1, price2)`

Check equality.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Related Types

* [BaseFeePerGas](/primitives/base-fee-per-gas) - Network base fee (burned)
* [MaxFeePerGas](/primitives/max-fee-per-gas) - Maximum total fee cap
* [MaxPriorityFeePerGas](/primitives/max-priority-fee-per-gas) - Maximum tip to miner

## Specification

* [EIP-1559: Fee market change for ETH 1.0 chain](https://eips.ethereum.org/EIPS/eip-1559)
* Formula: `effectiveGasPrice = baseFee + min(priorityFee, maxFee - baseFee)`
* Returned in transaction receipts as `effectiveGasPrice`
* Transaction cost: `effectiveGasPrice * gasUsed`