ERC-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
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
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
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
Returns the total number of all MCFTs currently tracked by this contract.
individualSupply
Returns the total number of MCFTs of class _classId
currently tracked by this contract.
balanceOf
Returns the number of MCFTs of token class _classId
assigned to address _owner
.
classesOwned
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
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
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 ofquantity
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
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.
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.
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.
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).
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.