EIP-1178: Multi-class Token Standard

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

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

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

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

function totalSupply() constant returns (uint256 totalSupply)

Returns the total number of all MCFTs currently tracked by this contract.

individualSupply

function individualSupply(uint256 _classId) constant returns (uint256 individualSupply)

Returns the total number of MCFTs of class _classId currently tracked by this contract.

balanceOf

function balanceOf(address _owner, uint256 _classId) constant returns (uint256 balance)

Returns the number of MCFTs of token class _classId assigned to address _owner.

classesOwned

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

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

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

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.

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.

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.

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).

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

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Albert Chon, "EIP-1178: Multi-class Token Standard," Ethereum Improvement Proposals, no. 1178, June 2018. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-1178.