cosmos/evm 的 x/ibc 模块实现了对链间通信（IBC）协议的支持，并提供了专门的 EVM 回调功能，用于跨链智能合约交互。

​
概览

IBC 模块在标准 IBC 协议基础上扩展了面向 EVM 的特性：
  • IBC 回调：在 IBC 数据包生命周期中自动执行 EVM 合约
  • 跨链合约调用：使智能合约能够跨链交互
  • 数据包生命周期管理：通过 EVM 合约处理确认和超时

​
组成部分

​
IBC 回调

EVM 回调模块实现了 EVM contractKeeper 接口，并与 ibc-go 的 callbacks middleware 交互，专门用于 ICS-20 转账应用。 核心特性：
  • 目标链回调：在收到数据包时执行合约（onRecvPacket）
  • 源链回调：处理确认（onAcknowledgePacket）和超时（onTimeoutPacket）
  • 原子执行：合约调用与代币转账以原子方式同时发生

​
IBC 转账集成

该模块与 ICS20 转账应用紧密配合，以支持：
  • 向 EVM 合约发起跨链代币转账
  • 在收到资金后自动执行合约
  • 在链间传递自定义 calldata
智能合约可通过 ICS20 预编译 发起 IBC 转账。该预编译提供了带有 memo 字段回调支持的 transfer 函数。
地址格式限制：当前，IBC 转账的接收方地址必须为 bech32 格式（例如 cosmos1...）。虽然发送方地址会自动从十六进制格式转换为 bech32，但接收方地址必须显式提供为 bech32 格式。未来版本计划为接收方提供完整的十六进制地址支持。

​
回调类型

​
目标链回调（onRecvPacket）

当目标链收到数据包时执行，使合约能够：
  • 接收跨链代币
  • 使用收到的资金执行自定义逻辑
  • 执行如 DEX 兑换或流动性提供等操作

​
源链回调（onAcknowledgePacket 与 onTimeoutPacket）

当数据包生命周期在源链完成时执行，使合约能够：
  • 处理成功转账的确认
  • 从失败或超时的转账中恢复资金
  • 为失败转账实现重试逻辑

​
实现细节

​
Memo 格式

EVM 回调在 ICS-20 转账中使用 memo 字段，并采用特定的 JSON 结构： 目标链回调： 
{
  "dest_callback": {
    "address": "0x...",
    "gas_limit": "1000000",
    "calldata": "0x..."
  }
}
源链回调： 
{
  "src_callback": {
    "address": "0x...",
    "gas_limit": "1000000"
  }
}

​
安全注意事项

  • 隔离地址：目标链回调使用临时地址，以避免与本地账户混淆
  • 发送方校验：源链回调会校验只有数据包发送方才能设置回调
  • Gas 限制：回调执行受到指定 gas 限额的约束

​
相关文档

​
外部资源

The x/ibc module from cosmos/evm implements Inter-Blockchain Communication (IBC) protocol support with specialized EVM callback functionality for cross-chain smart contract interactions.

​
Overview

The IBC module extends the standard IBC protocol with EVM-specific features:
  • IBC Callbacks: Execute EVM contracts automatically during IBC packet lifecycle
  • Cross-chain Contract Calls: Enable smart contracts to interact across chains
  • Packet Lifecycle Management: Handle acknowledgments and timeouts through EVM contracts

​
Components

​
IBC Callbacks

The EVM Callbacks module implements the EVM contractKeeper interface that interacts with ibc-go’s callbacks middleware, specifically for ICS-20 transfer applications. Key Features:
  • Destination Callbacks: Execute contracts on packet receipt (onRecvPacket)
  • Source Callbacks: Handle acknowledgments (onAcknowledgePacket) and timeouts (onTimeoutPacket)
  • Atomic Execution: Contract calls happen atomically with token transfers

​
IBC Transfer Integration

The module works closely with the ICS20 transfer application to enable:
  • Cross-chain token transfers to EVM contracts
  • Automatic contract execution with received funds
  • Custom calldata propagation across chains
Smart contracts can initiate IBC transfers using the ICS20 Precompile, which provides the transfer function with memo field support for callbacks.
Address Format Limitation: Currently, IBC transfer receiver addresses must be in bech32 format (e.g., cosmos1...). While sender addresses are automatically converted from hex to bech32, receiver addresses must be provided in bech32 format. Full hex address support for receivers is planned for a future release.

​
Callback Types

​
Destination Callbacks (onRecvPacket)

Executed on the destination chain when a packet is received, allowing contracts to:
  • Receive cross-chain tokens
  • Execute custom logic with the received funds
  • Perform operations like DEX swaps or liquidity provision

​
Source Callbacks (onAcknowledgePacket & onTimeoutPacket)

Executed on the source chain when packet lifecycle completes, enabling contracts to:
  • Handle successful transfer acknowledgments
  • Recover funds from failed/timed out transfers
  • Implement retry logic for failed transfers

​
Implementation Details

​
Memo Format

EVM callbacks use the memo field in ICS-20 transfers with specific JSON structure: Destination Callback: 
{
  "dest_callback": {
    "address": "0x...",
    "gas_limit": "1000000",
    "calldata": "0x..."
  }
}
Source Callback: 
{
  "src_callback": {
    "address": "0x...",
    "gas_limit": "1000000"
  }
}

​
Security Considerations

  • Isolated Addresses: Destination callbacks use ephemeral addresses to prevent confusion with local accounts
  • Sender Validation: Source callbacks validate that only the packet sender can set callbacks
  • Gas Limits: Callback execution is bounded by specified gas limits

​
External Resources