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

# Gas

> Gas limit and gas price types for transaction fees

## Overview

Gas provides branded types for gas limits and gas prices, preventing common bugs like mixing these values. Includes GasLimit for transaction gas limits and GasPrice for gas prices in wei.

```typescript theme={null}
import { GasLimit, GasPrice } from '@voltaire/primitives/Gas'

const limit = GasLimit.from(21000)
const price = GasPrice.fromGwei(20) // 20 gwei

const fee = GasLimit.toBigInt(21000) * GasPrice.toBigInt(price)
```

## Type Definitions

```typescript theme={null}
type GasLimitType = bigint & { readonly [brand]: "GasLimit" }
type GasPriceType = bigint & { readonly [brand]: "GasPrice" }
```

Both types wrap bigint with branding to prevent accidental mixing.

## GasLimit

### Creating GasLimit

#### from

Create from number, bigint, or hex string.

```typescript theme={null}
const limit1 = GasLimit.from(21000)
const limit2 = GasLimit.from(21000n)
const limit3 = GasLimit.from("0x5208") // 21000 in hex
```

### GasLimit Constants

Pre-defined gas limits for common operations:

```typescript theme={null}
import { SIMPLE_TRANSFER, ERC20_TRANSFER, DEFAULT_LIMIT } from '@voltaire/primitives/Gas'

SIMPLE_TRANSFER  // 21000 - ETH transfer
ERC20_TRANSFER   // 65000 - ERC-20 token transfer
DEFAULT_LIMIT    // 30000000 - Block gas limit
```

### GasLimit Methods

#### toBigInt

Convert to bigint.

```typescript theme={null}
const n = GasLimit.toBigInt(21000) // 21000n
```

#### toNumber

Convert to number.

```typescript theme={null}
const n = GasLimit.toNumber(21000) // 21000
```

## GasPrice

### Creating GasPrice

#### from

Create from wei value (number, bigint, or hex string).

```typescript theme={null}
const price1 = GasPrice.from(20_000_000_000)  // 20 gwei in wei
const price2 = GasPrice.from(20_000_000_000n)
const price3 = GasPrice.from("0x4a817c800")   // 20 gwei
```

#### fromGwei

Create from gwei (more convenient for typical gas prices).

```typescript theme={null}
const price = GasPrice.fromGwei(20)
// Equivalent to: GasPrice.from(20_000_000_000n)
```

### GasPrice Methods

#### toBigInt

Convert to bigint (wei).

```typescript theme={null}
const wei = GasPrice.toBigInt(price) // 20000000000n
```

#### toGwei

Convert to gwei.

```typescript theme={null}
const gwei = GasPrice.toGwei(price) // 20n
```

## Fee Calculation

Calculate transaction fees with type safety:

```typescript theme={null}
import { GasLimit, GasPrice } from '@voltaire/primitives/Gas'

// Simple transfer
const gasLimit = GasLimit.from(21000)
const gasPrice = GasPrice.fromGwei(30)

const fee = GasLimit.toBigInt(gasLimit) * GasPrice.toBigInt(gasPrice)
// fee = 21000n * 30_000_000_000n = 630_000_000_000_000n wei
// = 0.00063 ETH

// EIP-1559 transaction
const maxFeePerGas = GasPrice.fromGwei(50)
const maxPriorityFeePerGas = GasPrice.fromGwei(2)

const maxFee = GasLimit.toBigInt(gasLimit) * GasPrice.toBigInt(maxFeePerGas)
// maxFee = 21000n * 50_000_000_000n = 1_050_000_000_000_000n wei
```

## Common Gas Limits

| Operation       | Gas Limit |
| --------------- | --------- |
| ETH Transfer    | 21,000    |
| ERC-20 Transfer | \~65,000  |
| ERC-20 Approve  | \~45,000  |
| Uniswap Swap    | \~150,000 |
| NFT Mint        | \~100,000 |
| Contract Deploy | Variable  |

## EIP-1559 Gas Model

Post-London fork, gas pricing uses:

```typescript theme={null}
// Legacy (pre-EIP-1559)
const legacyTx = {
  gasLimit: GasLimit.from(21000),
  gasPrice: GasPrice.fromGwei(30),
}

// EIP-1559
const eip1559Tx = {
  gasLimit: GasLimit.from(21000),
  maxFeePerGas: GasPrice.fromGwei(50),
  maxPriorityFeePerGas: GasPrice.fromGwei(2),
}
```

<Note>
  Actual gas price in EIP-1559 is: `min(maxFeePerGas, baseFee + maxPriorityFeePerGas)`
</Note>

## Namespace Usage

```typescript theme={null}
import { GasLimit, GasPrice } from '@voltaire/primitives/Gas'

// Using namespace objects
const limit = GasLimit.from(21000)
const limitBigInt = GasLimit.toBigInt(21000)

const price = GasPrice.from(20_000_000_000n)
const priceGwei = GasPrice.fromGwei(20)
const priceBigInt = GasPrice.toBigInt(priceGwei)
```

## See Also

* [Gas (Effect)](https://voltaire-effect.tevm.sh/primitives/gas) - Effect.ts integration with Schema validation
* [Denomination](/primitives/denomination) - Wei/Gwei/Ether conversion
* [FeeMarket](/primitives/feemarket) - EIP-1559 fee calculation
* [GasConstants](/primitives/gasconstants) - Operation gas costs
* [Transaction](/primitives/transaction) - Transaction creation