From 191bf3806f9851f573ace075428750618ea69b60 Mon Sep 17 00:00:00 2001 From: Andrew Richardson Date: Thu, 28 Oct 2021 15:08:37 -0400 Subject: [PATCH 1/5] Add "Getting Started" documentation for tokens Signed-off-by: Andrew Richardson --- docs/gettingstarted/mint_tokens.md | 116 ++++++++++++++++++++++++++++- 1 file changed, 114 insertions(+), 2 deletions(-) diff --git a/docs/gettingstarted/mint_tokens.md b/docs/gettingstarted/mint_tokens.md index 1bd4868ae5..bb96c4d8b5 100644 --- a/docs/gettingstarted/mint_tokens.md +++ b/docs/gettingstarted/mint_tokens.md @@ -16,6 +16,118 @@ nav_order: 9 --- -## Work in progress +## Quick reference -... the tokens APIs are under development \ No newline at end of file +- FireFly provides an abstraction layer for multiple types of tokens +- Tokens are grouped into _pools_, which each represent a particular type or class of token +- Each pool is classified as _fungible_ or _non-fungible_ +- In the case of _non-fungible_ tokens, the pool is subdivided into individual tokens with a unique _token index_ +- Within a pool, you may _mint_, _transfer_, and _burn_ tokens +- Each operation can be optionally accompanied by a broadcast or private message, which will be recorded alongside the transfer on-chain +- FireFly tracks a history of all token operations along with all current token balances +- The blockchain backing each token connector may be the same _or_ different from the one backing FireFly message pinning + +## Create a pool + +Every application will need to create at least one token pool. At a minimum, you must always +specify a `name` and `type` (fungible or nonfungible) for the pool. + +`POST` `/api/v1/namespaces/default/tokens/pools` + +```json +{ + "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 + +## Mint tokens + +Once you have a token pool, you can mint tokens within it. With the default `firefly-tokens-erc1155` connector, +only the creator of a pool is allowed to mint - but each connector may define its own permission model. + +`POST` `/api/v1/namespaces/default/tokens/mint` + +```json +{ + "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 `firefly-tokens-erc1155` connector, only the owner of a token may transfer it away - but each connector may define its +own permission model. + +`POST` `/api/v1/namespaces/default/tokens/transfers` + +```json +{ + "amount": 1, + "to": "0x07eab7731db665caf02bc92c286f51dea81f923f" +} +``` + +Other parameters: +- You must specify a `pool` name if you've created more than one pool +- You must specify a `tokenIndex` for non-fungible pools (and the `amount` should be 1) +- 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 as described in [key concepts](/keyconcepts/broadcast.html). + +The message 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` `/api/v1/namespaces/default/tokens/transfers` + +```json +{ + "amount": 1, + "to": "0x07eab7731db665caf02bc92c286f51dea81f923f", + "message": { + "data": [{ + "value": "payment for goods" + }] + } +} +``` + +By default, a broadcast message is used. In order to send a private message, specify `"type": "transfer_private"` in the message header, +and include a `"group"` entry specifying the recipients. All parties in the network will be able to see the transfer (including the +message 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 `firefly-tokens-erc1155` connector, only the owner of a token may +burn it - but each connector may define its own permission model. + +`POST` `/api/v1/namespaces/default/tokens/burn` + +```json +{ + "amount": 1, +} +``` + +Other parameters: +- You must specify a `pool` name if you've created more than one pool +- You must specify a `tokenIndex` for non-fungible pools (and the `amount` should be 1) +- 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`) From 738e6f1ed2e6adf7156dfc6d028c70f59b3a353d Mon Sep 17 00:00:00 2001 From: Andrew Richardson Date: Wed, 24 Nov 2021 10:09:13 -0500 Subject: [PATCH 2/5] Add examples of token pools Signed-off-by: Andrew Richardson --- docs/gettingstarted/mint_tokens.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/gettingstarted/mint_tokens.md b/docs/gettingstarted/mint_tokens.md index bb96c4d8b5..3da635596d 100644 --- a/docs/gettingstarted/mint_tokens.md +++ b/docs/gettingstarted/mint_tokens.md @@ -27,6 +27,25 @@ nav_order: 9 - FireFly tracks a history of all token operations along with all current token balances - The blockchain backing each token connector may be the same _or_ different from the one backing FireFly message pinning +## What is a pool? + +Token pools are a FireFly construct for describing a set of tokens. The exact definition of a token pool +is dependent on the token connector implementation. Some examples of how pools might map to various well-defined +Ethereum standards: + +- **[ERC-1155](https://eips.ethereum.org/EIPS/eip-1155):** a single contract instance can efficiently allocate + many isolated pools of fungible or non-fungible tokens + (see [reference implementation](https://github.com/hyperledger/firefly-tokens-erc1155)) +- **[ERC-20](https://eips.ethereum.org/EIPS/eip-20) / [ERC-777](https://eips.ethereum.org/EIPS/eip-777):** + each contract instance represents a single fungible pool of value, e.g. "a coin" +- **[ERC-721](https://eips.ethereum.org/EIPS/eip-721):** each contract instance represents a single pool of NFTs, + each with unique identities within the pool +- **[ERC-1400](https://github.com/ethereum/eips/issues/1411) / [ERC-1410](https://github.com/ethereum/eips/issues/1410):** + partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions + +These are provided as examples only - a custom token connector could be backed by any token technology (Ethereum or otherwise) +as long as it can support the basic operations described here (create pool, mint, burn, transfer). + ## Create a pool Every application will need to create at least one token pool. At a minimum, you must always From 8807ec246be2eeb3b77f235c7d99c4f1b30d9069 Mon Sep 17 00:00:00 2001 From: Andrew Richardson Date: Wed, 24 Nov 2021 10:19:40 -0500 Subject: [PATCH 3/5] Add example for transfer with private message Signed-off-by: Andrew Richardson --- docs/gettingstarted/mint_tokens.md | 31 +++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/gettingstarted/mint_tokens.md b/docs/gettingstarted/mint_tokens.md index 3da635596d..04cdf85c5f 100644 --- a/docs/gettingstarted/mint_tokens.md +++ b/docs/gettingstarted/mint_tokens.md @@ -109,13 +109,14 @@ Other parameters: 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 as described in [key concepts](/keyconcepts/broadcast.html). +batched, hashed, and pinned to the primary blockchain as described in [key concepts](../keyconcepts/broadcast.html). -The message hash will also be sent to the token connector as part of the transfer operation, to be written to the token 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` `/api/v1/namespaces/default/tokens/transfers` +Broadcast message: ```json { "amount": 1, @@ -128,9 +129,29 @@ when the transaction is submitted. All recipients of the message will then be ab } ``` -By default, a broadcast message is used. In order to send a private message, specify `"type": "transfer_private"` in the message header, -and include a `"group"` entry specifying the recipients. All parties in the network will be able to see the transfer (including the -message hash), but only the recipients of the message will be able to view the actual message data. +Private message: +```json +{ + "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 From b8097176a7c513db7775877f120fa97feacbc039 Mon Sep 17 00:00:00 2001 From: Andrew Richardson Date: Wed, 24 Nov 2021 10:42:27 -0500 Subject: [PATCH 4/5] Add an intro paragraph to the token docs Signed-off-by: Andrew Richardson --- docs/gettingstarted/mint_tokens.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/gettingstarted/mint_tokens.md b/docs/gettingstarted/mint_tokens.md index 04cdf85c5f..6162fd67ec 100644 --- a/docs/gettingstarted/mint_tokens.md +++ b/docs/gettingstarted/mint_tokens.md @@ -18,11 +18,16 @@ nav_order: 9 ## Quick reference +Tokens are a critical building block in many blockchain-backed applications. Fungible tokens can represent a store +of value or a means of rewarding participation in a multi-party system, while non-fungible tokens provide a clear +way to identify and track unique entities across the network. FireFly provides flexible mechanisms to operate on +any type of token and to tie those operations to on- and off-chain data. + - FireFly provides an abstraction layer for multiple types of tokens - Tokens are grouped into _pools_, which each represent a particular type or class of token - Each pool is classified as _fungible_ or _non-fungible_ - In the case of _non-fungible_ tokens, the pool is subdivided into individual tokens with a unique _token index_ -- Within a pool, you may _mint_, _transfer_, and _burn_ tokens +- Within a pool, you may _mint (issue)_, _transfer_, and _burn (redeem)_ tokens - Each operation can be optionally accompanied by a broadcast or private message, which will be recorded alongside the transfer on-chain - FireFly tracks a history of all token operations along with all current token balances - The blockchain backing each token connector may be the same _or_ different from the one backing FireFly message pinning From 7edd2a22c964e46c22eabe5e309a5cd7a254eed4 Mon Sep 17 00:00:00 2001 From: Andrew Richardson Date: Wed, 24 Nov 2021 11:37:43 -0500 Subject: [PATCH 5/5] Fix firefly-tokens-erc1155 link in Getting Started Signed-off-by: Andrew Richardson --- docs/gettingstarted/setup_env.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gettingstarted/setup_env.md b/docs/gettingstarted/setup_env.md index fd04fd0758..1181b581da 100644 --- a/docs/gettingstarted/setup_env.md +++ b/docs/gettingstarted/setup_env.md @@ -58,7 +58,7 @@ within your stack. By default, it will include the following: - A [SQLite](https://www.sqlite.org) relational database is the default option - Token connector: one per member - The token service for your node - - A instance of [firefly-tokens-erc1155](https://github.com/kaleido-io/firefly-tokens-erc1155) is the default option + - A instance of [firefly-tokens-erc1155](https://github.com/hyperledger/firefly-tokens-erc1155) is the default option ## Check your `ff` CLI is healthy