# Ethereum Contract Application Binary Interface (ABI) in Elixir

### Background

Nowadays Ethereum is one of the most successful blockchain platforms. Foremost things that made it possible are the Ethereum Virtual Machine (EVM) and smart contracts that are executed in the EVM.

Smart contracts are little programs written in high-level languages like Solidity or LLL specifically created for Ethereum. Firstly a contract’s code is compiled to the EVM bytecode and only then it can be executed in the EVM.

Application Binary Interface (ABI) is the standard way to interact with contracts in the Ethereum ecosystem, both from outside the blockchain and for contract-to-contract interaction. An account wishing to use a smart contract’s function uses the ABI to hash the function definition so it can create the EVM bytecode required to call the function.

In this post, I’ll describe how a function and its parameters are encoded to ABI format and how ABI encoding/decoding can be implemented in Elixir.

### Specification

Let’s provide formal definition excerpts from the official ABI specification.

#### Function selector encoding

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-256 (SHA-3) hash of the signature of the function.

#### Argument encoding

Starting from the fifth byte, the encoded arguments follow.

Types can be static and dynamic. Dynamic types are:

`bytes`

`string`

`T[]`

for any`T`

`T[k]`

for any dynamic`T`

and any`k >= 0`

`(T1,...,Tk)`

if Ti is dynamic for some`1 <= i <= k`

Examples of static types:

`uint<M>`

: unsigned integer type of`M`

bits,`0 < M <= 256`

,`M % 8 == 0`

. e.g.`uint32`

,`uint8`

,`uint256`

.`bool`

: equivalent to`uint8`

restricted to the values`0`

and`1`

. For computing the function selector,`bool`

is used`address`

: equivalent to`uint160`

, except for the assumed interpretation and language typing. For computing the function selector,`address`

is used.`function`

: an address (20 bytes) followed by a function selector (4 bytes). Encoded identical to bytes24.

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)) tail(X(1)) ... tail(X(k))`

where`X = (X(1), ..., X(k))`

and`head`

and`tail`

are defined for`Ti`

being a static type as`head(X(i)) = enc(X(i))`

and`tail(X(i)) = ""`

(the empty string) and as`head(X(i)) = enc(len(head(X(1)) ... head(X(k)) tail(X(1)) ... tail(X(i-1)) ))`

`tail(X(i)) = enc(X(i))`

otherwise, i.e. if Ti is a dynamic type.

Let’s give examples of a couple of type encodings:

`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.`bool`

: as in the`uint8`

case, where 1 is used for true and 0 for false`address`

: as in the uint160 case`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.

#### Function Selector and Argument Encoding

A call to the function `f`

with parameters `a_1`

, …, `a_n`

is encoded as `function_selector(f) enc((a_1, ..., a_n))`

and the return values `v_1`

, …, `v_k`

of f are encoded as `enc((v_1, ..., v_k))`

i.e. the values are combined into a tuple and encoded.

### Elixir implementation

Let’s see how the ABI encoding can be implemented in Elixir. Decoding is done in reverse order.

#### Encoding

As described in the specification we should concatenate a function selector encoding and a parameters encoding.

```
def encode(data, %ABI.FunctionSelector{types: types} = function_selector) do
# calculates parameter data encoding base on function selector's types
{result, []} = encode_type({:tuple, types}, [List.to_tuple(data)])
# concatenates function selector encoding and paramer encoding
encode_method_id(function_selector) <> result
end
```

We calculate a function selector encoding as the first (left, high-order in big-endian) four bytes of the Keccak-256 (SHA-3) hash of the signature of the function.

```
defp encode_method_id(function_selector) do
# Encode selector e.g. "baz(uint32,bool)" and take keccak
kec =
function_selector
|> ABI.FunctionSelector.encode()
|> ExthCrypto.Hash.Keccak.kec()
# Take first four bytes
<<init::binary-size(4), _rest::binary>> = kec
# That's our method id
init
end
```

Here comes the hard part. We should traverse all parameters and encode them based on their type:

- If the type is dynamic we have to encode its size and append it to the head and add the element’s encoding to the tail.
- If the type is static we have to append its encoding to the head.

```
defp encode_type({:tuple, types}, [data | rest]) do
# all head items are 32 bytes in length and there will be exactly
# `count(types)` of them, so the tail starts at `32 * count(types)`.
tail_start = (types |> Enum.count()) * 32
{head, tail, [], _} =
Enum.reduce(types, {<<>>, <<>>, data |> Tuple.to_list(), tail_start}, fn type,
{head, tail, data,
tail_position} ->
{el, rest} = encode_type(type, data)
if ABI.FunctionSelector.is_dynamic?(type) do
# If we're a dynamic type, just encoded the length to head and the element to body
{head <> encode_uint(tail_position, 256), tail <> el, rest, tail_position + byte_size(el)}
else
# If we're a static type, simply encode the el to the head
{head <> el, tail, rest, tail_position}
end
end)
{head <> tail, rest}
end
```

We can use neat Elixir pattern matching to determine if a type is dynamic or not.

```
defmodule ABI.FunctionSelector do
...
def is_dynamic?(:bytes), do: true
def is_dynamic?(:string), do: true
...
def is_dynamic?(_), do: false
...
end
```

Here’s a couple of examples of data type encodings.

```
...
defp encode_type(:bool, [data | rest]) do
value =
case data do
true -> encode_uint(1, 8)
false -> encode_uint(0, 8)
_ -> raise "Invalid data for bool: #{data}"
end
{value, rest}
end
defp encode_uint(data, size_in_bits) when rem(size_in_bits, 8) == 0 do
size_in_bytes = round(size_in_bits / 8)
bin = maybe_encode_unsigned(data)
if byte_size(bin) > size_in_bytes,
do:
raise(
"Data overflow encoding uint, data `#{data}` cannot fit in #{size_in_bytes * 8} bits"
)
pad(bin, size_in_bytes, :left)
end
...
```

### ex_abi

Complete Elixir implementation is available in `ex_abi`

GitHub repo. In this short overview of ABI, I hope you got a basic understanding of this encoding.

### Acknowledgement

- Geoff Hayes - original
`ex_abi`

contributor `ex_abi`

contributors

### Update 2020

I completely re-wrote the encoder and made significant changes to the decoder, so this post is not up to date with the latest `ex_abi`

version.

## Comments