IBC ERC-20 Developer Guide: Cross-Chain Token Conversion Between Cosmos and OKTC

Overview

The IBC ERC-20 functionality enables seamless asset conversion between native tokens in the Cosmos ecosystem and ERC-20 tokens on OKTC through the Cosmos IBC cross-chain protocol. This process involves two primary scenarios:

1. Cosmos-to-OKTC Conversion:
   Native tokens from Cosmos chains are transferred to OKTC as ERC-20 tokens, allowing participation in OKTC's EVM ecosystem. These tokens can later revert to their native Cosmos form via IBC.
2. OKTC-to-Cosmos Conversion:
   Existing OKTC ERC-20 tokens are transferred to Cosmos chains as native tokens, with the option to return to OKTC as ERC-20 tokens.

👉 Explore cross-chain token integration

Cosmos Native Token Cross-Chain to OKTC

Determining the ERC-20 Contract

When transferring Cosmos native tokens to OKTC as ERC-20 tokens, the corresponding ERC-20 contract must be deployed on OKTC. Deployment methods include:

• Automatic Deployment:
  OKTC's built-in IBC ERC-20 module auto-deploys contracts if enable_auto_deployment=true. The module maps IBC tokens to contract addresses, converting native tokens to ERC-20 tokens.

• Manual Deployment:
  Developers can deploy custom ERC-20 contracts and submit a TokenMappingProposal to establish the token-contract mapping. Custom contracts must implement:

  • mint_by_okc_module
  • send_to_ibc
  • Event: __OKCSendToIbc

ERC-20 Conversion Requirements

By default, Cosmos native tokens remain as IBC tokens (ibc/xxxxx) on OKTC. Conversion to ERC-20 occurs only if:

1. Automatic deployment is enabled (enable_auto_deployment=true).
2. A valid token-contract mapping exists via TokenMappingProposal.

Returning Tokens to the Source Chain

• IBC Tokens: Use standard IBC operations (e.g., Keplr wallet).
• ERC-20 Tokens: Call the contract’s send_to_ibc method, specifying the recipient address and amount.

👉 Learn more about IBC token transfers

Native OKTC ERC-20 Token Cross-Chain to Cosmos

ERC-20 Contract Specifications

To enable cross-chain transfers, ERC-20 contracts must include:

• mint_by_okc_module
• send_native20_to_ibc
• Event: __OKCSendNative20ToIbc

Token Mapping Proposal

A TokenMappingProposal is required to link the ERC-20 contract with an OKTC token. Example:

exchaincli tx gov submit-proposal token-mapping okb 0x45dD91b0289E60D89Cec94dF0Aac3a2f539c514a

Existing mappings can be queried via exchaincli query ERC-20 token-mapping.

Cross-Chain Operations

Call send_native20_to_ibc with:

• Target chain recipient address.
• Transfer amount.
• IBC portID and channelID (available in chain documentation).

Returning Tokens to OKTC

Tokens transferred out appear as IBC tokens on the target chain. To return:

1. Use the target chain’s IBC tools (e.g., Keplr) to transfer back to OKTC.
2. Specify the original portID and channelID.

OKTC handles the returned tokens as follows:

• Valid Mapping: Converts to ERC-20 tokens.
• Invalid Mapping: Maintains as IBC tokens or fails if the contract is non-functional.

FAQ

1. Can any Cosmos native token be converted to ERC-20 on OKTC?

Yes, provided the token meets OKTC’s IBC standards and either auto-deployment is enabled or a manual mapping exists.

2. What happens if the ERC-20 contract fails during cross-chain?

The IBC transfer fails, and tokens remain on the source chain.

3. How do I find the IBC portID and channelID for transfers?

Refer to OKTC’s IBC documentation or chain explorers for active channels.

4. Is there a fee for token mapping proposals?

Yes, proposal submission requires staking a governance fee (varies by chain parameters).

5. Can I delete a token mapping?

Yes, submit a proposal with an empty contract address ("") to remove an existing mapping.

6. Are there limits to cross-chain transfer amounts?

Limits depend on the source and destination chain’s IBC relayers and liquidity pools.

Conclusion