Tracking of blockchain events via the gRPC interface

The gRPC interface has the ability to track certain groups of events occurring in the blockchain. Events are formed into streams that come to the gRPC interface by subscription. Enabling the gRPC interface and configuring it is done via the configuration file of the node that the interface will listen to. To initialize a subscription, send a SubscribeRequest(startFrom, transactionTypeFilter) which uses the following parameters:

  • startFrom - moment of stream start, possible variants:

    • CurrentEvent - obtaining of events from the node in real time upon occuring,

    • GenesisBlock - obtaining of events from the very first block,

    • BlockSignature - obtaining of events after a stated block.

  • transactionTypeFilter - filtering of transactions that will be obtained inside events, possible variants:

    • Any - all transactions,

    • Filter - events will contain only transaction types stated in the list inside a filter,

    • FilterNot - events will only contain transaction types that are not stated in the list inside a filter.

Authorization metadata including a token or the phrase api-key are sent along with the request. Both authorization options, by api-key and by a token, are supported.

After a successful subscription, the node will start streaming the following events:

  • MicroBlockAppended - mined microblock with parameters:

    • transactions - full bodies of microblock transactions.

  • BlockAppended - mined block with parameters:

    • signature - block signature,

    • reference - previous block signature,

    • tx ids - list of block transaction IDs,

    • miner address - address of a miner,

    • height - block height.

  • RollbackCompleted - blockchain rollback event with parameters:

    • return to block signature - signature of a block, to which a rollback will be performed,

    • rollback tx ids - list of transaction IDs that will be deleted from the blockchain.

  • AppendedBlockHistory - если в запросе на подписку не был выбран параметр CurrentEvent, клиент будет получать данный тип событий до тех пор, пока не дойдет до текущей высоты в блокчейне и тогда переключится на остальные события:

    • signature - block signature,

    • reference - previous block signature,

    • transactions - full bodies of transactions from a block,

    • miner address - address of a miner,

    • height - block height.

  • ErrorEvent - the event informs about errors occured. Types of errors:

    • GenericError - generic or unknown error with a message text,

    • MissingRequiredRequestField - unfilled not compulsory field from the SubscribeRequest,

    • BlockSignatureNotFoundError - signature of a requested block from the SubscribeRequest is not present in the blockchain,

    • MissingAuthorizationMetadata - absence of authorized metadata while sending the SubscribeRequest,

    • InvalidApiKey - invalid api-key phrase in case of the api-key authorization,

    • InvalidToken - invalid token in case of OAuth authorization.