Установка и использование платформы
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-интерфейс будут приходить данные следующих групп событий:
MicroBlockAppended – успешный майнинг микроблока:
transactions
– полные тела транзакций из полученного микроблока.
BlockAppended – успешное завершение раунда майнинга с формированием блока:
block_signature
– подпись полученного блока;reference
– подпись предыдущего блока;tx_ids
– список ID транзакций из полученного блока;miner_address
– адрес майнера;height
– высота, на которой расположен полученный блок;version
– версия блока;timestamp
– время формирования блока;fee
– сумма комиссий за транзакции внутри блока;block_size
– размер блока (в байтах);features
– список изменений блокчейна, за которые голосовал майнер в ходе раунда.
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-токен.