Skip to main content

Try it Live

Run Denomination examples in the interactive playground

Gwei

Ethereum gas price denomination, equal to 1 billion (10^9) Wei.

Overview

Gwei (gigawei) is the standard unit for gas prices and transaction fees. Gwei.Type is a branded Uint256 preventing accidental unit mixing. Common usage: Gas prices, transaction fees, network congestion pricing.

Type Definition

import * as Uint from 'tevm/Uint'

const gweiSymbol = Symbol("Gwei")

export type Type = Uint.Type & { __brand: typeof gweiSymbol }

Construction

Gwei.from(value)

Create Gwei from numeric value.
import * as Gwei from 'tevm/Gwei'

const gwei1 = Gwei(50n)    // 50 Gwei (typical gas price)
const gwei2 = Gwei(100n)   // 100 Gwei (high gas price)
const gwei3 = Gwei(1n)     // 1 Gwei (low gas price)
const gwei4 = Gwei("21")   // String input
const gwei5 = Gwei(42)     // Number input
Parameters:
  • value: bigint | number | string - Value to convert to Gwei
Returns: Gwei.Type Note: Uses Uint.from internally for conversion. Defined in: primitives/Denomination/Gwei.ts:10

Conversions From Other Units

Gwei.fromWei(wei)

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

const wei = Wei(50_000_000_000n)  // 50 billion Wei
const gwei = Gwei.fromWei(wei)  // 50n Gwei

// Fractional values truncate
const wei2 = Wei(50_000_000_001n)
const gwei2 = Gwei.fromWei(wei2)  // 50n (truncates)
Parameters:
  • wei: Wei.Type - Wei value
Returns: Gwei.Type Formula: gwei = wei / 1_000_000_000 (integer division) Defined in: primitives/Denomination/Gwei.ts:14

Gwei.fromEther(ether)

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

const ether = Ether(1n)  // 1 Ether
const gwei = Gwei.fromEther(ether)  // 1_000_000_000n Gwei
Parameters:
  • ether: Ether.Type - Ether value
Returns: Gwei.Type Formula: gwei = ether * 1_000_000_000 Defined in: primitives/Denomination/Gwei.ts:19

Conversions To Other Units

Gwei.toWei(gwei)

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

const gwei = Gwei(50n)  // 50 Gwei gas price
const wei = Gwei.toWei(gwei)  // 50_000_000_000n Wei
Parameters:
  • gwei: Gwei.Type - Gwei value
Returns: Wei.Type Formula: wei = gwei * 1_000_000_000 Defined in: primitives/Denomination/Gwei.ts:24

Gwei.toEther(gwei)

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

const gwei = Gwei(1_000_000_000n)  // 1 billion Gwei
const ether = Gwei.toEther(gwei)  // 1n Ether

// Fractional values truncate
const gwei2 = Gwei(500_000_000n)  // 0.5 Ether in Gwei
const ether2 = Gwei.toEther(gwei2)  // 0n (truncates)
Parameters:
  • gwei: Gwei.Type - Gwei value
Returns: Ether.Type Formula: ether = gwei / 1_000_000_000 (integer division) Defined in: primitives/Denomination/Gwei.ts:29

Conversions To Base Type

Gwei.toU256(gwei)

Convert Gwei to raw Uint256 (removes branding).
import * as Gwei from 'tevm/Gwei'
import * as Uint from 'tevm/Uint'

const gwei = Gwei(50n)
const u256 = Gwei.toU256(gwei)  // Uint.Type (unbranded)

// Can now use with Uint operations
const doubled = Uint.times(u256, Uint(2n))
Parameters:
  • gwei: Gwei.Type - Gwei value
Returns: Uint.Type Note: Removes type safety. Use for arithmetic operations requiring Uint.Type. Defined in: primitives/Denomination/Gwei.ts:34

Usage Examples

Gas Price Calculations

import * as Gwei from 'tevm/Gwei'
import * as Uint from 'tevm/Uint'

// Current gas prices (in Gwei)
const lowGasPrice = Gwei(10n)     // Low priority
const normalGasPrice = Gwei(30n)  // Normal priority
const highGasPrice = Gwei(50n)    // High priority

// Calculate transaction cost
const gasUsed = Uint(21_000n)
const gasPriceWei = Gwei.toWei(highGasPrice)
const txCost = Uint.times(gasPriceWei, gasUsed)

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

EIP-1559 Transaction

import * as Gwei from 'tevm/Gwei'

// EIP-1559 parameters
const baseFee = Gwei(30n)          // Base fee per gas
const maxPriorityFee = Gwei(2n)    // Tip for miner
const maxFeePerGas = Gwei(50n)     // Max willing to pay

const tx = {
  type: 2,
  maxFeePerGas: Gwei.toWei(maxFeePerGas),
  maxPriorityFeePerGas: Gwei.toWei(maxPriorityFee),
  gasLimit: 21_000n
}

// Actual fee paid = min(maxFeePerGas, baseFee + maxPriorityFee)
const actualFee = Gwei(32n)  // 30 + 2

Gas Price Comparison

import * as Gwei from 'tevm/Gwei'

const prices = [
  Gwei(15n),
  Gwei(25n),
  Gwei(40n),
]

// Find minimum (convert to Uint for comparison)
const minPrice = prices.reduce((min, price) => {
  const minU256 = Gwei.toU256(min)
  const priceU256 = Gwei.toU256(price)
  return minU`256 <= priceU256` ? min : price
})

console.log(`Cheapest: ${minPrice} Gwei`)

Gas Price Tracking

import * as Gwei from 'tevm/Gwei'
import * as Uint from 'tevm/Uint'

interface GasPrices {
  fast: Gwei.Type
  standard: Gwei.Type
  slow: Gwei.Type
}

const current: GasPrices = {
  fast: Gwei(50n),
  standard: Gwei(30n),
  slow: Gwei(15n),
}

// Calculate cost difference
const gasUsed = Uint(21_000n)
const fastCost = Uint.times(Gwei.toWei(current.fast), gasUsed)
const slowCost = Uint.times(Gwei.toWei(current.slow), gasUsed)
const savings = Uint.minus(fastCost, slowCost)

console.log(`Save ${savings} Wei by waiting`)

Conversion Constants

// Wei per Gwei
const WEI_PER_GWEI = 1_000_000_000n  // 10^9

// Gwei per Ether
const GWEI_PER_ETHER = 1_000_000_000n  // 10^9

Common Gwei Values

import * as Gwei from 'tevm/Gwei'

// Historical gas price ranges
const VERY_LOW = Gwei(1n)      // Network idle
const LOW = Gwei(10n)          // Low activity
const NORMAL = Gwei(30n)       // Normal activity
const HIGH = Gwei(50n)         // High activity
const EXTREME = Gwei(100n)     // Network congestion

// EIP-1559 parameters
const PRIORITY_FEE_LOW = Gwei(1n)
const PRIORITY_FEE_NORMAL = Gwei(2n)
const PRIORITY_FEE_HIGH = Gwei(3n)

Type Safety

Gwei type prevents mixing with other denominations:
import * as Gwei from 'tevm/Gwei'
import * as Wei from 'tevm/Wei'
import * as Uint from 'tevm/Uint'

const gasPrice = Gwei(50n)
const gasUsed = Uint(21_000n)

// ✗ Type error - cannot multiply Gwei directly
const cost = Uint.times(gasPrice, gasUsed)

// ✓ Correct - convert to Wei first
const gasPriceWei = Gwei.toWei(gasPrice)
const cost = Uint.times(gasPriceWei, gasUsed)

Display Formatting

Gwei is human-readable for gas prices:
import * as Gwei from 'tevm/Gwei'

const gasPrice = Gwei(42n)
console.log(`Gas Price: ${gasPrice} Gwei`)  // "Gas Price: 42 Gwei"

// More readable than Wei
const gasPriceWei = Gwei.toWei(gasPrice)
console.log(`Gas Price: ${gasPriceWei} Wei`)  // "Gas Price: 42000000000 Wei"

WASM Acceleration

Gwei conversions available in WebAssembly for performance:
import * as GweiWasm from 'tevm/Gwei.wasm'

const gwei = GweiWasm(50n)
const wei = GweiWasm.toWei(gwei)
See WASM for details.