ERC-6864 Upgradeable token (Upgradable Fungible Token)

Draft · Tokens · created 2023-04-05

An ERC-20 extension standard that lets an already-deployed ERC-20 token be upgraded to a new contract while preserving user balances, with the option to revert back to the original token if desired.

Why it is needed

Once a smart contract is deployed, its code cannot be changed. This means that when a bug is found in a token, or new features and standards need to be adopted, or regulatory changes need to be accommodated, there is no good way to modify an existing ERC-20 token. The commonly used proxy pattern only works if the contract was built as a proxy structure from the time of initial deployment, so it cannot be applied to tokens already deployed without a proxy. In addition, proxy upgrades happen silently without the user's knowledge and cannot be reverted, leaving users no option to refuse the upgrade. This standard narrows its scope to ERC-20 tokens, standardizing a way to layer a new contract on top of any already-deployed ERC-20 so it can be upgraded, with tokens moved only when the user explicitly consents, and with a path to revert if the user changes their mind.

What to implement

In depth

A design that extends ERC-20

IERC6864 is an interface that inherits from IERC20. The upgraded token still provides the standard ERC-20 functions such as transfer and balanceOf, so other contracts can keep interacting with it unmodified just by swapping the token address. The specification states that because the goal is to upgrade without affecting user balances, reusing existing data structures and methods is the path with the least engineering effort and the highest interoperability. The core interface consists of the two functions upgrade and downgrade, the two events Upgrade and Downgrade, and the baseToken lookup function that reports the base token address.

Requirements of the upgrade function

upgrade(to, amount) converts an amount of the base ERC-20 token held by msg.sender into ERC-6864 tokens for to. It MUST revert if to is the zero address, and it MUST revert if msg.sender does not directly hold at least amount of the base token. It MUST emit an Upgrade event on execution. The reference implementation moves the base token into the contract via transferFrom and then mints the same amount via _mint. In other words, the base token does not disappear; it is held by the ERC-6864 contract, and minting happens at the moment upgrade is called.

The downgrade function and reverting

downgrade(from, to, amount) burns an amount of ERC-6864 tokens held by from and returns the base ERC-20 token to to. It MUST revert if to is the zero address, if from holds less than amount, or if msg.sender is not from itself and has not been approved to spend at least amount. It MUST emit a Downgrade event on execution. The specification states that downgrading allows moving between multiple ERC-6864 implementations built on the same base token, and provides an exit if a bug or limitation is found in the new contract or if the user simply changes their mind.

The optional see-through extension

The see-through extension IERC6864SeeThrough defines three functions, combinedTotalSupply, combinedBalanceOf, and combinedAllowance, that show the combined state of the ERC-6864 contract and the base ERC-20 contract. The specification notes that these functions are useful in various situations but are easy to implement and the same values can be computed from other public functions, so they were placed in an optional extension rather than the core interface. Implementation is OPTIONAL.

Comparison with the proxy pattern and ERC-4931

The proxy pattern using delegatecall is a general-purpose upgrade solution, but it can only be used on contracts deployed as proxies from the start, the upgrade happens silently and irreversibly, and users cannot opt out. This standard, by contrast, applies to any existing or future ERC-20, is simpler to implement and maintain, can be reverted or nested, and gives users an explicit double-confirmation opportunity to opt in. ERC-4931, which addresses the same problem, separates token logic from upgrade logic with a dedicated bridge contract, but it requires tokens to be pre-minted at the destination contract and held by the bridge, and the specification notes it does not support upgrading during transfer or see-through functions.

Backward compatibility and the combined-balance transfer approach

This standard is broadly compatible with ERC-20. However, for user convenience some implementations may make transfer operate on the combined balance across both contracts rather than just the standard balanceOf amount. The reference implementation does this: if the ERC-6864 balance is insufficient during a transfer, it automatically upgrades the shortfall before sending. Contracts that take this approach are RECOMMENDED to implement totalSupply and balanceOf to also return the combined amount across both contracts. The reference implementation's totalSupply adds its own supply to the base token supply and then subtracts the amount of base token held by the contract, to avoid double counting.

The conversion ratio is left to the implementation

The conversion function used for upgrading and downgrading is left entirely to the implementation. The specification states that one-to-one, linear, and nonlinear conversions are all possible. The reference implementation uses a one-to-one approach, minting the same amount of base token received and returning the same amount on burn. Using a nonlinear conversion carries separate security considerations.

A proposal in Draft status

This proposal was created on April 5, 2023, and is currently in Draft status. It is not yet a finalized standard, so bear in mind that the specification may change or the proposal may stall.

Things to watch out for

Original ERC · ← ERCs