TokenTransfer

A Token Transfer is created for each transfer of value that happens under a token pool.

The transfers form an off-chain audit history (an "index") of the transactions that have been performed on the blockchain.

This historical information cannot be queried directly from the blockchain for most token implementations, because it is inefficient to use the blockchain to store complex data structures like this. So the blockchain simply emits events when state changes, and if you want to be able to query this historical information you need to track it in your own off-chain database.

Hyperledger FireFly maintains this index automatically for all Token Pools that are configured.

FireFly initiated vs. non-FireFly initiated transfers¶

There is no requirement at all to use FireFly to initiate transfers in Token Pools that Hyperledger FireFly is aware of. FireFly will listen to and update its audit history and balances for all transfers, regardless of whether they were initiated using a FireFly Supernode or not.

So you could for example use Metamask to initiate a transfer directly against an ERC-20/ERC-721 contract directly on your blockchain, and you will see it appear as a transfer. Or initiate a transfer on-chain via another Smart Contract, such as a Hashed Timelock Contract (HTLC) releasing funds held in digital escrow.

Message coordinated transfers¶

One special feature enabled when using FireFly to initiate transfers, is to coordinate an off-chain data transfer (private or broadcast) with the on-chain transfer of value. This is a powerful tool to allow transfers to have rich metadata associated that is too sensitive (or too large) to include on the blockchain itself.

These transfers have a message associated with them, and require a compatible Token Connector and on-chain Smart Contract that allows a data payload to be included as part of the transfer, and to be emitted as part of the transfer event.

Examples of how to do this are included in the ERC-20, ERC-721 and ERC-1155 Token Connector sample smart contracts.

Transfer types¶

There are three primary types of transfer:

Mint - new tokens come into existence, increasing the total supply of tokens within the pool. The from address will be unset for these transfer types.
Burn - existing tokens are taken out of circulation. The to address will be unset for these transfer types.
Transfer - tokens move from ownership by one account, to another account. The from and to addresses are both set for these type of transfers.

Note that the key that signed the Transfer transaction might be different to the from account that is the owner of the tokens before the transfer.

The Approval resource is used to track which signing accounts (other than the owner) have approval to transfer tokens on the owner's behalf.

Example¶

{
    "type": "transfer",
    "pool": "1244ecbe-5862-41c3-99ec-4666a18b9dd5",
    "uri": "firefly://token/1",
    "connector": "erc20_erc721",
    "namespace": "ns1",
    "key": "0x55860105D6A675dBE6e4d83F67b834377Ba677AD",
    "from": "0x55860105D6A675dBE6e4d83F67b834377Ba677AD",
    "to": "0x55860105D6A675dBE6e4d83F67b834377Ba677AD",
    "amount": "1000000000000000000",
    "protocolId": "000000000041/000000/000000",
    "message": "780b9b90-e3b0-4510-afac-b4b1f2940b36",
    "messageHash": "780204e634364c42779920eddc8d9fecccb33e3607eeac9f53abd1b31184ae4e",
    "created": "2022-05-16T01:23:15Z",
    "tx": {
        "type": "token_transfer",
        "id": "62767ca8-99f9-439c-9deb-d80c6672c158"
    },
    "blockchainEvent": "b57fcaa2-156e-4c3f-9b0b-ddec9ee25933"
}

Field Descriptions¶

Field Name	Description	Type
`type`	The type of transfer such as mint/burn/transfer	`FFEnum`: `"mint"` `"burn"` `"transfer"`
`localId`	The UUID of this token transfer, in the local FireFly node	`UUID`
`pool`	The UUID the token pool this transfer applies to	`UUID`
`tokenIndex`	The index of the token within the pool that this transfer applies to	`string`
`uri`	The URI of the token this transfer applies to	`string`
`connector`	The name of the token connector, as specified in the FireFly core configuration file. Required on input when there are more than one token connectors configured	`string`
`namespace`	The namespace for the transfer, which must match the namespace of the token pool	`string`
`key`	The blockchain signing key for the transfer. On input defaults to the first signing key of the organization that operates the node	`string`
`from`	The source account for the transfer. On input defaults to the value of 'key'	`string`
`to`	The target account for the transfer. On input defaults to the value of 'key'	`string`
`amount`	The amount for the transfer. For non-fungible tokens will always be 1. For fungible tokens, the number of decimals for the token pool should be considered when inputting the amount. For example, with 18 decimals a fractional balance of 10.234 will be specified as 10,234,000,000,000,000,000	`FFBigInt`
`protocolId`	An alphanumerically sortable string that represents this event uniquely with respect to the blockchain	`string`
`message`	The UUID of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector	`UUID`
`messageHash`	The hash of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector	`Bytes32`
`created`	The creation time of the transfer	`FFTime`
`tx`	If submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data)	`TransactionRef`
`blockchainEvent`	The UUID of the blockchain event	`UUID`
`config`	Input only field, with token connector specific configuration of the transfer. See your chosen token connector documentation for details	`JSONObject`

TransactionRef¶

Field Name	Description	Type
`type`	The type of the FireFly transaction	`FFEnum`:
`id`	The UUID of the FireFly transaction	`UUID`