Add "Getting Started" documentation for tokens #306

awrichar · 2021-10-28T19:10:24Z

Initial docs for #218.

~~Some of the routes described here are still being updated by @eberger727 in #307, so should wait for that PR before merging this.~~

I've published the docs in this PR to my own FireFly fork here, if you like reading the pretty pages instead of the Markdown: https://awrichar.github.io/firefly/gettingstarted/mint_tokens.html

codecov-commenter · 2021-10-28T19:15:36Z

Codecov Report

Merging #306 (7edd2a2) into main (ce74fe3) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff             @@
##              main      #306    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files          224       234    +10     
  Lines        12387     12788   +401     
==========================================
+ Hits         12387     12788   +401

Impacted Files	Coverage Δ
pkg/fftypes/batch.go	`100.00% <0.00%> (ø)`
pkg/fftypes/event.go	`100.00% <0.00%> (ø)`
pkg/fftypes/bigint.go	`100.00% <0.00%> (ø)`
pkg/database/filter.go	`100.00% <0.00%> (ø)`
pkg/fftypes/message.go	`100.00% <0.00%> (ø)`
pkg/fftypes/tokenpool.go	`100.00% <0.00%> (ø)`
internal/config/config.go	`100.00% <0.00%> (ø)`
internal/assets/manager.go	`100.00% <0.00%> (ø)`
internal/apiserver/server.go	`100.00% <0.00%> (ø)`
internal/assets/token_pool.go	`100.00% <0.00%> (ø)`
... and 51 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ce74fe3...7edd2a2. Read the comment docs.

Signed-off-by: Andrew Richardson <[email protected]>

peterbroadhurst

Really clear and straight forwards thanks @awrichar

Couple of comments, and deferral to @jimthematrix for a final review on this one before it goes in.

peterbroadhurst · 2021-11-09T17:50:48Z

docs/gettingstarted/mint_tokens.md

+- 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


Wonder if an example worthwhile here, such as?

Examples of how a pool might be used by a given token connector implementation:
- ERC-721: A contract instance, ready for issuance of NFTs within unique identities in the pool
- ERC-20 / ERC-777: A token contract instance, with a single fungible pool of value - "a coin"
- ERC-1155: An efficient to allocate isolated pool of fungible or non-fungible tokens (see ref implementation)
- ERC-1400 (and related security token standards): An partition within an overall fungible pool, representing part of the value of an overall non-fungible asset

Could do with @jimthematrix checking on the terminology above

Could be, and maybe not limited to pools... Maybe we need an extra section of "Example uses" to lay out a few examples of how you could map common token standards/use cases onto FireFly.

agree with the suggestion to add some details how a pool is mapped to the various contract specs.

agree with the suggested mapping above to ERC721, ERC20/777 and ERC1155.

on ERC-1400, however, a pool should be mapped to a contract instance instead of a partition. in ERC-1410 which describes the spec for partially fungible tokens, the interface methods that are compatible with ERC-20/ERC-777 all operate on the sum of all partitions. For example the balanceOf() method, same for totalSupply(): (ethereum/EIPs#1410):

balanceOf

Aggregates a token holders balances across all partitions. Equivalent to balanceOf in the ERC-20/777 specification.

MUST count the sum of all partition balances assigned to a token holder.

function balanceOf(address _tokenHolder) external view returns (uint256);

In addition, a token transfer is allowed to be received into a partition that is different than the partition it's sent from:

transferByPartition

When transferring tokens from a particular partition, it is useful to know on-chain (i.e. not just via an event being fired) the destination partition of those tokens. The destination partition will be determined by the implementation of this function and will vary depending on use-case.

_The function MUST return the bytes32 partition of the receiver.

function transferByPartition(bytes32 _partition, address _to, uint256 _value, bytes _data) external returns (bytes32)

Given the above interface in ERC-1410 (main spec of the security token standard captured by ERC-1400 as a compendium), the operations that target the sum of all partitions (eg balanceOf(), totalSupply(), authorizeOperator(), etc.) are already supported by the current tokens API interface when a pool is mapped to the contract instance, and it'd be straightforward to add support for partition based operations (eg balanceOfByPartition(), transferByPartition(), authorizeOperatorByPartition()) by simply adding additional payload parameters to indicate target partitions to the existing API endpoints.

On the other hand, if pools are mapped to partitions, then we have to add support for cross-pool transfers and aggregates in order to properly support the ERC-1410 operations.

if we agree with the above, we should also add that the current API endpoints support the ERC20, ERC777, ERC1155 and ERC721 contracts, while future work is needed to support ERC1400, in particular to support partitions (metadata to fungible tokens) within pools.

Added a new section with some of these examples.

docs/gettingstarted/mint_tokens.md

awrichar · 2021-11-11T20:05:25Z

Should I add a section on the FireFly configuration file? ie show the sample tokens config that is generated by the CLI?

jimthematrix

Nice writeup. Added my opinion on support for ERC-1400, and other relatively minor comments. Happy to discuss more if there are different thoughts.

jimthematrix · 2021-11-22T15:59:12Z

docs/gettingstarted/mint_tokens.md

+- 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


agree with the suggestion to add some details how a pool is mapped to the various contract specs.

agree with the suggested mapping above to ERC721, ERC20/777 and ERC1155.

on ERC-1400, however, a pool should be mapped to a contract instance instead of a partition. in ERC-1410 which describes the spec for partially fungible tokens, the interface methods that are compatible with ERC-20/ERC-777 all operate on the sum of all partitions. For example the balanceOf() method, same for totalSupply(): (ethereum/EIPs#1410):

balanceOf

Aggregates a token holders balances across all partitions. Equivalent to balanceOf in the ERC-20/777 specification.

MUST count the sum of all partition balances assigned to a token holder.

function balanceOf(address _tokenHolder) external view returns (uint256);

In addition, a token transfer is allowed to be received into a partition that is different than the partition it's sent from:

transferByPartition

When transferring tokens from a particular partition, it is useful to know on-chain (i.e. not just via an event being fired) the destination partition of those tokens. The destination partition will be determined by the implementation of this function and will vary depending on use-case.

_The function MUST return the bytes32 partition of the receiver.

function transferByPartition(bytes32 _partition, address _to, uint256 _value, bytes _data) external returns (bytes32)

Given the above interface in ERC-1410 (main spec of the security token standard captured by ERC-1400 as a compendium), the operations that target the sum of all partitions (eg balanceOf(), totalSupply(), authorizeOperator(), etc.) are already supported by the current tokens API interface when a pool is mapped to the contract instance, and it'd be straightforward to add support for partition based operations (eg balanceOfByPartition(), transferByPartition(), authorizeOperatorByPartition()) by simply adding additional payload parameters to indicate target partitions to the existing API endpoints.

On the other hand, if pools are mapped to partitions, then we have to add support for cross-pool transfers and aggregates in order to properly support the ERC-1410 operations.

jimthematrix · 2021-11-22T16:24:44Z

docs/gettingstarted/mint_tokens.md

+- 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


if we agree with the above, we should also add that the current API endpoints support the ERC20, ERC777, ERC1155 and ERC721 contracts, while future work is needed to support ERC1400, in particular to support partitions (metadata to fungible tokens) within pools.

jimthematrix · 2021-11-22T16:29:09Z

docs/gettingstarted/mint_tokens.md

+- 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


suggest adding operational aliases (issue vs. mint, redeem vs. burn) used in different token specs:

Within a pool, you may mint (issue), transfer, and burn (redeem) tokens

docs/gettingstarted/mint_tokens.md

jimthematrix · 2021-11-22T16:44:45Z

docs/gettingstarted/mint_tokens.md

+```
+
+By default, a broadcast message is used. In order to send a private message, specify `"type": "transfer_private"` in the message header,


a sample payload for a private message would be useful here

jimthematrix · 2021-11-22T16:48:15Z

docs/gettingstarted/mint_tokens.md

+## Sending data with a transfer
+
+All transfers (as well as mint/burn operations) support an optional `message` parameter that contains a broadcast or private


I think we effectively hijacked the _data field of the various operations that may have been needed for further on-chain authorizations (e.g signatures by parties other than the sender to indicate approval). as a mental note we should consider supporting an additional payload parameter to include into the _data field as-is

@jimthematrix yes, you're correct. The token connector exposes a data field, and FireFly packs JSON into this field to identify messages and other metadata. But FireFly itself does not (currently) expose any way for the user to control or add to this field from the level of the FireFly APIs.

nguyer · 2021-11-23T18:53:52Z

docs/gettingstarted/mint_tokens.md

+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`


I think the token pool name part is missing from this path

Okay actually I see now that it just works if there's only one pool defined. Does this URL break if there is more than one pool?

The pool name is not in the new paths (if there is only one pool, the name is optional; if there is more than one pool, you pass it in the body). The old path with the pool name is deprecated.

nguyer

Looks great. I ran through the instructions in Postman and it worked for me too. Jim has requested changes, but if he dismisses or approves after updates, I'm fine with this being merged. Thanks!

Signed-off-by: Andrew Richardson <[email protected]>

awrichar requested a review from dechdev October 28, 2021 19:10

awrichar requested review from nguyer, nickgaski and peterbroadhurst as code owners October 28, 2021 19:10

Add "Getting Started" documentation for tokens

191bf38

Signed-off-by: Andrew Richardson <[email protected]>

awrichar force-pushed the tokendocs branch from 9de4815 to 191bf38 Compare October 28, 2021 19:17

peterbroadhurst reviewed Nov 9, 2021

View reviewed changes

peterbroadhurst requested a review from jimthematrix November 9, 2021 17:58

jimthematrix suggested changes Nov 22, 2021

View reviewed changes

nguyer reviewed Nov 23, 2021

View reviewed changes

nguyer approved these changes Nov 23, 2021

View reviewed changes

awrichar added 2 commits November 24, 2021 10:11

Add examples of token pools

738e6f1

Signed-off-by: Andrew Richardson <[email protected]>

Add example for transfer with private message

8807ec2

Signed-off-by: Andrew Richardson <[email protected]>

jimthematrix approved these changes Nov 24, 2021

View reviewed changes

awrichar added 2 commits November 24, 2021 10:43

Add an intro paragraph to the token docs

b809717

Signed-off-by: Andrew Richardson <[email protected]>

Fix firefly-tokens-erc1155 link in Getting Started

7edd2a2

Signed-off-by: Andrew Richardson <[email protected]>

awrichar merged commit 0646451 into hyperledger:main Nov 24, 2021

awrichar deleted the tokendocs branch November 24, 2021 17:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add "Getting Started" documentation for tokens #306

Add "Getting Started" documentation for tokens #306

awrichar commented Oct 28, 2021 •

edited

Loading

codecov-commenter commented Oct 28, 2021 •

edited

Loading

peterbroadhurst left a comment

peterbroadhurst Nov 9, 2021

awrichar Nov 11, 2021

jimthematrix Nov 22, 2021

jimthematrix Nov 22, 2021

awrichar Nov 24, 2021

awrichar commented Nov 11, 2021

jimthematrix left a comment

jimthematrix Nov 22, 2021

jimthematrix Nov 22, 2021

jimthematrix Nov 22, 2021

jimthematrix Nov 22, 2021

awrichar Nov 24, 2021

jimthematrix Nov 22, 2021

awrichar Nov 24, 2021

nguyer Nov 23, 2021

nguyer Nov 23, 2021

awrichar Nov 24, 2021 •

edited

Loading

nguyer left a comment

		- 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

		```

		By default, a broadcast message is used. In order to send a private message, specify `"type": "transfer_private"` in the message header,

		## Sending data with a transfer

		All transfers (as well as mint/burn operations) support an optional `message` parameter that contains a broadcast or private

		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`

Add "Getting Started" documentation for tokens #306

Add "Getting Started" documentation for tokens #306

Conversation

awrichar commented Oct 28, 2021 • edited Loading

codecov-commenter commented Oct 28, 2021 • edited Loading

Codecov Report

peterbroadhurst left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

balanceOf

transferByPartition

Choose a reason for hiding this comment

Choose a reason for hiding this comment

awrichar commented Nov 11, 2021

jimthematrix left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

balanceOf

transferByPartition

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

awrichar Nov 24, 2021 • edited Loading

Choose a reason for hiding this comment

nguyer left a comment

Choose a reason for hiding this comment

awrichar commented Oct 28, 2021 •

edited

Loading

codecov-commenter commented Oct 28, 2021 •

edited

Loading

awrichar Nov 24, 2021 •

edited

Loading