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

Direct Usage
Gas Price Calculation
Transaction Values

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

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"

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"))
}

Types

Each denomination uses branded types for compile-time safety:

Wei
Gwei
Ether

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.

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 for details.

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 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:

Wei ↔ Gwei ↔ Ether
Common Values
Gas Price Reference

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

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

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

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:

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

Denomination (Effect) - Effect.ts integration with Schema validation

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 →

Try it Live

​Denomination

​Overview

​Quick Start

​Types

​Conversion Constants

​Interactive Converter

​Denomination Table

​API Variants

​Branded API (Type-safe)

​API Documentation

​Wei

​Gwei

​Ether

​BrandedWei

​BrandedGwei

​BrandedEther

​Conversions

​WASM Implementation

​Usage Patterns

​Gas Calculator

​Scale Visualization

​Type Safety

​Decimal Precision

​Related Types

​Uint256

​Branded Types

​Chain

​FeeMarket

​GasConstants

Denomination

Overview

Quick Start

Types

Conversion Constants

Interactive Converter

Denomination Table

API Variants

Branded API (Type-safe)

API Documentation

Wei

Gwei

Ether

BrandedWei

BrandedGwei

BrandedEther

Conversions

WASM Implementation

Usage Patterns

Gas Calculator

Scale Visualization

Type Safety

Decimal Precision

Related Types

Uint256

Branded Types

Chain

FeeMarket

GasConstants