The Cosmos Inter-Blockchain Communication protocol — a native, light-client-secured messaging layer that connects Cosmos SDK chains (and, via IBC Eureka and ZK light clients, Ethereum and other non-Cosmos chains). ICS-20 carries fungible tokens, ICS-721 carries NFTs, ICS-27 enables interchain accounts, and ICS-29 standardizes relayer fees.
- 01Cosmos <-> Cosmos token transfers (ICS-20)
- 02interchain accounts (ICS-27) for cross-chain DeFi
- 03NFT transfers across Cosmos (ICS-721)
- 04trust-minimized bridging via on-chain light clients
- 05Ethereum <-> Cosmos via IBC Eureka / ZK light clients
- pnpm add @cosmjs/stargate @cosmjs/proto-signing cosmjs-types
| Variable | Scope | Description |
|---|---|---|
| COSMOS_RPC_URL | Client | Tendermint/CometBFT RPC endpoint for the source chain (e.g., `https://rpc.osmosis.zone`). Required to construct the SigningStargateClient. |
Use `@cosmjs/stargate`: connect with `SigningStargateClient.connectWithSigner(rpcUrl, offlineSigner, { gasPrice })`. For ICS-20 token transfers call `client.sendIbcTokens(senderAddress, recipientAddress, transferAmount, sourcePort='transfer', sourceChannel, timeoutHeight, timeoutTimestamp, fee, memo)` — the `sourceChannel` (e.g., `channel-0`) is chain-pair-specific and MUST be looked up from a registry like `chain-registry` (https://github.com/cosmos/chain-registry) at call time, not hard-coded. The IBC denom on the destination is `ibc/{SHA256(path/baseDenom)}` — use `cosmjs-types` to compute it. For interchain accounts (ICS-27) register an account via `MsgRegisterInterchainAccount` and submit txs through `MsgSendTx`. To verify or build a relayer, use `ibc-go` (Go) or `hermes` for production-grade packet relaying. For Ethereum <-> Cosmos use IBC Eureka with a ZK light client (e.g., Polymer, Union, Composable) — the API is similar but the client type is `08-wasm` or `07-tendermint` with different update semantics.
- ⚑Channel IDs are NOT global — `channel-0` on Osmosis to Cosmos Hub is unrelated to `channel-0` on Juno. Always resolve via the chain-registry; hard-coding channels is the #1 production outage cause.
- ⚑IBC denoms (`ibc/...`) are PATH-DEPENDENT. The same underlying token routed through a different intermediate chain produces a DIFFERENT ibc/ hash and is non-fungible with the direct path. Surface the path to users and prefer canonical (Hub-routed or PFM-routed) paths.
- ⚑Packet timeouts: every IBC packet has a `timeoutHeight` and/or `timeoutTimestamp` — if neither relayer nor counterparty processes it in time, funds return to sender via a `MsgTimeout`, but ONLY if a relayer submits the timeout proof. Stuck packets without an active relayer require manual intervention.
- ⚑Light-client maintenance is real operational cost: each chain stores the counterparty's consensus state and must process header updates regularly; if a client expires (no updates within the trusting period, typically 14 days), the channel FREEZES and requires governance to recover. ZK light clients for IBC Eureka (Ethereum) need especially careful header-update operations.
- ⚑Relayer fees (ICS-29) are opt-in; if you don't pay relayers, transfers depend on altruistic relayers and can be slow or stall during low-fee periods. Use a fee middleware or a paid relayer service in production.
- ⚑Token vs message vs interchain-account: ICS-20 is fungible token transfer, ICS-27 is remote tx execution, ICS-721 is NFTs. Mixing them up — e.g., trying to send tokens via an interchain account when ICS-20 would suffice — wastes gas and adds failure modes.
- ⚑Packet-Forward Middleware (PFM) lets you hop through an intermediate chain in one tx via the `memo` field; the JSON schema is strict and any malformed memo silently drops the forward, leaving funds on the intermediate chain.
- ⚑Non-Cosmos IBC (Eureka with ZK light clients to Ethereum) is newer, lower-throughput, and has stricter gas/proof-size limits than Cosmos<->Cosmos IBC; do not assume the EVM side has the same UX latency.