Skip to main content

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.

Try it Live

Run Denomination examples in the interactive playground

​
BrandedEther

Data-first branded Ether type - BrandedUint representing Ether denomination with zero-overhead runtime.

​
Overview

BrandedEther is a branded BrandedUint (Uint8Array-based) providing compile-time type safety for Ether values with zero-overhead direct data representation.

​
Type Definition

import type { BrandedUint } from 'tevm/BrandedUint'

export type BrandedEther = BrandedUint & { readonly __brand: unique symbol }
Inherits all BrandedUint properties - 32-byte Uint8Array with bigint arithmetic.

​
Construction

​
BrandedEther.from(value)

Create BrandedEther from numeric input. 
import * as BrandedEther from 'tevm/BrandedEther'

const ether1 = BrandedEther(1n)         // 1 Ether
const ether2 = BrandedEther(5n)         // 5 Ether
const ether3 = BrandedEther("10")       // String input
const ether4 = BrandedEther(0.5)        // Number (truncates to 0n)
Parameters:
  • value: bigint | number | string - Value to convert
Returns: BrandedEther Note: Fractional numbers truncate to integer Ether.

​
BrandedEther.fromWei(wei)

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

const wei = BrandedWei(1_000_000_000_000_000_000n)
const ether = BrandedEther.fromWei(wei)  // 1n Ether

// Fractional values truncate
const wei2 = BrandedWei(500_000_000_000_000_000n)  // 0.5 ETH
const ether2 = BrandedEther.fromWei(wei2)  // 0n (truncates)
Parameters:
  • wei: BrandedWei - Wei amount
Returns: BrandedEther Formula: ether = wei / 1_000_000_000_000_000_000 (integer division)

​
BrandedEther.fromGwei(gwei)

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

const gwei = BrandedGwei(1_000_000_000n)
const ether = BrandedEther.fromGwei(gwei)  // 1n Ether

// Fractional values truncate
const gwei2 = BrandedGwei(500_000_000n)  // 0.5 ETH
const ether2 = BrandedEther.fromGwei(gwei2)  // 0n (truncates)
Parameters:
  • gwei: BrandedGwei - Gwei amount
Returns: BrandedEther Formula: ether = gwei / 1_000_000_000 (integer division)

​
Conversions To Other Units

​
BrandedEther.toWei(ether)

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

const ether = BrandedEther(1n)
const wei = BrandedEther.toWei(ether)  // BrandedWei(1_000_000_000_000_000_000n)

const ether2 = BrandedEther(5n)
const wei2 = BrandedEther.toWei(ether2)  // BrandedWei(5_000_000_000_000_000_000n)
Parameters:
  • ether: BrandedEther - Ether amount
Returns: BrandedWei Formula: wei = ether * 1_000_000_000_000_000_000

​
BrandedEther.toGwei(ether)

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

const ether = BrandedEther(1n)
const gwei = BrandedEther.toGwei(ether)  // BrandedGwei(1_000_000_000n)

const ether2 = BrandedEther(2n)
const gwei2 = BrandedEther.toGwei(ether2)  // BrandedGwei(2_000_000_000n)
Parameters:
  • ether: BrandedEther - Ether amount
Returns: BrandedGwei Formula: gwei = ether * 1_000_000_000

​
Conversions To Base Type

​
BrandedEther.toU256(ether)

Convert BrandedEther to raw BrandedUint (removes denomination branding). 
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedUint from 'tevm/BrandedUint'

const ether = BrandedEther(5n)
const u256 = BrandedEther.toU256(ether)  // BrandedUint (no denomination)

// Can use with BrandedUint operations
const doubled = BrandedUint.times(u256, BrandedUint(2n))
Parameters:
  • ether: BrandedEther - Ether amount
Returns: BrandedUint Note: Removes denomination type safety. Use for arithmetic requiring BrandedUint.

​
Constants

import { WEI_PER_ETHER, GWEI_PER_ETHER } from 'tevm/BrandedEther'

WEI_PER_ETHER   // 1_000_000_000_000_000_000n (10^18)
GWEI_PER_ETHER  // 1_000_000_000n (10^9)

​
Usage Examples

​
User Balance Display

import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'

// RPC returns balance in Wei
const balanceWei = BrandedWei(5_234_567_890_123_456_789n)

// Convert to Ether for display
const balanceEther = BrandedWei.toEther(balanceWei)  // 5n Ether

console.log(`Balance: ${balanceEther} ETH`)  // "Balance: 5 ETH"

​
Transaction Value

import * as BrandedEther from 'tevm/BrandedEther'

// User wants to send 1 ETH
const valueEther = BrandedEther(1n)

// Convert to Wei for transaction
const valueWei = BrandedEther.toWei(valueEther)

const tx = {
  to: "0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e",
  value: valueWei,  // Type-safe BrandedWei
  gasPrice: /* ... */,
}

​
Balance Operations

import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedUint from 'tevm/BrandedUint'

const balance = BrandedEther(10n)
const amount = BrandedEther(3n)

// Convert to Uint256 for arithmetic
const balanceU256 = BrandedEther.toU256(balance)
const amountU256 = BrandedEther.toU256(amount)

const remaining = BrandedUint.minus(balanceU256, amountU256)
const remainingEther = BrandedEther(remaining)  // 7n Ether

console.log(`Remaining: ${remainingEther} ETH`)

​
Conversion Chain

import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'
import * as BrandedGwei from 'tevm/BrandedGwei'

// Start with Ether (user input)
const ether = BrandedEther(1n)

// Convert to Wei (for calculations)
const wei = BrandedEther.toWei(ether)  // 1_000_000_000_000_000_000n

// Convert to Gwei (for gas price comparison)
const gwei = BrandedEther.toGwei(ether)  // 1_000_000_000n

// Back to Ether (for display)
const etherAgain = BrandedWei.toEther(wei)  // 1n

​
Fractional Display

import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'
import * as BrandedUint from 'tevm/BrandedUint'

// Balance with fractional Ether
const balanceWei = BrandedWei(1_500_000_000_000_000_000n)  // 1.5 ETH

// Convert to Ether (truncates)
const wholeEther = BrandedWei.toEther(balanceWei)  // 1n

// Calculate remainder for fractional display
const weiPerEther = BrandedUint(1_000_000_000_000_000_000n)
const balanceU256 = BrandedWei.toU256(balanceWei)
const remainder = BrandedUint.modulo(balanceU256, weiPerEther)

console.log(`${wholeEther}.${remainder} ETH`)  // "1.500000000000000000 ETH"

​
Type Safety

BrandedEther prevents mixing denominations at compile time: 
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'

const ether = BrandedEther(1n)
const wei = BrandedWei(1_000_000_000_000_000_000n)

// ✗ Type error - incompatible brands
BrandedEther.toWei(wei)

// ✗ Type error - cannot compare different denominations
if (ether === wei) { }

// ✓ Correct - explicit conversion
const etherFromWei = BrandedWei.toEther(wei)
if (ether === etherFromWei) { }  // Type-safe comparison

​
Performance

BrandedEther uses direct Uint8Array representation:
  • Zero wrapper overhead
  • Direct bigint arithmetic
  • Optimal for hot paths
  • Same memory layout as BrandedUint
For balance calculations in tight loops, prefer BrandedEther over Ether namespace.

​
Common Ether Values

import * as BrandedEther from 'tevm/BrandedEther'

// Common amounts
const ONE_ETH = BrandedEther(1n)
const TEN_ETH = BrandedEther(10n)
const HUNDRED_ETH = BrandedEther(100n)

// Contract deposits
const MIN_STAKE = BrandedEther(32n)     // ETH 2.0 validator stake
const SMALL_TX = BrandedEther(1n)       // Typical user transfer
const LARGE_TX = BrandedEther(100n)     // Large transfer

​
Integer Division Notes

All conversions to Ether use integer division. Fractional Wei/Gwei amounts truncate: 
import * as BrandedEther from 'tevm/BrandedEther'
import * as BrandedWei from 'tevm/BrandedWei'

// Less than 1 Ether truncates to 0
const smallWei = BrandedWei(999_999_999_999_999_999n)  // 0.999... ETH
const ether = BrandedWei.toEther(smallWei)  // 0n (truncates)

// Exact Ether amounts convert cleanly
const exactWei = BrandedWei(1_000_000_000_000_000_000n)  // 1.0 ETH
const exactEther = BrandedWei.toEther(exactWei)  // 1n
For fractional display, work with Wei and format manually (see Fractional Display example above).

​
When to Use BrandedEther

Use BrandedEther when:
  • Type safety is critical
  • Working with existing BrandedUint infrastructure
  • Building type-safe APIs
  • Performance-sensitive balance operations