ERC-7254 Token revenue distribution standard (Token Revenue Sharing)

Draft · Tokens · created 2023-06-29

An extension standard that lets holders simply hold an ERC-20 token to receive a share of the revenue a project earns as a reward, and withdraw it themselves whenever they want.

Why it is needed

The ERC-20 token only defines functions for transferring and checking balances, so there is no common way for a project to distribute the revenue it earns to token holders. As a result, receiving rewards usually required locking up tokens separately, staking, or participating in farming. This process is cumbersome for users, and since each project does it differently, they are not compatible with each other. This standard extends ERC-20 to give holders an additional means of receiving payouts. Whenever a project earns revenue, it distributes that revenue to holders, and holders can check and withdraw the accumulated rewards. The original text cites as use cases a company paying dividends to token holders, and directly sharing revenue earned from business activities such as marketplaces, automated market makers (AMMs), or games.

What to implement

In depth

The reward-per-share (rewardPerShare) method

The core value for distribution is rewardPerShare for each reward token. When updateReward(address[] memory token, uint256[] memory amount) is called, it is updated by the formula rewardPerShare = rewardPerShare + amount / totalSupply(). In other words, the structure accumulates reward per share by dividing the distributed amount by the total supply. The current value is queried with getRewardPerShare(address token). Multiple reward tokens, not just one, can be updated together as an array.

Per-account state UserInformation

Each account's reward state is managed with the UserInformation struct. It has three fields. inReward is updated when a user's balance decreases, and outReward is updated when a user's balance increases. withdraw is the total amount of reward tokens withdrawn so far. A given account's information for a specific reward token is queried with informationOf(token, account), and the list of information across all reward tokens with informationOfBatch(account).

Checking and claiming rewards

The list of reward amounts an account can receive is checked with viewReward(address account). The actual claim is made by calling getReward(address[] memory token), passing the list of reward token addresses you want to receive as an argument. The usage this standard promotes is that checking and claiming are both possible directly from the holding state, without any locking or staking procedure.

Reward token management

Multiple reward tokens can be registered to a single revenue distribution token. The list of registered reward token addresses is returned by tokenReward(), and whether a given address is a reward token is checked with existsTokenReward(address token). The upper limit on the number of reward tokens is returned by maxTokenReward().

Position as an ERC-20 extension

This standard is an extension of ERC-20, adding an additional means of payout for holders on top of the existing transfer and balance functions. The scope the standard defines is updating holder rewards and allowing reward withdrawal. ERC7254.sol and IERC7254.sol files are provided as the reference implementation.

A Proposal in Draft Stage

The status of this document is Draft, meaning it is still a proposal at a draft stage whose content may change. The Rationale section is TBD (undetermined), and the Security Considerations section only states that it needs discussion, so the design rationale and security analysis have not yet been filled in.

Original ERC · ← ERCs