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

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

Original ERC · ← ERCs