Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
ERC-1843 - Claims Token Standard #1843
A standard for a token that represents claims on future cash flow of an asset such as dividends, loan repayments, fee or revenue shares among large numbers of token holders. Anyone can deposit funds, token holders can withdraw their claims.
This standard proposes an efficient solution for distributing recurring payments such as dividends, loan repayments, fee or revenue shares among large numbers of token holders. The token holders are seen as fractional owners of future cash flow. The payments can be in Ether or ERC20 tokens and are stored in the token's "fund". Holders of a claims token can transfer their tokens at any time and can still be sure that their past claims to the cash flow of the token will be honored. The interface provides methods to deposit funds to be distributed, to get information about available funds and to withdraw funds a token holder is entitled to.
This standard can handle funds in Ether or in ERC223 compatible tokens.
In the DeFi and OpenFinance ecosystem assets such as debt positions, loans, derivatives and bonds are emerging. These assets incur future cash flows, e.g. repayments or dividends. Currently there is no standard for efficiently distributing claims on future cash flow of financial contracts among token holders. A clear and simple standard is needed to allow Dapps and exchanges to work with cash-flow producing tokens.
Sending cash flow to a large group of token holders whenever it is received is limited by gas consumption. Thus, a solution must be used in which token holders actively withdraw the cumulative funds that they have a claim on. A token holder must be able to withdraw funds she has a claim on at any time. It must also be possible to transfer tokens at any time and the already accrued claims must still be honored. This requires some background accounting to be done in the transfer functions. The claims token standard solves this elegantly.
Example: A bond is represented by 100 tokens. Alice owns all 100 of these tokens and Bob own zero. The bond yields 10 Ether. Alice has a claim on 100% of that cash flow because when the 10 Ether were received she owned all the tokens. She decides to not withdraw the tokens but wait until more has accumulated.
Now Alice sends 50 tokens to Bob. Shortly after the bond yield another 10 Ether. Now Alice has is entitled to 15 Ether and Bob to 5 Ether. The ownership history is honored and Alice doesn't need to withdraw before she transfers the tokens.
Requirements a claims token should fulfill
Executing tokenized financial contracts on a public ledger requires standards for distribution of cash flow incurred by the asset. In discussions with issuers the following requirements have been collected.
Requirements to observe when using the standard
The following requirements MUST be met in order to use the claims token standard.
Anyone can send Ether or tokens to be distributed among token holders. The default/fallback function behaves differently if Ether or tokens are sent to the contract.
In case of funds in Ether any Ether sent to the contract will be added to the fund by the default function.
In case of funds in ERC20/223 tokens the token that is registered will be added to the fund by the default function when it's sent to the contract.
The monotonously rising cumulative sum of funds received since the creation of the token. This number is the amount that the contract has had available for distribution so far.
Returns the amount of funds that can be withdrawn by a current or former token holder given as the
Withdraws the funds the message sender is entitled to at the time of execution of the function.
A field that stores a reference to the token used for the funds. In case of funds in Ether, the field must be set to
Emits when funds (Ether or tokens) are sent to the token contract's default/fallback function.
Emits when a token holder claims funds from the token contract.
The reference implementation consists of the accounting contract and two specializations. The first is for funds denoted in Ether and the second is for funds denoted in ERC20/ERC223 compatible tokens.
The claims token is realized by implementing the transfer functions to do the necessary accounting on two additional mappings (
Calculation of the available funds
The high efficiency of the solution is achieved by tracking 2 values for each token holder:
The available funds are calculated as the sum of the unprocessed funds and the claimed funds. Unprocessed funds are calculated by multiplying the ownership fraction with the difference between the total received funds and the fund that have already been considered for a user (
Total supply: 100 tokens
The Claims Token accounting system works in the background to take care of the fact that Alice's claims fraction changes and Bob sends his tokens away before withdrawing his available funds.
The standard is backwards compatible with ERC20 tokens.
Public domain via CC0
Yes, theoretically that is a potential problem. However it is limited by the economics of an attack:
why do you add this to token itself instead of using snapshots from MiniMe token (that btw. are used extensively in AragonOs apps) and implementing separate, specialized disbursal contract? claiming token is an app on the snapshot/MiniMe token protocol and 90% of the code to implement it, would be token snapshot re-implementation.
The MiniMe token is great, no question! It can probably be used to create an alternative implementation for the proposed interface. However, I see the snapshots as an unnecessary overhead for the core functionality of claims distribution. The elegance in our reference implementation lies in the fact that the balance history doesn't have to be recorded explicitly and it is still possible to correctly distribute payments to token holders. The consequence is that payments are free and transfers and payouts are very cheap, allowing for scaling to high frequency payments and large amounts of transfers.
The Claims Token is specifically designed to be integrated into the ERC1400 and similar modular frameworks. It adds a very well defined & limited functionality to Tokens derived from e.g. the OpenZeppelin reference implementations. Happy to discuss this further.
@Roger-Wu We're currently working on a merge between our approaches. It uses the implementation of #1726 but the terminology of this EIP #1843 (avoiding the term Dividend). We also integrated our solution for claims paid in Tokens, so now ERC20 token payments can be distributed. Let's have a conversation with on the past path to converge. I'll ping you via mail.