Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 0b4c355

Browse files
author
David Echelberger
committedNov 29, 2021
Merge branch 'main' of github.com:hyperledger/firefly into metrics
2 parents a53ee8b + e3f38d0 commit 0b4c355

File tree

71 files changed

+1323
-1110
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+1323
-1110
lines changed
 

‎db/migrations/sqlite/000047_add_token_uri_fields.up.sql

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
DROP INDEX tokenbalance_pool;
2+
3+
ALTER TABLE tokenbalance ADD COLUMN uri VARCHAR(1024);
4+
ALTER TABLE tokentransfer ADD COLUMN uri VARCHAR(1024);
5+
6+
CREATE UNIQUE INDEX tokenbalance_pool ON tokenbalance(namespace,key,pool_id,token_index);
7+
CREATE UNIQUE INDEX tokenbalance_uri ON tokenbalance(namespace,key,pool_id,uri);

‎docs/gettingstarted/mint_tokens.md

+159-2
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,163 @@ nav_order: 9
1616

1717
---
1818

19-
## Work in progress
19+
## Quick reference
2020

21-
... the tokens APIs are under development
21+
Tokens are a critical building block in many blockchain-backed applications. Fungible tokens can represent a store
22+
of value or a means of rewarding participation in a multi-party system, while non-fungible tokens provide a clear
23+
way to identify and track unique entities across the network. FireFly provides flexible mechanisms to operate on
24+
any type of token and to tie those operations to on- and off-chain data.
25+
26+
- FireFly provides an abstraction layer for multiple types of tokens
27+
- Tokens are grouped into _pools_, which each represent a particular type or class of token
28+
- Each pool is classified as _fungible_ or _non-fungible_
29+
- In the case of _non-fungible_ tokens, the pool is subdivided into individual tokens with a unique _token index_
30+
- Within a pool, you may _mint (issue)_, _transfer_, and _burn (redeem)_ tokens
31+
- Each operation can be optionally accompanied by a broadcast or private message, which will be recorded alongside the transfer on-chain
32+
- FireFly tracks a history of all token operations along with all current token balances
33+
- The blockchain backing each token connector may be the same _or_ different from the one backing FireFly message pinning
34+
35+
## What is a pool?
36+
37+
Token pools are a FireFly construct for describing a set of tokens. The exact definition of a token pool
38+
is dependent on the token connector implementation. Some examples of how pools might map to various well-defined
39+
Ethereum standards:
40+
41+
- **[ERC-1155](https://eips.ethereum.org/EIPS/eip-1155):** a single contract instance can efficiently allocate
42+
many isolated pools of fungible or non-fungible tokens
43+
(see [reference implementation](https://github.com/hyperledger/firefly-tokens-erc1155))
44+
- **[ERC-20](https://eips.ethereum.org/EIPS/eip-20) / [ERC-777](https://eips.ethereum.org/EIPS/eip-777):**
45+
each contract instance represents a single fungible pool of value, e.g. "a coin"
46+
- **[ERC-721](https://eips.ethereum.org/EIPS/eip-721):** each contract instance represents a single pool of NFTs,
47+
each with unique identities within the pool
48+
- **[ERC-1400](https://github.com/ethereum/eips/issues/1411) / [ERC-1410](https://github.com/ethereum/eips/issues/1410):**
49+
partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions
50+
51+
These are provided as examples only - a custom token connector could be backed by any token technology (Ethereum or otherwise)
52+
as long as it can support the basic operations described here (create pool, mint, burn, transfer).
53+
54+
## Create a pool
55+
56+
Every application will need to create at least one token pool. At a minimum, you must always
57+
specify a `name` and `type` (fungible or nonfungible) for the pool.
58+
59+
`POST` `/api/v1/namespaces/default/tokens/pools`
60+
61+
```json
62+
{
63+
"name": "testpool",
64+
"type": "fungible"
65+
}
66+
```
67+
68+
Other parameters:
69+
- You must specify a `connector` if you have configured multiple token connectors
70+
- You may pass through a `config` object of additional parameters, if supported by your token connector
71+
- 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
72+
73+
## Mint tokens
74+
75+
Once you have a token pool, you can mint tokens within it. With the default `firefly-tokens-erc1155` connector,
76+
only the creator of a pool is allowed to mint - but each connector may define its own permission model.
77+
78+
`POST` `/api/v1/namespaces/default/tokens/mint`
79+
80+
```json
81+
{
82+
"amount": 10
83+
}
84+
```
85+
86+
Other parameters:
87+
- You must specify a `pool` name if you've created more than one pool
88+
- 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
89+
- You may specify `to` if you'd like to send the minted tokens to a specific identity (default is the same as `key`)
90+
91+
## Transfer tokens
92+
93+
You may transfer tokens within a pool by specifying an amount and a destination understood by the connector (i.e. an Ethereum address).
94+
With the default `firefly-tokens-erc1155` connector, only the owner of a token may transfer it away - but each connector may define its
95+
own permission model.
96+
97+
`POST` `/api/v1/namespaces/default/tokens/transfers`
98+
99+
```json
100+
{
101+
"amount": 1,
102+
"to": "0x07eab7731db665caf02bc92c286f51dea81f923f"
103+
}
104+
```
105+
106+
Other parameters:
107+
- You must specify a `pool` name if you've created more than one pool
108+
- You must specify a `tokenIndex` for non-fungible pools (and the `amount` should be 1)
109+
- 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
110+
- You may specify `from` if you'd like to send tokens from a specific identity (default is the same as `key`)
111+
112+
## Sending data with a transfer
113+
114+
All transfers (as well as mint/burn operations) support an optional `message` parameter that contains a broadcast or private
115+
message to be sent along with the transfer. This message follows the same convention as other FireFly messages, and may be comprised
116+
of text or blob data, and can provide context, metadata, or other supporting information about the transfer. The message will be
117+
batched, hashed, and pinned to the primary blockchain as described in [key concepts](../keyconcepts/broadcast.html).
118+
119+
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
120+
when the transaction is submitted. All recipients of the message will then be able to correlate the message with the token transfer.
121+
122+
`POST` `/api/v1/namespaces/default/tokens/transfers`
123+
124+
Broadcast message:
125+
```json
126+
{
127+
"amount": 1,
128+
"to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
129+
"message": {
130+
"data": [{
131+
"value": "payment for goods"
132+
}]
133+
}
134+
}
135+
```
136+
137+
Private message:
138+
```json
139+
{
140+
"amount": 1,
141+
"to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
142+
"message": {
143+
"header": {
144+
"type": "transfer_private",
145+
},
146+
"group": {
147+
"members": [{
148+
"identity": "org_1"
149+
}]
150+
},
151+
"data": [{
152+
"value": "payment for goods"
153+
}]
154+
}
155+
}
156+
```
157+
158+
Note that all parties in the network will be able to see the transfer (including the message ID and hash), but only
159+
the recipients of the message will be able to view the actual message data.
160+
161+
## Burn tokens
162+
163+
You may burn tokens by simply specifying an amount. With the default `firefly-tokens-erc1155` connector, only the owner of a token may
164+
burn it - but each connector may define its own permission model.
165+
166+
`POST` `/api/v1/namespaces/default/tokens/burn`
167+
168+
```json
169+
{
170+
"amount": 1,
171+
}
172+
```
173+
174+
Other parameters:
175+
- You must specify a `pool` name if you've created more than one pool
176+
- You must specify a `tokenIndex` for non-fungible pools (and the `amount` should be 1)
177+
- 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
178+
- You may specify `from` if you'd like to burn tokens from a specific identity (default is the same as `key`)

‎docs/gettingstarted/setup_env.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ within your stack. By default, it will include the following:
5858
- A [SQLite](https://www.sqlite.org) relational database is the default option
5959
- Token connector: one per member
6060
- The token service for your node
61-
- A instance of [firefly-tokens-erc1155](https://github.com/kaleido-io/firefly-tokens-erc1155) is the default option
61+
- A instance of [firefly-tokens-erc1155](https://github.com/hyperledger/firefly-tokens-erc1155) is the default option
6262

6363
## Check your `ff` CLI is healthy
6464

There was a problem loading the remainder of the diff.

0 commit comments

Comments
 (0)
Failed to load comments.