Skip to main content

Try it Live

Run Denomination examples in the interactive playground

Ether

Primary user-facing Ethereum denomination, equal to 1 quintillion (10^18) Wei.

Overview

Ether (ETH) is the native cryptocurrency of Ethereum. Ether.Type is a branded Uint256 preventing accidental unit mixing. Common usage: Account balances, transaction values, user-facing amounts.

Type Definition

import * as Uint from 'tevm/Uint'

const etherSymbol = Symbol("Ether")

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

Construction

Ether.from(value)

Create Ether from numeric value.
import * as Ether from 'tevm/Ether'

const ether1 = Ether(1n)       // 1 ETH
const ether2 = Ether(10n)      // 10 ETH
const ether3 = Ether(0n)       // 0 ETH
const ether4 = Ether("5")      // String input
const ether5 = Ether(2)        // Number input
Parameters:
  • value: bigint | number | string - Value to convert to Ether
Returns: Ether.Type Note: Uses Uint.from internally for conversion. Defined in: primitives/Denomination/Ether.ts:10

Conversions From Other Units

Ether.fromWei(wei)

Convert Wei to Ether (divide by 10^18).
import * as Wei from 'tevm/Wei'
import * as Ether from 'tevm/Ether'

const wei = Wei(1_000_000_000_000_000_000n)  // 1 quintillion Wei
const ether = Ether.fromWei(wei)  // 1n Ether

// Fractional values truncate
const wei2 = Wei(500_000_000_000_000_000n)  // 0.5 ETH in Wei
const ether2 = Ether.fromWei(wei2)  // 0n (truncates)
Parameters:
  • wei: Wei.Type - Wei value
Returns: Ether.Type Formula: ether = wei / 1_000_000_000_000_000_000 (integer division) Defined in: primitives/Denomination/Ether.ts:14

Ether.fromGwei(gwei)

Convert Gwei to Ether (divide by 10^9).
import * as Gwei from 'tevm/Gwei'
import * as Ether from 'tevm/Ether'

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

// Fractional values truncate
const gwei2 = Gwei(500_000_000n)  // 0.5 ETH in Gwei
const ether2 = Ether.fromGwei(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/Ether.ts:19

Conversions To Other Units

Ether.toWei(ether)

Convert Ether to Wei (multiply by 10^18).
import * as Ether from 'tevm/Ether'

const ether = Ether(1n)  // 1 ETH
const wei = Ether.toWei(ether)  // 1_000_000_000_000_000_000n Wei

const ether2 = Ether(5n)  // 5 ETH
const wei2 = Ether.toWei(ether2)  // 5_000_000_000_000_000_000n Wei
Parameters:
  • ether: Ether.Type - Ether value
Returns: Wei.Type Formula: wei = ether * 1_000_000_000_000_000_000 Defined in: primitives/Denomination/Ether.ts:24

Ether.toGwei(ether)

Convert Ether to Gwei (multiply by 10^9).
import * as Ether from 'tevm/Ether'

const ether = Ether(1n)  // 1 ETH
const gwei = Ether.toGwei(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/Ether.ts:29

Conversions To Base Type

Ether.toU256(ether)

Convert Ether to raw Uint256 (removes branding).
import * as Ether from 'tevm/Ether'
import * as Uint from 'tevm/Uint'

const ether = Ether(10n)
const u256 = Ether.toU256(ether)  // Uint.Type (unbranded)

// Can now use with Uint operations
const doubled = Uint.times(u256, Uint(2n))
Parameters:
  • ether: Ether.Type - Ether value
Returns: Uint.Type Note: Removes type safety. Use for arithmetic operations requiring Uint.Type. Defined in: primitives/Denomination/Ether.ts:34

Usage Examples

Account Balance

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

// Get balance from RPC (returns Wei)
const balanceWei = Wei(5_250_000_000_000_000_000n)

// Convert to Ether for display
const balanceEther = Wei.toEther(balanceWei)  // 5n Ether
console.log(`Balance: ${balanceEther} ETH`)

// Note: Fractional part truncated (should use Wei for display)

Transaction Value

import * as Ether from 'tevm/Ether'

// User wants to send 2 ETH
const valueEther = Ether(2n)

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

const tx = {
  to: "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e",
  value: valueWei,  // 2_000_000_000_000_000_000n Wei
}

Balance Comparison

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

const minimumEther = Ether(1n)  // Require at least 1 ETH
const balanceWei = Wei(2_500_000_000_000_000_000n)  // 2.5 ETH in Wei

// Convert to same unit for comparison
const minimumWei = Ether.toWei(minimumEther)
const minimumU256 = Wei.toU256(minimumWei)
const balanceU256 = Wei.toU256(balanceWei)

if (balanceU`256 >= minimumU256`) {
  console.log("Sufficient balance")
}

Total Value Calculation

import * as Ether from 'tevm/Ether'
import * as Uint from 'tevm/Uint'

// Multiple balances
const balances = [
  Ether(1n),
  Ether(5n),
  Ether(10n),
]

// Sum (convert to Uint for arithmetic)
const total = balances.reduce((sum, balance) => {
  const sumU256 = Ether.toU256(sum)
  const balanceU256 = Ether.toU256(balance)
  const newSum = Uint.plus(sumU256, balanceU256)
  return Ether(newSum)
}, Ether(0n))

console.log(`Total: ${total} ETH`)  // 16 ETH

Fractional Ether Display

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

// Balance has fractional Ether
const balanceWei = Wei(1_250_000_000_000_000_000n)  // 1.25 ETH

const weiPerEther = Uint(1_000_000_000_000_000_000n)
const balanceU256 = Wei.toU256(balanceWei)

const wholePart = Uint.dividedBy(balanceU256, weiPerEther)  // 1n
const fractionalPart = Uint.modulo(balanceU256, weiPerEther)  // 250000000000000000n

// Format for display
const etherStr = `${wholePart}.${fractionalPart.toString().padStart(18, '0')}`
console.log(`Balance: ${etherStr} ETH`)  // "1.250000000000000000 ETH"

Conversion Constants

// Wei per Ether
const WEI_PER_ETHER = 1_000_000_000_000_000_000n  // 10^18

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

Common Ether Values

import * as Ether from 'tevm/Ether'

// Standard amounts
const ZERO = Ether(0n)
const ONE = Ether(1n)
const TEN = Ether(10n)
const HUNDRED = Ether(100n)

// Minimum balances for contracts
const MIN_ACCOUNT_BALANCE = Ether(1n)
const MIN_STAKING = Ether(32n)  // Validator stake

Type Safety

Ether type prevents mixing with other denominations:
import * as Ether from 'tevm/Ether'
import * as Gwei from 'tevm/Gwei'

const balance = Ether(10n)
const gasPrice = Gwei(50n)

// ✗ Type error - cannot mix Ether and Gwei
const total = balance + gasPrice

// ✓ Correct - explicit conversion
const gasPriceEther = Gwei.toEther(gasPrice)
// (Though this makes little sense - Gwei should stay Gwei for gas)

Precision Considerations

Ether uses integer arithmetic. For fractional Ether:
import * as Ether from 'tevm/Ether'
import * as Wei from 'tevm/Wei'

// ✗ Fractional Ether lost
const ether = Ether(1n)  // Can only represent whole Ether
const halfEther = Ether(0.5)  // ✗ Not possible

// ✓ Use Wei for fractional values
const halfEtherWei = Wei(500_000_000_000_000_000n)  // 0.5 ETH

// Convert back to Ether when needed
const ether = Wei.toEther(halfEtherWei)  // 0n (truncates)
Recommendation: Store all values in Wei, display in Ether.

Display Best Practices

import * as Wei from 'tevm/Wei'

// Store in Wei
const balanceWei = Wei(1_234_567_890_123_456_789n)

// Display formatted Ether
function formatEther(wei: Wei.Type): string {
  const weiStr = wei.toString()
  const padded = weiStr.padStart(19, '0')  // Ensure 18 decimals + 1
  const wholePart = padded.slice(0, -18) || '0'
  const fractionalPart = padded.slice(-18)
  return `${wholePart}.${fractionalPart} ETH`
}

console.log(formatEther(balanceWei))  // "1.234567890123456789 ETH"

WASM Acceleration

Ether conversions available in WebAssembly for performance:
import * as EtherWasm from 'tevm/Ether.wasm'

const ether = EtherWasm(10n)
const wei = EtherWasm.toWei(ether)
See WASM for details.