BlockchainEvent

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 block

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.

Example

{
    "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

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