Skip to content

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:

  1. 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.
  2. Burn - existing tokens are taken out of circulation. The to address will be unset for these transfer types.
  3. 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