Denomination Fundamentals

Try it Live

Run Denomination examples in the interactive playground

Conceptual Guide - For API reference and method documentation, see Denomination API.

Ethereum uses multiple denominations to represent value at different scales. This guide teaches denomination fundamentals using Tevm.

What are Denominations?

Denominations are units of value in Ethereum. All values are internally stored as Wei (the smallest unit), but expressed in different units for readability:

Wei - Base unit for precise calculations (like cents)
Gwei - Gas price unit (like dollars)
Ether - User-facing unit (like thousands of dollars)

The Three Units

Wei
Gwei
Ether

import * as Wei from 'tevm/Wei';

// Wei is the smallest unit (1 Wei = 10^-18 Ether)
const oneWei = Wei(1n);
const oneEtherInWei = Wei(1_000_000_000_000_000_000n);

// Used for precise calculations
const gasPrice = Wei(50_000_000_000n);  // 50 Gwei in Wei

Use Wei for: Internal calculations, smart contract values, precision

import * as Gwei from 'tevm/Gwei';

// Gwei (gigawei) = 1 billion Wei (10^9)
const oneGwei = Gwei(1n);  // 1_000_000_000 Wei
const gasPrice = Gwei(50n);  // 50 Gwei

// Convert to Wei for calculations
const gasPriceWei = Gwei.toWei(gasPrice);  // 50_000_000_000n Wei

Use Gwei for: Gas prices, transaction fees, miner tips

import * as Ether from 'tevm/Ether';

// Ether = 1 quintillion Wei (10^18)
const oneEther = Ether(1n);  // 1_000_000_000_000_000_000 Wei
const balance = Ether(5n);    // 5 ETH

// Convert to Wei for transactions
const valueWei = Ether.toWei(balance);  // 5_000_000_000_000_000_000n Wei

Use Ether for: User displays, wallet balances, human-readable amounts

Conversion Scale

Understanding the relationships between units:

Ether = 1,000,000,000 Gwei = 1,000,000,000,000,000,000 Wei

Ether = 10^9 Gwei = 10^18 Wei
Gwei  = 10^9 Wei
Wei   = 10^-18 Ether

Visual Scale
Real-World Analogy

Wei:   1
       |
       × 10^9
       |
Gwei:  1,000,000,000
       |
       × 10^9
       |
Ether: 1,000,000,000,000,000,000

If 1 ETH = $2,000:

Wei   ≈ $0.000000000000002    (dust)
Gwei  ≈ $0.000002              (fraction of a cent)
Ether ≈ $2,000                 (full amount)

Converting Between Units

Ether → Gwei → Wei
Wei → Gwei → Ether
Gwei Conversions

import * as Ether from 'tevm/Ether';
import * as Gwei from 'tevm/Gwei';
import * as Wei from 'tevm/Wei';

const ethAmount = Ether(1n);  // 1 ETH

// Ether to Gwei
const gweiAmount = Ether.toGwei(ethAmount);  // 1_000_000_000n Gwei

// Ether to Wei
const weiAmount = Ether.toWei(ethAmount);    // 1_000_000_000_000_000_000n Wei

// Gwei to Wei
const weiFromGwei = Gwei.toWei(gweiAmount);  // 1_000_000_000_000_000_000n Wei

console.log(`1 ETH = ${gweiAmount} Gwei = ${weiAmount} Wei`);

import * as Wei from 'tevm/Wei';

const weiAmount = Wei(1_500_000_000_000_000_000n);  // 1.5 ETH in Wei

// Wei to Gwei
const gweiAmount = Wei.toGwei(weiAmount);   // 1_500_000_000n Gwei

// Wei to Ether (truncates decimals)
const ethAmount = Wei.toEther(weiAmount);   // 1n Ether (truncates 0.5)

console.log(`${weiAmount} Wei = ${gweiAmount} Gwei = ${ethAmount} ETH`);

Note: Integer division truncates fractional parts.

import * as Gwei from 'tevm/Gwei';

const gasPrice = Gwei(50n);  // 50 Gwei

// Gwei to Wei (multiply by 10^9)
const weiValue = Gwei.toWei(gasPrice);      // 50_000_000_000n Wei

// Gwei to Ether (divide by 10^9, truncates)
const ethValue = Gwei.toEther(gasPrice);    // 0n Ether (< 1 billion Gwei)

// Need at least 1 billion Gwei for 1 Ether
const oneEthInGwei = Gwei(1_000_000_000n);
const ethResult = Gwei.toEther(oneEthInGwei);  // 1n Ether

Complete Example: Gas Cost Calculation

Calculate total transaction cost from gas price and gas used:

import * as Gwei from 'tevm/Gwei';
import * as Wei from 'tevm/Wei';
import * as Ether from 'tevm/Ether';
import * as Uint from 'tevm/Uint';

// Gas price from network (commonly displayed in Gwei)
const gasPriceGwei = Gwei(50n);  // 50 Gwei

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

// Simple transfer uses 21,000 gas
const gasUsed = Uint(21_000n);

// Calculate total cost: gasPrice × gasUsed
const txCostWei = Uint.times(gasPriceWei, gasUsed);
// Result: 1_050_000_000_000_000n Wei (0.00105 ETH)

// Convert to Ether for display
const txCostEther = Wei.toEther(Wei(txCostWei));
console.log(`Transaction cost: ${txCostEther} ETH`);

Gas Price Examples

Different Gas Prices
Complex Transaction

import * as Gwei from 'tevm/Gwei';
import * as Uint from 'tevm/Uint';

const gasUsed = Uint(21_000n);

// Calculate costs at different gas prices
const prices = [20n, 50n, 100n, 200n];  // Gwei

prices.forEach(price => {
  const gasPriceGwei = Gwei(price);
  const gasPriceWei = Gwei.toWei(gasPriceGwei);
  const costWei = Uint.times(gasPriceWei, gasUsed);

  console.log(`${price} Gwei: ${costWei} Wei`);
});

// Output:
// 20 Gwei: 420_000_000_000_000 Wei (0.00042 ETH)
// 50 Gwei: 1_050_000_000_000_000 Wei (0.00105 ETH)
// 100 Gwei: 2_100_000_000_000_000 Wei (0.0021 ETH)
// 200 Gwei: 4_200_000_000_000_000 Wei (0.0042 ETH)

import * as Gwei from 'tevm/Gwei';
import * as Wei from 'tevm/Wei';
import * as Uint from 'tevm/Uint';

// EIP-1559 transaction with priority fee
const baseFee = Gwei(40n);      // 40 Gwei
const priorityFee = Gwei(2n);   // 2 Gwei tip

// Total gas price
const totalPriceGwei = Uint.plus(baseFee, priorityFee);  // 42 Gwei
const totalPriceWei = Gwei.toWei(Gwei(totalPriceGwei));

// Complex contract interaction
const gasUsed = Uint(150_000n);

// Total cost
const txCostWei = Uint.times(totalPriceWei, gasUsed);
// Result: 6_300_000_000_000_000n Wei (0.0063 ETH)

Formatting for Display

When displaying values to users, convert to appropriate units:

import * as Wei from 'tevm/Wei';
import * as Ether from 'tevm/Ether';

const balance = Wei(1_234_567_890_123_456_789n);

// Convert to Ether for user display
const ethBalance = Wei.toEther(balance);  // 1n Ether

// For fractional display, handle remainder separately
const weiPerEther = 1_000_000_000_000_000_000n;
const wholePart = balance / weiPerEther;      // 1n
const fractionalPart = balance % weiPerEther;  // 234_567_890_123_456_789n

console.log(`Balance: ${wholePart}.${fractionalPart} ETH`);
// "Balance: 1.234567890123456789 ETH"

Common Use Cases

Wallet Balance
Gas Price Display
Precise Calculations

import * as Ether from 'tevm/Ether';
import * as Wei from 'tevm/Wei';

// User sees balance in Ether
const userBalance = Ether(5n);  // 5 ETH

// Convert to Wei for transaction
const valueWei = Ether.toWei(userBalance);  // 5_000_000_000_000_000_000n

const tx = {
  to: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2",
  value: valueWei,  // Transaction uses Wei
};

import * as Wei from 'tevm/Wei';
import * as Gwei from 'tevm/Gwei';

// Gas price from RPC (in Wei)
const gasPriceWei = Wei(50_000_000_000n);

// Convert to Gwei for user display
const gasPriceGwei = Wei.toGwei(gasPriceWei);  // 50n Gwei

console.log(`Current gas price: ${gasPriceGwei} Gwei`);

import * as Wei from 'tevm/Wei';
import * as Uint from 'tevm/Uint';

// Always use Wei for precise calculations
const amount1 = Wei(1_000_000_000_000_000_000n);  // 1 ETH
const amount2 = Wei(500_000_000_000_000_000n);    // 0.5 ETH

// Add amounts (in Wei)
const total = Uint.plus(amount1, amount2);
// Result: 1_500_000_000_000_000_000n Wei (1.5 ETH)

// Avoid float arithmetic:
// ❌ const total = 1.0 + 0.5  // Floating point errors
// ✅ Use Wei with bigint        // Always precise

Precision Considerations

Always Use BigInt
Integer Division
Avoid Floating Point

import * as Wei from 'tevm/Wei';

// ✅ Correct: Use bigint for precise values
const correct = Wei(1_000_000_000_000_000_000n);

// ❌ Wrong: JavaScript numbers lose precision beyond 2^53
const wrong = Wei(1000000000000000000);  // Precision loss!

// ✅ Use bigint literals (n suffix)
const gasPrice = 50_000_000_000n;

// ✅ Convert from string if needed
const amount = Wei("1000000000000000000");

import * as Wei from 'tevm/Wei';
import * as Ether from 'tevm/Ether';

// Integer division truncates (rounds down)
const halfEther = Wei(500_000_000_000_000_000n);  // 0.5 ETH

const ethAmount = Wei.toEther(halfEther);  // 0n (truncated)

// To preserve fractions, stay in Wei
const doubleHalfEther = halfEther * 2n;  // 1_000_000_000_000_000_000n
const result = Wei.toEther(Wei(doubleHalfEther));  // 1n Ether ✓

import * as Uint from 'tevm/Uint';

// ❌ WRONG: Floating point arithmetic
const float1 = 0.1;
const float2 = 0.2;
const floatSum = float1 + float2;  // 0.30000000000000004 ❌

// ✅ CORRECT: Use Wei with bigint
const wei1 = 100_000_000_000_000_000n;  // 0.1 ETH in Wei
const wei2 = 200_000_000_000_000_000n;  // 0.2 ETH in Wei
const weiSum = Uint.plus(wei1, wei2);    // 300_000_000_000_000_000n ✓

Type Safety

Tevm prevents accidental unit mixing at compile time:

import * as Wei from 'tevm/Wei';
import * as Gwei from 'tevm/Gwei';
import * as Uint from 'tevm/Uint';

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

// ❌ Type error - cannot mix Gwei and Uint
const costWrong = Uint.times(gasPrice, gasUsed);

// ✅ Correct - explicit conversion to Wei
const gasPriceWei = Gwei.toWei(gasPrice);
const costCorrect = Uint.times(gasPriceWei, gasUsed);

Resources

Ethereum Units - Official Ethereum documentation
EIP-1559 - Fee market and gas pricing
Etherscan Gas Tracker - Real-time gas prices in Gwei
Uint Documentation - Underlying 256-bit integer type

Next Steps

Overview - Type definitions and API reference
Wei - Base unit operations
Gwei - Gas price unit
Ether - User-facing unit
Conversions - Converting between units

Documentation Index

Try it Live

​What are Denominations?

​The Three Units

​Conversion Scale

​Converting Between Units

​Complete Example: Gas Cost Calculation

​Gas Price Examples

​Formatting for Display

​Common Use Cases

​Precision Considerations

​Type Safety

​Resources

​Next Steps

What are Denominations?

The Three Units

Conversion Scale

Converting Between Units

Complete Example: Gas Cost Calculation

Gas Price Examples

Formatting for Display

Common Use Cases

Precision Considerations

Type Safety

Resources

Next Steps