​
Custom ERC20 Integration

​
Overview

In the initial release of solidity-ibc-eureka, receiving a non-native token (e.g., ATOM from Cosmos Hub) deploys a default IBCERC20 contract to represent that token on Ethereum.

Many teams bridging through the Cosmos Hub, however, want ownership and control over their ERC20 contracts on Ethereum. Since IBCERC20 is managed by the ICS20Transfer contract and isn’t customizable, direct ownership isn’t possible.

To address this, we allow teams to deploy custom ERC20 contracts—provided they implement a simple interface that lets the ICS20Transfer contract mint and burn tokens.

​
Benefits

The benefits of this approach include:

Custom Metadata

Customize metadata and token naming on deployment. Tokens will not initially be named ibc/transfer/channel-0... and can be represented with the name they are recognized by.

Contract Verification

Easier contract verification on Etherscan. Each project can easily verify the ERC20 contract deployed for their project to increase trust by associating the token with the official project domain.

Improved CEX Listing

This is likely to result in easier CEX listing and generally increased trust in the bridged asset.

Full Control

Complete ownership and control over the ERC20 contract representing your token on Ethereum.

​
Requirements

To replace the default IBCERC20, your custom ERC20 contract must implement the IMintableAndBurnable interface:

interface IMintableAndBurnable {
    /// @notice Mint new tokens to the Escrow contract
    /// @dev This function can only be called by an authorized contract (e.g., ICS20)
    /// @dev This function needs to allow minting tokens to the Escrow contract
    /// @param mintAddress Address to mint tokens to
    /// @param amount Amount of tokens to mint
    function mint(address mintAddress, uint256 amount) external;

    /// @notice Burn tokens from the Escrow contract
    /// @dev This function can only be called by an authorized contract (e.g., ICS20)
    /// @dev This function needs to allow burning of tokens from the Escrow contract
    /// @param mintAddress Address to burn tokens from
    /// @param amount Amount of tokens to burn
    function burn(address mintAddress, uint256 amount) external;
}

For an example implementation of this interface, you can refer to the RefImplIBCERC20.sol contract in the solidity-ibc-eureka repository.

​
Access Control Requirements

These functions must be callable by the proxy of the ICS20Transfer contract:

  • Mainnet: 0xa348CfE719B63151F228e3C30EB424BA5a983012

Security Note:
Access to the mint and burn functions must be strictly limited to the ICS20Transfer proxy. Allowing any other address or contract to call these functions could lead to unauthorized token manipulation and compromise the integrity of your token. While token teams may implement additional access controls or rate limits as needed, the ICS20Transfer proxy must always retain its ability to perform mint and burn operations.

Upgradability & Extensibility:
We may update our interface over time, but we’re committed to ensuring backwards compatibility. While making your contract upgradable is not required, doing so allows you to adopt new features or improvements we introduce in the future.

​
Upgradability

You are not required to deploy an upgradable contract for your custom ERC20. We commit to maintaining the stability of the IMintableAndBurnable interface. However, please note that if we extend the interface with new functionality in the future, a non-upgradable contract would not be able to utilize these new features.

​
Registering a Custom ERC20

The ICS20Transfer contract includes a permissioned method for registering a custom ERC20 via the setCustomERC20 function.

​
Prerequisites

Only addresses assigned the ERC20_CUSTOMIZER_ROLE can call this function. This role is established by the protocol’s security council and administered by the Eureka Ops multi-sig. To request registration of your custom ERC20 contract, join our Discord and open a support ticket.

Additionally, the token’s denomination on the Cosmos Hub must be established. The token must either be live on the Hub, or its original denomination and complete IBC path must be known if it originates elsewhere. We require the token to be active on the Cosmos Hub before registration can proceed.

​
Critical Timing Requirement

setCustomERC20 must be called before the first IBC transfer of the token to the chain where the custom ERC20 is deployed. Once the initial transfer is made, the ERC20 mapping becomes immutable.

​
Getting Started

If you’re an asset issuer looking to deploy a custom ERC20 contract for your token on Ethereum:

1

Implement the Interface

Deploy your custom ERC20 contract that implements the IMintableAndBurnable interface with proper access controls for the ICS20Transfer proxy. For an example, see the reference implementation in the solidity-ibc-eureka repository.

2

Request Registration

Join our Discord and open a support ticket to request registration of your custom ERC20 contract.

3

Verify and Launch

Verify your contract on Etherscan for greater transparency. For assistance, see the Etherscan Contract Verification page. Once verified, start bridging your token with complete control over its ERC20 representation.

​
Support and Resources

Need help with your custom ERC20 integration? Our team is ready to assist:

Additional resources: