Skip to content

Utilities & Addresses

Tevm exports a set of lightweight utility functions and classes. Many of these build upon lower-level packages like tevm/utils and viem while standardizing usage for Tevm Node. Below are the most commonly used.

createAddress

Creates an Ethereum address from various input formats:

import { createAddress } from 'tevm/address'
 
// Creates a TEVM-style Address object from various input forms
let addr = createAddress(`0x${"00".repeat(20)}`)
// from a hex string
addr = createAddress(420n)
// from a bigint
addr = createAddress(new Uint8Array(20))
// from a 20-byte array

Signature

declare function createAddress(
  address: number | bigint | string | Uint8Array | EthjsAddress
): Address

Behavior & Notes

  • Accepts various input types: 0x-prefixed hex strings, unprefixed hex, numbers, bigints, Uint8Arrays, or EthjsAddress.
  • Throws InvalidAddressError if it can't parse a valid 20-byte address from the input.

Address Class

A thin wrapper around EthjsAddress offering a simple, consistent shape for Tevm Node. Created by createAddress or by forging your own:

import { Address } from 'tevm/address'
 
const a = new Address(Uint8Array.from([ /* 20 bytes */ ]))
console.log(a.bytes)  // a raw 20-byte address
console.log(a.toString()) // 0x....

createContractAddress

Creates a contract address following EIP-1014:

import { createContractAddress } from 'tevm/address'
 
// from an existing address + nonce, produce the CREATE address
const from = createAddress("0x1111...1111")
const nonce = 1n
const contractAddr = createContractAddress(from, nonce)

Usage

  1. Follows standard Ethereum's keccak256(rlp([senderAddress, nonce]))[-20..].
  2. Ideal for simulating CREATE addresses in test or dev flows.

Error Handling

  • Throws InvalidAddressError if the from address is invalid.

Common Errors

  • InvalidAddressError Thrown when a string/bytes input fails to parse as a valid 20-byte address.

  • UnreachableCodeError Thrown internally if a code path was unexpectedly reached. Generally wrapped into a more descriptive error.

Other Handy Utilities

Some additional lower-level utility re-exports from tevm/utils or viem:

  • hexToBytes(hex: string): Uint8Array Convert a hex string to raw bytes (with optional size checks).
  • keccak256(data: Uint8Array | HexString, 'bytes' | 'hex') A standard keccak256 hasher.
  • encodeFunctionData(...), toRlp(...), etc. Various encoding helpers used by Tevm Node internally.

Tip: If you are building higher-level code in the browser or Node, you may prefer viem's standardized utilities for bytes conversions, hashing, and ABIs. Tevm re-exports many of these for convenience.

@tevm/utils

Generated API Documentation: View the full API documentation in the evmts/tevm-monorepo/packages/utils/docs folder.

The @tevm/utils package provides a comprehensive collection of utility functions and types for working with Ethereum data structures, encoding/decoding, and common operations. It combines functionality from various Ethereum libraries and adds Tevm-specific utilities.

Installation

npm install @tevm/utils

Main Components

Data Types and Encoding

Hex and Bytes Conversion

import {
  bytesToHex,
  hexToBytes,
  bytesToBigInt,
  bytesToNumber,
  hexToBigInt,
  hexToNumber,
  numberToHex,
  stringToHex,
  hexToString
} from '@tevm/utils'
 
// Convert bytes to hex
const hex = bytesToHex(new Uint8Array([1, 164])) // '0x01a4'
 
// Convert hex to bytes
const bytes = hexToBytes('0x01a4') // Uint8Array([1, 164])
 
// Convert to/from numbers
const num = hexToNumber('0x01a4') // 420
const hex2 = numberToHex(420) // '0x01a4'
 
// String conversion
const str = hexToString('0x48656c6c6f') // 'Hello'
const hex3 = stringToHex('Hello') // '0x48656c6c6f'

Type Checking

import { isHex, isBytes, isAddress } from '@tevm/utils'
 
isHex('0x123') // true
isBytes(new Uint8Array()) // true
isAddress('0x123...') // true

Ethereum Specific

Unit Conversion

import {
  formatEther,
  parseEther,
  formatGwei,
  parseGwei
} from '@tevm/utils'
 
// Convert wei to ether
formatEther(1000000000000000000n) // '1.0'
 
// Convert ether to wei
parseEther('1.0') // 1000000000000000000n
 
// Work with gwei
formatGwei(1000000000n) // '1.0'
parseGwei('1.0') // 1000000000n

Cryptographic Functions

import {
  keccak256,
  ecrecover,
  ecsign,
  randomBytes
} from '@tevm/utils'
 
// Generate keccak256 hash
const hash = keccak256('0x1234')
 
// Sign data
const signature = ecsign(messageHash, privateKey)
 
// Recover address from signature
const address = ecrecover(messageHash, v, r, s)
 
// Generate random bytes
const random = randomBytes(32)

ABI Encoding/Decoding

import {
  encodeAbiParameters,
  decodeAbiParameters,
  encodeFunctionData,
  decodeFunctionData,
  encodeEventTopics,
  decodeEventLog
} from '@tevm/utils'
 
// Encode function data
const data = encodeFunctionData({
  abi: [...],
  functionName: 'transfer',
  args: [address, amount]
})
 
// Decode function data
const result = decodeFunctionData({
  abi: [...],
  data: '0x...'
})
 
// Work with events
const topics = encodeEventTopics({
  abi: [...],
  eventName: 'Transfer',
  args: [from, to, null]
})

RLP Encoding/Decoding

import { toRlp, fromRlp } from '@tevm/utils'
 
// Encode to RLP
const rlp = toRlp(['0x123', '0x456'])
 
// Decode from RLP
const decoded = fromRlp(rlp)

Memory Database

import { createMemoryDb } from '@tevm/utils'
 
// Create an in-memory database
const db = createMemoryDb()
 
// Initialize with existing data
const initialData = new Map()
const db2 = createMemoryDb(initialData)

Event Emitter

import { AsyncEventEmitter } from '@tevm/utils'
 
const emitter = new AsyncEventEmitter()
 
// Add listener
emitter.on('event', async (data) => {
  // Handle event
})
 
// Emit event
await emitter.emit('event', data)

Types

Basic Types

import type {
  Address,
  Hex,
  BlockTag,
  BlockNumber,
  BytesLike,
  BigIntLike
} from '@tevm/utils'
 
// Example type usage
const address: Address = '0x...'
const hex: Hex = '0x...'
const blockTag: BlockTag = 'latest'

ABI Types

import type {
  Abi,
  AbiFunction,
  AbiEvent,
  AbiConstructor,
  ParseAbi,
  FormatAbi
} from '@tevm/utils'
 
// Parse ABI
type ParsedAbi = ParseAbi<typeof abiString>
 
// Format ABI
type FormattedAbi = FormatAbi<typeof parsedAbi>

Contract Types

import type {
  ContractFunctionName,
  ContractConstructorArgs,
  ExtractAbiFunction,
  ExtractAbiEvent
} from '@tevm/utils'
 
// Extract function from ABI
type TransferFunction = ExtractAbiFunction<typeof abi, 'transfer'>
 
// Extract event from ABI
type TransferEvent = ExtractAbiEvent<typeof abi, 'Transfer'>

Constants

import {
  GWEI_TO_WEI,
  KECCAK256_RLP,
  KECCAK256_RLP_ARRAY
} from '@tevm/utils'
 
// Common conversion factors and constants
console.log(GWEI_TO_WEI) // 1000000000n

Error Handling

The package uses the @tevm/errors package for standardized error handling:

import { invariant } from '@tevm/utils'
 
// Assert conditions
invariant(condition, 'Error message')

See Also