自定义 ERC20 集成

概述

在 solidity-ibc-eureka 的初始版本中，接收非原生代币（例如来自 Cosmos Hub 的 ATOM）时，会部署一个默认的 IBCERC20 合约，用于在以太坊上表示该代币。不过，许多通过 Cosmos Hub 进行跨链的团队希望在以太坊上拥有并控制自己的 ERC20 合约。由于 IBCERC20 由 ICS20Transfer 合约管理，且不可自定义，因此无法直接拥有其控制权。为了解决这一问题，我们允许团队部署自定义 ERC20 合约，但前提是该合约需要实现一个简单接口，使 ICS20Transfer 合约能够铸造和销毁代币。

优势

这种方式的优势包括：

自定义元数据

你可以在部署时自定义元数据和代币命名。代币初始名称不必是 ibc/transfer/channel-0...，而可以使用用户熟悉和识别的名称进行展示。

合约验证

更容易在 Etherscan 上完成合约验证。各项目可以更方便地验证为自身项目部署的 ERC20 合约，并通过将代币与官方项目域名关联来提升信任度。

更利于中心化交易所上线

这通常有助于更顺利地上线中心化交易所，并整体提升用户对跨链资产的信任。

完全控制权

你将完全拥有并控制在以太坊上代表你的代币的 ERC20 合约。

要求

若要替换默认的 IBCERC20，你的自定义 ERC20 合约必须实现 IMintableAndBurnable 接口：

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;
}

关于该接口的实现示例，你可以参考 solidity-ibc-eureka 仓库中的 RefImplIBCERC20.sol 合约。

访问控制要求

这些函数必须可由 ICS20Transfer 合约的代理合约调用：

主网: 0xa348CfE719B63151F228e3C30EB424BA5a983012

安全说明： mint 和 burn 函数的访问权限必须严格限制为仅 ICS20Transfer 代理可调用。允许任何其他地址或合约调用这些函数，都可能导致未授权的代币操作，并破坏你的代币完整性。虽然代币团队可以按需实现额外的访问控制或速率限制，但 ICS20Transfer 代理必须始终保留执行铸造和销毁操作的能力。 可升级性与可扩展性： 我们可能会随着时间推移更新接口，但会承诺保持向后兼容。虽然你的合约不要求必须可升级，但如果采用可升级设计，你就可以在未来更方便地接入我们新增的功能或改进。

可升级性

你并不需要为自定义 ERC20 部署可升级合约。我们承诺保持 IMintableAndBurnable 接口的稳定性。但请注意，如果未来我们向该接口扩展新的功能，不可升级的合约将无法使用这些新特性。

注册自定义 ERC20

ICS20Transfer 合约包含一个受权限控制的方法，可以通过 setCustomERC20 函数注册自定义 ERC20。

前置条件

只有被授予 ERC20_CUSTOMIZER_ROLE 的地址才能调用该函数。该角色由协议安全委员会设立，并由 Eureka Ops 多签进行管理。若要申请注册你的自定义 ERC20 合约，请加入我们的 Discord并提交支持工单。此外，代币在 Cosmos Hub 上的 denomination 必须已明确。该代币要么已经在 Hub 上线，要么如果源自其他链，则必须已知其原始 denomination 以及完整的 IBC 路径。我们要求该代币在注册前必须已经在 Cosmos Hub 上处于可用状态。

关键时序要求

必须在该代币首次通过 IBC 转入部署了自定义 ERC20 的链之前调用 setCustomERC20。一旦首次转账已经发生，ERC20 映射关系就会变为不可更改。

开始使用

如果你是资产发行方，并希望在以太坊上为你的代币部署自定义 ERC20 合约：

实现接口

部署你的自定义 ERC20 合约，并实现 IMintableAndBurnable 接口，同时为 ICS20Transfer 代理配置正确的访问控制。示例可参考 solidity-ibc-eureka 仓库中的参考实现。

申请注册

加入我们的 Discord并提交支持工单，申请注册你的自定义 ERC20 合约。

验证并上线

在 Etherscan 上验证你的合约，以获得更高透明度。如需帮助，请参阅 Etherscan Contract Verification page。验证完成后，你就可以开始跨链你的代币，并完全掌控其 ERC20 表示。

支持与资源

需要帮助完成自定义 ERC20 集成？我们的团队可以提供协助：

加入我们的 Discord并提交支持工单

其他资源：

如需技术规格，请访问 solidity-ibc-eureka repository
查看参考实现，获取示例 ERC20 合约
了解 Etherscan contract verification，进一步提升用户对你的代币的信任

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:

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.

Request Registration

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

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:

Join our Discord and open a support ticket

Additional resources:

For technical specifications, visit the solidity-ibc-eureka repository
View the reference implementation for a sample ERC20 contract
Learn about Etherscan contract verification to enhance trust in your token

​自定义 ERC20 集成

​概述

​优势

自定义元数据

合约验证

更利于中心化交易所上线

完全控制权

​要求

​访问控制要求

​可升级性

​注册自定义 ERC20

​前置条件

​关键时序要求

​开始使用

​支持与资源

​Custom ERC20 Integration

​Overview

​Benefits

Custom Metadata

Contract Verification

Improved CEX Listing

Full Control

​Requirements

​Access Control Requirements

​Upgradability

​Registering a Custom ERC20

​Prerequisites

​Critical Timing Requirement

​Getting Started

​Support and Resources

自定义 ERC20 集成

概述

优势

要求

访问控制要求

可升级性

注册自定义 ERC20

前置条件

关键时序要求

开始使用

支持与资源

Custom ERC20 Integration

Overview

Benefits

Requirements

Access Control Requirements

Upgradability

Registering a Custom ERC20

Prerequisites

Critical Timing Requirement

Getting Started

Support and Resources