Try it Live

Run ABI examples in the interactive playground

Abi

Complete Application Binary Interface (ABI) encoding and decoding with type safety for Ethereum smart contracts.

Start with ABI Fundamentals to learn about function selectors, encoding rules, and event structure.

Overview

Branded array of ABI items (functions, events, errors, constructors). Zero-overhead design supports both tree-shakeable methods and class instances, following the same pattern as Address.

Quick Start

Encode Function Call
Decode Event Log
Parse Full ABI

import * as Abi from 'tevm/Abi';
import * as S from 'effect/Schema';
import * as AbiSchema from 'voltaire-effect/primitives/Abi';

// Define function ABI item
const transferAbi = {
  type: 'function',
  name: 'transfer',
  inputs: [
    { type: 'address', name: 'to' },
    { type: 'uint256', name: 'amount' }
  ],
  outputs: [{ type: 'bool' }],
  stateMutability: 'nonpayable'
} as const;

// Get function selector (4 bytes)
const selector = Abi.Function.getSelector(transferAbi);
// 0xa9059cbb

// Encode parameters
const encoded = Abi.Function.encodeParams(transferAbi, [
  '0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e',
  1000000000000000000n
]);

import * as Abi from 'tevm/Abi';

// Define event ABI item
const transferEvent = {
  type: 'event',
  name: 'Transfer',
  inputs: [
    { type: 'address', name: 'from', indexed: true },
    { type: 'address', name: 'to', indexed: true },
    { type: 'uint256', name: 'value', indexed: false }
  ]
} as const;

// Decode log from transaction receipt
const decoded = Abi.Event.decodeLog(transferEvent, {
  topics: [
    '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
    '0x000000000000000000000000742d35cc6634c0532925a3b844bc9e7595f51e3e',
    '0x000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045'
  ],
  data: '0x0000000000000000000000000000000000000000000000000de0b6b3a7640000'
});
// { from: '0x742d...', to: '0xd8dA...', value: 1000000000000000000n }

import * as Abi from 'tevm/Abi';

// ERC-20 ABI (partial)
const erc20Abi = S.decodeUnknownSync(AbiSchema.fromArray)([
  {
    type: 'function',
    name: 'transfer',
    inputs: [
      { type: 'address', name: 'to' },
      { type: 'uint256', name: 'amount' }
    ],
    outputs: [{ type: 'bool' }],
    stateMutability: 'nonpayable'
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { type: 'address', name: 'from', indexed: true },
      { type: 'address', name: 'to', indexed: true },
      { type: 'uint256', name: 'value' }
    ]
  }
]);

// Get specific item by name and type
const transferFn = Abi.getItem(erc20Abi, 'transfer', 'function');
const transferEvt = Abi.getItem(erc20Abi, 'Transfer', 'event');

Types

Abi
Parameter
AbiType
Item Types

// Main ABI type: array of ABI items
export type Abi = ReadonlyArray<
  Function | Event | BrandedError | Constructor | Fallback | Receive
>

// Example ABI
const erc20Abi: Abi = [
  {
    type: "function",
    name: "transfer",
    stateMutability: "nonpayable",
    inputs: [
      { type: "address", name: "to" },
      { type: "uint256", name: "amount" }
    ],
    outputs: [{ type: "bool" }]
  },
  {
    type: "event",
    name: "Transfer",
    inputs: [
      { type: "address", name: "from", indexed: true },
      { type: "address", name: "to", indexed: true },
      { type: "uint256", name: "value" }
    ]
  }
]

Source: Abi.ts:49-51

export type Parameter<
  TType extends AbiType = AbiType,
  TName extends string = string,
  TInternalType extends string = string
> = {
  type: TType
  name?: TName
  internalType?: TInternalType
  indexed?: boolean  // For event parameters
  components?: readonly Parameter[]  // For tuples
}

// Type conversion utilities
export type ParametersToPrimitiveTypes<TParams extends readonly Parameter[]>
export type ParametersToObject<TParams extends readonly Parameter[]>

Source: Parameter.ts:9-41

// All supported Solidity types
export type AbiType =
  // Unsigned integers
  | "uint" | "uint8" | "uint16" | "uint24" | "uint32" | "uint40"
  | "uint48" | "uint56" | "uint64" | "uint72" | "uint80" | "uint88"
  | "uint96" | "uint104" | "uint112" | "uint120" | "uint128" | "uint136"
  | "uint144" | "uint152" | "uint160" | "uint168" | "uint176" | "uint184"
  | "uint192" | "uint200" | "uint208" | "uint216" | "uint224" | "uint232"
  | "uint240" | "uint248" | "uint256"
  // Signed integers
  | "int" | "int8" | "int16" | "int24" | "int32" | "int40"
  | "int48" | "int56" | "int64" | "int72" | "int80" | "int88"
  | "int96" | "int104" | "int112" | "int120" | "int128" | "int136"
  | "int144" | "int152" | "int160" | "int168" | "int176" | "int184"
  | "int192" | "int200" | "int208" | "int216" | "int224" | "int232"
  | "int240" | "int248" | "int256"
  // Other types
  | "address" | "bool" | "string" | "bytes"
  // Fixed-size bytes
  | "bytes1" | "bytes2" | "bytes3" | "bytes4" | "bytes5" | "bytes6"
  | "bytes7" | "bytes8" | "bytes9" | "bytes10" | "bytes11" | "bytes12"
  | "bytes13" | "bytes14" | "bytes15" | "bytes16" | "bytes17" | "bytes18"
  | "bytes19" | "bytes20" | "bytes21" | "bytes22" | "bytes23" | "bytes24"
  | "bytes25" | "bytes26" | "bytes27" | "bytes28" | "bytes29" | "bytes30"
  | "bytes31" | "bytes32"
  // Tuple and arrays
  | "tuple"
  | `${string}[]`  // Dynamic arrays
  | `${string}[${number}]`  // Fixed arrays

Source: Type.ts:1-107

// Function item
export type Function<
  TName extends string = string,
  TStateMutability extends StateMutability = StateMutability,
  TInputs extends readonly Parameter[] = readonly Parameter[],
  TOutputs extends readonly Parameter[] = readonly Parameter[]
> = {
  type: "function"
  name: TName
  stateMutability: TStateMutability
  inputs: TInputs
  outputs: TOutputs
}

// Event item
export type Event<
  TName extends string = string,
  TInputs extends readonly Parameter[] = readonly Parameter[]
> = {
  type: "event"
  name: TName
  inputs: TInputs
  anonymous?: boolean
}

// Error item
export type BrandedError<
  TName extends string = string,
  TInputs extends readonly Parameter[] = readonly Parameter[]
> = {
  type: "error"
  name: TName
  inputs: TInputs
}

// Constructor item
export type BrandedConstructor<
  TStateMutability extends StateMutability = StateMutability,
  TInputs extends readonly Parameter[] = readonly Parameter[]
> = {
  type: "constructor"
  stateMutability: TStateMutability
  inputs: TInputs
}

// Fallback and Receive
export type Fallback<
  TStateMutability extends StateMutability = StateMutability
> = {
  type: "fallback"
  stateMutability: TStateMutability
}

export type Receive = {
  type: "receive"
  stateMutability: "payable"
}

// State mutability
export type StateMutability = "pure" | "view" | "nonpayable" | "payable"

API Documentation

Core Concepts

Fundamentals

Learn ABI encoding structure, selectors, and data layout

ABI Types

Function, Event, Error, Constructor type definitions

Encoding Guide

ABI encoding and decoding mechanics

Selectors & Signatures

Function selectors and event topic hashes

Usage Patterns

Common patterns: contract calls, log parsing

Top-Level Methods

format

Format ABI item to human-readable signature

formatWithArgs

Format with concrete argument values

getItem

Find ABI item by name and type

encode

Generic ABI encoding for any item type

decode

Generic ABI decoding for any item type

decodeData

Decode without selector prefix

parseLogs

Parse multiple event logs using full ABI

Function Methods

getSelector

Get function selector (4 bytes)

getSignature

Get human-readable function signature

encodeParams

Encode function input parameters

decodeParams

Decode function input parameters

encodeResult

Encode function return values

decodeResult

Decode function return values

GetSelector

Factory for custom keccak256

Event Methods

getSelector

Get event selector (32 bytes, topic0)

getSignature

Get human-readable event signature

encodeTopics

Encode indexed parameters to topics

decodeLog

Decode event log data and topics

GetSelector

Factory for custom keccak256

EncodeTopics

Factory for custom keccak256

Error Methods

getSelector

Get error selector (4 bytes)

getSignature

Get human-readable error signature

encodeParams

Encode error parameters

decodeParams

Decode error parameters

GetSelector

Factory for custom keccak256

Constructor Methods

encodeParams

Encode constructor parameters for deployment

decodeParams

Decode constructor parameters from bytecode

Item Utilities

isFunction

Type guard: check if item is function

isEvent

Type guard: check if item is event

isError

Type guard: check if item is error

isConstructor

Type guard: check if item is constructor

isFallback

Type guard: check if item is fallback

isReceive

Type guard: check if item is receive

format

Format ABI item to signature string

formatWithArgs

Format with concrete argument values

getItem

Get specific item from ABI by name/type

ABI JSON Format

Contract ABIs are typically JSON arrays describing the contract interface:

const abi = [
  {
    "type": "function",
    "name": "transfer",
    "stateMutability": "nonpayable",
    "inputs": [
      { "type": "address", "name": "to" },
      { "type": "uint256", "name": "amount" }
    ],
    "outputs": [{ "type": "bool" }]
  },
  {
    "type": "event",
    "name": "Transfer",
    "inputs": [
      { "type": "address", "name": "from", "indexed": true },
      { "type": "address", "name": "to", "indexed": true },
      { "type": "uint256", "name": "value", "indexed": false }
    ]
  },
  {
    "type": "error",
    "name": "InsufficientBalance",
    "inputs": [
      { "type": "uint256", "name": "balance" },
      { "type": "uint256", "name": "required" }
    ]
  }
]

Error Types

import {
  AbiEncodingError,
  AbiDecodingError,
  AbiParameterMismatchError,
  AbiItemNotFoundError,
  AbiInvalidSelectorError
} from '@tevm/primitives/Abi'

try {
  const encoded = encodeParameters(params, values)
} catch (error) {
  if (error instanceof AbiEncodingError) {
    // Invalid encoding (out of range, wrong type, etc.)
  } else if (error instanceof AbiParameterMismatchError) {
    // Parameter count mismatch
  }
}

Source: Errors.ts:1-35

Tree-Shaking

Import only what you need for optimal bundle size:

// Import specific namespace
import { Function } from '@tevm/primitives/Abi'

// Or import individual functions
import { encodeParameters, decodeParameters } from '@tevm/primitives/Abi'

Sub-Namespaces

The Abi module is organized into specialized sub-namespaces:

Function - Function encoding/decoding and selectors
Event - Event log encoding/decoding and topics
Error - Custom error encoding/decoding
Constructor - Constructor parameter encoding
Wasm - WASM-accelerated implementations

Each namespace provides focused functionality with tree-shakeable exports.

Abi (Effect) - Effect.ts integration with Schema validation
Keccak256 - Keccak256 hashing used for selectors and signatures
Address - 20-byte Ethereum addresses used in ABI encoding
Uint - Unsigned integer types used in ABI encoding
Bytes - Fixed and dynamic byte arrays in ABI encoding

Specification References

Solidity ABI Specification - Official ABI encoding specification
Contract ABI Specification - JSON ABI format
EIP-712 - Typed structured data hashing and signing

Documentation Index

Try it Live

​Abi

​Overview

​Quick Start

​Types

​API Documentation

​Core Concepts

Fundamentals

ABI Types

Encoding Guide

Selectors & Signatures

Usage Patterns

​Top-Level Methods

format

formatWithArgs

getItem

encode

decode

decodeData

parseLogs

​Function Methods

getSelector

getSignature

encodeParams

decodeParams

encodeResult

decodeResult

GetSelector

​Event Methods

getSelector

getSignature

encodeTopics

decodeLog

GetSelector

EncodeTopics

​Error Methods

getSelector

getSignature

encodeParams

decodeParams

GetSelector

​Constructor Methods

encodeParams

decodeParams

​Item Utilities

isFunction

isEvent

isError

isConstructor

isFallback

isReceive

format

formatWithArgs

getItem

​ABI JSON Format

​Error Types

​Tree-Shaking

​Sub-Namespaces

​Related Types

​Specification References

Abi

Overview

Quick Start

Types

API Documentation

Core Concepts

Top-Level Methods

Function Methods

Event Methods

Error Methods

Constructor Methods

Item Utilities

ABI JSON Format

Error Types

Tree-Shaking

Sub-Namespaces

Related Types

Specification References