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
function maxTokenReward() public view returns (uint256): Returns the maximum number of reward tokens.function informationOf(address token, address account) public view returns (UserInformation memory): Returns an account's information (inReward, outReward, withdraw) for a specific reward token.function informationOfBatch(address account) public view returns (UserInformation[] memory): Returns a list grouping an account's reward information (inReward, outReward, withdraw) by reward token.function tokenReward() public view returns (address[] memory): Returns the list of reward token addresses registered to this token.function updateReward(address[] memory token, uint256[] memory amount) public: Updates the rewardPerShare value for each reward token. It adds amount divided by totalSupply() to rewardPerShare.function viewReward(address account) public view returns (uint256[] memory): Returns, as a list by reward token, the reward amounts an account can receive.function getReward(address[] memory token) public: Claims the accumulated rewards for the specified list of reward tokens.function getRewardPerShare(address token) public view returns (uint256): Returns the reward-per-share (rewardPerShare) value for that reward token.function existsTokenReward(address token) public view returns (bool): Returns whether that address is registered as a reward token.
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.