The Application Binary Interface is the standard way to interact with contracts in the Ethereum ecosystem, both
from outside the blockchain and for contract-to-contract interaction. Data is encoded according to its type,
as described in this specification. The encoding is not self describing and thus requires a schema in order to decode.

We assume the interface functions of a contract are strongly typed, known at compilation time and static. No introspection mechanism will be provided. We assume that all contracts will have the interface definitions of any contracts they call available at compile-time.

This specification does not address contracts whose interface is dynamic or otherwise known only at run-time. Should these cases become important they can be adequately handled as facilities built within the Ethereum ecosystem.

The first four bytes of the call data for a function call specifies the function to be called. It is the
first (left, high-order in big-endian) four bytes of the Keccak (SHA-3) hash of the signature of the function. The signature is defined as the canonical expression of the basic prototype, i.e.
the function name with the parenthesised list of parameter types. Parameter types are split by a single comma - no spaces are used.

Note

The return type of a function is not part of this signature. In Solidity’s function overloading return types are not considered. The reason is to keep function call resolution context-independent.
The JSON description of the ABI however contains both inputs and outputs. See (the JSON ABI)

Starting from the fifth byte, the encoded arguments follow. This encoding is also used in other places, e.g. the return values and also event arguments are encoded in the same way, without the four bytes specifying the function.

We will now formally specify the encoding, such that it will have the following
properties, which are especially useful if some arguments are nested arrays:

Properties:

The number of reads necessary to access a value is at most the depth of the value inside the argument array structure, i.e. four reads are needed to retrieve a_i[k][l][r]. In a previous version of the ABI, the number of reads scaled linearly with the total number of dynamic parameters in the worst case.

The data of a variable or array element is not interleaved with other data and it is relocatable, i.e. it only uses relative “addresses”

We distinguish static and dynamic types. Static types are encoded in-place and dynamic types are encoded at a separately allocated location after the current block.

Definition: The following types are called “dynamic”:

bytes

string

T[] for any T

T[k] for any dynamic T and any k>0

(T1,...,Tk) if any Ti is dynamic for 1<=i<=k

All other types are called “static”.

Definition:len(a) is the number of bytes in a binary string a.
The type of len(a) is assumed to be uint256.

We define enc, the actual encoding, as a mapping of values of the ABI types to binary strings such
that len(enc(X)) depends on the value of X if and only if the type of X is dynamic.

Definition: For any ABI value X, we recursively define enc(X), depending
on the type of X being

(T1,...,Tk) for k>=0 and any types T1, …, Tk

enc(X)=head(X(1))...head(X(k-1))tail(X(0))...tail(X(k-1))

where X(i) is the ith component of the value, and
head and tail are defined for Ti being a static type as

Note that in the dynamic case, head(X(i)) is well-defined since the lengths of
the head parts only depend on the types and not the values. Its value is the offset
of the beginning of tail(X(i)) relative to the start of enc(X).

T[k] for any T and k:

enc(X)=enc((X[0],...,X[k-1]))

i.e. it is encoded as if it were a tuple with k elements
of the same type.

T[] where X has k elements (k is assumed to be of type uint256):

enc(X)=enc(k)enc([X[1],...,X[k]])

i.e. it is encoded as if it were an array of static size k, prefixed with
the number of elements.

bytes, of length k (which is assumed to be of type uint256):

enc(X)=enc(k)pad_right(X), i.e. the number of bytes is encoded as a

uint256 followed by the actual value of X as a byte sequence, followed by
the minimum number of zero-bytes such that len(enc(X)) is a multiple of 32.

string:

enc(X)=enc(enc_utf8(X)), i.e. X is utf-8 encoded and this value is interpreted as of bytes type and encoded further. Note that the length used in this subsequent encoding is the number of bytes of the utf-8 encoded string, not its number of characters.

uint<M>: enc(X) is the big-endian encoding of X, padded on the higher-order (left) side with zero-bytes such that the length is 32 bytes.

address: as in the uint160 case

int<M>: enc(X) is the big-endian two’s complement encoding of X, padded on the higher-order (left) side with 0xff for negative X and with zero bytes for positive X such that the length is 32 bytes.

bool: as in the uint8 case, where 1 is used for true and 0 for false

fixed<M>x<N>: enc(X) is enc(X*10**N) where X*10**N is interpreted as a int256.

fixed: as in the fixed128x19 case

ufixed<M>x<N>: enc(X) is enc(X*10**N) where X*10**N is interpreted as a uint256.

ufixed: as in the ufixed128x19 case

bytes<M>: enc(X) is the sequence of bytes in X padded with trailing zero-bytes to a length of 32 bytes.

If we wanted to call sam with the arguments "dave", true and [1,2,3], we would pass 292 bytes total, broken down into:

0xa5643bf2: the Method ID. This is derived from the signature sam(bytes,bool,uint256[]). Note that uint is replaced with its canonical representation uint256.

0x0000000000000000000000000000000000000000000000000000000000000060: the location of the data part of the first parameter (dynamic type), measured in bytes from the start of the arguments block. In this case, 0x60.

0x0000000000000000000000000000000000000000000000000000000000000001: the second parameter: boolean true.

0x00000000000000000000000000000000000000000000000000000000000000a0: the location of the data part of the third parameter (dynamic type), measured in bytes. In this case, 0xa0.

0x0000000000000000000000000000000000000000000000000000000000000004: the data part of the first argument, it starts with the length of the byte array in elements, in this case, 4.

0x6461766500000000000000000000000000000000000000000000000000000000: the contents of the first argument: the UTF-8 (equal to ASCII in this case) encoding of "dave", padded on the right to 32 bytes.

0x0000000000000000000000000000000000000000000000000000000000000003: the data part of the third argument, it starts with the length of the array in elements, in this case, 3.

0x0000000000000000000000000000000000000000000000000000000000000001: the first entry of the third parameter.

0x0000000000000000000000000000000000000000000000000000000000000002: the second entry of the third parameter.

0x0000000000000000000000000000000000000000000000000000000000000003: the third entry of the third parameter.

A call to a function with the signature f(uint,uint32[],bytes10,bytes) with values (0x123,[0x456,0x789],"1234567890","Hello,world!") is encoded in the following way:

We take the first four bytes of sha3("f(uint256,uint32[],bytes10,bytes)"), i.e. 0x8be65246.
Then we encode the head parts of all four arguments. For the static types uint256 and bytes10, these are directly the values we want to pass, whereas for the dynamic types uint32[] and bytes, we use the offset in bytes to the start of their data area, measured from the start of the value encoding (i.e. not counting the first four bytes containing the hash of the function signature). These are:

0x0000000000000000000000000000000000000000000000000000000000000080 (offset to start of data part of second parameter, 4*32 bytes, exactly the size of the head part)

0x3132333435363738393000000000000000000000000000000000000000000000 ("1234567890" padded to 32 bytes on the right)

0x00000000000000000000000000000000000000000000000000000000000000e0 (offset to start of data part of fourth parameter = offset to start of data part of first dynamic parameter + size of data part of first dynamic parameter = 4*32 + 3*32 (see below))

After this, the data part of the first dynamic argument, [0x456,0x789] follows:

0x0000000000000000000000000000000000000000000000000000000000000002 (number of elements of the array, 2)

Events are an abstraction of the Ethereum logging/event-watching protocol. Log entries provide the contract’s address, a series of up to four topics and some arbitrary length binary data. Events leverage the existing function ABI in order to interpret this (together with an interface spec) as a properly typed structure.

Given an event name and series of event parameters, we split them into two sub-series: those which are indexed and those which are not. Those which are indexed, which may number up to 3, are used alongside the Keccak hash of the event signature to form the topics of the log entry. Those which are not indexed form the byte array of the event.

In effect, a log entry using this ABI is described as:

address: the address of the contract (intrinsically provided by Ethereum);

topics[0]: keccak(EVENT_NAME+"("+EVENT_ARGS.map(canonical_type_of).join(",")+")") (canonical_type_of is a function that simply returns the canonical type of a given argument, e.g. for uintindexedfoo, it would return uint256). If the event is declared as anonymous the topics[0] is not generated;

topics[n]: EVENT_INDEXED_ARGS[n-1] (EVENT_INDEXED_ARGS is the series of EVENT_ARGS that are indexed);

data: abi_serialise(EVENT_NON_INDEXED_ARGS) (EVENT_NON_INDEXED_ARGS is the series of EVENT_ARGS that are not indexed, abi_serialise is the ABI serialisation function used for returning a series of typed values from a function, as described above).

For all fixed-length Solidity types, the EVENT_INDEXED_ARGS array contains the 32-byte encoded value directly. However, for types of dynamic length, which include string, bytes, and arrays, EVENT_INDEXED_ARGS will contain the Keccak hash of the encoded value, rather than the encoded value directly. This allows applications to efficiently query for values of dynamic-length types (by setting the hash of the encoded value as the topic), but leaves applications unable to decode indexed values they have not queried for. For dynamic-length types, application developers face a trade-off between fast search for predetermined values (if the argument is indexed) and legibility of arbitrary values (which requires that the arguments not be indexed). Developers may overcome this tradeoff and achieve both efficient search and arbitrary legibility by defining events with two arguments — one indexed, one not — intended to hold the same value.

Despite that names are intentionally not part of the ABI encoding they do make a lot of sense to be included
in the JSON to enable displaying it to the end user. The structure is nested in the following way:

An object with members name, type and potentially components describes a typed variable.
The canonical type is determined until a tuple type is reached and the string description up
to that point is stored in type prefix with the word tuple, i.e. it will be tuple followed by
a sequence of [] and [k] with
integers k. The components of the tuple are then stored in the member components,
which is of array type and has the same structure as the top-level object except that
indexed is not allowed there.

More specifically, each statically-sized type takes as many bytes as its range has
and dynamically-sized types like string, bytes or uint[] are encoded without
their length field. This means that the encoding is ambiguous as soon as there are two
dynamically-sized elements.