ERC-7417 Token standard converter (Token Converter)

Review · Tokens · created 2023-07-27

Defines a converter contract that can convert an ERC-20 token into its ERC-223 version at any time at a 1:1 ratio, and convert it back to ERC-20 again. A single token exists simultaneously in both standards and can be freely exchanged.

Why it is needed

Ethereum uses several token standards side by side, but they are not compatible with each other. Because the most widely used ERC-20 already has an established ecosystem, even when a new standard appears there is no defined procedure for migrating to it, creating a bottleneck that blocks adoption. Token developers must pick one standard at deployment time and stick with it, with no way to use the advantages of another standard even if they want to. On top of that, implementations of the same ERC-20 vary significantly. The source points out that, regarding the return value of the transfer function, tokens are inconsistent: some return true on success and revert on failure, some return false, and some have no return value at all (most notably USDT), making them incompatible with each other. This proposal aims to provide a shared conversion service that lets anyone create a different-standard version of an existing token, so that two versions can coexist and be exchanged for each other without needing to choose only one standard.

What to implement

In depth

Two components: the converter and the wrapper

The system consists of a Converter contract and wrapper contracts. A given original token can have exactly one wrapper per standard, and every ERC-20 token MUST have exactly one corresponding ERC-223 wrapper. Because wrappers are deployed with the CREATE2 opcode, their address can be precomputed with predictWrapperAddress even before deployment. Since the wrapper address depends on its bytecode, the _isERC20 argument must specify whether the wrapper being predicted is ERC-20 or ERC-223. According to the rationale, the bidirectional design that also creates an ERC-20 wrapper for an original ERC-223 token was chosen to support developers who deployed on ERC-223 first and to let decentralized exchanges recognize the two versions as a valid pair.

1:1 conversion rule

When the converter receives an ERC-20 deposit, it MUST send the same amount of ERC-223 tokens. Depositing 1234 units of ERC20 token_A yields exactly 1234 units of ERC223 token_A. The ERC-223 token is newly minted at the time of deposit, and the original ERC-20 is frozen in the converter so it can be reclaimed later. Conversely, when an ERC-223 deposit is received, the held original ERC-20 is released 1:1 and the received ERC-223 wrapper must be burned. There is no separate function to convert an ERC-223 wrapper back to ERC-20; this logic is implemented inside the converter's tokenReceived function.

Wrapper creation and lack of standard verification

createERC223Wrapper and createERC20Wrapper only create a new wrapper if one does not already exist, and revert if one already exists. A wrapper cannot have a wrapper of its own. These functions do not verify the standard of the input token, because there is no reliable way to guarantee that a specific standard is implemented, and as a result combinations such as creating an ERC-223 wrapper for an ERC-223 original are also possible. Every ERC-223 wrapper created by the converter uses the same code, implementing approve and transferFrom functions for compatibility with the existing ecosystem and also emitting ERC-20-style Transfer events. This is a choice that prioritizes compatibility so existing explorers and wallets can recognize transfer history.

Standard identification via the standard() function

Since ERC-165 only checks function signatures, it cannot distinguish whether the internal transfer logic is ERC-20-style or ERC-223-style, and many tokens do not even implement ERC-165 itself. For this reason, every ERC-223 wrapper deployed by the converter implements a standard() function that returns 223, and it is assumed that an original ERC-223 token can likewise declare itself via the same function. If this function is absent, the token is treated as ERC-20. The source text describes this approach as a more precise method of standard identification than ERC-165. However, the return type notation for this function is written inconsistently in the source text, variously as bytes32, uint32, or string.

Rescue of directly transferred tokens

An ERC-20 token can be sent via transfer to any contract, and the recipient has no way to recognize it, so the converter must separately record the amount formally deposited through wrapERC20toERC223. The extractStuckERC20 function allows withdrawal of the difference between the token contract's balanceOf(address(this)) value and the recorded deposit amount, that is, the amount sent directly by mistake, preventing users from permanently losing their tokens. In the reference implementation, only a designated extractor address can call this function, and the wrapper contract also has a similarly purposed rescueERC20 function.

Caution regarding approve and transferFrom

In ERC-223, a deposit to a contract can be made with transfer alone, making approve and transferFrom unnecessary, but they were included in the wrapper for compatibility with existing contracts such as multisigs that were built on the assumption of receiving tokens without a callback. However, since transferFrom does not support error handling, sending tokens into a contract that approves itself and then receives tokens via transferFrom, when that contract was not designed for this, can permanently lock the tokens. The source text explicitly states that transfers via the approve/transferFrom method should be avoided as much as possible for ERC-223 tokens.

Proposal status: Review

This proposal's status is Review. It is not yet a finalized standard, and its content may change during the review process. The source text states that it will resolve trust concerns by specifying the deployed converter address in the body, but the address is not yet written in the body as of now.

Things to watch out for

Original ERC · ← ERCs