ERC-7621 Basket token
Draft · Vaults & DeFi · created 2024-02-11
A standard that bundles several ERC-20 tokens into a single token at target weights. Basket token holders have a proportional claim on all underlying assets, and a designated owner can adjust the composition and weights.
Why it is needed
Projects that want to build products holding several tokens at fixed ratios, like index funds, have so far each built their own differently designed contracts. There is ERC-4626, the single-asset vault standard, and ERC-7575, which extends it with multiple entry points, but neither standard fits a weighted basket whose manager changes the constituent tokens and target weights over time. Without a standard, wallets, aggregators, and DeFi protocols each have to integrate separately with every basket product. This standard defines, under one common interface, contribution (depositing assets to receive shares), withdrawal (burning shares to receive assets back proportionally), lookup of composition and target weights, and rebalancing (composition readjustment) by the owner. Because the basket contract itself is an ERC-20 token, it is compatible with existing token infrastructure as is.
What to implement
event Rebalanced(address[] newTokens, uint256[] newWeights);: An event that must be emitted whenever the set of constituent tokens or their weights changes. It records the new constituent token addresses and the new target weights.function getConstituents() external view returns (address[] memory tokens, uint256[] memory weights);: Returns the constituent token addresses along with each one's target weight (in basis points, summing to 10000). The return order stays stable between rebalance calls.function totalConstituents() external view returns (uint256 count);: Returns the number of constituent tokens.function getReserve(address token) external view returns (uint256 balance);: Returns the reserve of that constituent token recognized for share accounting. In implementations using internal accounting this may differ from the actual balanceOf.function getWeight(address token) external view returns (uint256 weight);: Returns the target weight of a specific constituent token in basis points. Reverts with NotConstituent if it is not a constituent token.function isConstituent(address token) external view returns (bool);: Returns whether the given address is currently a constituent token.function totalBasketValue() external view returns (uint256 value);: Returns the total value of the basket in the accounting unit defined by the implementation. It must be deterministic and consistent with previewContribute, and is not comparable across different implementations.function contribute(uint256[] calldata amounts, address receiver, uint256 minShares) external returns (uint256 lpAmount);: Deposits constituent tokens and mints shares to receiver. Reverts if the minted shares are less than minShares.function withdraw(uint256 lpAmount, address receiver, uint256[] calldata minAmounts) external returns (uint256[] memory amounts);: Burns shares and sends the reserves proportionally to receiver. Reverts if any token would return less than its corresponding minAmounts.function rebalance(address[] calldata newTokens, uint256[] calldata newWeights) external;: Updates the set of constituent tokens and target weights. Callable only by the owner() as defined in ERC-173.function previewContribute(uint256[] calldata amounts) external view returns (uint256 lpAmount);: Estimates the shares that would be minted for depositing the given amounts. Must equal the value contribute would return in the same transaction.function previewWithdraw(uint256 lpAmount) external view returns (uint256[] memory amounts);: Estimates the constituent token amounts that would be received for burning shares. Must equal the value withdraw would return in the same transaction.
In depth
Required interface and basic structure
A compliant contract must implement ERC-20 with the metadata extension (name, symbol, decimals), ERC-165, ERC-173, and IERC7621, all together. The contract's ERC-20 supply itself represents the shares, and holders have a proportional claim on the basket reserves. Each contract manages exactly one basket. It must return true via ERC-165 for the IERC7621 identifier 0xc9c80f73 and the ERC-173 identifier 0x7f5828d0. Implementing EIP-2612 for gasless approvals is optional.
Weights are target values expressed in basis points
Weights are expressed in basis points (10000 = 100%) and must sum to exactly 10000. A constituent token with a weight of 0 is not allowed; it must be removed instead. Weights are informational targets only and do not guarantee the current reserve ratio. Actual reserves may drift from the target between rebalances and during contributions and withdrawals. getConstituents() returns the target weights, while getReserve() returns the reserve recognized by the implementation's accounting; in implementations using internal accounting, getReserve() may differ from the actual balanceOf(address(this)).
Contribution mechanics and valuation
The amounts array passed to contribute must follow the getConstituents order, and each constituent token must be approved beforehand. Reverts with LengthMismatch if the array length differs from totalConstituents(), with ZeroAmount if all entries are zero, and with InsufficientShares if the minted shares fall below minShares. To prevent a larger contribution from yielding fewer shares, minting must be monotonically non-decreasing in the contributed amount, and rounding must favor the basket by rounding down. The implementation must define a deterministic valuation function that converts reserves into total value, report it via totalBasketValue(), and mint shares in proportion to the contributed value relative to this total value. The valuation method itself (summing balances, an oracle, time-weighted prices, etc.) is not specified by the standard.
Withdrawal mechanics
Withdrawal amounts are proportional to the shares burned, following the formula amount_i = reserve_i * lpAmount / totalSupply per constituent token, rounded down. Reverts with ZeroAmount if lpAmount is 0, reverts if the caller holds insufficient shares, with LengthMismatch if the minAmounts length differs from the number of constituents, and with InsufficientAmount if any token's returned amount falls below its minAmounts. withdraw must revert if totalSupply() is 0. To prevent reentrancy, share burning must occur before the constituent token transfers.
Standardized semantics of rebalance
rebalance is callable only by the owner() as defined in ERC-173, and must revert with LengthMismatch on mismatched array lengths, InvalidWeights if the weights do not sum to 10000, DuplicateConstituent for duplicate addresses, and ZeroAddress for the zero address, and must emit a Rebalanced event. The only standardized effect is updating the constituent set and target weights. Whether the actual assets are swapped to match the new weights is left to the implementation, so integrators must not assume that reserves match the new weights merely because rebalance was called. Renouncing ownership via transferOwnership(address(0)) permanently disables rebalance, so implementations seeking to avoid lockup are advised to restrict renouncement. Changes of ownership must not affect shareholders' claims.
Initialization rules and edge cases
In an empty basket where totalSupply() is 0, shares must be minted according to a deterministic initialization rule, which must match previewContribute under the same state and must not vary by caller. Mitigations such as dead shares or virtual shares are recommended to prevent a first-depositor inflation attack. previewContribute and previewWithdraw must return 0 rather than reverting when the input is 0, getReserve must return 0 for an address that is not a constituent token, and getWeight must revert with NotConstituent if the address is not a constituent token.
Scope not covered by the standard, and proposal status
This standard does not cover swap execution and routing during rebalancing, oracle design and pricing methodology, fee models, value comparisons across implementations, a registry for querying multiple baskets, or architectures that separate the share token externally. totalBasketValue() is meaningful only within that implementation's own accounting model. This proposal is currently in Draft status, so its content may change going forward.
Things to watch out for
- Reentrancy attack: contribute, withdraw, and rebalance call external ERC-20 contracts. Reentrancy guards or a checks-effects-interactions ordering must be followed, and in particular, in withdraw, share burning must occur before token transfers.
- First-contributor exchange rate manipulation: The first contributor to an empty basket can control the initial share-to-reserve exchange rate and extract value from later contributors. This is the same inflation attack known from ERC-4626, and minting a minimum number of shares to a dead address or using virtual shares is recommended.
- Rebalancing front-running: Because rebalancing transactions are visible in the mempool, the intended weight change is exposed, and implementations that execute swaps during rebalance can be sandwich-attacked. Private mempools, commit-reveal, off-chain routing with signature verification, and slippage limits are recommended.
- Trust in the owner: Shareholders must trust that the owner rebalances responsibly. The owner could swap constituent tokens into illiquid or worthless tokens, or trigger a rebalance at an unfavorable price. Timelocks, governance voting, and maximum slippage constraints can reduce this trust assumption, but the standard does not require them.
- Constituent tokens that block transfers: A constituent token with transfer restrictions such as a blacklist or pause function can halt all basket withdrawals. If even a single constituent token becomes untransferable, every holder's withdraw call will revert, so maintaining an allowlist or implementing a partial withdrawal mechanism that skips untransferable tokens is recommended.