Event

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.

Sequence¶

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.

Reference¶

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.

Correlator¶

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.

Topic¶

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.

Transaction¶

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_confirmed` `message_rejected`	Message	`message.header.topics[i]`*	`message.header.cid`
`token_pool_confirmed`	TokenPool	`tokenPool.id`
`token_pool_op_failed`	Operation	`tokenPool.id`	`tokenPool.id`
`token_transfer_confirmed`	TokenTransfer	`tokenPool.id`
`token_transfer_op_failed`	Operation	`tokenPool.id`	`tokenTransfer.localId`
`token_approval_confirmed`	TokenApproval	`tokenPool.id`
`token_approval_op_failed`	Operation	`tokenPool.id`	`tokenApproval.localId`
`namespace_confirmed`	Namespace	`"ff_definition"`
`datatype_confirmed`	Datatype	`"ff_definition"`
`identity_confirmed` `identity_updated`	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.

Example¶

{
    "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`: `"transaction_submitted"` `"message_confirmed"` `"message_rejected"` `"datatype_confirmed"` `"identity_confirmed"` `"identity_updated"` `"token_pool_confirmed"` `"token_pool_op_failed"` `"token_transfer_confirmed"` `"token_transfer_op_failed"` `"token_approval_confirmed"` `"token_approval_op_failed"` `"contract_interface_confirmed"` `"contract_api_confirmed"` `"blockchain_event_received"` `"blockchain_invoke_op_succeeded"` `"blockchain_invoke_op_failed"` `"blockchain_contract_deploy_op_succeeded"` `"blockchain_contract_deploy_op_failed"`
`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`