Link Search Menu Expand Document


Table of contents

  1. Event
    1. Sequence
    2. Reference
    3. Correlator
    4. Topic
    5. Transaction
    6. Reference, Topic and Correlator by Event Type
    7. Example
    8. Field Descriptions


Every Event emitted by FireFly shares a common structure.

See Events for a reference for how the overall event bus in Hyperledger FireFly operates, and descriptions of all the sub-categories of events.


A local sequence number is assigned to each event, and you can use an API to query events using this sequence number in exactly the same order that they are delivered to your application.


Events have a reference to the UUID of an object that is the subject of the event, such as a detailed Blockchain Event, or an off-chain Message.

When events are delivered to your application, the reference field is automatically retrieved and included in the JSON payload that is delivered to your application.

You can use the ?fetchreferences query parameter on API calls to request the same in-line JSON payload be included in query results.

The type of the reference also determines what subscription filters apply when performing server-side filters.

Here is the mapping between event types, and the object that you find in the reference field.


For some event types, there is a secondary reference to an object that is associated with the event. This is set in a correlator field on the Event, but is not automatically fetched. This field is primarily used for the confirm option on API calls to allow FireFly to determine when a request has succeeded/failed.


Events have a topic, and how that topic is determined is specific to the type of event. This is intended to be a property you would use to filter events to your application, or query all historical events associated with a given business data stream.

For example when you send a Message, you set the topics you want that message to apply to, and FireFly ensures a consistent global order between all parties that receive that message.


When actions are submitted by a FireFly node, they are performed within a FireFly Transaction. The events that occur as a direct result of that transaction, are tagged with the transaction ID so that they can be grouped together.

This construct is a distinct higher level construct than a Blockchain transaction, that groups together a number of operations/events that might be on-chain or off-chain. In some cases, such as unpinned off-chain data transfer, a FireFly transaction can exist when there is no blockchain transaction at all. Wherever possible you will find that FireFly tags the FireFly transaction with any associated Blockchain transaction(s).

Note that some events cannot be tagged with a Transaction ID:

  • Blockchain events, unless they were part of a batch-pin transaction for transfer of a message
  • Token transfers/approvals, unless they had a message transfer associated with them (and included a data payload in the event they emitted)

Reference, Topic and Correlator by Event Type

Types Reference Topic Correlator
transaction_submitted Transaction transaction.type  
Message message.header.topics[i]* message.header.cid
token_pool_confirmed TokenPool  
token_pool_op_failed Operation
token_transfer_confirmed TokenTransfer  
token_transfer_op_failed Operation tokenTransfer.localId
token_approval_confirmed TokenApproval  
token_approval_op_failed Operation tokenApproval.localId
namespace_confirmed Namespace "ff_definition"  
datatype_confirmed Datatype "ff_definition"  
Identity "ff_definition"  
contract_interface_confirmed FFI "ff_definition"  
contract_api_confirmed ContractAPI "ff_definition"  
blockchain_event_received BlockchainEvent From listener **  
blockchain_invoke_op_succeeded Operation    
blockchain_invoke_op_failed Operation    
blockchain_contract_deploy_op_succeeded Operation    
blockchain_contract_deploy_op_failed Operation    
  • A separate event is emitted for each topic associated with a Message.

** The topic for a blockchain event is inherited from the blockchain listener, allowing you to create multiple blockchain listeners that all deliver messages to your application on a single FireFly topic.


    "id": "5f875824-b36b-4559-9791-a57a2e2b30dd",
    "sequence": 168,
    "type": "transaction_submitted",
    "namespace": "ns1",
    "reference": "0d12aa75-5ed8-48a7-8b54-45274c6edcb1",
    "tx": "0d12aa75-5ed8-48a7-8b54-45274c6edcb1",
    "topic": "batch_pin",
    "created": "2022-05-16T01:23:15Z"

Field Descriptions

Field Name Description Type
id The UUID assigned to this event by your local FireFly node UUID
sequence A sequence indicating the order in which events are delivered to your application. Assure to be unique per event in your local FireFly database (unlike the created timestamp) int64
type All interesting activity in FireFly is emitted as a FireFly event, of a given type. The ‘type’ combined with the ‘reference’ can be used to determine how to process the event within your application FFEnum:
namespace The namespace of the event. Your application must subscribe to events within a namespace string
reference The UUID of an resource that is the subject of this event. The event type determines what type of resource is referenced, and whether this field might be unset UUID
correlator For message events, this is the ‘header.cid’ field from the referenced message. For certain other event types, a secondary object is referenced such as a token pool UUID
tx The UUID of a transaction that is event is part of. Not all events are part of a transaction UUID
topic A stream of information this event relates to. For message confirmation events, a separate event is emitted for each topic in the message. For blockchain events, the listener specifies the topic. Rules exist for how the topic is set for other event types string
created The time the event was emitted. Not guaranteed to be unique, or to increase between events in the same order as the final sequence events are delivered to your application. As such, the ‘sequence’ field should be used instead of the ‘created’ field for querying events in the exact order they are delivered to applications FFTime