Установка и использование платформы

gRPC: отслеживание событий в блокчейне

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

Набор полей, предназначенный для сериализации и передачи данных о событиях в блокчейне, приведен в файлах, которые находятся в каталоге messagebroker пакета we-proto-x.x.x.zip:

  • messagebroker_blockchain_events_service.proto – основной protobuf-файл;

  • messagebroker_blockchain_event.proto – файл, содержащий поля ответов с данными групп событий и сообщениями об ошибках.

Для отслеживания определенной группы событий в блокчейне отправьте запрос SubscribeOn(startFrom, transactionTypeFilter), который инициализирует подписку на выбранную группу событий.

Важно

Типы данных полей для запросов и ответов указаны в protobuf-файлах.

Параметры запроса:

  • startFrom – момент начала отслеживания событий; доступны следующие значения:

  • CurrentEvent – начало отслеживания от текущего события;

  • GenesisBlock – получение всех событий выбранной группы, начиная от генезис-блока;

  • BlockSignature – начало отслеживания от указанного блока.

  • transactionTypeFilter – фильтрация выводимых событий по транзакциям, которые производятся в ходе этих событий:

  • Any – выводить события со всеми типами транзакций;

  • Filter – выводить события с типами транзакций, указанными в виде списка;

  • FilterNot – выводить события со всеми транзакциями кроме тех, которые указаны в этом параметре в виде списка.

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

Вместе с запросом SubscribeOnRequest отправляются данные авторизации: JWT-токен или ключевая фраза api-key, в зависимости от используемого метода авторизации.

Примеры запроса:

Примечание

Различную информацию о блоках можно получить также при помощи REST методов группы blocks.

Информация о событиях

После успешной отправки запроса на gRPC-интерфейс будут приходить данные следующих групп событий:

  1. MicroBlockAppended – успешный майнинг микроблока:

  • transactions – полные тела транзакций из полученного микроблока.

  1. BlockAppended – успешное завершение раунда майнинга с формированием блока:

  • block_signature – подпись полученного блока;

  • reference – подпись предыдущего блока;

  • tx_ids – список ID транзакций из полученного блока;

  • miner_address – адрес майнера;

  • height – высота, на которой расположен полученный блок;

  • version – версия блока;

  • timestamp – время формирования блока;

  • fee – сумма комиссий за транзакции внутри блока;

  • block_size – размер блока (в байтах);

  • features – список изменений блокчейна, за которые голосовал майнер в ходе раунда.

  1. RollbackCompleted – откат блока:

  • return_to_block_signature – подпись блока, до которого произошел откат;

  • rollback_tx_ids – список ID транзакций, которые будут удалены из блокчейна.

4. AppendedBlockHistory – информация о транзакциях сформированного блока. Данный тип событий поступает на gRPC-интерфейс до достижения текущей высоты блокчейна, если в запросе в качестве отправной точки для получения событий указаны GenesisBlock или BlockSignature. После достижения текущей высоты начинают выводиться текущие события по заданным фильтрам.

Данные ответа:

  • signature – подпись блока;

  • reference – подпись предыдущего блока;

  • transactions – полные тела транзакций из блока;

  • miner address – адрес майнера;

  • height – высота, на которой расположен блок;

  • version – версия блока;

  • timestamp – время формирования блока;

  • fee – сумма комиссий за транзакции внутри блока;

  • block_size – размер блока (в байтах);

  • features – список изменений блокчейна, за которые голосовал майнер в ходе раунда.

Информация об ошибках

Для вывода информации об ошибках в ходе отслеживания событий в блокчейне предусмотрено сообщение ErrorEvent со следующими вариантами ошибок:

  • GenericError – общая или неизвестная ошибка с текстом сообщения;

  • MissingRequiredRequestField – не заполнено обязательное поле при формировании запроса SubscribeOnRequest;

  • BlockSignatureNotFoundError – в блокчейне отсутствует подпись запрошенного блока;

  • MissingAuthorizationMetadata – при формировании запроса SubscribeOn не введены данные авторизации;

  • InvalidApiKey – при авторизации по api-key, неверная ключевая фраза;

  • InvalidToken – при авторизации по OAuth, неверный JWT-токен.