fftokens

Table of contents

1. fftokens
   1. Overview
   2. HTTP APIs
      1. POST /createpool
      2. POST /activatepool
      3. POST /checkinterface
      4. POST /mint
      5. POST /burn
      6. POST /transfer
      7. POST /approval
   3. Websocket Events
      1. receipt
      2. token-pool
      3. token-mint
      4. token-burn
      5. token-transfer
      6. token-approval
   4. Response Types
      1. Async Request
      2. Receipt
      3. Token Pool
      4. Token Transfer
      5. Token Approval

Overview

fftokens is a protocol that can be implemented by token connector runtimes in order to be usable by the fftokens plugin in FireFly.

The connector runtime must expose an HTTP and websocket server, along with a minimum set of HTTP APIs and websocket events. Each connector will be strongly coupled to a specific ledger technology and token standard(s), but no assumptions are made in the fftokens spec about what these technologies must be, as long as they can satisfy the basic requirements laid out here.

Note that this is an internal protocol in the FireFly ecosystem - application developers working against FireFly should never need to care about or directly interact with a token connector runtime. The audience for this document is only developers interested in creating new token connectors (or editing/forking existing ones).

Two implementations of this specification have been created to date (both based on common Ethereum token standards) - firefly-tokens-erc1155 and firefly-tokens-erc20-erc721.

HTTP APIs

This is the minimum set of APIs that must be implemented by a conforming token connector. A connector may choose to expose other APIs for its own purposes. All requests and responses to the APIs below are encoded as JSON. The APIs are currently understood to live under a /api/v1 prefix.

POST /createpool

Create a new token pool. The exact meaning of this is flexible - it may mean invoking a contract or contract factory to actually define a new set of tokens via a blockchain transaction, or it may mean indexing a set of tokens that already exists (depending on the options a connector accepts in config).

In a multiparty network, this operation will only be performed by one of the parties, and FireFly will broadcast the result to the others.

FireFly will store a “pending” token pool after a successful creation, but will replace it with a “confirmed” token pool after a successful activation (see below).

Request

{
  "type": "fungible",
  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "name": "FFCoin",
  "symbol": "FFC",
  "data": "pool-metadata",
  "requestId": "1",
  "config": {}
}

Response

HTTP 200: pool creation was successful, and the pool details are returned in the response.

See Response Types: Token Pool

HTTP 202: request was accepted, but pool will be created asynchronously, with “receipt” and “token-pool” events sent later on the websocket.

See Response Types: Async Request

POST /activatepool

Activate a token pool to begin receiving events. Generally this means the connector will create blockchain event subscriptions to transfer and approval events related to the set of tokens encompassed by this token pool.

In a multiparty network, this step will be performed by every member after a successful token pool broadcast. It therefore also serves the purpose of validating the broadcast info - if the connector does not find a valid pool given the poolLocator and config information passed in to this call, the pool should not get confirmed.

Request

{
  "poolLocator": "id=F1",
  "poolData": "extra-pool-info",
  "requestId": "1",
  "config": {}
}

Response

HTTP 200: pool activation was successful, and the pool details are returned in the response.

See Response Types: Token Pool

HTTP 202: request was accepted, but pool will be activated asynchronously, with “receipt” and “token-pool” events sent later on the websocket.

See Response Types: Async Request

HTTP 204: activation was successful - no separate receipt will be delivered, but “token-pool” event will be sent later on the websocket.

No body

POST /checkinterface

This is an optional (but recommended) API for token connectors. If implemented, support will be indicated by the presence of the interfaceFormat field in all Token Pool responses.

In the case that a connector supports multiple variants of a given token standard (such as many different ways to structure “mint” or “burn” calls on an underlying smart contract), this API allows the connector to be provided with a full description of the interface methods in use for a given token pool, so the connector can determine which methods it knows how to invoke.

Request

{
  "poolLocator": "id=F1",
  "format": "abi",
  "methods": [
    {
      "name": "burn",
      "type": "function",
      "inputs": [
        {
          "internalType": "uint256",
          "name": "tokenId",
          "type": "uint256"
        }
      ],
      "outputs": [],
      "stateMutability": "nonpayable"
    },
    ...
  ]
}

Response

HTTP 200: interface was successfully parsed, and methods of interest are returned in the body.

The response body includes a section for each type of token operation (burn/mint/transfer/approval), which specifies a subset of the input body useful to that operation. The caller (FireFly) can then store and provide the proper subset of the interface for every future token operation (via the interface parameter).

{
  "burn": {
    "format": "abi",
    "methods": [
      {
        "name": "burn",
        "type": "function",
        "inputs": [
          {
            "internalType": "uint256",
            "name": "tokenId",
            "type": "uint256"
          }
        ],
        "outputs": [],
        "stateMutability": "nonpayable"
      }
    ]
  },
  "mint": { ... },
  "transfer": { ... },
  "approval": { ... }
}

POST /mint

Mint new tokens.

Request

{
  "poolLocator": "id=F1",
  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "to": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "amount": "10",
  "tokenIndex": "1",
  "uri": "ipfs://000000",
  "requestId": "1",
  "data": "transfer-metadata",
  "config": {},
  "interface": {}
}

Response

HTTP 202: request was accepted, but mint will occur asynchronously, with “receipt” and “token-mint” events sent later on the websocket.

See Response Types: Async Request

POST /burn

Burn tokens.

Request

{
  "poolLocator": "id=F1",
  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "from": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "amount": "10",
  "tokenIndex": "1",
  "requestId": "1",
  "data": "transfer-metadata",
  "config": {},
  "interface": {}
}

Response

HTTP 202: request was accepted, but burn will occur asynchronously, with “receipt” and “token-burn” events sent later on the websocket.

See Response Types: Async Request

POST /transfer

Transfer tokens from one address to another.

Request

{
  "poolLocator": "id=F1",
  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "from": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "to": "0xb107ed9caa1323b7bc36e81995a4658ec2251951",
  "amount": "1",
  "tokenIndex": "1",
  "requestId": "1",
  "data": "transfer-metadata",
  "config": {},
  "interface": {}
}

Response

HTTP 202: request was accepted, but transfer will occur asynchronously, with “receipt” and “token-transfer” events sent later on the websocket.

See Response Types: Async Request

POST /approval

Approve another identity to manage tokens.

Request

{
  "poolLocator": "id=F1",
  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "operator": "0xb107ed9caa1323b7bc36e81995a4658ec2251951",
  "approved": true,
  "requestId": "1",
  "data": "approval-metadata",
  "config": {},
  "interface": {}
}

Response

HTTP 202: request was accepted, but approval will occur asynchronously, with “receipt” and “token-approval” events sent later on the websocket.

See Response Types: Async Request

Websocket Events

A connector should expose a websocket at /api/ws. All emitted websocket events are a JSON string of the form:

{
  "id": "event-id",
  "event": "event-name",
  "data": {}
}

The event name will match one of the names listed below, and the data payload will correspond to the linked response object.

All events except the receipt event must be acknowledged by sending an ack of the form:

{
  "event": "ack",
  "data": {
    "id": "event-id"
  }
}

Many messages may also be batched into a single websocket event of the form:

{
  "id": "event-id",
  "event": "batch",
  "data": {
    "events": [
      {
        "event": "event-name",
        "data": {}
      },
      ...
    ]
  }
}

Batched messages must be acked all at once using the ID of the batch.

receipt

An asynchronous operation has completed.

See Response Types: Receipt

token-pool

A new token pool has been created or activated.

See Response Types: Token Pool

token-mint

Tokens have been minted.

See Response Types: Token Transfer

token-burn

Tokens have been burned.

See Response Types: Token Transfer

token-transfer

Tokens have been transferred.

See Response Types: Token Transfer

token-approval

Token approvals have changed.

See Response Types: Token Approval

Response Types

Async Request

Many operations may happen asynchronously in the background, and will return only a request ID. This may be a request ID that was passed in, or if none was passed, will be randomly assigned. This ID can be used to correlate with a receipt event later received on the websocket.

{
  "id": "b84ab27d-0d50-42a6-9c26-2fda5eb901ba"
}

Receipt

  "headers": {
    "type": "",
    "requestId": ""
  }
  "transactionHash": "",
  "errorMessage": ""
}

Token Pool

{
  "type": "fungible",
  "data": "pool-metadata",
  "poolLocator": "id=F1",
  "standard": "ERC20",
  "interfaceFormat": "abi",
  "symbol": "FFC",
  "decimals": 18,
  "info": {},
  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "blockchain": {}
}

Token Transfer

Note that mint and burn operations are just specialized versions of transfer. A mint will omit the “from” field, while a burn will omit the “to” field.

{
  "id": "1",
  "data": "transfer-metadata",
  "poolLocator": "id=F1",
  "poolData": "extra-pool-info",
  "from": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "to": "0xb107ed9caa1323b7bc36e81995a4658ec2251951",
  "amount": "1",
  "tokenIndex": "1",
  "uri": "ipfs://000000",
  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "blockchain": {}
}

Token Approval

{
  "id": "1",
  "data": "transfer-metadata",
  "poolLocator": "id=F1",
  "poolData": "extra-pool-info",
  "operator": "0xb107ed9caa1323b7bc36e81995a4658ec2251951",
  "approved": true,
  "subject": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A:0xb107ed9caa1323b7bc36e81995a4658ec2251951",
  "info": {},
  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
  "blockchain": {}
}