Skip to main content

Try it Live

Run Denomination examples in the interactive playground

​
BrandedGwei

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

​
Overview

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

​
Type Definition

import type { BrandedUint } from 'tevm/BrandedUint'

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

​
Construction

​
BrandedGwei.from(value)

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

const gwei1 = BrandedGwei(50n)      // 50 Gwei gas price
const gwei2 = BrandedGwei(21)       // 21 Gwei
const gwei3 = BrandedGwei("100")    // String input
const gwei4 = BrandedGwei("0x32")   // Hex input (50 Gwei)
Parameters:
  • value: bigint | number | string - Value to convert
Returns: BrandedGwei

​
BrandedGwei.fromWei(wei)

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

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

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

​
BrandedGwei.fromEther(ether)

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

const ether = BrandedEther(1n)
const gwei = BrandedGwei.fromEther(ether)  // 1_000_000_000n Gwei
Parameters:
  • ether: BrandedEther - Ether amount
Returns: BrandedGwei Formula: gwei = ether * 1_000_000_000

​
Conversions To Other Units

​
BrandedGwei.toWei(gwei)

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

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

const gwei2 = BrandedGwei(21n)
const wei2 = BrandedGwei.toWei(gwei2)  // BrandedWei(21_000_000_000n)
Parameters:
  • gwei: BrandedGwei - Gwei amount
Returns: BrandedWei Formula: wei = gwei * 1_000_000_000

​
BrandedGwei.toEther(gwei)

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

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

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

​
Conversions To Base Type

​
BrandedGwei.toU256(gwei)

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

const gwei = BrandedGwei(50n)
const u256 = BrandedGwei.toU256(gwei)  // BrandedUint (no denomination)

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

​
Constants

import { WEI_PER_GWEI, GWEI_PER_ETHER } from 'tevm/BrandedGwei'

WEI_PER_GWEI    // 1_000_000_000n (10^9)
GWEI_PER_ETHER  // 1_000_000_000n (10^9)

​
Usage Examples

​
Gas Price Calculation

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

// Gas price from RPC (often in Gwei)
const gasPriceGwei = BrandedGwei(50n)

// Convert to Wei for transaction
const gasPriceWei = BrandedGwei.toWei(gasPriceGwei)

// Calculate total cost
const gasUsed = BrandedUint(21_000n)
const gasPriceU256 = BrandedWei.toU256(gasPriceWei)

const totalCost = BrandedUint.times(gasPriceU256, gasUsed)
console.log(`Total: ${BrandedWei(totalCost)} Wei`)

​
Priority Fee Calculation

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

const baseFee = BrandedGwei(30n)
const priorityFee = BrandedGwei(2n)

// Convert to Uint256 for addition
const baseU256 = BrandedGwei.toU256(baseFee)
const priorityU256 = BrandedGwei.toU256(priorityFee)

const maxFeeU256 = BrandedUint.plus(baseU256, priorityU256)
const maxFeeGwei = BrandedGwei(maxFeeU256)  // 32n Gwei

console.log(`Max fee: ${maxFeeGwei} Gwei`)

​
Conversion Chain

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

// Start with Gwei (common for gas prices)
const gwei = BrandedGwei(50n)

// Convert to Wei (for calculations)
const wei = BrandedGwei.toWei(gwei)  // 50_000_000_000n

// Convert to Ether (for display, requires full Ether)
const largeGwei = BrandedGwei(1_000_000_000n)  // 1 ETH
const ether = BrandedGwei.toEther(largeGwei)  // 1n

​
Display Gas Price

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

// RPC returns Wei
const gasPriceWei = BrandedWei(50_000_000_000n)

// Convert to Gwei for user display
const gasPriceGwei = BrandedWei.toGwei(gasPriceWei)

console.log(`Gas price: ${gasPriceGwei} Gwei`)  // "Gas price: 50 Gwei"

​
Type Safety

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

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

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

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

// ✓ Correct - explicit conversion
const gweiFromWei = BrandedWei.toGwei(wei)
if (gwei === gweiFromWei) { }  // Type-safe comparison

​
Performance

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

​
Common Gwei Values

import * as BrandedGwei from 'tevm/BrandedGwei'

// Gas price levels
const LOW_GAS = BrandedGwei(10n)      // 10 Gwei - cheap
const NORMAL_GAS = BrandedGwei(30n)   // 30 Gwei - normal
const HIGH_GAS = BrandedGwei(100n)    // 100 Gwei - fast
const URGENT_GAS = BrandedGwei(200n)  // 200 Gwei - urgent

// Priority fees (EIP-1559)
const LOW_PRIORITY = BrandedGwei(1n)   // 1 Gwei tip
const MED_PRIORITY = BrandedGwei(2n)   // 2 Gwei tip
const HIGH_PRIORITY = BrandedGwei(5n)  // 5 Gwei tip

​
When to Use BrandedGwei

Use BrandedGwei when:
  • Type safety is critical
  • Working with existing BrandedUint infrastructure
  • Building type-safe APIs
  • Performance-sensitive gas calculations