Link Search Menu Expand Document


Table of contents

  1. BlockchainEvent
    1. Protocol ID
    2. Example
    3. Field Descriptions
  2. BlockchainTransactionRef


Blockchain Events are detected by the blockchain plugin:

  1. When a ContractListener has been configured against any custom smart contract through the FireFly API
  2. Indirectly via a Token Connector, which understands the correct events to listen to for a Token Pool configured against a standard such as ERC-20/ERC-721/ERC-1155
  3. Automatically by FireFly core, for the BatchPin contract that can be used for high throughput batched pinning of off-chain data transfers to the blockchain (complementary to using your own smart contracts).

Protocol ID

Each Blockchain Event (once final) exists in an absolute location somewhere in the transaction history of the blockchain. A particular slot, in a particular block.

How to describe that position contains blockchain specifics - depending on how a particular blockchain represents transactions, blocks and events (or “logs”).

So FireFly is flexible with a string protocolId in the core object to represent this location, and then there is a convention that is adopted by the blockchain plugins to try and create some consistency.

An example protocolId string is: 000000000041/000020/000003

  • 000000000041 - this is the block number
  • 000020 - this is the transaction index within that block
  • 000003 - this is the event (/log) index within that transaction

The string is alphanumerically sortable as a plain string;

Sufficient zero padding is included at each layer to support future expansion without creating a string that would no longer sort correctly.


    "id": "e9bc4735-a332-4071-9975-b1066e51ab8b",
    "source": "ethereum",
    "namespace": "ns1",
    "name": "MyEvent",
    "listener": "c29b4595-03c2-411a-89e3-8b7f27ef17bb",
    "protocolId": "000000000048/000000/000000",
    "output": {
        "addr1": "0x55860105d6a675dbe6e4d83f67b834377ba677ad",
        "value2": "42"
    "info": {
        "address": "0x57A9bE18CCB50D06B7567012AaF6031D669BBcAA",
        "blockHash": "0xae7382ef2573553f517913b927d8b9691ada8d617266b8b16f74bb37aa78cae8",
        "blockNumber": "48",
        "logIndex": "0",
        "signature": "Changed(address,uint256)",
        "subId": "sb-e4d5efcd-2eba-4ed1-43e8-24831353fffc",
        "timestamp": "1653048837",
        "transactionHash": "0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d",
        "transactionIndex": "0x0"
    "timestamp": "2022-05-16T01:23:15Z",
    "tx": {
        "blockchainId": "0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d"

Field Descriptions

Field Name Description Type
id The UUID assigned to the event by FireFly UUID
source The blockchain plugin or token service that detected the event string
namespace The namespace of the listener that detected this blockchain event string
name The name of the event in the blockchain smart contract string
listener The UUID of the listener that detected this event, or nil for built-in events in the system namespace UUID
protocolId An alphanumerically sortable string that represents this event uniquely on the blockchain (convention for plugins is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) string
output The data output by the event, parsed to JSON according to the interface of the smart contract JSONObject
info Detailed blockchain specific information about the event, as generated by the blockchain connector JSONObject
timestamp The time allocated to this event by the blockchain. This is the block timestamp for most blockchain connectors FFTime
tx If this blockchain event is coorelated to FireFly transaction such as a FireFly submitted token transfer, this field is set to the UUID of the FireFly transaction BlockchainTransactionRef


Field Name Description Type
type The type of the FireFly transaction FFEnum:
id The UUID of the FireFly transaction UUID
blockchainId The blockchain transaction ID, in the format specific to the blockchain involved in the transaction. Not all FireFly transactions include a blockchain string