CIP: IBC Dev Abstraction Layer for Developers

Networks Cosmos
1

CIP: IBC Dev Abstraction Layer for Developers

Simple Summary

A standardized IBC Dev Abstraction Layer simplifies cross-chain development by providing high-level APIs that hide low-level client, connection, and channel management details.

Abstract

IBC requires developers to manually set up light clients, perform multi-step handshakes for connections and channels, and run off-chain relayers to forward packets. This tedious workflow burdens developers and inflates costs: even a simple cross-chain token transfer involves multiple on-chain transactions. We propose an IBC Dev Abstraction Layer: a common interface (implemented as a Cosmos SDK module or CosmWasm contract) that encapsulates all low-level IBC logic. The layer exposes high-level methods (such as queryRemoteState, sendBatchTransfer, executeRemoteContract) that internally perform all necessary IBC steps. With this abstraction, developers issue a single API call and the layer automatically manages client creation, connection/channel handshakes, and packet sending. All security (light-client verification, proofs) remains in place, and existing relayers handle packet delivery. No changes to the core IBC protocol are required; existing IBC infrastructure remains compatible. For example, the layer can bundle multiple transfers into one packet with automatic timeouts, or route a message to invoke a contract on a remote chain without manual channel setup. In effect, developers focus on application logic while the abstraction handles protocol details. This improvement closes the UX gap with EVM ecosystems and makes Cosmos more composable for multi-chain applications.

Motivation

Developers face a steep learning curve with current IBC. Setting up a cross-chain path requires creating a light client on each chain and performing a connection handshake (4 steps) followed by a channel handshake (4 steps). In total, connecting two chains can require ~10 separate transactions. For example, to make two CosmWasm contracts communicate, a developer must implement six IBC callbacks (ibc_channel_open, ibc_channel_connect, ibc_channel_close, ibc_packet_receive, ibc_packet_ack, ibc_packet_timeout). The official Cosmos documentation even states that app developers “do not need to be concerned with low-level details”, but in practice the setup remains complex and manual.

Relaying is also expensive. An IBC transfer involves three on-chain transactions (one from the sender, two by relayers). On Cosmos Hub today, a single transfer costs roughly 0.0045 ATOM in gas. With the Hub handling ~400k IBC messages per month (over 1800 ATOM in relayer fees), operators now spend thousands of ATOM monthly. As a result, multiple relayers have halted service, leading to delays or failures in IBC transfers.

Current IBC also lacks a simple mechanism for querying arbitrary state on another chain. Developers must run a full (or light) node of the counterparty chain or rely on third-party RPCs to fetch data, which is cumbersome. Proposed solutions like Interchain Queries are still under development and not yet standard.

Finally, although Cosmos is designed to be modular, these complexities make it less developer-friendly than many EVM ecosystems with built-in bridges and APIs. Without a unified abstraction layer, each project must reinvent similar cross-chain tools, raising the barrier to building multi-chain apps in Cosmos.

The IBC Dev Abstraction Layer addresses these pain points by automating client/connection setup and packet transfers, reducing reliance on manual relaying, and providing a unified cross-chain interface.

Documentation

Developers interact with the abstraction layer using simple messages or contract calls, as shown in these examples:

  • queryRemoteState(chainID, keyPath): Queries a specific key (e.g. account balance or storage value) on the given chain. The layer constructs an IBC query, submits it, and upon receiving a proof, returns the value or an error if proof verification fails.
  • sendBatchTransfer(destChain, transfers[]): Sends one or more token transfers (or arbitrary ICS-20 packet data) to the destination chain. The layer ensures the target channel exists (creating it if needed) and sends a packet containing all transfers with automatic timeouts. It can bundle multiple transfers in one atomic packet. The developer later receives acknowledgments indicating success or timeout for each transfer.
  • executeRemoteContract(destChain, contractAddr, msg): Calls a smart contract at contractAddr on the destination chain with the provided message payload. The DevAL packs this into an IBC packet. When the remote chain processes the packet, any return data or acknowledgement is delivered back to the origin (e.g. via an IBC acknowledgement), which the developer can query or observe.

In all cases, the developer does not send any low-level IBC messages (MsgCreateClient, MsgConnOpenTry, MsgChanOpenInit, etc.); those are managed internally by the layer. The layer automatically handles client/connection/channel setup. If an operation fails (for example, due to an invalid chain ID, proof failure, or channel error), the layer returns a standardized error. All data is still verified via IBC light clients and proofs, so the trust model remains the same. This documentation assumes the DevAL is deployed and configured (e.g., a port ID is reserved for it). The developer only uses high-level calls; no manual relayer management or handshake transactions are needed on their side.

Specification

The technical design can be described separately for an on-chain SDK module and a CosmWasm contract, though both serve the same high-level interface.

  • SDK Module (on-chain):
    • Client/Connection/Channel Management: Upon receiving a high-level message (e.g. MsgSendBatchTransfer or MsgExecRemote), the module checks if an IBC client exists for the target chain; if not, it issues MsgCreateClient. It then checks for a connection and a channel on a dedicated port (e.g. port ID “devlayer”); if needed, it performs the handshake steps (MsgConnOpenInit/Try/Ack/Confirm, then MsgChanOpenInit/Try/Ack/Confirm) automatically via the IBCModule callbacks.
    • Packet Construction: Once the channel is open, the module encodes the action into one or more IBC packets. For token transfers, it uses the standard ICS-20 packet format (MsgTransfer); for remote contract execution, it defines a custom packet payload containing the target contract address and message. It then calls MsgSendPacket to dispatch the packet(s).
    • State Tracking: The module records any outstanding requests in its state, indexed by packet sequence or transaction ID. When the IBC stack delivers an acknowledgement or timeout, the module’s OnAcknowledgementPacket and OnTimeoutPacket callbacks match it to the original request and emit a module event or store the result.
    • Query Interface: The module provides a query service to inspect pending requests or previous transfers. For example, a user could query which packets from their address are awaiting acknowledgment. These queries read from the module’s KV store.
    • Fee Handling: Optionally, the module can accept a fee or fee grant on the high-level call and use it to pay for the packet transactions. This might involve forwarding funds to relayers or using the existing FeeGrant module so the developer’s call covers all necessary fees.
  • CosmWasm Contract (off-chain):
    • Execute Endpoints: The contract exposes entrypoints such as execute_batch_transfer or execute_remote_call. Each entrypoint constructs one or more IbcMsg::SendPacket messages with encoded instructions. For example, execute_batch_transfer might encode multiple coin transfers into a single IBC packet (similar to ICS-20).
    • Channel Setup: Contracts cannot initiate channel handshakes on their own. A pre-established IBC channel on a known port is required. This channel may be created by an administrator or a prior setup step. The contract must be deployed with knowledge of the port and channel IDs it will use.
    • State and Callbacks: The contract stores a mapping of pending packet sequences to original requests in its state. It implements IBC packet callbacks (ibc_packet_ack, ibc_packet_timeout) to handle success or failure of operations, e.g. by emitting events or updating its state for the original caller to query.
    • Integration Notes: This approach requires no change to the base chain code. However, it only supports tokens and messages available to CosmWasm (additional modules like wasm.x might be needed for native token transfers). The contract should be audited to avoid logic errors (e.g. reentrancy in callbacks).

In both implementations, corner cases are handled explicitly. For example, if no IBC path exists to the destination, the call fails early. The layer surfaces any IBC errors (e.g. timeouts, bad proofs) back to the caller. All packets and queries still use the standard IBC verification mechanism, so the underlying security assumptions are unchanged. Existing IBC tools (relayers, explorers) see no difference: they relay the DevAL-generated packets just like any other IBC traffic.

Drawbacks

  • Increased Complexity: Adding a new module or contract increases the codebase and attack surface on each chain. Bugs or vulnerabilities in the abstraction logic could impact many cross-chain operations.
  • Centralization/Coordination: If a single common contract or module is used network-wide, it becomes a focal point. Reliance on a shared component might be seen as centralizing some cross-chain logic.
  • Overhead: Automatic client/channel creation and state tracking incur additional on-chain transactions and storage, which may be wasted if a channel is rarely used.
  • Fee Management Risks: Handling fees through grants or escrows adds complexity. Misconfigured fees could stall packet relaying or lock funds.
  • Maintenance Burden: The abstraction layer itself must be maintained and audited. It may need updates for new IBC versions or use cases, requiring community coordination.

Rationale

This design follows Cosmos’s modular philosophy by concretely hiding IBC boilerplate from applications. The official documentation explicitly states that IBC app developers “do not need to be concerned with low-level details”, so a shared DevAL implements that vision. By packaging IBC flows into high-level calls, we let developers focus on logic instead of protocol plumbing.

We considered other approaches. Teams could each build their own helper contracts or libraries, but that leads to fragmentation and duplicated effort. Waiting for fully-featured IBC standards (like Interchain Queries or ICS-27/29) would solve parts of the problem, but those are still in progress and lack a unified interface. In contrast, other ecosystems already offer such abstractions. For example, Circle’s Bridge Kit “exposes key operations as high-level SDK methods, abstracting routine setup steps”, demonstrating the benefit of bundling IBC complexity into simple APIs.

Among implementation options, an on-chain SDK module is preferred: it is fully auditable, upgradeable via governance, and works across any Cosmos SDK chain without extra infrastructure. A CosmWasm contract version can serve as a quick prototype or shared interface (for example, a hub-level contract that application chains call via IBC), but contracts cannot autonomously open channels and require pre-configured ports. The interface proposed here can be implemented in either form depending on chain capabilities.

If we do nothing, cross-chain development in Cosmos will remain slow and fragmented, as each team must re-solve the same IBC obstacles. By contrast, a unified DevAL ensures consistent behavior and documentation across the ecosystem. This design balances ease of use (high-level calls) with the security guarantees of IBC light-client verification.

Prior Art

IBC itself is the foundational protocol; this proposal builds on existing IBC applications:

  • ICS-20 (Token Transfer): The standard IBC token transfer application. It defines how to send coins across chains, but does not simplify client/connection/channel setup.
  • ICS-27 (Interchain Accounts): Allows one chain to execute arbitrary transactions on another chain via a controlled account. It can batch multiple actions in one IBC transaction, but still requires clients/channels and specialized logic; it does not remove the handshake complexity.
  • ICS-34 (Interchain Queries and Middleware): Proposed standards for IBC data queries and packet middleware are under discussion, but no final spec is widely adopted yet.
  • Other Ecosystems: EVM and other networks have developer-friendly bridge SDKs (e.g. Ethereum’s Wormhole or Circle’s CCTP Bridge) and cross-chain libraries. Polkadot’s XCM and other cross-chain messaging systems illustrate alternative approaches. None of these are native to Cosmos SDK, however.

To our knowledge, there is no existing Cosmos network application or shared library that provides the full DevAL interface. This CIP defines a new common standard on top of IBC, inspired by successful patterns in other ecosystems.

Unresolved Questions

  • Interface Design: The exact naming and format of messages and queries (e.g. parameter types, error codes) need community input. We have not specified a final API; this is left to the CIP process and implementation feedback.
  • Channel Discovery: How should the DevAL select or create a channel if multiple IBC paths exist? (For now, we assume a single designated port per counterparty.)
  • Fee Handling: The best method for handling fees (direct user payment vs. fee grants vs. gas abstraction) remains to be decided.
  • Scope: Support for arbitrary IBC packet types (beyond token transfers and simple contract calls) could be added later; the initial scope may focus on the most common use cases.

Backwards Compatibility

This CIP only adds new functionality on top of IBC; it does not change the IBC protocol itself. All existing IBC messages and behaviors remain unchanged. Chains that do not implement the DevAL module or contract continue to operate normally. Implementing the DevAL module requires a chain upgrade (if not already present), but it introduces no protocol-breaking changes. Existing relayers, explorer tools, and IBC middleware continue to operate as before, simply relaying the additional packets generated by DevAL.

Test Cases

Not applicable.

This CIP does not introduce consensus-critical changes that would require deterministic cross-client tests. Any implementation of the DevAL module or contract should include its own unit and integration tests to verify correct IBC behavior as part of normal development.

Reference Implementation

No reference implementation is provided inline. We encourage the community to develop example implementations in a separate repository (for example, as a Cosmos SDK module in Gaia or as a CosmWasm contract). Such reference code should demonstrate how each high-level call translates into IBC transactions, and provide a starting point for others.

Security Considerations

The abstraction layer must preserve IBC’s security guarantees. All cross-chain state (packet data, query results) must still be verified against the target chain’s light client proofs. The module or contract should use the existing IBC verification logic rather than bypass it. By simplifying IBC usage, the DevAL reduces user error, but it also introduces a larger attack surface if the abstraction logic contains bugs. For example, improper channel management could lead to unintended packet leakage or denial-of-service.

Because the DevAL performs actions on behalf of users, care must be taken to authenticate requests properly. The module’s messages should require signatures from the initiating account, and the contract should check the sender and funds for execute calls. Any future extensions (like bundling multiple calls) should be permissioned to avoid abuse. Finally, as with any IBC application, misconfiguration of client parameters (like trusting a malicious light client) could compromise security; this proposal does not change those fundamental assumptions.

Future Possibilities

Potential extensions include:

  • Native Cross-Chain Queries: Integrate upcoming standards for automated interchain data queries (ICS-18/ICS-34), allowing subscriptions to remote state changes.
  • Relayer Incentives: Combine with IBC fee market or grant mechanisms (e.g. ICS-29) to automate relayer compensation for DevAL-driven packets.
  • Multi-Hop Support: Enable multi-leg transfers or calls through multiple chains in one abstract operation.
  • EVM Integration: Provide an adapter or contract that bridges the DevAL interface to EVM-compatible chains (e.g. Ethermint).
  • Chaining Composability: Allow bundling multiple remote calls into a single operation (e.g. call contract B and then A in one user call).
    These ideas are out of scope for the initial CIP but indicate how the DevAL could evolve.

Conclusion

IBC is a powerful protocol, but its current developer experience limits practical cross-chain adoption in Cosmos. This proposal shows that the problem can be solved without changing consensus or the IBC core, by introducing a standardized IBC Developer Abstraction Layer at the Cosmos SDK level, with an optional CosmWasm façade.

This approach aligns with Cosmos’s modular philosophy, preserves existing security guarantees, and significantly improves developer UX by removing low-level IBC complexity. By standardizing common cross-chain operations, it reduces fragmentation and makes Cosmos composability practical rather than theoretical.