Cosmos
Cosmos IBC authenticates relayed packets through on-chain clients
Last updated
Cosmos IBC lets connected blockchains authenticate cross-chain messages with on-chain clients and packet proofs. Inter-Blockchain Communication (IBC) separates message transport from the application that interprets each message. A relayer carries packet data and evidence between chains. The receiving chain uses its configured client to verify that evidence before processing the packet. Light clients derive trusted state from the counterparty's consensus; other client types use different verification assumptions. IBC Classic organizes communication through connections and channels. IBC v2 uses client pairs and application routing. Receipt, acknowledgement, and timeout records establish different outcomes, so a successful source transaction alone does not establish destination execution.
The short version: Delayed IBC acknowledgements can leave source commitments outstanding after the destination application has executed.
Compatibility begins with the client and application
A usable IBC path requires compatible verification and application support on the chains involved. Each chain needs a client that can authenticate the relevant counterparty state. The receiving application must also understand the sending application's messages. Token transfers move fungible tokens between chains. Interchain accounts use different application logic to let an owner on a controller chain request permitted transactions through a registered account on a host chain. Installing IBC core does not automatically enable every application, and an application's availability on one chain does not establish support on another.
Client selection changes the security assumptions behind that path. A consensus-verifying light client checks evidence under the remote chain's consensus rules. An attestation-based client relies on its configured signers to attest to remote state. Both can expose the verification interface that IBC needs. Their trust requirements differ, so the client type and its parameters matter when assessing a particular connection.
Trusted state comes before packet proofs
An on-chain light client starts from a trusted consensus state and validates subsequent updates under its verification rules. The Tendermint client stores consensus states containing a state root, timestamp, and next-validator-set hash. These compact records support proof verification without replaying every transaction on the remote chain. Initial configuration must identify the intended counterparty and an appropriate trusted starting state; a client identifier alone does not establish either.
The proof height identifies remote state. The receiving chain's local block height belongs to a different ledger.
The Tendermint client needs an available consensus state at the proof's height. A newer latest client height does not establish that every earlier state remains stored. Classic connections can also impose a delay between accepting a consensus state and using it for packet verification. Where that delay applies, a valid update and proof still need to satisfy the configured waiting condition.
What does a packet proof actually verify?
A packet proof authenticates a commitment in the remote chain's state, using the verification rules of the selected client. For a Merkle-based client, the proof connects a specific stored value to a previously verified state root. IBC core supplies the expected path and commitment value. That binds verification to the packet being processed.
Presence and absence against a state root
Membership and non-membership answer different questions about the same authenticated state. Their meaning includes the proof height. Neither establishes an unrestricted claim about every earlier or later block.
Membership proofs
A membership proof establishes that a particular key holds the expected value. Receiving a packet uses this mechanism to authenticate the source's packet commitment. Acknowledgement processing uses it to authenticate the destination's acknowledgement commitment. Changing the packet data changes the expected commitment and prevents the original proof from authenticating the altered message.
Non-membership proofs
A non-membership proof establishes that a specified key is absent at the verified height. An unordered packet timeout uses absence of the destination receipt, together with deadline checks. An empty search result from a block explorer supplies no equivalent cryptographic evidence.
Identifiers bind evidence to the intended packet
Classic commitment paths include port and channel identifiers and a packet sequence. V2 paths use client identifiers and sequences. These paths stop evidence for one communication context from serving as evidence for another. The packet data and its timeout also contribute to the commitment, tying the verified value to the message's conditions.
A missing consensus state changes the next valid action
Consider a hypothetical Classic packet on an open unordered channel. Assume the applications are compatible, the packet remains unreceived before its deadline, and the receiving chain's light client is active. The source has committed the packet, and a relayer has obtained its membership proof. The destination client may already hold the consensus state for that proof height, or it may lack that state.
If the state exists and any connection delay has elapsed, the relayer can submit the receive message for verification. If it is missing, using this proof requires a valid client update that supplies the required state. The receiving chain must accept that update before the proof can pass. Any applicable delay must then elapse while the packet remains within its deadline.
Assume the update succeeds and the destination application accepts the packet. The destination records receipt and writes a successful acknowledgement. Relaying its proof back lets the source process that acknowledgement and clear the packet commitment. The destination application state establishes execution; the cleared source commitment establishes acknowledgement processing. When the required state is missing and no update is accepted, the receive attempt cannot establish receipt.
Relayers transport evidence and provide liveness
Relayers are off-chain processes that submit packet messages, proofs, and client updates to the participating chains. Permissionless deployments allow another relayer to deliver the same eligible packet. On-chain replay checks prevent duplicate processing, while verification rejects altered packet contents. Delivery still requires transactions that the chains accept. Missing relayer coverage, unavailable proof data, or congestion can delay submissions. Relayers incur execution costs; reimbursement follows the deployed incentive or service arrangements. Authentication and timely delivery address different requirements: a correctly configured path can wait for relay even when its verification rules remain sound.
What does an acknowledgement establish?
An acknowledgement records the destination application's response, which may represent success or an application error. The source authenticates the acknowledgement commitment using its client of the destination chain, then passes the response to the sending application's acknowledgement handler. Processing removes the outstanding packet commitment. Interpreting the response requires the application's acknowledgement format. A token-transfer acknowledgement describes the transfer's outcome. It does not establish success for unrelated actions. Successful proof verification can still lead to an application error, whereas a receive transaction rejected by core verification produces no receipt or application acknowledgement.
Classic applications can write acknowledgements asynchronously. Receipt can therefore exist before the application's response becomes available.
When can an unreceived packet time out?
Classic packets specify a timeout height, timestamp, or both; reaching an enabled bound on the destination prevents receipt. V2 uses a timeout timestamp. Eligibility follows authenticated destination state, not the sender's wall clock or a browser countdown. The source also needs protocol-specific evidence that the packet was not received.
A timeout on an unordered Classic channel requires proof that the destination has no receipt for that packet. For a deadline-based timeout, the source must also authenticate destination state that has reached an enabled bound. Classic's timeout-on-close path instead requires proof of destination channel closure and non-receipt; it can apply before the deadline. Timeout processing clears the source commitment and invokes the application's timeout logic. A destination halt can prevent fresh evidence from becoming available, so elapsed real-world time alone does not release an outstanding transfer.
A packet already received cannot take the non-receipt timeout path merely because its acknowledgement is delayed.
Client expiry and freezing require different responses
An expired Tendermint client has reached or exceeded its configured trusting period since its latest stored consensus timestamp. Ordinary updates cannot simply continue from that expired trust basis. The trusting period is a client parameter, distinct from a packet's delivery deadline. Keeping packets within their timeout does not keep a neglected client active.
Freezing addresses evidence of consensus misbehaviour. Conflicting authenticated headers or other client-defined violations can cause the implementation to freeze the client and stop packet processing through it. Freezing limits continued use of the affected verification state. It does not automatically reverse application changes that have already occurred.
Recovery depends on the deployed implementation and chain authority. In ibc-go, client recovery can use a compatible active substitute with a later height. The client implementation checks the substitute's parameters before accepting replacement state. Such recovery is separate from ordinary relaying; an expired or frozen status requires that recovery mechanism to succeed before the affected path resumes.
Token accounting belongs to the transfer application
ICS-20, the fungible-token transfer application, defines the balance changes attached to authenticated packets. Classic transfer logic checks the denomination trace against the sending port and channel. When that prefix matches, the sender burns vouchers and the receiver releases their backing from escrow. Otherwise, the sender escrows its local denomination and the receiver creates vouchers with an extended trace. The denomination trace records the transfer path, so the token's origin and its immediate sending chain can differ.
Different paths can produce different denominations even when a wallet displays the same ticker. The trace identifies the representation that the transfer module handles. In ibc-go, a hashed IBC denomination maps to that trace; the display name does not replace it. An authenticated error acknowledgement or processed timeout invokes ICS-20 refund logic. It restores escrowed tokens or remints burned vouchers for the original sender, as the direction requires.
Ordering changes packet dependencies
A strictly ordered Classic channel requires packets to arrive in sequence. A missing earlier packet blocks receipt of later packets on that channel. Processing a timeout closes the source end of a strictly ordered channel because continued delivery would break its sequence guarantees. Applications that require ordered remote operations must account for this interruption in their channel management.
Unordered channels track individual receipts and allow packets to arrive independently. Timing out one packet does not impose the same channel closure. Classic ICS-20 uses unordered channels, while other applications can require different ordering semantics. Both modes protect against replay. Ordering specifies dependencies between messages; it does not rank the security of the connected chains.
Classic channels and v2 routing make different agreements
IBC Classic and v2 retain client-based authentication while organizing counterparties and application compatibility differently. Their identifiers and setup requirements must match the deployed protocol.
Classic negotiates channel parameters
A Classic connection associates clients on the participating chains. Channels connect application ports over that connection and negotiate application versions and ordering. Multiple channels can share a connection, allowing separate application relationships to reuse its client infrastructure. An open connection alone does not establish an open, compatible application channel.
V2 carries application choices in payloads
V2 registers counterparty information for client pairs and routes payloads to application ports. Each payload states its application version and encoding. The receiving application must support those choices; valid client verification cannot make an incompatible payload executable. This arrangement removes Classic's separate connection and channel handshakes while retaining counterparties that require correct configuration.
The v2 packet format permits multiple payloads, although an implementation may support only one. Compatibility therefore includes the deployed handler's limits alongside the application's encoding and version. A route's useful capabilities come from that actual combination of client, core handler, and application.
Cosmos IBC - common questions
-
Does IBC encrypt the message carried in a packet?
- IBC packet authentication does not encrypt the packet contents. Public-chain transactions and events can expose application data, including token-transfer sender and receiver fields. A commitment hash authenticates those contents without providing confidentiality. Applications that need private messages require a separate confidentiality design.
-
Why can packet verification fail after a chain upgrade?
- An upgrade that changes the chain revision or client verification parameters can require a corresponding client upgrade. Tendermint clients distinguish revision numbers from heights within a revision. In ibc-go, the upgrade path authenticates replacement client and consensus state through proofs; relaying an ordinary header does not substitute for that procedure.
-
Which timestamp units distinguish Classic packets from v2 packets?
- Classic packet timeout timestamps use Unix nanoseconds, while IBC v2 timeout timestamps use Unix seconds. Both refer to the destination chain's clock. Supplying a timestamp in the other protocol's units changes the encoded deadline. A Classic timeout height is a separate field, not a timestamp conversion.
-
Must a Tendermint light client verify every intermediate block header?
- A Tendermint light client can verify non-adjacent headers when its trust and validator-overlap checks succeed. Insufficient overlap can require intermediate headers to establish a valid update. This reduces verification work without removing consensus checks. A packet proof still needs a stored consensus state at its particular proof height.
-
Where can a relayer obtain packet data if the source stores only a commitment?
- The implementation must make the full packet fields available through events or another supported data mechanism. A commitment hash cannot reconstruct those fields. Relayers need the original packet alongside its proof, and source acknowledgement processing needs the packet again to match the outstanding commitment.
-
Are client updates and packet receipt always separate transactions?
- Compatible Cosmos SDK implementations can place a client-update message before a receive message in one transaction. Verification must still see the required consensus state before processing receipt. A configured connection delay can prevent immediate use of a newly accepted state, so transaction bundling does not bypass that waiting condition.
-
Can an interchain account execute any message on its host chain?
- An interchain account can execute only operations that its host implementation permits and correctly authenticates. The ibc-go host checks allowed message types and requires their signers to match the registered interchain account. An authenticated IBC packet does not grant unrestricted authority over host-chain accounts or applications.