EIP1203 - ERC-1203 Multi-Class Token Standard (ERC-20 Extension)

# Simple Summary

A standard interface for multi-class tokens (MCTs).

# Abstract

The following standard allows for the implementation of a standard API for MCTs within smart contracts. This standard provides basic functionality to track, transfer, and convert MCTs.

# Motivation

This standard is heavily inspired by ERC-20 Token Standard and ERC-721 Non-Fungible Token Standard. However, whereas these standards are chiefly concerned with representation of items/value in a single class, fungible or note, this proposed standard focus on that of a more complexed, multi-class system. It is fair to think of MCTs as a hybrid of fungible tokens (FT) and non-fungible tokens (NFTs), that is tokens are fungible within the same class but non-fungible with that from a different class. And conversions between classes may be optionally supported.

MCTs are useful in representing various structures with heterogeneous components, such as:

Abstract Concepts: A company may have different classes of stocks (e.g. senior preferred, junior preferred, class A common, class B common) that together make up its outstanding equities. A shareholder's position of such company composites of zero or more shares in each class.
Virtual Items: A sandbox computer game may have many types of resources (e.g. rock, wood, berries, cows, meat, knife, etc.) that together make up that virtual world. A player's inventory has any combination and quantity of these resources
Physical Items: A supermarket may have many SKUs it has available for purchase (e.g. eggs, milk, beef jerky, beer, etc.). Things get added or removed from a shopper's cart as it moves down the aisle.

It's sometimes possible, especially with regard to abstract concepts or virtual items, to convert from one class to another, at a specified conversion ratio. When it comes to physical items, such conversion essentially is the implementation of bartering. Though it might generally be easier to introduce a common intermediary class, i.e. money.

# Specification

contract ERC20 {
    function totalSupply() public view returns (uint256);
    function balanceOf(address _owner) public view returns (uint256);
    function transfer(address _to, uint256 _value) public returns (bool);
    function approve(address _spender, uint256 _value) public returns (bool);
    function allowance(address _owner, address _spender) public view returns (uint256);
    function transferFrom(address _from, address _to, uint256 _value) public returns (bool);

    event Transfer(address indexed _from, address indexed _to, uint256 _value);
    event Approval(address indexed _owner, address indexed _spender, uint256 _value);
}

contract ERC1203 is ERC20 {
    function totalSupply(uint256 _class) public view returns (uint256);
    function balanceOf(address _owner, uint256 _class) public view returns (uint256);
    function transfer(address _to, uint256 _class, uint256 _value) public returns (bool);
    function approve(address _spender, uint256 _class, uint256 _value) public returns (bool);
    function allowance(address _owner, address _spender, uint256 _class) public view returns (uint256);
    function transferFrom(address _from, address _to, uint256 _class, uint256 _value) public returns (bool);

    function fullyDilutedTotalSupply() public view returns (uint256);
    function fullyDilutedBalanceOf(address _owner) public view returns (uint256);
    function fullyDilutedAllowance(address _owner, address _spender) public view returns (uint256);
    function convert(uint256 _fromClass, uint256 _toClass, uint256 _value) public returns (bool);

    event Transfer(address indexed _from, address indexed _to, uint256 _class, uint256 _value);
    event Approval(address indexed _owner, address indexed _spender, uint256 _class, uint256 _value);
    event Convert(uint256 indexed _fromClass, uint256 indexed _toClass, uint256 _value);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# ERC-20 Methods and Events (fully compatible)

Please see ERC-20 Token Standard for detailed specifications. Do note that these methods and events only work on the "default" class of an MCT.

    function totalSupply() public view returns (uint256);
    function balanceOf(address _owner) public view returns (uint256);
    function transfer(address _to, uint256 _value) public returns (bool);
    function approve(address _spender, uint256 _value) public returns (bool);
    function allowance(address _owner, address _spender) public view returns (uint256);
    function transferFrom(address _from, address _to, uint256 _value) public returns (bool);

    event Transfer(address indexed _from, address indexed _to, uint256 _value);
    event Approval(address indexed _owner, address indexed _spender, uint256 _value);

1
2
3
4
5
6
7
8
9

# Tracking and Transferring

totalSupply

Returns the total number of tokens in the specified _class

    function totalSupply(uint256 _class) public view returns (uint256);

balanceOf

Returns the number of tokens of a specified _class that the _owner has

    function balanceOf(address _owner, uint256 _class) public view returns (uint256);

transfer

Transfer _value tokens of _class to address specified by _to, return true if successful

    function transfer(address _to, uint256 _class, uint256 _value) public returns (bool);

approve

Grant _spender the right to transfer _value tokens of _class, return true if successful

    function approve(address _spender, uint256 _class, uint256 _value) public returns (bool);

allowance

Return the number of tokens of _class that _spender is authorized to transfer on the behalf of _owner

    function allowance(address _owner, address _spender, uint256 _class) public view returns (uint256);

transferFrom

Transfer _value tokens of _class from address specified by _from to address specified by _to as previously approved, return true if successful

    function transferFrom(address _from, address _to, uint256 _class, uint256 _value) public returns (bool);

Transfer

Triggered when tokens are transferred or created, including zero value transfers

    event Transfer(address indexed _from, address indexed _to, uint256 _class, uint256 _value);

Approval

Triggered on successful approve

    event Approval(address indexed _owner, address indexed _spender, uint256 _class, uint256 _value);

# Conversion and Dilution

fullyDilutedTotalSupply

Return the total token supply as if all converted to the lowest common denominator class

    function fullyDilutedTotalSupply() public view returns (uint256);

fullyDilutedBalanceOf

Return the total token owned by _owner as if all converted to the lowest common denominator class

    function fullyDilutedBalanceOf(address _owner) public view returns (uint256);

fullyDilutedAllowance

Return the total token _spender is authorized to transfer on behalf of _owner as if all converted to the lowest common denominator class

    function fullyDilutedAllowance(address _owner, address _spender) public view returns (uint256);

convert

Convert _value of _fromClass to _toClass, return true if successful

    function convert(uint256 _fromClass, uint256 _toClass, uint256 _value) public returns (bool);

Conversion

Triggered on successful convert

    event Conversion(uint256 indexed _fromClass, uint256 indexed _toClass, uint256 _value);

# Rationale

This standard purposely extends ERC-20 Token Standard so that new MCTs following or existing ERC-20 tokens extending this standard are fully compatible with current wallets and exchanges. In addition, new methods and events are kept as closely to ERC-20 conventions as possible for ease of adoption.

We have considered alternative implementations to support the multi-class structure, as discussed below, and we found current token standards incapable or inefficient in deal with such structures.

Using multiple ERC-20 tokens

It is certainly possible to create an ERC-20 token for each class, and a separate contract to coordinate potential conversions, but the short coming in this approach is clearly evident. The rationale behind this standard is to have a single contract to manage multiple classes of tokens.

Shoehorning ERC-721 token

Treating each token as unique, the non-fungible token standard offers maximum representational flexibility arguably at the expense of convenience. The main challenge of using ERC-721 to represent multi-class token is that separate logic is required to keep track of which tokens belongs to which class, a hacky and unnecessary endeavor.

Using ERC-1178 token

We came across ERC-1178 as we were putting final touches on our own proposal. The two ERCs look very similar on the surface but we believe there're a few key advantages this one has over ERC-1178.

ERC-1178 offers no backward compatibility whereas this proposal is an extension of ERC-20 and therefore fully compatible with all existing wallets and exchanges
By the same token, existing ERC-20 contracts can extend themselves to adopt this standard and support additional classes without affecting their current behaviors
This proposal introduces the concept of cross class conversion and dilution, making each token class integral part of a whole system rather than many silos

# Backwards Compatibility

This EIP is fully compatible with the mandatory methods of ERC20 Token Standard so long as the implementation includes a "lowest common denominator" class, which may be class B common/gold coin/money in the abstract/virtual/physical examples above respectively. Where it is not possible to implement such class, then the implementation should specify a default class for tracking or transferring unless otherwise specified, e.g. US dollar is transferred unless other currency is explicitly specified.

We find it contrived to require the optional methods of ERC20 Token Standard, name(), symbol(), and decimals(), but developers are certainly free to implement these as they wish.

# Test Cases

The repository at jeffishjeff/ERC-1203 (opens new window) contains the sample test cases (opens new window).

# Implementation

The repository at jeffishjeff/ERC-1203 (opens new window) contains the sample implementation (opens new window).

# References

ERC-20 Token Standard. ./eip-20.md
ERC-721 Non-Fungible Token Standard. ./eip-721.md
ERC-1178 Multi-class Token Standard. ./eip-1178.md