Skip to main content

Try it Live

Run Denomination examples in the interactive playground

​
BrandedWei

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

​
Overview

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

​
Type Definition

import type { BrandedUint } from 'tevm/BrandedUint'

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

​
Construction

​
BrandedWei.from(value)

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

const wei1 = BrandedWei(1_000_000_000n)              // 1 Gwei in Wei
const wei2 = BrandedWei(1_000_000_000_000_000_000n)  // 1 Ether in Wei
const wei3 = BrandedWei("1000000000000000000")       // String input
const wei4 = BrandedWei(42)                          // Number input
Parameters:
  • value: bigint | number | string - Value to convert
Returns: BrandedWei

​
BrandedWei.fromGwei(gwei)

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

const gwei = BrandedGwei(50n)
const wei = BrandedWei.fromGwei(gwei)  // 50_000_000_000n Wei
Parameters:
  • gwei: BrandedGwei - Gwei amount
Returns: BrandedWei Formula: wei = gwei * 1_000_000_000

​
BrandedWei.fromEther(ether)

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

const ether = BrandedEther(1n)
const wei = BrandedWei.fromEther(ether)  // 1_000_000_000_000_000_000n Wei
Parameters:
  • ether: BrandedEther - Ether amount
Returns: BrandedWei Formula: wei = ether * 1_000_000_000_000_000_000

​
Conversions To Other Units

​
BrandedWei.toGwei(wei)

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

const wei = BrandedWei(50_000_000_000n)
const gwei = BrandedWei.toGwei(wei)  // BrandedGwei(50n)

// Fractional values truncate
const wei2 = BrandedWei(50_000_000_001n)
const gwei2 = BrandedWei.toGwei(wei2)  // BrandedGwei(50n) - truncates
Parameters:
  • wei: BrandedWei - Wei amount
Returns: BrandedGwei Formula: gwei = wei / 1_000_000_000 (integer division)

​
BrandedWei.toEther(wei)

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

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

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

​
Conversions To Base Type

​
BrandedWei.toU256(wei)

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

const wei = BrandedWei(1_000_000_000n)
const u256 = BrandedWei.toU256(wei)  // BrandedUint (no denomination)

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

​
Constants

import { WEI_PER_GWEI, WEI_PER_ETHER } from 'tevm/BrandedWei'

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

​
Usage Examples

​
Gas Cost Calculation

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

const gasPrice = BrandedGwei(50n)  // 50 Gwei
const gasUsed = BrandedUint(21_000n)

// Convert to Wei for calculation
const gasPriceWei = BrandedGwei.toWei(gasPrice)
const gasPriceU256 = BrandedWei.toU256(gasPriceWei)

const totalCost = BrandedUint.times(gasPriceU256, gasUsed)
const totalCostWei = BrandedWei(totalCost)

console.log(`Cost: ${totalCostWei} Wei`)

​
Transaction Value

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

const valueEther = BrandedEther(1n)  // 1 ETH
const valueWei = BrandedEther.toWei(valueEther)

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

​
Conversion Chain

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

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

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

// Convert to Gwei
const gwei = BrandedWei.toGwei(wei)  // 1_000_000_000n

// Back to Ether
const etherAgain = BrandedGwei.toEther(gwei)  // 1n

​
Type Safety

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

const wei = BrandedWei(1_000_000_000n)
const gwei = BrandedGwei(1n)

// ✗ Type error - incompatible brands
BrandedWei.toGwei(gwei)

// ✓ Correct - explicit conversion
const weiFromGwei = BrandedGwei.toWei(gwei)
BrandedWei.toGwei(weiFromGwei)

​
Performance

BrandedWei uses direct Uint8Array representation:
  • Zero wrapper overhead
  • Direct bigint arithmetic
  • Optimal for hot paths
  • Same memory layout as BrandedUint
For maximum performance in tight loops, prefer BrandedWei over Wei namespace.

​
When to Use BrandedWei

Use BrandedWei when:
  • Type safety is critical
  • Working with existing BrandedUint infrastructure
  • Building type-safe APIs
  • Performance-sensitive code paths