Как устроена платформа

Сервисы gRPC, используемые смарт-контрактом

Общие указания по применению gRPC при разработке смарт-контрактов рассмотрены в статье Пример смарт-контракта с использованием gRPC.

Версии API смарт-контрактов

gRPC-методы, используемые смарт-контрактами, формируют API, заданное protobuf-файлами. Для четкого определения новых методов и внесения изменений в уже существующие предусмотрено версионирование API. Благодаря присвоенному номеру версии, нода при исполнении смарт-контракта определяет соответствующий набор методов для использования.

Актуальная версия gRPC API для версии блокчейн-платформы содержится в файле api_version.proto. Смарт-контракты, которые требуют версию API выше, чем у майнящей ноды, игнорируются при майнинге.

Для создания и обновления смарт-контрактов предусмотрены поля apiVersion в транзакциях 103 CreateContract Transaction и 107 UpdateContract Transaction версии 4. Эти поля указывают майнящей ноде на версию API, используемую смарт-контарктом.

В таблице ниже приведены версии API, соответствующие версиям блокчейн-платформы:

Версия API

Версия платформы

1.0

1.6.0 и старше

1.1

1.6.2

Protobuf-файлы методов

Смарт-контрактам, использующим gRPC для обмена даными с нодой, доступны сервисы, названия protobuf-файлов которых начинаются с contract:

contract_address_service.proto

Набор методов, предназначенных для получения адресов участников из keystore ноды и получения данных, записанных на адресе.

``GetAddresses`` - метод для получения всех адресов участников, ключевые пары которых хранятся в keystore ноды. В ответе метода массив строк addresses.

``GetAddressData`` - метод для получения всех данных, записанных на аккаунт адресата при помощи транзакций 12. В запросе метода вводятся следующие параметры:

  • address - адрес, данные которого необходимо вывести;

  • limit - ограничение количества выводимых блоков данных;

  • offset - количество блоков данных для пропуска в выводе.

В ответе метода выводится массив DataEntry, содержащий записанные данные адреса.

``GetAssetBalance`` - метод для получения текущего баланса определенного ассета для определенного пользователя смарт-контракта. В запросе метода вводятся следующие параметры:

  • address - адрес, баланс которого необходимо вывести;

  • assetId - идентификатор ассета. Для WEST параметр остается пустым.

contract_contract_service.proto

Набор методов, предназначенный для работы со смарт-контрактами.

``Connect`` - метод для подключения смарт-контракта к ноде. В запросе метода указываются следующие параметры:

``CommitExecutionSuccess`` - метод для получения результата успешного исполнения контракта по его идентификатору и отправки результатов на ноду.

``CommitExecutionError`` - метод для получения ошибки, возникшей при исполнении смарт-контракта, по его идентификатору и отправки содержания ошибки на ноду.

``GetContractKeys`` - метод для получения результата исполнения смарт-контракта по его идентификатору. В запросе метода указываются следующие данные:

  • contract_id - идентификатор смарт-контракта;

  • limit - ограничение количества выводимых блоков данных;

  • offset - количество блоков данных для пропуска в выводе;

  • matches - опциональный параметр для составления регулярного выражения, по которому фильтруются ключи.

В ответе метода выводится массив Entries, содержащий результаты исполнения смарт-контракта.

``GetContractKey`` - метод для получения определенного результата исполнения смарт-контракта по его ключу. В запросе метода указываются следующие данные:

  • contract_id - идентификатор смарт-контракта;

  • key - запрашиваемый ключ.

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

contract_crypto_service.proto

Набор методов для шифрования и дешифровки. Подробнее см. статью gRPC: реализация методов шифрования.

contract_permission_service.proto

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

``GetPermissions`` - метод для получения списка всех ролей указанного адреса, действительных на момент отправки запроса. В запросе передаются следующие данные:

  • address - запрашиваемый адрес;

  • timestamp - временная метка в формате Unix Timestamp (в миллисекундах), на момент которой запрашиваются действующие роли.

В ответе метода выводится массив roles, содержащий роли запрашиваемого адреса, и указанная временная метка timestamp.

``GetPermissionsForAddresses`` - метод для получения списка всех ролей нескольких адресов, действительных на момент отправки запроса. В запросе передаются следующие данные:

  • addresses - массив строк с запрашиваемыми адресами;

  • timestamp - временная метка в формате Unix Timestamp (в миллисекундах), на момент которой запрашиваются действующие роли.

В ответе метода выводится массив address_to_roles, содержащий роли для каждого запрашиваемого адреса, и указанная временная метка timestamp.

contract_pki_service.proto

Набор методов, предназначенный для формирования и проверки электронных подписей для данных. Подробнее см. статью gRPC: формирование и проверка электронной подписи данных (PKI).

contract_privacy_service.proto

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

Подробнее об обмене конфиденциальными данными и группах доступа см. статью Обмен конфиденциальными данными.

``GetPolicyRecipients`` - метод для получения адресов участников группы доступа к конфиденциальным данным, идентификатор которой передается в запросе как policy_id. В ответе метода выводится массив строк recipients, содержащий адреса участников группы доступа.

``GetPolicyOwners`` - метод для получения адресов владельцев группы для обмена конфиденциальными данными, идентификатор которой передается в запросе как policy_id. В ответе метода выводится массив строк owners, содержащий адреса владельцев группы доступа.

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

В запросе метода указываются идентификатор группы доступа policy_id и идентификационных хэш конфиденциальных данных item_hash. В ответе метода возвращается строка data, содержащая хэш пакета конфиденциальных данных.

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

В запросе метода указываются идентификатор группы доступа policy_id и идентификационных хэш конфиденциальных данных item_hash. В ответе метода возвращаются следующие данные:

  • sender - адрес отправителя конфиденциальных данных;

  • policy_id - идентификатор группы доступа;

  • type - тип конфиденциальных данных (file);

  • info - массив данных о файле: * filename - имя файла; * size - размер файла; * timestamp - временная метка размещения файла в формате Unix Timestamp (в миллисекундах); * author - автор файла; * comment - опциональный комментарий к файлу;

  • hash - идентификационный хэш конфиденциальных данных.

contract_transaction_service.proto

Набор методов, предназначенный для получения информации о транзакциях, отправленных в блокчейн. Подробнее см. статью gRPC: получение информации о транзакции по ее ID.

contract_util_service.proto

Файл содержит метод ``GetNodeTime``, предназначенный для получения текущего времени ноды. Метод возвращает текущее время ноды в двух форматах:

  • system - системное время на машине ноды;

  • ntp - сетевое время.