BrandedGwei

Data-first branded Gwei type with direct Uint8Array methods

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

Related

• BrandedWei - Branded Wei type
• BrandedEther - Branded Ether type
• BrandedUint - Underlying branded Uint256 type
• Conversions - Converting between units