forked from DecentralizedClimateFoundation/DCIPs
157 lines
10 KiB
Markdown
157 lines
10 KiB
Markdown
---
|
||
eip: 1178
|
||
title: Multi-class Token Standard
|
||
author: Albert Chon <achon@stanford.edu>
|
||
discussions-to: https://github.com/ethereum/EIPs/issues/1179
|
||
status: Stagnant
|
||
type: Standards Track
|
||
category: ERC
|
||
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-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.
|
||
|
||
## 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.)
|
||
|
||
<!--
|
||
ActionPrior State_to addressNew StateEventClear unset approvalClear0ClearNoneSet new approvalClearXSet to XApproval(owner, X, _classId)Change approvalSet to XYSet to YApproval(owner, Y, _classId)Reaffirm approvalSet to XXSet to XApproval(owner, X, _classId)Clear approvalSet to X0ClearApproval(owner, 0, _classId)
|
||
Note: ANY change of ownership of an MCFT – whether directly through the `transfer` and `transferFrom` methods defined in this interface, or through any other mechanism defined in the conforming contract – MUST clear any and all approvals for the transferred MCFT. The implicit clearing of approval via ownership transfer MUST also fire the event `Approval(0, _classId)` if there was an outstanding approval. (i.e. All actions that transfer ownership must emit the same Approval event, if any, as would emitted by calling `approve(0, _classId)`.)-->
|
||
|
||
**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`).
|
||
|
||
## Advanced Ownership and Exchange
|
||
```solidity
|
||
function approveForToken(uint256 classIdHeld, uint256 quantityHeld, uint256 classIdWanted, uint256 quantityWanted)
|
||
```
|
||
Allows holder of one token to allow another individual (or the smart contract itself) to approve the exchange of their tokens of one class for tokens of another class at their specified exchange rate (see sample implementation for more details). This is equivalent to posting a bid in a marketplace.
|
||
|
||
```solidity
|
||
function exchange(address to, uint256 classIdPosted, uint256 quantityPosted, uint256 classIdWanted, uint256 quantityWanted)
|
||
```
|
||
Allows an individual to fill an existing bid (see above function) and complete the exchange of their tokens of one class for another. In the sample implementation, this function call should fail unless the callee has already approved the contract to transfer their tokens. Of course, it is possible to create an implementation where calling this function implicitly assumes approval and the transfer is completed in one step.
|
||
|
||
```solidity
|
||
transferFrom(address from, address to, uint256 classId)
|
||
```
|
||
Allows a third party to initiate a transfer of tokens from `from` to `to` assuming the approvals have been granted.
|
||
|
||
## 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
|
||
A sample implementation can be found [here](https://github.com/achon22/ERC-1178/blob/master/erc1178-sample.sol)
|
||
|
||
## Copyright
|
||
Copyright and related rights waived via [CC0](../LICENSE.md).
|
||
|