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

# Denomination

> Ethereum value denominations - Wei, Gwei, and Ether

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

# Denomination

Type-safe Ethereum value denominations with compile-time unit tracking.

<Tip title="New to denominations?">
  Start with [Fundamentals](/primitives/denomination/fundamentals) to learn about Wei, Gwei, Ether, and unit conversions.
</Tip>

## Overview

[Branded](/getting-started/branded-types) types representing Ethereum denominations. Wei is a branded `bigint` (whole numbers only). Ether and Gwei are branded `string` types that support decimal values like `"1.5"`. Each denomination prevents accidental unit mixing at compile time while enabling seamless conversions.

## Quick Start

<Tabs>
  <Tab title="Direct Usage">
    ```typescript theme={null}
    import * as Wei from 'tevm/Wei'
    import * as Gwei from 'tevm/Gwei'
    import * as Ether from 'tevm/Ether'

    // Create values
    const wei = Wei(1_000_000_000n)      // 1 Gwei in Wei (bigint)
    const gwei = Gwei("21")               // 21 Gwei (string - supports decimals)
    const ether = Ether("1.5")            // 1.5 Ether (string - supports decimals)

    // Convert between units
    const weiFromGwei = Gwei.toWei(gwei)       // 21_000_000_000n Wei
    const gweiFromEther = Ether.toGwei(ether)  // "1500000000" Gwei
    const etherFromWei = Wei.toEther(wei)      // "0.000000001" Ether (preserves precision)

    // Type safety prevents mixing
    const total = wei + gwei  // ✗ Type error - cannot mix Wei and Gwei
    ```
  </Tab>

  <Tab title="Gas Price Calculation">
    ```typescript theme={null}
    import * as Wei from 'tevm/Wei'
    import * as Gwei from 'tevm/Gwei'
    import * as Uint from 'tevm/Uint'

    // Gas price in Gwei (common format)
    const gasPriceGwei = Gwei("50")  // 50 Gwei

    // Convert to Wei for calculation
    const gasPriceWei = Gwei.toWei(gasPriceGwei)

    // Calculate total cost: gasPrice * gasUsed
    const gasUsed = Uint(21_000n)
    const txCostWei = Uint.times(gasPriceWei, gasUsed)

    // Convert to Ether for display
    const txCostEther = Wei.toEther(Wei(txCostWei))
    console.log(`Cost: ${txCostEther} ETH`)  // "0.00105"
    ```
  </Tab>

  <Tab title="Transaction Values">
    ```typescript theme={null}
    import * as Ether from 'tevm/Ether'
    import * as Wei from 'tevm/Wei'

    // User inputs value in Ether with decimals
    const valueEther = Ether("0.5")  // 0.5 ETH

    // Transaction requires Wei
    const valueWei = Ether.toWei(valueEther)  // 500_000_000_000_000_000n Wei

    const tx = {
      to: "0x...",
      value: valueWei,  // Wei.Type ensures correct unit
      gasPrice: Gwei.toWei(Gwei("50"))
    }
    ```
  </Tab>
</Tabs>

## Types

Each denomination uses branded types for compile-time safety:

<Tabs>
  <Tab title="Wei">
    ```typescript theme={null}
    export type Wei = bigint & { __brand: typeof weiSymbol }

    // Smallest unit - 1 Wei = 10^-18 Ether
    // Wei is always a bigint (whole numbers only)
    const wei = Wei(1_000_000_000_000_000_000n)  // 1 Ether in Wei
    ```

    See [Wei](/primitives/denomination/wei) for details.
  </Tab>

  <Tab title="Gwei">
    ```typescript theme={null}
    export type Gwei = string & { __brand: typeof gweiSymbol }

    // 1 Gwei = 10^9 Wei = 10^-9 Ether
    // Gwei is a decimal string (supports fractional values)
    const gwei = Gwei("1.5")  // 1.5 Gwei = 1_500_000_000 Wei
    ```

    See [Gwei](/primitives/denomination/gwei) for details.
  </Tab>

  <Tab title="Ether">
    ```typescript theme={null}
    export type Ether = string & { __brand: typeof etherSymbol }

    // 1 Ether = 10^18 Wei = 10^9 Gwei
    // Ether is a decimal string (supports fractional values)
    const ether = Ether("1.5")  // 1.5 Ether
    ```

    See [Ether](/primitives/denomination/ether) for details.
  </Tab>
</Tabs>

## Conversion Constants

```typescript theme={null}
// Wei per Gwei
1 Gwei = 1_000_000_000 Wei  // 10^9

// Gwei per Ether
1 Ether = 1_000_000_000 Gwei  // 10^9

// Wei per Ether
1 Ether = 1_000_000_000_000_000_000 Wei  // 10^18
```

Wei uses integer arithmetic (bigint). Ether and Gwei use decimal strings to preserve fractional precision.

## Interactive Converter

Try converting between denominations:

<Tabs>
  <Tab title="Wei ↔ Gwei ↔ Ether">
    ```typescript theme={null}
    import * as Wei from 'tevm/Wei'
    import * as Gwei from 'tevm/Gwei'
    import * as Ether from 'tevm/Ether'

    // Example: Convert 1.5 ETH to all units
    const etherValue = Ether("1.5")  // 1.5 Ether

    // Forward conversions
    const gweiFromEther = Ether.toGwei(etherValue)      // "1500000000" Gwei
    const weiFromEther = Ether.toWei(etherValue)        // 1_500_000_000_000_000_000n Wei

    // Reverse conversions (precision preserved)
    const etherFromGwei = Gwei.toEther(gweiFromEther)   // "1.5" Ether ✓
    const etherFromWei = Wei.toEther(weiFromEther)      // "1.5" Ether ✓

    console.log(`${etherValue} ETH = ${gweiFromEther} Gwei = ${weiFromEther} Wei`)
    ```
  </Tab>

  <Tab title="Common Values">
    | Value    | Wei                        | Gwei           | Ether                |
    | -------- | -------------------------- | -------------- | -------------------- |
    | Dust     | 1                          | 0.000000001    | 0.000000000000000001 |
    | Small    | 1,000,000,000              | 1              | 0.000000001          |
    | Transfer | 21,000,000,000,000,000     | 21,000,000     | 0.021                |
    | Standard | 1,000,000,000,000,000,000  | 1,000,000,000  | 1                    |
    | Large    | 10,000,000,000,000,000,000 | 10,000,000,000 | 10                   |
  </Tab>

  <Tab title="Gas Price Reference">
    ```typescript theme={null}
    // Typical gas prices (varies by network conditions)
    const slow = Gwei("20")      // 20 Gwei
    const standard = Gwei("50")  // 50 Gwei
    const fast = Gwei("100")     // 100 Gwei
    const urgent = Gwei("200")   // 200 Gwei

    // Transfer cost (21,000 gas)
    const transferCostSlow = Uint.times(
      Gwei.toWei(slow),
      Uint(21_000n)
    )  // 420,000,000,000,000 Wei (0.00042 ETH)

    const transferCostUrgent = Uint.times(
      Gwei.toWei(urgent),
      Uint(21_000n)
    )  // 4,200,000,000,000,000 Wei (0.0042 ETH)
    ```
  </Tab>
</Tabs>

## Denomination Table

| Unit      | Wei   | Gwei  | Ether  | Common Use                          |
| --------- | ----- | ----- | ------ | ----------------------------------- |
| **Wei**   | 1     | 10^-9 | 10^-18 | Precise calculations, smallest unit |
| **Gwei**  | 10^9  | 1     | 10^-9  | Gas prices, transaction fees        |
| **Ether** | 10^18 | 10^9  | 1      | User-facing values, balances        |

## API Variants

Two APIs for different use cases:

#### Branded API (Type-safe)

Requires branded types, compile-time safety:

```typescript theme={null}
import * as BrandedWei from 'tevm/BrandedWei'
const wei = BrandedWei(1000000000n)
BrandedWei.toGwei(wei)  // Must pass BrandedWei
```

**Choose namespace for convenience, branded for type safety.**

## API Documentation

### Wei

Smallest denomination for precise calculations and internal representation.

[View Wei →](/primitives/denomination/wei)

### Gwei

Gas price denomination, 1 billion Wei.

[View Gwei →](/primitives/denomination/gwei)

### Ether

User-facing denomination, 1 quintillion Wei.

[View Ether →](/primitives/denomination/ether)

### BrandedWei

Type-safe Wei with BrandedUint data representation.

[View BrandedWei →](/primitives/denomination/branded-wei)

### BrandedGwei

Type-safe Gwei with BrandedUint data representation.

[View BrandedGwei →](/primitives/denomination/branded-gwei)

### BrandedEther

Type-safe Ether with BrandedUint data representation.

[View BrandedEther →](/primitives/denomination/branded-ether)

### Conversions

Converting between Wei, Gwei, and Ether with type safety.

[View Conversions →](/primitives/denomination/conversions)

### WASM Implementation

WebAssembly-accelerated conversions compiled from Zig.

[View WASM →](/primitives/denomination/wasm)

### Usage Patterns

Common patterns for gas calculations, transaction values, and conversions.

[View Usage Patterns →](/primitives/denomination/usage-patterns)

### Gas Calculator

Calculate transaction costs and convert between denominations and USD.

[View Gas Calculator →](/primitives/denomination/gas-calculator)

### Scale Visualization

Visual guides to understanding denomination relationships and magnitudes.

[View Scale Visualization →](/primitives/denomination/scale-visualization)

<Tip title="Why separate types?">
  Compile-time type safety prevents unit mixing bugs. `Wei.Type` and `Gwei.Type` are incompatible - explicit conversion required.
</Tip>

## Type Safety

Each denomination prevents accidental mixing:

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

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

// ✗ Type error - cannot pass Gwei where Wei expected
const cost = Uint.times(gasPrice, gasUsed)

// ✓ Correct - explicit conversion
const gasPriceWei = Gwei.toWei(gasPrice)
const cost = Uint.times(gasPriceWei, gasUsed)
```

## Decimal Precision

Ether and Gwei use decimal strings to preserve fractional values:

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

// 500 Wei = 0.0000000000000005 Ether
const wei = Wei(500n)
const ether = Wei.toEther(wei)  // "0.0000000000000005" (preserved)

// Fractional Ether supported natively
const fractional = Ether("1.5")
const weiValue = Ether.toWei(fractional)  // 1_500_000_000_000_000_000n
```

Round-trip conversions preserve full precision:

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

const originalWei = Wei(1_500_000_000_000_000_000n)  // 1.5 Ether in Wei

// Convert to Ether and back
const etherValue = Wei.toEther(originalWei)  // "1.5"
const backToWei = Ether.toWei(etherValue)    // 1_500_000_000_000_000_000n

console.log(originalWei === backToWei)  // true - no precision loss
```

## Related Types

* [Denomination (Effect)](https://voltaire-effect.tevm.sh/primitives/denomination) - Effect.ts integration with Schema validation

### Uint256

Underlying 256-bit unsigned integer type for all denominations.

[View Uint256 →](/primitives/uint)

### Branded Types

Zero-overhead type branding pattern used throughout primitives.

[View Branded Types →](/getting-started/branded-types)

### Chain

Network configuration with RPC endpoints and currency decimals.

[View Chain →](/primitives/chain)

### FeeMarket

EIP-1559 fee market dynamics and gas pricing.

[View FeeMarket →](/primitives/feemarket)

### GasConstants

Standard gas amounts for common operations.

[View GasConstants →](/primitives/gasconstants)