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

Сервисы 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

1.4

1.7.0

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 – сетевое время.