IBC ERC-20 Developer Guide

Cross-chain interoperability is a cornerstone of the evolving blockchain ecosystem, enabling seamless asset transfers across disparate networks. The IBC ERC-20 functionality on OKTC (OKX Chain) leverages the Inter-Blockchain Communication (IBC) protocol to bridge tokens between the Cosmos ecosystem and OKTC’s EVM-compatible environment. This guide provides developers with a comprehensive understanding of how native tokens and ERC-20 assets can move bidirectionally while preserving value, control, and usability.

Whether you're migrating Cosmos-native tokens to OKTC or deploying ERC-20 assets across IBC-connected chains, this documentation outlines the technical requirements, deployment options, and operational workflows necessary for successful cross-chain integration.

Understanding IBC ERC-20 Functionality

The IBC ERC-20 feature enables two primary use cases:

1. Cosmos-native tokens → OKTC as ERC-20:
   A native token from any IBC-connected Cosmos chain can be transferred to OKTC and automatically or manually converted into an ERC-20 token. This allows it to participate in OKTC’s EVM-based DeFi, NFT, and dApp ecosystems. The process is reversible—users can send the ERC-20 back and reclaim the original Cosmos-native asset.
2. OKTC-native ERC-20 tokens → Cosmos chains:
   An existing ERC-20 token on OKTC can be bridged to other Cosmos chains via IBC, where it appears as a native IBC token. This expands the reach of OKTC-based projects into the broader Cosmos network.

👉 Learn how to deploy cross-chain tokens securely and efficiently.

It’s important to distinguish between these two flows:

• In the first case, the source token originates outside OKTC (e.g., ATOM, JUNO).
• In the second, the token already exists on OKTC as an ERC-20 and is being exported.

This bidirectional bridge enhances liquidity, composability, and user accessibility across ecosystems.

Transferring Cosmos-Native Tokens to OKTC

When a Cosmos-native token is sent to OKTC via IBC, it does not automatically become an ERC-20 token. Instead, its behavior depends on configuration and contract mapping.

How Is the Corresponding ERC-20 Contract Determined?

To convert a Cosmos-native token into an ERC-20 on OKTC, one of two methods is used:

1. Automatic Deployment by OKTC

OKTC includes a built-in IBC ERC-20 contract that supports essential functions for cross-chain minting and burning. If the enable_auto_deployment=true parameter is enabled in the ERC-20 module, OKTC will automatically deploy an ERC-20 wrapper when a new IBC token arrives. The system maintains a mapping between the ibc/xxxxx denomination and the deployed contract address, allowing automatic conversion.

This method is ideal for projects seeking plug-and-play compatibility without custom logic.

2. Manual Deployment by Project Teams

For teams requiring advanced features—such as governance mechanisms, fee distribution, or vesting schedules—a custom ERC-20 contract can be deployed. However, to ensure IBC compatibility, the following must be implemented:

• mint_by_okc_module(address to, uint256 amount) – Allows the OKTC module to mint tokens upon inbound transfer.
• send_to_ibc(address recipient, uint256 amount) – Initiates the return journey to the source chain.
• __OKCSendToIbc – Emits an event recognized by the IBC handler.

A TokenMappingProposal must then be submitted to register the relationship between the IBC token (ibc/xxxxx) and the custom contract address.

👉 Explore secure smart contract deployment practices for cross-chain assets.

Does Every Cosmos Token Become an ERC-20 on OKTC?

No—by default, incoming Cosmos-native tokens remain as ibc/xxxxx tokens within OKTC unless one of the following conditions is met:

• Automatic deployment is enabled (enable_auto_deployment = true)
• A manual token mapping has been established via governance proposal

Otherwise, the token remains in its native IBC form and can still be used in wallets or basic transfers but won’t be accessible in EVM dApps that expect standard ERC-20 interfaces.

Returning ERC-20 Tokens to Their Source Chain

There are two scenarios for returning assets:

Case 1: Returning ibc/xxxxx Tokens

These can be sent back using standard IBC tools like Keplr Wallet or CLI commands—no smart contract interaction required.

Case 2: Returning ERC-20 Tokens

If the asset was converted to an ERC-20 (either automatically or manually), users must call the send_to_ibc(recipient, amount) function on the corresponding contract. This triggers a burn on OKTC and initiates an IBC packet to deliver the equivalent native token back to the original Cosmos chain.

This ensures full reversibility and trustless cross-chain movement.

Bridging Native OKTC ERC-20 Tokens to Cosmos Chains

OKTC also supports exporting locally issued ERC-20 tokens to other Cosmos SDK-based chains through IBC.

Contract Requirements for Exporting ERC-20s

To enable cross-chain transfer of an OKTC-native ERC-20 token, the contract must implement specific interfaces defined in INativeERC-20.sol:

• mint_by_okc_module(address to, uint256 amount) – Enables minting on receipt of IBC packets.
• send_native20_to_ibc(address recipient, uint256 amount, string memory portID, string memory channelID) – Initiates the outbound transfer.
• __OKCSendNative20ToIbc – Event emitted to signal cross-chain action.

These functions ensure that tokens can be safely locked on OKTC and minted on the destination chain.

Is Token Mapping Required?

Yes. Even if your contract implements all required methods, you must submit a TokenMappingProposal to link your ERC-20 contract address with a designated token identifier on OKTC (e.g., mytoken). Once approved by governance, this mapping enables recognition by the IBC module.

You can verify existing mappings using:

exchaincli query erc-20 token-mapping

Leaving the contract field empty ("") removes an existing mapping.

How to Execute Cross-Chain Transfer

After deployment and mapping approval:

1. Call send_native20_to_ibc() with:

   • Target recipient address
   • Amount
   • Destination port ID
   • Destination channel ID

Port and channel IDs can be found in chain explorers or configuration files of connected Cosmos zones.

This call locks the specified amount on OKTC and sends an IBC message to mint equivalent tokens on the destination chain.

Recovering Tokens Sent Across Chains

If an OKTC-based ERC-20 is transferred out via IBC and later returned:

• With valid mapping & functioning contract: Automatically converted back into ERC-20 form.
• With broken or faulty contract: Transfer fails; investigation and fix required.
• With deleted mapping: Token remains as ibc/xxxxx on OKTC under the original denomination used during registration.

This ensures safety even in edge cases.

Frequently Asked Questions (FAQ)

Q: Can I customize my ERC-20 contract when importing a Cosmos-native token?
A: Yes. While automatic deployment offers convenience, you can deploy a custom contract as long as it implements mint_by_okc_module, send_to_ibc, and emits __OKCSendToIbc. Then submit a TokenMappingProposal.

Q: What happens if I don’t enable auto-deployment or create a mapping?
A: The token will exist on OKTC as an ibc/xxxxx asset—usable for transfers but not in EVM dApps expecting ERC-20 standards.

Q: Do I need permission to export my ERC-20 token to Cosmos chains?
A: Yes. You must go through governance by submitting a TokenMappingProposal. This ensures security and prevents unauthorized wrappers.

Q: Can users interact with my cross-chain token in DeFi apps on OKTC?
A: Only if it’s in ERC-20 form. Native ibc/xxxxx tokens require wrapping before use in EVM-compatible protocols.

Q: Is there a fee for cross-chain transfers via IBC?
A: Yes. Standard gas fees apply on both sending and receiving chains. Fees vary based on network congestion and transaction complexity.

Q: How do I find the correct port and channel IDs for IBC transfers?
A: Use chain explorers like Mintscan or consult relayer configurations. Common pairs include transfer as port ID and pre-established channel numbers.

Core Keywords: IBC ERC-20, Cosmos ecosystem, OKTC, cross-chain transfer, ERC-20 bridge, smart contract deployment, token mapping, EVM compatibility

With robust tooling and clear standards, OKTC empowers developers to build truly interoperable applications across blockchain frontiers. By mastering these patterns, teams can unlock global liquidity and expand their user base across ecosystems.