BrandedEther

Data-first branded Ether type with direct Uint8Array methods

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

Related

• BrandedWei - Branded Wei type
• BrandedGwei - Branded Gwei type
• BrandedUint - Underlying branded Uint256 type
• Conversions - Converting between units