4 Создание ABI-файла

Бинарный интерфейс приложения ABI (англ. Application Binary Interface) — это описание в JSON-формате методов преобразования действий пользователя между JSON и двоичным представлениями. ABI также описывает методы для преобразования состояния базы данных в JSON-формат и обратно. После того, как контракт описан через ABI, разработчики и пользователи могут с ним легко взаимодействовать через JSON.

Для создания ABI-файла используется утилита eosio-cpp, размещенная в cyberway.cdt. Иногда для отладки участков программы или анализа различных ситуаций приходится в ручном режиме вносить изменения в уже созданный ABI-файл. Поэтому разработчикам необходимо ознакомиться с его структурой, а также с описанием его отдельных компонентов. Структура ABI-файла имеет следующий вид:

{
   "version": "cyberway::abi/1.1",
   "structs": [],
   "types": [],
   "actions": [],
   “events”: [],
   "tables": [],
   "variants": [],
   “abi_extensions”: []
}

structs — описание структур, которые используются для обработки действий (actions) пользователя. Также структуры могут использоваться для описания полей объектов, которые хранятся в таблицах tables, или полей (параметров) функций в actions.

types — описание пользовательских типов, которые используются в качестве параметров в любом публичном действии (action) пользователя или структуре. Также могут использоваться в публичных действиях или структурах. Как правило, следует описывать свои собственные типы.

actions — описание публичных действий пользователя, объединяет все функции, описанные в заголовочном файле контракта.

events — описание событий, каждое из которых представляет собой реакцию (ответ) контракта на определенное действие (action) пользователя.

tables — описание таблиц, которые используются для обработки действий (actions) пользователя. Таблицы представляют собой контейнеры типа multi_index или eosio::singleton, которые хранят данные в базе данных узла блокчейна. Внутри таблицы находятся объекты structs. Создание, получение, изменение или удаление объектов выполняется в операциях actions.

abi_extensions — описание дополнительных возможностей ABI (резерв, не используется).

Структуры (structs)

Пример описания структуры в ABI-файле:

{
   "name": "issue", // Имя 
   "base": "",         // Наследование, родительская структура
   "fields": []        // Массив объектов поля
}

Пример описания поля структуры в ABI-файле:

{
   "name":"",       // Имя поля 
   "type":""        // Тип поля
}

Пример описания структуры операции create для создания токенов в ABI-файле:

{
  "name": "create",      
  "base": "",           

  "fields": [
    {
      "name":"issuer",      // Создатель токенов
      "type":"name"      
    },
    {
      "name":"maximum_supply", // Максимальное количество токенов типа "asset" 
      "type":"asset"
    }
  ]
}

Типы (types)

Пример описания типа в ABI-файле:

{
   "new_type_name": "name",
   "type": "name"
}

Действия (actions)

Пример описания действия в ABI-файле:

{
  "name": "transfer",     // Имя действия
  "type": "transfer"     // Имя неявно заданной структуры
}

События (events)

Пример описания событий для контракта публикации в ABI-файле:

"events": [
    {"name": "poolstate", "type": "pool_event"},
    {"name": "poolerase", "type": "uint64"},
    {"name": "postcreate","type": "create_event"},
    {"name": "poststate", "type": "post_event"},
    {"name": "postclose", "type": "post_close"},
    {"name": "votestate", "type": "vote_event"}
  ],

Таблицы (tables)

Пример описания таблицы в ABI-файле:

{
    "name": "emitparams",
    "type": "emit_state",
    "indexes" : [{
        "name": "primary",
        "unique": true,
        "orders": [{"field": "id", "order": "asc"}]
    }]
}

Описание векторов

Для описания вектора в ABI-файле необходимо добавить тип с помощью символов []. Таблицы должны быть точно описаны в ABI-файле. Например, в случае использования cleos при добавлении таблицы в контракт с искаженным ABI-описанием возможна потеря данных при отсутствии сообщения об ошибке.

После каждого изменения в контракте структуры, таблицы, действия или события, а также после введения нового типа необходимо обновлять ABI-файл. Во многих случаях сбой, возникающий при обновлении ABI-файла, не приводит к появлению сообщения об ошибке, из-за чего затрудняется анализ работы контракта.