Use ERC-1155 tokens¶

Previous steps: Install the FireFly CLI¶

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

← ① Install the FireFly CLI

Create a stack with an ERC-1155 connector¶

The default token connector that the FireFly CLI sets up is for ERC-20 and ERC-721. If you would like to work with ERC-1155 tokens, you need to create a stack that is configured to use that token connector. To do that, run:

ff init ethereum -t erc-1155

Then run:

ff start <your_stack_name>

About the sample token contract¶

When the FireFly CLI set up your FireFly stack, it also deployed a sample ERC-1155 contract that conforms to the expectations of the token connector. When you create a token pool through FireFly's token APIs, that contract will be used by default.

⚠️ WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed.

Use the Sandbox (optional)¶

At this point you could open the Sandbox at http://127.0.0.1:5109/home?action=tokens.pools and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. Tokens Sandbox

Create a pool (using default token contract)¶

After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a name and type (fungible or nonfungible) for the pool.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

NOTE: Without passing the query parameter publish=true when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to /tokens/pools/{nameOrId}/publish

{
  "name": "testpool",
  "type": "fungible"
}

Other parameters:

You must specify a connector if you have configured multiple token connectors
You may pass through a config object of additional parameters, if supported by your token connector
You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity

Create a pool (from a deployed token contract)¶

If you wish to use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by creating a FireFly contract interface. This step is optional if you're certain that your ERC-1155 ABI conforms to the default expectations of the token connector, but is generally recommended.

See the README of the token connector for details on what contract variants can currently be understood.

You can pass a config object with an address when you make the request to create the token pool, and if you created a contract interface, you can include the interface ID as well.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

NOTE: Without passing the query parameter publish=true when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to /tokens/pools/{nameOrId}/publish

{
  "name": "testpool",
  "type": "fungible",
  "interface": {
    "id": "b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8"
  },
  "config": {
    "address": "0xb1C845D32966c79E23f733742Ed7fCe4B41901FC"
  }
}

Mint tokens¶

Once you have a token pool, you can mint tokens within it. With the default sample contract, only the creator of a pool is allowed to mint - but each contract may define its own permission model.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint

{
  "amount": 10
}

Other parameters:

You must specify a pool name if you've created more than one pool
You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
You may specify to if you'd like to send the minted tokens to a specific identity (default is the same as key)

Transfer tokens¶

You may transfer tokens within a pool by specifying an amount and a destination understood by the connector (i.e. an Ethereum address). With the default sample contract, only the owner of a token or another approved account may transfer it away - but each contract may define its own permission model.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

{
  "amount": 1,
  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f"
}

NOTE: When transferring a non-fungible token, the amount must always be 1. The tokenIndex field is also required when transferring a non-fungible token.

Other parameters:

You must specify a pool name if you've created more than one pool
You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
You may specify from if you'd like to send tokens from a specific identity (default is the same as key)

Sending data with a transfer¶

All transfers (as well as mint/burn operations) support an optional message parameter that contains a broadcast or private message to be sent along with the transfer. This message follows the same convention as other FireFly messages, and may be comprised of text or blob data, and can provide context, metadata, or other supporting information about the transfer. The message will be batched, hashed, and pinned to the primary blockchain.

The message ID and hash will also be sent to the token connector as part of the transfer operation, to be written to the token blockchain when the transaction is submitted. All recipients of the message will then be able to correlate the message with the token transfer.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

Broadcast message¶

{
  "amount": 1,
  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
  "message": {
    "data": [
      {
        "value": "payment for goods"
      }
    ]
  }
}

Private message¶

{
  "amount": 1,
  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
  "message": {
    "header": {
      "type": "transfer_private"
    },
    "group": {
      "members": [
        {
          "identity": "org_1"
        }
      ]
    },
    "data": [
      {
        "value": "payment for goods"
      }
    ]
  }
}

Note that all parties in the network will be able to see the transfer (including the message ID and hash), but only the recipients of the message will be able to view the actual message data.

Burn tokens¶

You may burn tokens by simply specifying an amount. With the default sample contract, only the owner of a token or another approved account may burn it - but each connector may define its own permission model.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn

{
  "amount": 1
}

NOTE: When burning a non-fungible token, the amount must always be 1. The tokenIndex field is also required when burning a non-fungible token.

Other parameters:

You must specify a pool name if you've created more than one pool
You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
You may specify from if you'd like to burn tokens from a specific identity (default is the same as key)

Token approvals¶

You can also approve other wallets to transfer tokens on your behalf with the /approvals API. The important fields in a token approval API request are as follows:

approved: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to true. Setting to false can revoke an existing approval.
operator: The other account that is allowed to transfer tokens out of the wallet specified in the key field
key: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction

Here is an example request that would let the signing account 0x634ee8c7d0894d086c7af1fc8514736aed251528 transfer any amount of tokens from my wallet

Request¶

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals

{
  "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528"
}

Response¶

{
  "localId": "46fef50a-cf93-4f92-acf8-fae161b37362",
  "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d",
  "connector": "erc1155",
  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
  "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528",
  "approved": true,
  "tx": {
    "type": "token_approval",
    "id": "00faa011-f42c-403d-a047-2df7318967cd"
  }
}