Architecture Overview

Documentation Index

Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt

Use this file to discover all available pages before exploring further.

IBC v2 enables direct connectivity between Cosmos chains and EVM-compatible networks, including Ethereum, Base, Arbitrum, Optimism, and Polygon. This is made possible by implementing the IBC protocol as Solidity contracts that can be deployed to any EVM chain without modifications to the chain itself. IFT (Interchain Fungible Token) transfers are the primary mechanism for moving tokens across these chains. Unlike the ICS-20 escrow model where denoms are transfer path dependent, IFT uses mint and burn semantics: tokens are burned on the source chain and minted as the canonical asset on the destination. Users always hold a native token rather than a wrapped version, and token issuers maintain control over supply across chains. This page covers the components that make up a Cosmos to EVM IFT deployment and how they work together end-to-end. To see this in action, check out the Cosmos ↔ EVM Interoperability Tutorial.

​

System Architecture

​

On-Chain Components

​

Cosmos Modules

On the Cosmos side, IFT transfers rely on three components: the core IBC stack, an attestation light client, and the IFT token transfer modules.

• Core IBC Modules (x/ibc): the core IBC stack including the ICS-26 Router
• ICS-27 GMP: General Message Passing used to send arbitrary cross-chain messages
• Callbacks middleware: used by the GMP module to register callback handlers on acknowledgement and timeout
• Attestation Light Client (x/ibc attestation LC): an IBC light client that verifies packets using quorum-signed ECDSA attestations from a trusted set of off-chain signers. See below for more info.
• Token Factory + IFT (x/tokenfactory, x/ift): chain-native token management and the IFT bridge module. Handles core asset logic and is configured with the IBC stack to initiate outgoing and process incoming IBC packets.

​

EVM Contracts

On the EVM side, the same components are mirrored as Solidity contracts from cosmos/solidity-ibc-eureka, deployable to any EVM-compatible chain without modifications to the chain itself.

• Core IBC Contracts (ICS26Router): the core IBC contract stack, including the ICS-26 Router.
• ICS-27 GMP: General Message Passing used to send arbitrary cross-chain messages
• ICS-27 Account: Minimal execution account used by ICS-27 to perform arbitrary calls
• Attestation Light Client (AttestationLightClient): the Solidity implementation of the same attestation-based light client, verifying packets using quorum-signed ECDSA attestations from a signer set. See below for more info.
• Interchain Fungible Token (IFTOwnable): a contract for creating and managing fungible tokens that can be transferred across chains using ICS-27 GMP.

​

IFT (Interchain Fungible Token)

IFT is a cross-chain token standard for transferring tokens between chains. Instead of locking tokens in escrow on the source chain and minting a wrapped version on the destination (the ICS-20 model), IFT burns tokens on the source and mints the canonical token on the destination. Users always hold a native token rather than a wrapped one, and token issuers maintain control over total supply across chains. IFT contracts can be deployed across multiple chains, enabling direct token transfers between them without requiring intermediate routing or path dependencies. On the Cosmos side, the IFT module wraps a token factory module. The register-bridge command links a token factory denom to a specific EVM IFT contract. On outbound transfers, the module burns the tokens; on inbound packets it mints them. On the Solidity side, the IFT ERC20 contract handles the same flow. iftTransfer burns ERC20 tokens and initiates an outbound IBC packet via the ICS-26 Router. iftMint is called via GMP (explained below) on inbound packets to mint tokens to the recipient. For more details on IFT, see the Interchain Fungible Token (IFT) page.

​

GMP (General Message Passing)

GMP is the ICS-27 application protocol used to send arbitrary cross-chain messages. GMP is used to deliver encoded payloads to a target contract on the destination chain. When a GMP message arrives, the destination chain lazily creates a deterministic account derived from the sender address, source client ID, and a salt. That account then executes the payload on the target contract. In IFT transfers, GMP carries the MsgIFTMint instruction that tells the destination chain what to mint and to whom. For more details on GMP, see the General Message Passing (GMP) page.

​

Attestation Light Client

Like other IBC light clients, the attestation light client stores counterparty chain state. Unlike Tendermint light clients, which verify state using consensus headers and Merkle proofs, it verifies incoming packets using quorum-signed ECDSA attestations from a trusted off-chain signer set. It is configured with a set of registered attestors and a quorum threshold, and verifies incoming IBC packets by recovering and validating signer addresses from the submitted signatures. Packets are accepted only when signatures from a minimum number of registered attestors are present (m-of-n). There are two implementations: one in Go for the Cosmos side and one in Solidity for the EVM side. For more details on the attestation light client, see the Attestation Light Client page.

​

Off-Chain

​

Attestor Service

The attestor is a lightweight, stateless Rust service (cosmos/ibc-attestor) that watches a chain and produces ECDSA-signed attestations on demand via gRPC. When the Proof API asks for an attestation, the attestor queries the chain, signs the relevant state, and returns it. Attestors are registered with their on-chain light clients on counterparty chains. For more details on the attestor, see the Attestor Overview page.

​

Proof API

The Proof API is a gRPC server that sits between the attestor instances and the relayer. When the relayer needs a proof for a packet, it queries the Proof API, which collects signatures from the relevant attestors, verifies the quorum threshold is met, and returns a proof bundle ready for on-chain submission. For more details on the Proof API, see the Proof API page.

​

Relayer

Cosmos to EVM connections use the production-ready IBC v2 relayer (cosmos/ibc-relayer) that submits RecvPacket and MsgTimeout transactions. When a relay is triggered by a user submitting a source transaction hash, it queries the Proof API to construct the relay transaction, then submits it to the destination chain. It then relays the acknowledgement and proof back to the origin chain. For packets that time out, it submits a MsgTimeout to the source chain to trigger a refund. For more details on the relayer, see the Relayer Overview page.

​

Example IBC Transfer Flows

​

Cosmos to EVM

1. The user or client submits a transaction on the Cosmos source chain which contains a burn/transfer message to the chain-dependent Token Factory module (interchangeable module that interfaces with IBC and handles core asset logic).
   • 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 core IBC contract (ICS 26 Router) on the EVM destination chain.
   • The IBC modules emit the relevant packet information as an event.
   • The Attestor, which continuously monitors blocks for relevant IBC events, parses a valid IBC transfer packet based on its configuration and generates a signed attestation of the packet with associated blockchain state.
2. The client submits a request to the relayer service to relay the IBC transfer packet.
   • The relayer requests the data necessary to submit the IBC transaction and proof on the destination chain for packet delivery from the Proof API.
   • The Proof API:
     • Queries each Attestor configured for the given transfer path,
     • Aggregates the signed attestations until the threshold is reached,
     • Uses the aggregated signed attestations along with block data to generate the IBC RecvPacket data necessary to submit the transaction on chain, and
     • Responds back to the relayer with the relevant data.
3. The relayer takes the IBC RecvPacket transaction data and submits it to the EVM destination chain.
   • On 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 according to the light client’s validation rules.
   • Once a packet is validated by the light client contract, the ICS 26 Router routes the packet to the GMP contract.
   • The GMP contract parses/interprets the GMP payload, which encodes a call to the IFT contract mint function on the EVM destination chain and executes that call to the contract.
   • 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 which calls iftTransfer on the IFT contract to initiate an IBC transfer to a Cosmos destination chain.
   • 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 the 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 the data necessary to submit the IBC transaction and proof on the destination chain for packet delivery from the Proof API.
   • The Proof API:
     • Queries each Attestor configured for the given transfer path,
     • Aggregates the signed attestations until the threshold is reached,
     • Uses the aggregated signed attestations along with block data to generate the IBC RecvPacket data necessary to submit the transaction on chain, and
     • Responds back to the relayer with the relevant data.
3. The relayer takes the IBC RecvPacket transaction data and submits it to the Cosmos destination chain.
   • On 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 according to the light client’s validation rules.
   • Once a packet is validated by the light client module, the IBC Core modules route the packet to the GMP application module.
   • The GMP application module parses/interprets the GMP payload, which encodes a call to the Token Factory module on the Cosmos destination chain to mint tokens via hooks.
   • The Token Factory module mints and transfers the token to the destination address specified in the GMP payload.

​

Timeout

Each IBC packet carries a timeout: either a block height or a timestamp on the destination chain. If the relayer does not deliver the packet before the timeout expires, the packet can no longer be received. The relayer then submits a MsgTimeout to the source chain instead.

1. A packet is sent on the source chain with a timeout height or timestamp.
2. The relayer detects that the packet has not been delivered before the timeout expires.
3. The relayer queries the Proof API for a timeout proof and submits a MsgTimeout transaction to the source chain.
4. The source chain verifies the proof and refunds the sender: on the Cosmos side, the IFT module mints the tokens back to the sender; on the EVM side, the IFT contract mints the tokens back to the sender’s address.