Guidelines

ABI

What is ABI

ABI stands for Application Binary Interface. It is an interface file that describes the data exchange format between a smart contract and an upper-layer application. The ABI file format is similar to JSON and is easily readable, facilitating the collaboration between smart contract engineers and upper-layer application engineers.

The smart contract ABI file consists of five parts:

1
2
3
4
5
6
7
{
    "version": "eosio::abi/1.0",//Definition of ABI version number
    "types":[...],              //Definition of type aliases
    "structs":[...],            //Data structures for various types
    "actions":[...],            //action of the smart contract
    "tables":[...]            //Data structures for struct types
}

We will explore the development approach for DMC smart contract ABI in the following order: actions, tables, structs, and types. actions -> tables -> structs -> types

ABI development

actions

The purpose of the action section is to declare which actions can be called in the smart contract. Here is an example:

1
2
3
4
5
"actions": [{
    "name": "hi",
    "type": "hi",
    "ricardian_contract": ""
}]

In each item, the name represents the name of the action, the type is used to look up the data structure in structs, and ricardian_contract refers to the Ricardian contract.

A Ricardian contract is a special structured text used to explicitly define the intentions of both parties in a transaction. On DMC, every action you send can be accompanied by a contract. This contract has a specific format that can be read by programs and is also human-readable. This type of contract is called a Ricardian contract.

Note: Currently, the naming convention for names in actions is limited to the following constraints: only supports digits 1 to 5 and lowercase English letters, and the maximum character length is 12.

If there are any changes in the future, we will promptly update the documentation.

tables

The tables section lists the names of the data tables that need to be created in the smart contract, along with the names of the structs stored in each data table.

1
2
3
4
5
6
7
"tables": [{
    "name": "players",
    "type": "player",
    "index_type": "i64",
    "key_names": ["id"],
    "key_types": ["int64"]
}]

The above code constructs a data table named “players” with a struct type “player”. The primary key of the table is named “id” and has a type of “int64”.

structs

The content in the structs section corresponds to the content in the actions section. In the previous actions section, we declared the names of actions, and now we need to declare the parameters required for each action in the structs section. It is shown below.

1
2
3
4
5
6
7
8
"structs":  [{
    "name": "shape",
    "base": "",
    "fields": [{
        "name": "area",
        "type": "flout64"
    }]
}]
1
2
3
4
5
6
7
8
"structs":  [{
    "name": "colorshape",
    "base": "shape",
    "fields": [{
        "name": "color",
        "type": "int64"
    }]
}]

Inheriting through the base field is equivalent to:

1
2
3
4
5
6
7
8
9
10
11
"structs":  [{
    "name": "colorshape",
    "base": "",
    "fields": [{
        "name": "area",
        "type": "flout64"
    },{
        "name": "color",
        "type": "int64"
    }]
}]

DMC system will search for the corresponding data structure in the structs section based on the type declared in the actions section. Each data structure in the structs section lists the names and types of each parameter in its fields.

In addition to the items in the actions section, detailed data structures also need to be listed in the structs section for the items in the tables section.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
"structs": [{
    "name": "player",
    "base": "",
    "fields": [{
        "name": "nickname",
        "type": "my_account_name"
    }, {
        "name": "age",
        "type": "int32"
    }]
}, {
    "name": "hi",
    "base": "",
    "fields": [{
        "name": "nickname",
        "type": "my_account_name"
    }]
}]

In this way, in the structs section, we have defined a struct named player that lists the two fields nickname and age for the player table. The types of these fields are my_account_name and int32, respectively.

types

types is used to define custom data types:

1
2
3
4
{
    "new_type_name": "my_account_name",
    "type": "name"
}

In this ABI file, we have defined a custom data type named my_account_name of type name using the new_type_name and type keywords. The type name is a system-defined data type.

Conclusion

A complete ABI file has been written.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
    "version": "eosio::abi/1.0",
    "types": [{
        "new_type_name": "my_account_name",
        "type": "name"
    }],
    "structs": [{
        "name": "player",
        "base": "",
        "fields": [{
            "name": "nickname",
            "type": "my_account_name"
        }, {
            "name": "age",
            "type": "int32"
        }]
    }, {
        "name": "hi",
        "base": "",
        "fields": [{
            "name": "nickname",
            "type": "my_account_name"
        }]
    }],
    "actions": [{
        "name": "hi",
        "type": "hi",
        "ricardian_contract": ""
    }],
    "tables": [{
        "name": "players",
        "type": "player",
        "index_type": "i64",
        "key_names": ["id"],
        "key_types": ["int64"]
    }] 
};

With this ABI file, we have defined a data table named player with three fields: id, nickname, and age, with types int64, my_account_name, and int32 respectively. The primary key is id. We have also defined an action method named hi that takes a parameter named nickname of type my_account_name.