Installation and usage of the platform

gRPC: monitoring of blockchain events

The gRPC interface provides the ability to track certain groups of events occurring in the blockchain. Information about the selected groups of events is collected in streams, which are sent to the gRPC interface of the node.

A set of fields for serializing and transmitting blockchain event data are given in the files that are located in the messagebroker directory of the we-proto-x.x.x.zip package:

  • messagebroker_blockchain_events_service.proto – main protobuf file;

  • messagebroker_blockchain_event.proto – a file that contains response fields with event group data and error messages.

To track a specific group of events on the blockchain, send the SubscribeOn(startFrom, transactionTypeFilter) query that initializes a subscription to the selected event group.

Important

The field data types for the request and response are specified in the protobuf files.

Query parameters:

  • startFrom – the moment when the event tracking starts; the following values are available:

  • CurrentEvent – start tracking from the current event;

  • GenesisBlock – getting all events of the selected group, starting from the genesis block;

  • BlockSignature – the start of tracking from the specified block.

  • transactionTypeFilter – filter output events by transactions that are produced during these events:

  • Any – output events with all types of transactions;

  • Filter – output events with transaction types specified as a list;

  • FilterNot – display events with all transactions except those specified in this parameter as a list.

  • connectionId – optional parameter which can be sent in order to alleviate identification of the request in the node logs.

Together with the SubscribeOnRequest query, authorization data is sent: the JWT token or the api-key passphrase, depending on the authorization method used.

Query examples:

SubscribeOn:

Send messages starting from the first block:

{"genesis_block": {}}

Send messages starting from the current moment:

{"current_event": {}}

Send messages starting from the block spacified:

{
   "block_signature": {
        "last_block_signature": {
            "value": "G4gTl/5fA2g2YAFCjCGu+tXJVqvQCLNM8CxzT6Nfc3KSRg3egAY8Mb4df5tufIf9Tv2xfCPQQ5m7X4MoPBvnBg=="
        }
   }
}

Note

Various information about blocks can also be obtained using the REST methods of the blocks group.

Information about events

After a successful request is sent to the gRPC interface, the following groups of events will receive data:

  1. MicroBlockAppended – successful microblock mining:

  • transactions – full transaction bodies from the received microblock.

  1. BlockAppended – successful completion of a mining round with a block formation:

  • block_signature – signature of an obtained block;

  • reference – signature of a previous block;

  • tx_ids – list of transaction IDs from the received block;

  • miner_address – miner address;

  • height – height at which the resulting block is located;

  • version – version of the block;

  • timestamp – time of block formation;

  • fee – total fee amount for transactions within the block;

  • block_size – size of a block (in bytes);

  • features – list of blockchain soft-forks that the miner voted for during the round.

  1. RollbackCompleted – block rollback:

  • return_to_block_signature – signature of the block to which the rollback occurred;

  • rollback_tx_ids – list of IDs of transactions that will be deleted from the blockchain.

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

Response data:

  • signature – block signature;

  • reference – signature of a previous block;

  • transactions – full transaction bodies from the microblock;

  • miner_address – miner address;

  • height – height at which the resulting block is located;

  • version – version of the block;

  • timestamp – time of block formation;

  • fee – total fee amount for transactions within the block;

  • block_size – size of a block (in bytes);

  • features – list of blockchain soft-forks that the miner voted for during the round.

Information about errors

The ErrorEvent message with the following error options is provided to display information about errors during blockchain event tracking:

  • GenericError – a general or unknown error with the message text;

  • MissingRequiredRequestField – the required field is not filled in when forming a SubscribeOnRequest query;

  • BlockSignatureNotFoundError – the signature of the requested block is missing in the blockchain;

  • MissingAuthorizationMetadata – no authorization data was entered when forming the SubscribeOn query;

  • InvalidApiKey – wrong passphrase when authorizing by api-key;

  • InvalidToken – wrong JWT-token when authorizing by OAuth.

See also