ABI details

The ABI (Application Binary Interface) is a specification that defines the encoding/decoding of data types and a standard for exposing and invoking methods in a smart contract.

The specification is defined in ARC4.

At a high level, the ABI allows contracts to define an API with rich types and offer an interface description so clients know exactly what the contract is expecting to be passed.

To encode or decode ABI types with the SDKs, see the ABI encoding and decoding documentation.

Note

When constructing Application Call transactions that are expected to encode arguments, using the Atomic Transaction Composer is recommended.

Data Types

Encoding for the data types is specified here.

The data types specified are:

Type	Description
uintN	An N-bit unsigned integer, where 8 <= N <= 512 and N % 8 = 0
byte	An alias for uint8
bool	A boolean value that is restricted to either 0 or 1. When encoded, up to 8 consecutive bool values will be packed into a single byte
ufixedNxM	An N-bit unsigned fixed-point decimal number with precision M, where 8 <= N <= 512, N % 8 = 0, and 0 < M <= 160, which denotes a value v as v / (10^M)
type[N]	A fixed-length array of length N, where N >= 0. type can be any other type
address	Used to represent a 32-byte Algorand address. This is equivalent to byte[32]
type[]	A variable-length array. type can be any other type
string	A variable-length byte array (byte[]) assumed to contain UTF-8 encoded content
(T1,T2,...,TN)	A tuple of the types T1, T2, …, TN, N >= 0
reference type	account, asset, application only for arguments, in which case they are an alias for uint8. See section "Reference Types" below

The encoding and decoding of these types should be handled by the SDKs for calling methods and reading out return values.

Because stack types in the AVM are limited to uint64 and bytes, a smart contract may rely on ABI types defined in PyTeal to encode or decode the data passed in the application args.

Reference Types

Reference types may be specified in the method signature referring to some transaction parameters that must be passed. The value encoded is a uint8 reference to the index of element in the relevant array (i.e. for account, the index in the foreign accounts array).

Methods

Methods may be exposed by the smart contract and called by submitting an ApplicationCall transaction to the existing application id.

A method signature is defined as a name, argument types, and return type. The stringified version is then hashed and the first 4 bytes are taken as a method selector.

For example:

A method signature for an add method that takes 2 uint64s and returns 1 uint128:

Method signature: add(uint64,uint64)uint128

The string version of the method signature is hashed and the first 4 bytes are its method selector:

SHA-512/256 hash (in hex): 8aa3b61f0f1965c3a1cbfa91d46b24e54c67270184ff89dc114e877b1753254a
Method selector (in hex): 8aa3b61f

Once the method selector is known, it is used in the smart contract logic to route to the appropriate logic that implements the add method.

The method pseudo-opcode can be used in a contract to do the above work and produce a method selector given the method signature string.

method "add(uint64,uint64)uint128"

Implementing a method

Implementing a method is done by handling an ApplicationCall transaction where the first element matches its method selector and the subsequent elements are used by the logic in the method body.

The initial handling logic of the contract should route to the correct method given a match against the method selector passed and the known method selector of the application method.

The return value of the method must be logged with the prefix 151f7c75 which is the result of sha256("return")[:4]. Only the last logged element with this prefix is considered the return value of this method call.

API

The API of a smart contract can be published as an interface description object. A user may read this object and instantiate a client that handles the encoding/decoding of the arguments and returns values using one of the SDKs.

A full example of a contract json file might look like:

{
    "name":"super-awesome-contract",
    "networks":{
        "MainNet":{
            "appID": 123456
        }
    },
    "methods":[
        {
            "name":"add",
            "desc":"Add 2 integers",
            "args":[ { "type":"uint64" }, { "type":"uint64" } ],
            "returns": {"type":"uint64"}
        },
        {
            "name":"sub",
            "desc":"Subtract 2 integers",
            "args":[ { "type":"uint64" }, { "type":"uint64" } ],
            "returns": {"type":"uint64"}
        },
        {
            "name":"mul",
            "desc":"Multiply 2 integers",
            "args":[ { "type":"uint64" }, { "type":"uint64" } ],
            "returns": {"type":"uint64"}
        },
        {
            "name":"div",
            "desc":"Divide 2 integers, throw away the remainder",
            "args":[ { "type":"uint64" }, { "type":"uint64" } ],
            "returns": {"type":"uint64"}
        },
        {
            "name":"qrem",
            "desc":"Divide 2 integers, return both the quotient and remainder",
            "args":[ { "type":"uint64" }, { "type":"uint64" } ],
            "returns": {"type":"(uint64,uint64)"}
        },
        {
            "name":"reverse",
            "desc":"Reverses a string",
            "args":[ { "type":"string" } ],
            "returns": {"type":"string"}
        },
        {
            "name":"txntest",
            "desc":"just check it",
            "args":[{"type":"uint64"}, {"type": "pay"}, {"type":"uint64"}],
            "returns":{"type": "uint64"}
        },
        {
            "name":"concat_strings",
            "desc":"concat some strings",
            "args":[{"type":"string[]"}],
            "returns":{"type": "string"}
        },
        {
            "name":"manyargs",
            "desc":"Try to send 20 arguments",
            "args":[
                {"type":"uint64"}, {"type": "uint64"}, {"type":"uint64"},{"type":"uint64"},
                {"type":"uint64"}, {"type": "uint64"}, {"type":"uint64"},{"type":"uint64"},
                {"type":"uint64"}, {"type": "uint64"}, {"type":"uint64"},{"type":"uint64"},
                {"type":"uint64"}, {"type": "uint64"}, {"type":"uint64"},{"type":"uint64"},
                {"type":"uint64"}, {"type": "uint64"}, {"type":"uint64"},{"type":"uint64"}
            ],
            "returns":{"type": "uint64"}
        },
        {
            "name":"min_bal",
            "desc":"Get the minimum balance for given account",
            "args":[
                {"type":"account"}
            ],
            "returns":{"type":"uint64"}
        },
        {
            "name":"tupler",
            "desc":"",
            "args":[
                {"type":"(string,uint64,string)"}
            ],
            "returns":{"type":"uint64"}
        }
    ]
}