IBC ERC-20 Cross-Chain Conversion Guide

Introduction

The IBC ERC-20 functionality enables seamless asset conversion between the Cosmos ecosystem and the OKTC network. By leveraging the Cosmos Inter-Blockchain Communication (IBC) protocol, native tokens from Cosmos can be represented as ERC-20 tokens on OKTC, and vice versa. This interoperability allows users to participate in both ecosystems without sacrificing asset utility.

This guide explains the technical requirements, conversion processes, and operational steps for transferring assets between these networks. Whether you are a developer, project owner, or advanced user, understanding these mechanisms will help you navigate cross-chain transactions effectively.

Converting Cosmos Native Tokens to OKTC ERC-20

Determining the Corresponding ERC-20 Contract

When transferring a native Cosmos token to OKTC as an ERC-20 token, a corresponding ERC-20 contract must exist on OKTC. There are two primary methods for establishing this contract:

1. Automatic Deployment by OKTC: OKTC features a built-in IBC ERC-20 contract. If the network parameter enable_auto_deployment is set to true, this contract is deployed automatically upon the arrival of a Cosmos native token via IBC. The system maintains a mapping between the IBC token and the new contract address, automatically converting the incoming tokens into ERC-20 tokens for the recipient.
2. Manual Deployment by Projects: For projects requiring customized ERC-20 contract features, manual deployment is necessary. After developing and deploying a custom contract to OKTC, a TokenMappingProposal must be initiated to register the mapping between the IBC token and the new contract address. It is critical that any custom contract implements the exact same interface as the built-in contract, including the methods mint_by_okc_module and send_to_ibc, and the event __OKCSendToIbc.

Is Conversion to ERC-20 Mandatory?

By default, a Cosmos native token arriving on OKTC via IBC remains an IBC token (denoted by a ibc/xxxxx denom). Conversion to an ERC-20 token only occurs under two specific conditions:

• The OKTC chain has the enable_auto_deployment parameter set to true.
• A valid mapping between the specific IBC token and an ERC-20 contract address has been officially established via a TokenMappingProposal.

Without meeting one of these conditions, the asset will remain an IBC token within the OKTC ecosystem.

Returning ERC-20 Tokens to the Source Chain

Once a Cosmos native token is on OKTC, its state determines how it is sent back to its origin chain.

• As an OKTC IBC Token: If the token was not converted to ERC-20, standard IBC transfer operations (e.g., using a Keplr wallet) can return it to the source chain.
• As an OKTC ERC-20 Token: If the token was converted, you must interact with its smart contract. Calling the send_to_ibc method on the contract and providing the recipient's address on the source chain and the transfer amount will initiate the process. The tokens are then returned and converted back to the original Cosmos native asset.

👉 Explore more strategies for cross-chain asset management

Converting Native OKTC ERC-20 Tokens to Cosmos

ERC-20 Contract Specifications

To transfer a native OKTC ERC-20 token to a Cosmos chain, the token's smart contract must adhere to a specific interface. The contract must implement the following critical components:

• Method: mint_by_okc_module
• Method: send_native20_to_ibc
• Event: __OKCSendNative20ToIbc

Developing a contract without these elements will prevent it from being compatible with the IBC cross-chain functionality on OKTC.

Establishing a Token Mapping Proposal

Beyond the technical contract specifications, a formal mapping must be created on-chain. This is achieved by initiating and passing a TokenMappingProposal that links the ERC-20 contract address to a token denomination on OKTC (e.g., okb). This governance step is mandatory for the cross-chain functionality to be activated. The proposal can also be used to delete an existing mapping if necessary. You can check current mappings on the OKTC chain using the query command exchaincli query erc-20 token-mapping.

Operating the Cross-Chain Transfer

Once the compliant contract is deployed and the mapping proposal is approved, users can initiate transfers. This is done by calling the send_native20_to_ibc method on the ERC-20 contract. The call must include:

• The recipient's address on the target Cosmos chain.
• The amount of tokens to transfer.
• The correct IBC portID and channelID for the destination chain. These identifiers must be obtained from reliable chain information sources.

Returning Assets to OKTC

An ERC-20 token transferred out to a Cosmos chain will typically exist there as an IBC token. To return it to OKTC, use the IBC transfer tools available on that Cosmos chain (e.g., a wallet like Keplr or a cross-chain bridge), ensuring you use the same channel and port identifiers used for the original outgoing transfer.

Upon arrival back on OKTC, one of three things will happen:

1. Successful Conversion: If the token mapping still exists and the contract executes correctly, the asset is converted back into an ERC-20 token.
2. Execution Failure: If the mapping exists but the contract interaction fails (e.g., due to a bug), the IBC transfer will fail.
3. Mapping Deleted: If the mapping relationship has been removed, the token will remain on OKTC as the denomination that was originally registered in the mapping.

👉 Get advanced methods for managing smart contract interactions

Frequently Asked Questions

What is the primary benefit of IBC ERC-20 conversion?

The primary benefit is full interoperability. It allows decentralized application (dApp) users and developers to move assets freely between the expansive Cosmos ecosystem and the powerful EVM-compatible environment on OKTC. This unlocks greater liquidity and utility for assets that were previously confined to a single network.

Can any ERC-20 token on OKTC be transferred to Cosmos?

No, only ERC-20 tokens whose smart contracts have been specifically built to support the IBC standard (implementing the required methods and events) and which have successfully passed a TokenMappingProposal on OKTC are eligible for cross-chain transfer to Cosmos networks.

What happens if I send tokens to a wrong address during an IBC transfer?

IBC transactions, like most blockchain transactions, are irreversible. If tokens are sent to an incorrect or incompatible address on the destination chain, they may be permanently lost. It is crucial to double-check all recipient addresses and destination chain parameters before confirming any transaction.

Who is responsible for deploying the ERC-20 contract for a Cosmos token?

The responsibility can fall to either the OKTC network (if auto-deployment is enabled) or the project team behind the token. Projects that want custom token behavior (e.g., special minting or governance rules) must deploy and manage their own compliant contract and propose the token mapping.

How can I find the correct IBC channel ID for a transfer?

IBC channel IDs are not arbitrary; they are established through a process called "channel handshaking" between two chains. You should consult the official documentation or block explorers of both the source and destination chains to find the correct and active channel ID for the asset you wish to transfer. Using an incorrect channel will result in a failed transaction.