Deployment Overview

本文档说明了 IBC v2 部署如何端到端运行，以支持 Cosmos 链与 EVM 链之间基于 mint/burn 模式的转账。该部署使用 IBC v2 协议、企业级中继器以及证明者服务。

​

系统架构

图例

• 蓝色 = 链上合约（EVM）
• 紫色 = IBC / SDK 模块
• 橙色 = 链下基础设施
• 虚线箭头 = 证明 / 验证

​

组件

​

链上

Cosmos 模块

• 核心 IBC 模块 —— 核心 IBC 栈，包括 ICS 26 Router、ICS 26 Application Callbacks 和 ICS 27 GMP。
  • 规范： cosmos/ibc
  • 实现： cosmos/ibc-go
• Attestor 轻客户端 —— 一种基于 attestor 的 IBC 轻客户端，使用来自固定可信签名者集合、达到法定阈值的 ECDSA 签名证明来验证 IBC 数据包，采用 Go 实现。
  • 规范： cosmos/ibc ics-026-application-callbacks
  • 实现： cosmos/ibc-go attestor light client
• Token Factory —— 与具体链相关的模块，负责核心资产逻辑，并与 IBC 栈集成，用于发起出站 IBC 数据包和/或处理入站 IBC 数据包。

EVM 合约

• 核心 IBC 合约 —— 核心 IBC 合约，包括 ICS 26 Router 以及 ICS 27 GMP + Callbacks 合约。
  • 规范： cosmos/ibc
  • 实现： cosmos/solidity-ibc-eureka
• Attestor 轻客户端 —— 一种基于 attestor 的 IBC 轻客户端，使用来自固定可信签名者集合、达到法定阈值的 ECDSA 签名证明来验证 IBC 数据包，采用 Solidity 实现。
  • 规范： cosmos/solidity-ibc-eureka design
  • 实现： cosmos/solidity-ibc-eureka attestation
• 跨链同质化代币（IFT） —— 一组规则和接口，用于创建和管理可通过 ICS-27 GMP 在不同区块链网络之间转移的同质化代币。
  • 实现： cosmos/solidity-ibc-eureka IFTBase.sol

​

链下

• 证明服务 —— 轻量级、与区块链无关的证明服务，为 IBC 跨链通信提供带有密码学签名的区块链状态证明。详情请参阅 Attestor 文档。
  • 实现： cosmos/ibc-attestor（位于 apps/ibc-attestor/ 的 Rust 服务）
• Proof API —— 一个 gRPC 服务器，客户端可查询它以获取生成中继 IBC 数据包所需交易的数据。
  • 实现： cosmos/solidity-ibc-eureka proof-api
• 中继器 —— 一个独立的、可用于生产环境的、请求驱动的 IBC v2 协议中继服务。详情请参阅 Relayer 文档。

​

IBC 转账流程示例

​

Cosmos 到 EVM

1. 用户或客户端在 Cosmos 源链上提交一笔交易，其中包含发送到 Token Factory 模块的 burn/transfer 消息。
   • Token Factory 模块调用 IBC GMP 模块，向 EVM 目标链上的 IFT 合约的 mint 函数发起一次 GMP 调用。
   • GMP 模块调用核心 IBC 模块，发送一个携带 GMP 负载的数据包到 EVM 目标链上的 ICS 26 Router。
   • IBC 模块将相关数据包信息作为事件发出。
   • Attestor 持续监控区块中的相关 IBC 事件，解析出有效的 IBC 转账数据包，并生成带签名且附带相关区块链状态的证明。
2. 客户端向中继服务提交请求，以中继该 IBC 转账数据包。
   • 中继器向 Proof API 请求在目标链上提交 IBC 交易及证明所需的数据。
   • Proof API 查询每个已配置的 Attestor，聚合签名证明直到达到法定阈值，生成 IBC RecvPacket 数据，并返回给中继器。
3. 中继器将 IBC RecvPacket 交易提交到 EVM 目标链。
   • ICS 26 Router 合约解析数据包并执行核心校验逻辑（顺序、超时等），然后将其路由到相应的轻客户端合约。
   • 轻客户端合约验证 IBC 数据包。
   • ICS 26 Router 将已验证的数据包路由到 GMP 合约，由其执行 IFT 合约的 mint 函数。
   • IFT 合约铸造代币，并将其转账到 GMP 负载中指定的目标地址。

​

EVM 到 Cosmos

1. 用户或客户端在 EVM 源链上提交一笔交易，调用 IFT 合约上的 iftTransfer。
   • IFT 合约销毁发送方的代币，并使用 IBC mint/burn 转账数据包所需的信息调用 ICS 27 GMP 合约。
   • GMP 合约调用 IBC Router 合约，发起一次 GMP 调用以在 Cosmos 目标链上铸造代币。
   • IBC 合约将相关数据包信息作为事件发出。
   • Attestor 为该数据包及相关区块链状态生成带签名的证明。
2. 客户端向中继服务提交请求，以中继该 IBC 转账数据包。
   • 中继器从 Proof API 请求数据，后者聚合证明并生成 IBC RecvPacket 数据。
3. 中继器将 IBC RecvPacket 交易提交到 Cosmos 目标链。
   • 核心 IBC 模块解析数据包并执行核心校验逻辑（顺序、超时等），然后将其路由到相应的轻客户端模块。
   • 轻客户端模块验证 IBC 数据包。
   • IBC 核心模块将已验证的数据包路由到 GMP 应用模块。
   • GMP 模块调用 Token Factory 模块，将代币铸造到 GMP 负载中指定的目标地址。

---

This document explains how an IBC v2 deployment works end-to-end to support mint/burn transfers between Cosmos and EVM chains using the IBC v2 protocol, the enterprise-ready relayer, and the attestor service.

​

System Architecture

Legend

• Blue = on-chain contracts (EVM)
• Purple = IBC / SDK modules
• Orange = off-chain infrastructure
• Dashed arrows = proofs / verification

​

Components

​

On-Chain

Cosmos Modules

• Core IBC Modules — Core IBC stack including the ICS 26 Router, ICS 26 Application Callbacks, and ICS 27 GMP.
  • Specifications: cosmos/ibc
  • Implementations: cosmos/ibc-go
• Attestor Light Client — An attestor-based IBC light client that verifies IBC packets using quorum-signed ECDSA attestations from a fixed set of trusted signers, implemented in Go.
  • Specification: cosmos/ibc ics-026-application-callbacks
  • Implementation: cosmos/ibc-go attestor light client
• Token Factory — Chain-dependent module that handles core asset logic and is configured with the IBC stack to initiate outgoing and/or process incoming IBC packets.

EVM Contracts

• Core IBC Contracts — Core IBC contracts including the ICS 26 Router and ICS 27 GMP + Callbacks contracts.
  • Specifications: cosmos/ibc
  • Implementations: cosmos/solidity-ibc-eureka
• Attestor Light Client — An attestor-based IBC light client that verifies IBC packets using quorum-signed ECDSA attestations from a fixed set of trusted signers, implemented in Solidity.
  • Specification: cosmos/solidity-ibc-eureka design
  • Implementation: cosmos/solidity-ibc-eureka attestation
• Interchain Fungible Token (IFT) — A set of rules and interfaces for creating and managing fungible tokens that can be transferred across different blockchain networks using ICS-27 GMP.
  • Implementation: cosmos/solidity-ibc-eureka IFTBase.sol

​

Off-Chain

• Attestation Service — A lightweight, blockchain-agnostic attestation service that provides cryptographically signed attestations of blockchain state for IBC cross-chain communication. See the Attestor documentation for details.
  • Implementation: cosmos/ibc-attestor (Rust service in apps/ibc-attestor/)
• Proof API — A gRPC server that can be queried by a client to get the data needed to generate transaction(s) for relaying IBC packets.
  • Implementation: cosmos/solidity-ibc-eureka proof-api
• Relayer — A standalone, production-ready, request-driven relayer service for the IBC v2 Protocol. See the Relayer documentation for details.

​

Example IBC Transfer Flows

​

Cosmos to EVM

1. The user or client submits a transaction on the Cosmos source chain containing a burn/transfer message to the Token Factory module.
   • The Token Factory module calls the IBC GMP module to make a GMP call to the mint function on the EVM destination chain’s IFT contract.
   • The GMP module calls the core IBC module to send a packet with the GMP payload to the ICS 26 Router on the EVM destination chain.
   • The IBC modules emit the relevant packet information as an event.
   • The Attestor continuously monitors blocks for relevant IBC events, parses a valid IBC transfer packet, and generates a signed attestation with associated blockchain state.
2. The client submits a request to the relayer service to relay the IBC transfer packet.
   • The relayer requests data necessary to submit the IBC transaction and proof on the destination chain from the Proof API.
   • The Proof API queries each configured Attestor, aggregates signed attestations until the quorum threshold is reached, generates the IBC RecvPacket data, and responds to the relayer.
3. The relayer submits the IBC RecvPacket transaction to the EVM destination chain.
   • The ICS 26 Router contract parses the packet and executes core validation logic (sequencing, timeouts, etc.), then routes it to the relevant light client contract.
   • The light client contract validates the IBC packet.
   • The ICS 26 Router routes the validated packet to the GMP contract, which executes the IFT contract’s mint function.
   • The IFT contract mints and transfers the token to the destination address specified in the GMP payload.

​

EVM to Cosmos

1. The user or client submits a transaction on the EVM source chain calling iftTransfer on the IFT contract.
   • The IFT contract burns the tokens from the sender and calls the ICS 27 GMP contract with the necessary information for an IBC mint/burn transfer packet.
   • The GMP contract calls the IBC Router contract to send a GMP call to mint tokens on the Cosmos destination chain.
   • The IBC contracts emit the relevant packet information as an event.
   • The Attestor generates a signed attestation of the packet and associated blockchain state.
2. The client submits a request to the relayer service to relay the IBC transfer packet.
   • The relayer requests data from the Proof API, which aggregates attestations and generates IBC RecvPacket data.
3. The relayer submits the IBC RecvPacket transaction to the Cosmos destination chain.
   • The core IBC modules parse the packet and execute core validation logic (sequencing, timeouts, etc.), then route it to the relevant light client module.
   • The light client module validates the IBC packet.
   • The IBC Core modules route the validated packet to the GMP application module.
   • The GMP module calls the Token Factory module to mint tokens to the destination address specified in the GMP payload.