Skip to main content

Documentation Index

Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt

Use this file to discover all available pages before exploring further.

Try it Live

Run GasUsed examples in the interactive playground

​
GasUsed

GasUsed represents the actual amount of gas consumed by a transaction during execution. Found in transaction receipts as receipt.gasUsed.

​
Type Definition

type GasUsedType = bigint & { readonly [brand]: "GasUsed" };
Branded bigint representing gas consumed (always non-negative).

​
Gas Mechanics

​
Yellow Paper

Gas mechanics defined in Yellow Paper Section 6 (Transaction Execution):
  • Gas vs Gas Price: Total cost = gasUsed × gasPrice (in Wei)
  • Gas Limit: Maximum gas transaction can consume (gasUsed ≤ gasLimit)
  • Refund: Unused gas refunded: (gasLimit - gasUsed) × gasPrice

​
Gas Ranges

  • Minimum: 21,000 gas (simple ETH transfer)
  • Typical: 50,000 - 200,000 gas (contract interactions)
  • Maximum: Block gas limit (~30M on mainnet)

​
API

​
Constructors

​
from(value)

Create GasUsed from number, bigint, or string. 
import { GasUsed } from '@tevm/primitives';

// From transaction receipt
const gasUsed = GasUsed.from(receipt.gasUsed);

// From bigint
const gas = GasUsed.from(51234n);

// From number
const gas2 = GasUsed.from(21000);

// From hex string
const gas3 = GasUsed.from("0xc822");
Throws: InvalidFormatError if value is negative.

​
Conversions

​
toNumber(gasUsed)

Convert to number. 
const gasUsed = GasUsed.from(51234n);
GasUsed.toNumber(gasUsed); // 51234

​
toBigInt(gasUsed)

Convert to bigint (identity operation). 
const gasUsed = GasUsed.from(51234n);
GasUsed.toBigInt(gasUsed); // 51234n

​
toHex(gasUsed)

Convert to hex string. 
const gasUsed = GasUsed.from(51234n);
GasUsed.toHex(gasUsed); // "0xc822"

​
Comparisons

​
equals(gas1, gas2)

Check equality. 
GasUsed.equals(51234n, 51234n); // true
GasUsed.equals(51234n, 21000n); // false

​
compare(gas1, gas2)

Compare values (-1, 0, 1). 
GasUsed.compare(21000n, 51234n); // -1 (first < second)
GasUsed.compare(51234n, 51234n); // 0 (equal)
GasUsed.compare(51234n, 21000n); // 1 (first > second)

​
Utilities

​
calculateCost(gasUsed, gasPrice)

Calculate transaction cost in Wei. 
const gasUsed = GasUsed.from(51234n);
const gasPrice = 20_000_000_000n; // 20 gwei

const cost = GasUsed.calculateCost(gasUsed, gasPrice);
// 1,024,680,000,000,000n Wei (0.00102468 ETH)

​
Common Gas Costs

​
Basic Operations

OperationGas Cost
Simple transfer21,000
ERC20 transfer~65,000
Uniswap V2 swap~150,000
Contract creation32,000+

​
Opcodes

OpcodeGas Cost
SLOAD (cold)2,100
SSTORE (set)20,000
SSTORE (reset)5,000
CALL100+
CREATE32,000+
LOG0375
KECCAK25630 + 6/word
See GasCosts for complete list.

​
Usage Examples

​
Calculate Transaction Cost

import { GasUsed } from '@tevm/primitives';

// Get from receipt
const receipt = await provider.getTransactionReceipt(txHash);
const gasUsed = GasUsed.from(receipt.gasUsed);

// Calculate cost
const gasPrice = receipt.effectiveGasPrice;
const cost = GasUsed.calculateCost(gasUsed, gasPrice);

console.log(`Gas used: ${GasUsed.toNumber(gasUsed)}`);
console.log(`Cost: ${cost} Wei`);

​
Compare Gas Usage

import { GasUsed } from '@tevm/primitives';

const tx1Gas = GasUsed.from(receipt1.gasUsed);
const tx2Gas = GasUsed.from(receipt2.gasUsed);

if (GasUsed.compare(tx1Gas, tx2Gas) > 0) {
  console.log('Transaction 1 used more gas');
}

​
Analyze Block Gas Usage

import { GasUsed } from '@tevm/primitives';

const block = await provider.getBlock(blockNumber, true);
let totalGas = 0n;

for (const tx of block.transactions) {
  const receipt = await provider.getTransactionReceipt(tx.hash);
  const gasUsed = GasUsed.from(receipt.gasUsed);
  totalGas += GasUsed.toBigInt(gasUsed);
}

console.log(`Block ${blockNumber} total gas: ${totalGas}`);
console.log(`Block utilization: ${(Number(totalGas) / 30_000_000 * 100).toFixed(2)}%`);

​
Block Gas Limit

Ethereum blocks have a gas limit (~30M on mainnet):
  • Individual transaction: gasUsed ≤ gasLimit (set in tx)
  • Block total: Σ gasUsed ≤ blockGasLimit
  • Full block: High priority transactions fill blocks

​
EIPs

  • EIP-2929: Gas cost increases for state access opcodes
  • EIP-1559: Fee market change (doesn’t affect gasUsed, but introduces base fee)
  • EIP-3529: Reduction in gas refunds (affects net cost but not gasUsed)

​
See Also