Upgrade existing tokens into Interchain Token(s)

If you already have an ERC-20 token on one or more blockchains, you can turn it into an Interchain Token by deploying Token Managers. Token Managers can be either Lock/Release or Mint/Burn. Canonical tokens are registered under the local chain’s Lock/Release token manager and mint/burn on remote chains. They can be deployed to remote chains by anyone and don’t depend on a deployer address/salt.

The Interchain Token Service is deployed to 0xB5FB4BE02232B1bBA4dC8f81dc24C26980dE9e3C while the Interchain Token Factory is deployed to 0x83a93500d23Fbc3e82B410aD07A6a9F7A0670D66.

Now, let’s explore how to transform existing tokens into Interchain Tokens.

Canonical Tokens (Simple wrappers)

If you own an ERC-20 token on a single chain and want a wrapped, bridgeable version on other chains, register it as a Canonical Token with the Interchain Token Service using the Interchain Token Factory contract. Each token can only be registered a single time as a canonical chain.

Want to try this out? Use Remix to create your own ERC-20 and register your token on the Interchain Token Portal.

You can also do this directly via the InterchainTokenService.sol using InterchainTokenFactory.sol to register canonical tokens and deploy remote canonical tokens.

Follow these steps to register your token as a canonical token:

• Register your token as a canonical token using the registerCanonicalInterchainToken method on the InterchainTokenFactory.sol. This will deploy a Lock/Release - Token Manager on the source chain

Here is an example of registering a canonical token:

/**
 * @notice Registers a canonical token as an interchain token and deploys its token manager.
 * @param tokenAddress The address of the canonical token.
 * @return tokenId The tokenId corresponding to the registered canonical token.
 */
function registerCanonicalInterchainToken(address tokenAddress) external payable returns (bytes32 tokenId)

• Deploy a remote canonical interchain token for a pre-existing token on remote chains using the deployRemoteCanonicalInterchainToken method on the InterchainTokenFactory for each destination chain. This will create the token on each destination chain and its registered under Mint/Burn - Token Manager. They can be deployed to remote chains by anyone and don’t depend on a deployer address/salt

Here is an example of deploying a remote canonical token:

/**
 * @notice Deploys a canonical interchain token on a remote chain.
 * @param originalChain The name of the chain where the token originally exists.
 * @param originalTokenAddress The address of the original token on the original chain.
 * @param destinationChain The name of the chain where the token will be deployed.
 * @param gasValue The gas amount to be sent for deployment.
 * @return tokenId The tokenId corresponding to the deployed InterchainToken.
 */
function deployRemoteCanonicalInterchainToken(
    string calldata originalChain,
    address originalTokenAddress,
    string calldata destinationChain,
    uint256 gasValue
) external payable returns (bytes32 tokenId)

• Approve the Interchain Token Service to spend tokens by calling the approve method on your token, specifying the Interchain Token Service address and the amount to be approved. Then, proceed to transfer Interchain Tokens between chains via the Interchain Token Service by calling the interchainTransfer method

If pre-mint is needed, you must make ERC20 approval to the Interchain Token Factory contract. When tokens are moved from the origin chain to another chain, the token will be locked on the origin chain and minted on the destination chain. If you moved tokens directly from one non-origin chain to another, the token would be burned on the source chain and minted on the destination chain.

Link deployed tokens on multiple chains into Interchain Token(s)

For custom functionality on multiple chains:

• Deploy your custom token on multiple chains or have existing versions on multiple chains
• Deploy a Mint/Burn - Token Manager for existing tokens on all chains using deployTokenManager on Interchain Token Service. The deployTokenManager method requires parameters like salt, destinationChain, tokenManagerType, params, and gasValue
• Transfer Interchain Tokens between chains via the Interchain Token Service by calling the interchainTransfer

You can optionally have any of these custom tokens extend IInterchainTokenStandard to offer interchainTransfer and interchainTransferFrom methods directly on your token.

You could decide to make all of these Token Managers Mint/Burn, or you could specify at most one (likely your primary/origin chain) to be Lock/Release as indicated in the ITokenManagerType.sol depending on your needs.

Here is an example of deploying a token manager:

/**
 * @notice Used to deploy TokenManagers.
 * @dev At least the `gasValue` amount of native token must be passed to the function call. `gasValue` exists because this function can be
 * part of a multicall involving multiple functions that could make remote contract calls.
 * @param salt The salt to be used during deployment.
 * @param destinationChain The name of the chain to deploy the TokenManager and standardized token to.
 * @param tokenManagerType The type of TokenManager to be deployed.
 * @param params The params that will be used to initialize the TokenManager.
 * @param gasValue The amount of native tokens to be used to pay for gas for the remote deployment.
 * @return tokenId The tokenId corresponding to the deployed TokenManager.
 */
function deployTokenManager(
    bytes32 salt,
    string calldata destinationChain,
    TokenManagerType tokenManagerType,
    bytes calldata params,
    uint256 gasValue
) external payable 

To create the params that will be used to initialize the Token Manager in the deployTokenManager method above, you can use the Online Ethereum ABI Encoder specifying the operator of the Token Manager and the token address with the argument type bytes and address respectively.

Note: If you want to build your token with the IInterchainToken feature yourself, make sure your token implements the IInterchainTokenStandard interface so you can offer interchainTransfer and interchainTransferFrom methods directly on your token.

You can try our sample custom token as a starting point. This token self-registers with the Interchain Token Service and can be deployed to multiple chains. Once you have designed your token, you can deploy it to multiple chains using a tool such as the Constant Address Deployer to give it the same address everywhere.