Установка и использование платформы
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-интерфейс будут приходить данные следующих групп событий:
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-токен.