HL Fabric Events and Subscriptions

The Hyperledger Fabric framework internally implements an event engine. There are three event types to subscribe to.

1. A chaincode (contract) event is emitted explicitly from a chaincode. A chaincode developer can customize the event data making this type of event very flexible.

2. A transaction (commit) event is emitted automatically when a certain transaction is committed to a ledger.

3. A block event is emitted automatically when a block is committed to a ledger. Note that there can be multiple transactions in a block, so you can get multiple transaction events for a single block event.

A client application may use the Hyperledger Fabric Node.js SDK to register a listener to receive blocks as they are added to the channel ledger. This is known as channel-based events, and it allows a client to start receiving blocks from a specific block number, allowing event processing to run normally on blocks that may have been missed. The Hyperledger Fabric Node.js SDK can also assist client applications by processing the incoming blocks and looking for specific transactions or chaincode events. This allows a client application to be notified of transaction completion or arbitrary chaincode events without having to perform multiple queries or search through the blocks as they are received. After a transaction proposal has been successfully endorsed, and before the transaction message has been successfully broadcasted to an orderer, the application should register a listener to be notified of the event when a transaction achieves finality. This happens when the block containing the transaction gets added to peer's ledger/blockchain.

The Hyperledger Fabric committing peers provide an event stream to publish blocks to registered listeners. A block gets published whenever a committing peer adds a validated block to a ledger. There are three ways to register a listener to get notified.

1. Register a block listener to get called for every block event. The listener is passed a fully decoded Block object.

2. Register a transaction (commit) listener to get called when a transaction with a specified ID is committed (i.e., discovered inside a published block). The listener is passed a transaction ID, a transaction status, and a block number.

3. Register a chaincode (contract) event listener to get called when a specific chaincode event has arrived. The listener is passed a chaincode event object, a block number, a transaction ID, and a transaction status.

Listeners can be used to provide channel data to other applications. For example, you can perform different types of analytics or monitor the network based on the block content. Another example can be an e-mail notification system based on chaincode events.

Further in this chapter, we will use terms such as chaincode event/listener and contract event/listener, interchangeably, as well as transaction event/listener and commit event/listener.