Skip to main content

Try it Live

Run Denomination examples in the interactive playground

Denomination

Type-safe Ethereum value denominations with compile-time unit tracking.
Start with Fundamentals to learn about Wei, Gwei, Ether, and unit conversions.

Overview

Branded 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

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

Types

Each denomination uses branded types for compile-time safety:
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 for details.

Conversion Constants

// 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:
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`)

Denomination Table

UnitWeiGweiEtherCommon Use
Wei110^-910^-18Precise calculations, smallest unit
Gwei10^9110^-9Gas prices, transaction fees
Ether10^1810^91User-facing values, balances

API Variants

Two APIs for different use cases:

Branded API (Type-safe)

Requires branded types, compile-time safety:
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 →

Gwei

Gas price denomination, 1 billion Wei. View Gwei →

Ether

User-facing denomination, 1 quintillion Wei. View Ether →

BrandedWei

Type-safe Wei with BrandedUint data representation. View BrandedWei →

BrandedGwei

Type-safe Gwei with BrandedUint data representation. View BrandedGwei →

BrandedEther

Type-safe Ether with BrandedUint data representation. View BrandedEther →

Conversions

Converting between Wei, Gwei, and Ether with type safety. View Conversions →

WASM Implementation

WebAssembly-accelerated conversions compiled from Zig. View WASM →

Usage Patterns

Common patterns for gas calculations, transaction values, and conversions. View Usage Patterns →

Gas Calculator

Calculate transaction costs and convert between denominations and USD. View Gas Calculator →

Scale Visualization

Visual guides to understanding denomination relationships and magnitudes. View Scale Visualization →
Compile-time type safety prevents unit mixing bugs. Wei.Type and Gwei.Type are incompatible - explicit conversion required.

Type Safety

Each denomination prevents accidental mixing:
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:
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:
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

Uint256

Underlying 256-bit unsigned integer type for all denominations. View Uint256 →

Branded Types

Zero-overhead type branding pattern used throughout primitives. View Branded Types →

Chain

Network configuration with RPC endpoints and currency decimals. View Chain →

FeeMarket

EIP-1559 fee market dynamics and gas pricing. View FeeMarket →

GasConstants

Standard gas amounts for common operations. View GasConstants →