Abi

Application Binary Interface encoding and decoding for Ethereum smart contracts

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

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
]);

Decode Event Log

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 }

Parse Full ABI

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

// 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

Parameter

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

AbiType

// 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

Item Types

// 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.

Related Types

• 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