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

# Gwei

> Gas price denomination (1 billion Wei)

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

# Gwei

Ethereum gas price denomination, equal to 1 billion (10^9) Wei.

## Overview

Gwei (gigawei) is the standard unit for gas prices and transaction fees. `Gwei.Type` is a [branded](/getting-started/branded-types) `Uint256` preventing accidental unit mixing.

**Common usage:** Gas prices, transaction fees, network congestion pricing.

## Type Definition

```typescript theme={null}
import * as Uint from 'tevm/Uint'

const gweiSymbol = Symbol("Gwei")

export type Type = Uint.Type & { __brand: typeof gweiSymbol }
```

## Construction

### `Gwei.from(value)`

Create Gwei from numeric value.

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'

const gwei1 = Gwei(50n)    // 50 Gwei (typical gas price)
const gwei2 = Gwei(100n)   // 100 Gwei (high gas price)
const gwei3 = Gwei(1n)     // 1 Gwei (low gas price)
const gwei4 = Gwei("21")   // String input
const gwei5 = Gwei(42)     // Number input
```

**Parameters:**

* `value: bigint | number | string` - Value to convert to Gwei

**Returns:** `Gwei.Type`

**Note:** Uses `Uint.from` internally for conversion.

Defined in: [primitives/Denomination/Gwei.ts:10](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Gwei.ts)

## Conversions From Other Units

### `Gwei.fromWei(wei)`

Convert Wei to Gwei (divide by 10^9).

```typescript theme={null}
import * as Wei from 'tevm/Wei'
import * as Gwei from 'tevm/Gwei'

const wei = Wei(50_000_000_000n)  // 50 billion Wei
const gwei = Gwei.fromWei(wei)  // 50n Gwei

// Fractional values truncate
const wei2 = Wei(50_000_000_001n)
const gwei2 = Gwei.fromWei(wei2)  // 50n (truncates)
```

**Parameters:**

* `wei: Wei.Type` - Wei value

**Returns:** `Gwei.Type`

**Formula:** `gwei = wei / 1_000_000_000` (integer division)

Defined in: [primitives/Denomination/Gwei.ts:14](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Gwei.ts)

### `Gwei.fromEther(ether)`

Convert Ether to Gwei (multiply by 10^9).

```typescript theme={null}
import * as Ether from 'tevm/Ether'
import * as Gwei from 'tevm/Gwei'

const ether = Ether(1n)  // 1 Ether
const gwei = Gwei.fromEther(ether)  // 1_000_000_000n Gwei
```

**Parameters:**

* `ether: Ether.Type` - Ether value

**Returns:** `Gwei.Type`

**Formula:** `gwei = ether * 1_000_000_000`

Defined in: [primitives/Denomination/Gwei.ts:19](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Gwei.ts)

## Conversions To Other Units

### `Gwei.toWei(gwei)`

Convert Gwei to Wei (multiply by 10^9).

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'

const gwei = Gwei(50n)  // 50 Gwei gas price
const wei = Gwei.toWei(gwei)  // 50_000_000_000n Wei
```

**Parameters:**

* `gwei: Gwei.Type` - Gwei value

**Returns:** `Wei.Type`

**Formula:** `wei = gwei * 1_000_000_000`

Defined in: [primitives/Denomination/Gwei.ts:24](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Gwei.ts)

### `Gwei.toEther(gwei)`

Convert Gwei to Ether (divide by 10^9).

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'

const gwei = Gwei(1_000_000_000n)  // 1 billion Gwei
const ether = Gwei.toEther(gwei)  // 1n Ether

// Fractional values truncate
const gwei2 = Gwei(500_000_000n)  // 0.5 Ether in Gwei
const ether2 = Gwei.toEther(gwei2)  // 0n (truncates)
```

**Parameters:**

* `gwei: Gwei.Type` - Gwei value

**Returns:** `Ether.Type`

**Formula:** `ether = gwei / 1_000_000_000` (integer division)

Defined in: [primitives/Denomination/Gwei.ts:29](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Gwei.ts)

## Conversions To Base Type

### `Gwei.toU256(gwei)`

Convert Gwei to raw Uint256 (removes branding).

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'
import * as Uint from 'tevm/Uint'

const gwei = Gwei(50n)
const u256 = Gwei.toU256(gwei)  // Uint.Type (unbranded)

// Can now use with Uint operations
const doubled = Uint.times(u256, Uint(2n))
```

**Parameters:**

* `gwei: Gwei.Type` - Gwei value

**Returns:** `Uint.Type`

**Note:** Removes type safety. Use for arithmetic operations requiring `Uint.Type`.

Defined in: [primitives/Denomination/Gwei.ts:34](https://github.com/evmts/voltaire/blob/main/src/primitives/Denomination/Gwei.ts)

## Usage Examples

### Gas Price Calculations

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'
import * as Uint from 'tevm/Uint'

// Current gas prices (in Gwei)
const lowGasPrice = Gwei(10n)     // Low priority
const normalGasPrice = Gwei(30n)  // Normal priority
const highGasPrice = Gwei(50n)    // High priority

// Calculate transaction cost
const gasUsed = Uint(21_000n)
const gasPriceWei = Gwei.toWei(highGasPrice)
const txCost = Uint.times(gasPriceWei, gasUsed)

console.log(`Cost: ${txCost} Wei`)
```

### EIP-1559 Transaction

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'

// EIP-1559 parameters
const baseFee = Gwei(30n)          // Base fee per gas
const maxPriorityFee = Gwei(2n)    // Tip for miner
const maxFeePerGas = Gwei(50n)     // Max willing to pay

const tx = {
  type: 2,
  maxFeePerGas: Gwei.toWei(maxFeePerGas),
  maxPriorityFeePerGas: Gwei.toWei(maxPriorityFee),
  gasLimit: 21_000n
}

// Actual fee paid = min(maxFeePerGas, baseFee + maxPriorityFee)
const actualFee = Gwei(32n)  // 30 + 2
```

### Gas Price Comparison

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'

const prices = [
  Gwei(15n),
  Gwei(25n),
  Gwei(40n),
]

// Find minimum (convert to Uint for comparison)
const minPrice = prices.reduce((min, price) => {
  const minU256 = Gwei.toU256(min)
  const priceU256 = Gwei.toU256(price)
  return minU`256 <= priceU256` ? min : price
})

console.log(`Cheapest: ${minPrice} Gwei`)
```

### Gas Price Tracking

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'
import * as Uint from 'tevm/Uint'

interface GasPrices {
  fast: Gwei.Type
  standard: Gwei.Type
  slow: Gwei.Type
}

const current: GasPrices = {
  fast: Gwei(50n),
  standard: Gwei(30n),
  slow: Gwei(15n),
}

// Calculate cost difference
const gasUsed = Uint(21_000n)
const fastCost = Uint.times(Gwei.toWei(current.fast), gasUsed)
const slowCost = Uint.times(Gwei.toWei(current.slow), gasUsed)
const savings = Uint.minus(fastCost, slowCost)

console.log(`Save ${savings} Wei by waiting`)
```

## Conversion Constants

```typescript theme={null}
// Wei per Gwei
const WEI_PER_GWEI = 1_000_000_000n  // 10^9

// Gwei per Ether
const GWEI_PER_ETHER = 1_000_000_000n  // 10^9
```

## Common Gwei Values

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'

// Historical gas price ranges
const VERY_LOW = Gwei(1n)      // Network idle
const LOW = Gwei(10n)          // Low activity
const NORMAL = Gwei(30n)       // Normal activity
const HIGH = Gwei(50n)         // High activity
const EXTREME = Gwei(100n)     // Network congestion

// EIP-1559 parameters
const PRIORITY_FEE_LOW = Gwei(1n)
const PRIORITY_FEE_NORMAL = Gwei(2n)
const PRIORITY_FEE_HIGH = Gwei(3n)
```

## Type Safety

Gwei type prevents mixing with other denominations:

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'
import * as Wei from 'tevm/Wei'
import * as Uint from 'tevm/Uint'

const gasPrice = Gwei(50n)
const gasUsed = Uint(21_000n)

// ✗ Type error - cannot multiply Gwei directly
const cost = Uint.times(gasPrice, gasUsed)

// ✓ Correct - convert to Wei first
const gasPriceWei = Gwei.toWei(gasPrice)
const cost = Uint.times(gasPriceWei, gasUsed)
```

## Display Formatting

Gwei is human-readable for gas prices:

```typescript theme={null}
import * as Gwei from 'tevm/Gwei'

const gasPrice = Gwei(42n)
console.log(`Gas Price: ${gasPrice} Gwei`)  // "Gas Price: 42 Gwei"

// More readable than Wei
const gasPriceWei = Gwei.toWei(gasPrice)
console.log(`Gas Price: ${gasPriceWei} Wei`)  // "Gas Price: 42000000000 Wei"
```

## WASM Acceleration

Gwei conversions available in WebAssembly for performance:

```typescript theme={null}
import * as GweiWasm from 'tevm/Gwei.wasm'

const gwei = GweiWasm(50n)
const wei = GweiWasm.toWei(gwei)
```

See [WASM](/primitives/denomination/wasm) for details.

## Related

* [Wei](/primitives/denomination/wei) - Smallest denomination
* [Ether](/primitives/denomination/ether) - User-facing denomination
* [Conversions](/primitives/denomination/conversions) - Converting between units
* [Usage Patterns](/primitives/denomination/usage-patterns) - Common patterns
* [Uint256](/primitives/uint) - Underlying numeric type