From 80fc8630c27d79222bc13cc61bafd5531814fdbe Mon Sep 17 00:00:00 2001 From: achon22 Date: Fri, 22 Jun 2018 13:49:48 -0400 Subject: [PATCH 1/7] eip-1169 --- EIPS/eip-1169.md | 145 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 EIPS/eip-1169.md diff --git a/EIPS/eip-1169.md b/EIPS/eip-1169.md new file mode 100644 index 0000000000000..184c1a636c2eb --- /dev/null +++ b/EIPS/eip-1169.md @@ -0,0 +1,145 @@ +--- +eip: 1169 +title: Multi-class Token Standard +author: Albert Chon +discussions-to: https://ethereum-magicians.org/t/erc-1169-multi-class-fungible-tokens/588 +status: Draft +type: Standards Track - Interface +created: 2018-06-22 +--- + + +## Simple Summary + +A standard interface for multi-class fungible tokens. +## Abstract + +This standard allows for the implementation of a standard API for multi-class fungible tokens (henceforth referred to as "MCFTs") within smart contracts. This standard provides basic functionality to track and transfer ownership of MCFTs. +## Motivation + +Currently, there is no standard to support tokens that have multiple classes. In the real world, there are many situations in which defining distinct classes of the same token would be fitting (e.g. distinguishing between preferred/common/restricted shares of a company). Yet, such nuance cannot be supported in today's token standards. An ERC-20 token contract defines tokens that are all of one class while an ERC-721 token contract creates a class (defined by token_id) for each individual token. The ERC-XXXX token standard proposes a new standard for creating multiple classes of tokens within one token contract. + +> Aside: In theory, while it is possible to implement tokens with classes using the properties of token structs in ERC-721 tokens, gas costs of implementing this in practice are prohibitive for any non-trivial application. + +## Specification +### ERC-20 Compatibility (partial) +**name** + +```solidity +function name() constant returns (string name) +``` + +*OPTIONAL - It is recommended that this method is implemented for enhanced usability with wallets and exchanges, but interfaces and other contracts MUST NOT depend on the existence of this method.* + +Returns the name of the aggregate collection of MCFTs managed by this contract. - e.g. `"My Company Tokens"`. + +**class name** + +```solidity +function className(uint256 classId) constant returns (string name) +``` + +*OPTIONAL - It is recommended that this method is implemented for enhanced usability with wallets and exchanges, but interfaces and other contracts MUST NOT depend on the existence of this method.* + +Returns the name of the class of MCFT managed by this contract. - e.g. `"My Company Preferred Shares Token"`. + +**symbol** +```solidity +function symbol() constant returns (string symbol) +``` + +*OPTIONAL - It is recommend that this method is implemented for enhanced usability with wallets and exchanges, but interfaces and other contracts MUST NOT depend on the existence of this method.* + +Returns a short string symbol referencing the entire collection of MCFT managed in this contract. e.g. "MUL". This symbol SHOULD be short (3-8 characters is recommended), with no whitespace characters or new-lines and SHOULD be limited to the uppercase latin alphabet (i.e. the 26 letters used in English). + +**totalSupply** +```solidity +function totalSupply() constant returns (uint256 totalSupply) +``` +Returns the total number of all MCFTs currently tracked by this contract. + +**individualSupply** +```solidity +function individualSupply(uint256 _classId) constant returns (uint256 individualSupply) +``` +Returns the total number of MCFTs of class `_classId` currently tracked by this contract. + +**balanceOf** +```solidity +function balanceOf(address _owner, uint256 _classId) constant returns (uint256 balance) +``` + +Returns the number of MCFTs of token class `_classId` assigned to address `_owner`. + +**classesOwned** +```solidity +function classesOwned(address _owner) constant returns (uint256[] classes) +``` + +Returns an array of `_classId`'s of MCFTs that address `_owner` owns in the contract. +> NOTE: returning an array is supported by `pragma experimental ABIEncoderV2` + +## Basic Ownership + +**approve** +```solidity +function approve(address _to, uint256 _classId, uint256 quantity) +``` +Grants approval for address `_to` to take possession `quantity` amount of the MCFT with ID `_classId`. This method MUST `throw` if `balanceOf(msg.sender, _classId) < quantity`, or if `_classId` does not represent an MCFT class currently tracked by this contract, or if `msg.sender == _to`. + +Only one address can "have approval" at any given time for a given address and `_classId`. Calling `approve` with a new address and `_classId` revokes approval for the previous address and `_classId`. Calling this method with 0 as the `_to` argument clears approval for any address and the specified `_classId`. + +Successful completion of this method MUST emit an `Approval` event (defined below) unless the caller is attempting to clear approval when there is no pending approval. In particular, an Approval event MUST be fired if the `_to` address is zero and there is some outstanding approval. Additionally, an Approval event MUST be fired if `_to` is already the currently approved address and this call otherwise has no effect. (i.e. An `approve()` call that "reaffirms" an existing approval MUST fire an event.) + + + +**transfer** +```solidity +function transfer(address _to, uint256 _classId, uint256 quantity) +``` +Assigns the ownership of `quantity` MCFT's with ID `_classId` to `_to` if and only if `quantity == balanceOf(msg.sender, _classId)`. A successful transfer MUST fire the `Transfer` event (defined below). + +This method MUST transfer ownership to `_to` or `throw`, no other outcomes can be possible. Reasons for failure include (but are not limited to): + +* `msg.sender` is not the owner of `quantity` amount of tokens of `_classId`'s. +* `_classId` does not represent an MCFT class currently tracked by this contract + +A conforming contract MUST allow the current owner to "transfer" a token to themselves, as a way of affirming ownership in the event stream. (i.e. it is valid for `_to == msg.sender` if `balanceOf(msg.sender, _classId) >= balance`.) This "no-op transfer" MUST be considered a successful transfer, and therefore MUST fire a `Transfer` event (with the same address for `_from` and `_to`). + +## Events +**Transfer** + +This event MUST trigger when MCFT ownership is transferred via any mechanism. + +Additionally, the creation of new MCFTs MUST trigger a Transfer event for each newly created MCFTs, with a `_from` address of 0 and a `_to` address matching the owner of the new MCFT (possibly the smart contract itself). The deletion (or burn) of any MCFT MUST trigger a Transfer event with a `_to` address of 0 and a `_from` address of the owner of the MCFT (now former owner!). + +NOTE: A Transfer event with `_from == _to` is valid. See the `transfer()` documentation for details. + +```solidity +event Transfer(address indexed _from, address indexed _to, uint256 _classId) +``` + +**Approval** +This event MUST trigger on any successful call to `approve(_to, _classId, quantity)` (unless the caller is attempting to clear approval when there is no pending approval). + +```solidity +event Approval(address indexed _owner, address indexed _approved, uint256 _classId) +``` +## Rationale + +### Current Limitations +The design of this project was motivated when I tried to create different classes of fungible ERC-721 tokens (an oxymoron) but ran into gas limits from having to create each tokens individually and maintain them in an efficient data structure for access. Using the maximum gas amount one can send with a transaction on Metamask (a popular web wallet), I was only able to create around 46 ERC-721 tokens before exhausting all gas. This experience motivated the creation of the multi-class fungible token standard. + + +## Backwards Compatibility + +Adoption of the MCFT standard proposal would not pose backwards compatibility issues as it defines a new standard for token creation. This standard follows the semantics of ERC-721 as closely as possible, but can't be entirely compatible with it due to the fundamental differences between multi-class fungible and non-fungible tokens. For example, the `ownerOf`, `takeOwnership`, and `tokenOfOwnerByIndex` methods in the ERC-721 token standard cannot be implemented in this standard. Furthermore, the function arguments to `balanceOf`, `approve`, and `transfer` differ as well. + +## Implementation + +Coming soon. + +## Copyright +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 44cbfc2833570ada682c9bd1ae1ed2669c1046b0 Mon Sep 17 00:00:00 2001 From: achon22 Date: Fri, 22 Jun 2018 14:08:16 -0400 Subject: [PATCH 2/7] added standard --- EIPS/eip-1169.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/EIPS/eip-1169.md b/EIPS/eip-1169.md index 184c1a636c2eb..1909a2e05d31a 100644 --- a/EIPS/eip-1169.md +++ b/EIPS/eip-1169.md @@ -4,9 +4,11 @@ title: Multi-class Token Standard author: Albert Chon discussions-to: https://ethereum-magicians.org/t/erc-1169-multi-class-fungible-tokens/588 status: Draft -type: Standards Track - Interface +type: Standards Track +category: ERC created: 2018-06-22 --- + ## Simple Summary From 38f78742c17fc168dd68e03898eebd7a31fb7515 Mon Sep 17 00:00:00 2001 From: achon22 Date: Fri, 22 Jun 2018 14:28:51 -0400 Subject: [PATCH 3/7] Update and rename eip-1169.md to eip-1179.md --- EIPS/{eip-1169.md => eip-1179.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename EIPS/{eip-1169.md => eip-1179.md} (99%) diff --git a/EIPS/eip-1169.md b/EIPS/eip-1179.md similarity index 99% rename from EIPS/eip-1169.md rename to EIPS/eip-1179.md index 1909a2e05d31a..5643258e82574 100644 --- a/EIPS/eip-1169.md +++ b/EIPS/eip-1179.md @@ -1,8 +1,8 @@ --- -eip: 1169 +eip: 1179 title: Multi-class Token Standard author: Albert Chon -discussions-to: https://ethereum-magicians.org/t/erc-1169-multi-class-fungible-tokens/588 +discussions-to: https://github.com/ethereum/EIPs/issues/1179 status: Draft type: Standards Track category: ERC From d20176ae0b21812c2b02e91ae1abb03b82f500c7 Mon Sep 17 00:00:00 2001 From: achon22 Date: Fri, 22 Jun 2018 14:31:09 -0400 Subject: [PATCH 4/7] Update eip-1179.md --- EIPS/eip-1179.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1179.md b/EIPS/eip-1179.md index 5643258e82574..fde9508d918a7 100644 --- a/EIPS/eip-1179.md +++ b/EIPS/eip-1179.md @@ -1,5 +1,5 @@ --- -eip: 1179 +eip: 1178 title: Multi-class Token Standard author: Albert Chon discussions-to: https://github.com/ethereum/EIPs/issues/1179 From 45c89373d02ab64756e97bd6ba1ea77243ac66a4 Mon Sep 17 00:00:00 2001 From: achon22 Date: Fri, 22 Jun 2018 14:31:26 -0400 Subject: [PATCH 5/7] name change --- EIPS/{eip-1179.md => eip-1178.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename EIPS/{eip-1179.md => eip-1178.md} (100%) diff --git a/EIPS/eip-1179.md b/EIPS/eip-1178.md similarity index 100% rename from EIPS/eip-1179.md rename to EIPS/eip-1178.md From 992b04ad0de697a6b38e8baae7427e1a36120049 Mon Sep 17 00:00:00 2001 From: achon22 Date: Fri, 22 Jun 2018 14:33:28 -0400 Subject: [PATCH 6/7] Update eip-1178.md --- EIPS/eip-1178.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-1178.md b/EIPS/eip-1178.md index fde9508d918a7..c2a0c0bb365af 100644 --- a/EIPS/eip-1178.md +++ b/EIPS/eip-1178.md @@ -19,7 +19,7 @@ A standard interface for multi-class fungible tokens. This standard allows for the implementation of a standard API for multi-class fungible tokens (henceforth referred to as "MCFTs") within smart contracts. This standard provides basic functionality to track and transfer ownership of MCFTs. ## Motivation -Currently, there is no standard to support tokens that have multiple classes. In the real world, there are many situations in which defining distinct classes of the same token would be fitting (e.g. distinguishing between preferred/common/restricted shares of a company). Yet, such nuance cannot be supported in today's token standards. An ERC-20 token contract defines tokens that are all of one class while an ERC-721 token contract creates a class (defined by token_id) for each individual token. The ERC-XXXX token standard proposes a new standard for creating multiple classes of tokens within one token contract. +Currently, there is no standard to support tokens that have multiple classes. In the real world, there are many situations in which defining distinct classes of the same token would be fitting (e.g. distinguishing between preferred/common/restricted shares of a company). Yet, such nuance cannot be supported in today's token standards. An ERC-20 token contract defines tokens that are all of one class while an ERC-721 token contract creates a class (defined by token_id) for each individual token. The ERC-1178 token standard proposes a new standard for creating multiple classes of tokens within one token contract. > Aside: In theory, while it is possible to implement tokens with classes using the properties of token structs in ERC-721 tokens, gas costs of implementing this in practice are prohibitive for any non-trivial application. From 1ba1372f8911f12d040b638d1ae1d337738fd77f Mon Sep 17 00:00:00 2001 From: achon22 Date: Fri, 22 Jun 2018 14:59:05 -0400 Subject: [PATCH 7/7] Update eip-1178.md --- EIPS/eip-1178.md | 1 + 1 file changed, 1 insertion(+) diff --git a/EIPS/eip-1178.md b/EIPS/eip-1178.md index c2a0c0bb365af..b609cc121bb83 100644 --- a/EIPS/eip-1178.md +++ b/EIPS/eip-1178.md @@ -145,3 +145,4 @@ Coming soon. ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). +