CallData

Transaction calldata contains the function selector and ABI-encoded parameters sent to smart contracts. It’s the primary mechanism for invoking contract functions on Ethereum.

New to EVM calldata? Start with Fundamentals to learn how calldata works in the EVM, function selectors, and ABI encoding.

Overview

CallData is a specialized branded Uint8Array that subtypes Hex for representing transaction data. It contains a 4-byte function selector followed by ABI-encoded parameters.

Type Definition
Decoded Form

import type { brand } from './brand.js'

export type CallDataType = Uint8Array & {
  readonly [brand]: "CallData"
}

CallData is a branded Uint8Array. TypeScript enforces type safety through a unique Symbol brand, preventing accidental mixing with other byte arrays while maintaining zero runtime overhead.

export type CallDataDecoded = {
  selector: [4]u8,        // Function selector
  signature: ?[]const u8, // Optional function signature
  parameters: []AbiValue, // Decoded parameters
}

CallDataDecoded represents the structured form with parsed selector and parameters.

Developer Experience

Despite being a Uint8Array, calldata displays formatted in most environments:

const calldata = CallData("0xa9059cbb000000000000000000000000...");
console.log(calldata);
// CallData("0xa9059cbb...")

This makes debugging more readable than raw byte arrays while maintaining performance.

Quick Start

Encode Function Call
Decode CallData
Extract Selector

import { CallData, Abi, Address, TokenBalance } from '@tevm/voltaire';

// Define ABI
const abi = Abi([{
  name: "transfer",
  type: "function",
  inputs: [
    { name: "to", type: "address" },
    { name: "amount", type: "uint256" }
  ]
}]);

// Encode function call
const recipient = Address("0x70997970C51812dc3A010C7d01b50e0d17dc79C8");
const amount = TokenBalance.fromUnits("1", 18);

const calldata: CallData = abi.transfer.encode(recipient, amount);

console.log(CallData.toHex(calldata));
// "0xa9059cbb00000000000000000000000070997970..."

import { CallData } from '@tevm/voltaire';

const calldata = CallData("0xa9059cbb...");

// Decode to structured form
const decoded = CallData.decode(calldata, abi);

console.log(decoded.selector); // [0xa9, 0x05, 0x9c, 0xbb]
console.log(decoded.signature); // "transfer(address,uint256)"
console.log(decoded.parameters); // [Address, Uint256]

import { CallData } from '@tevm/voltaire';

const calldata = CallData("0xa9059cbb...");

// Get function selector (first 4 bytes)
const selector = CallData.getSelector(calldata);
console.log(selector); // 0xa9059cbb

// Check for specific function
if (CallData.hasSelector(calldata, "0xa9059cbb")) {
  console.log("This is a transfer call");
}

Practical Examples

See Fundamentals for detailed explanations of how the EVM processes calldata, function selector derivation, and ABI encoding mechanics.

API Methods

Constructors

from(value) - Universal constructor from any input
fromHex(hex) - Parse hex string (with or without 0x prefix)
fromBytes(bytes) - Create from Uint8Array
encode(signature, params) - Encode function call from signature and parameters

Conversions

toHex(calldata) - Convert to hex string with 0x prefix
toBytes(calldata) - Return raw Uint8Array
decode(calldata, abi) - Decode to CallDataDecoded structure

Selectors

getSelector(calldata) - Extract 4-byte function selector
hasSelector(calldata, selector) - Check if calldata matches selector

Validation

isValid(value) - Check if value can be converted to calldata
is(value) - Type guard to check if value is CallData

Comparisons

equals(a, b) - Check equality of two calldata instances

Type Hierarchy

CallData conceptually subtypes Hex but stores as Uint8Array internally:

// Conceptual relationship
CallData extends Hex

// Runtime representation
CallData: Uint8Array & { readonly [brand]: "CallData" }

This design provides:

Type safety: Can’t accidentally pass arbitrary Uint8Array where CallData expected
Performance: Direct byte manipulation without string conversion
Interop: Works with Web APIs expecting Uint8Array

Abi

ABI encoding and decoding for function calls

Bytecode

Contract bytecode and EVM instructions

Transaction

Ethereum transactions that carry calldata

Hex

Hexadecimal encoding utilities

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

Overview

Developer Experience

Quick Start

Practical Examples

API Methods

Constructors

Conversions

Selectors

Validation

Comparisons

Type Hierarchy

Abi

Bytecode

Transaction

Hex

Overview

Getting Started

Core Concepts

Skills

JSONRPCProvider

Contract

Primitives

Cryptography

EVM

Utils

Guides

Examples

Swift

Zig

Developer Documentation

Generated API (TypeDoc)

​Overview

​Developer Experience

​Quick Start

​Practical Examples

​API Methods

​Constructors

​Conversions

​Selectors

​Validation

​Comparisons

​Type Hierarchy

​Related

Abi

Bytecode

Transaction

Hex

Overview

Developer Experience

Quick Start

Practical Examples

API Methods

Constructors

Conversions

Selectors

Validation

Comparisons

Type Hierarchy

Related