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

Сервисы 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`` – метод для подключения смарт-контракта к ноде. В запросе метода указываются следующие параметры:

connection_id – идентификатор соединения смарт-контракта (см. Авторизация смарт-контракта с gRPC);
async_factor – максимальное количество одновременно исполняемых транзакций по смарт-контракту (см. Параллельное исполнения смарт-контрактов).

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