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

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

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

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

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

  • messagebroker_subscribe_on_request.proto - файл, содержащий поля с параметрами запроса;

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

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

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

startFrom - момент начала отслеживания событий:

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

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

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

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

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

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

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

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

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

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

После успешной отправки запроса на 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-токен.

Смотрите также