IBC Integration

Monolythium supports Inter-Blockchain Communication (IBC), the trustless cross-chain protocol that underpins the Cosmos ecosystem. IBC enables Monolythium to transfer tokens and relay data packets to and from any IBC-enabled chain without relying on centralized bridges or custodians.

---

Overview

Property	Value
IBC Version	ibc-go v8
EVM Precompile	cosmos/evm v0.5.1
ICS-20 Transfer Precompile	0x0000000000000000000000000000000000000802
Activation Block	500,000 (mainnet/testnet), 270,000 (Sprintnet)
Relayer	Go Relayer (rly) v2.6.0
Finality	Deterministic (LythiumBFT)

---

How IBC Works

Inter-Blockchain Communication is a layered protocol consisting of light clients, connections, channels, and relayers. Together, these components allow two sovereign blockchains to verify each other's state and exchange packets trustlessly.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        IBC Protocol Stack                       │
├───────────────┬───────────────┬───────────────┬─────────────────┤
│  Application  │  ICS-20       │  ICS-721      │  Custom Apps    │
│  Layer        │  Token        │  NFT          │                 │
│               │  Transfer     │  Transfer     │                 │
├───────────────┴───────────────┴───────────────┴─────────────────┤
│  Transport Layer       Channels + Ports                         │
├─────────────────────────────────────────────────────────────────┤
│  Connection Layer      Authenticated connections                │
├─────────────────────────────────────────────────────────────────┤
│  Client Layer          Light clients (07-tendermint)            │
└─────────────────────────────────────────────────────────────────┘

Core Components

1. Light Clients -- Track the consensus state of a counterparty chain, enabling cryptographic verification of cross-chain messages without trusting a third party.

2. Connections -- Authenticated communication links between two chains, established through a four-step handshake on top of light clients.

3. Channels -- Application-specific pathways scoped to a port (e.g., transfer for ICS-20 token transfers). Each channel is bound to a single connection.

4. Relayers -- Off-chain processes that monitor both chains for pending packets and relay them across. Relayers are permissionless; anyone can operate one.

---

ICS-20 Transfer Precompile

Monolythium exposes IBC token transfers as an EVM precompiled contract, allowing Solidity contracts and EVM wallets to initiate IBC transfers directly without switching to the Cosmos transaction format.

Precompile Address

0x0000000000000000000000000000000000000802

Technical Details

The ICS-20 precompile is powered by cosmos/evm v0.5.1. The TransferKeeper is passed into DefaultStaticPrecompiles in the chain application setup (chain/app.go), making the precompile available at genesis.

// chain/app.go — precompile registration
precompiles := evmtypes.DefaultStaticPrecompiles(
    app.TransferKeeper,   // ICS-20 transfer
    // ... other keepers
)

All precompiles are activated at genesis via:

ActiveStaticPrecompiles = AvailableStaticPrecompiles

Calling the Precompile from Solidity

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IICS20Transfer {
    function transfer(
        string calldata sourcePort,
        string calldata sourceChannel,
        string calldata denom,
        uint256 amount,
        string calldata receiver,
        uint64 revisionNumber,
        uint64 revisionHeight,
        uint64 timeoutTimestamp,
        string calldata memo
    ) external returns (bool);
}

contract IBCExample {
    IICS20Transfer constant IBC_TRANSFER =
        IICS20Transfer(0x0000000000000000000000000000000000000802);

    function sendTokensViaIBC(
        string calldata channel,
        string calldata denom,
        uint256 amount,
        string calldata receiver
    ) external {
        IBC_TRANSFER.transfer(
            "transfer",
            channel,
            denom,
            amount,
            receiver,
            0,            // revision number (0 = use timestamp)
            0,            // revision height (0 = use timestamp)
            uint64(block.timestamp + 600) * 1_000_000_000, // 10 min timeout
            ""            // memo
        );
    }
}

caution

The precompile only becomes available after the IBC activation block (500,000 on mainnet/testnet, 270,000 on Sprintnet). Calls before activation will revert.

---

IBC Transfer Flow

A standard ICS-20 token transfer follows this sequence:

Monolythium                    Relayer                    Counterparty Chain
     │                            │                              │
     │── MsgTransfer ────────────>│                              │
     │   (tokens escrowed)        │                              │
     │                            │── SendPacket ───────────────>│
     │                            │                              │── RecvPacket
     │                            │                              │   (mint ibc/HASH
     │                            │                              │    vouchers)
     │                            │<────────── WriteAck ─────────│
     │<──── AcknowledgePacket ────│                              │
     │   (finalize escrow)        │                              │
     │                            │                              │

Step-by-Step

1. MsgTransfer -- The sender submits a transfer message. Tokens are locked in the IBC escrow account on Monolythium.
2. SendPacket -- A packet containing the transfer data is committed to state.
3. Relayer -- The relayer detects the committed packet and submits a MsgRecvPacket on the counterparty chain.
4. RecvPacket -- The counterparty chain verifies the packet proof against its light client and mints voucher tokens in the ibc/HASH denomination.
5. Acknowledgement -- The counterparty chain writes an acknowledgement (success or error). The relayer delivers it back to Monolythium.
6. Finalization -- Monolythium processes the acknowledgement. On success, the escrow is finalized. On failure, tokens are refunded.

Timeouts

Every IBC transfer includes a timeout (by block height, timestamp, or both). If the counterparty chain does not receive the packet before the timeout expires, the transfer is automatically refunded to the sender.

---

IBC Denomination Format

When tokens arrive on a chain via IBC, they are represented with a hashed denomination that encodes their origin path.

Format

ibc/SHA256("transfer/channel-X/denom")

Example

For ATOM arriving on Monolythium through channel-0:

Path:  transfer/channel-0/uatom
Hash:  SHA256("transfer/channel-0/uatom")
Denom: ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2

Multi-Hop Denominations

Tokens that traverse multiple chains accumulate path segments:

Original: uatom (Cosmos Hub)
After 1 hop: ibc/HASH1  (transfer/channel-0/uatom)
After 2 hops: ibc/HASH2 (transfer/channel-5/transfer/channel-0/uatom)

Querying Denom Traces

# Query the origin of an IBC denomination
monod query ibc-transfer denom-trace <hash>

# List all known denom traces
monod query ibc-transfer denom-traces

---

Active Channels

Channel	Counterparty	Port	Status
channel-0	Provider Chain	transfer	Active
channel-1	Gaia Devnet	transfer	Active

Querying Channels

# List all channels
monod query ibc channel channels

# Query a specific channel
monod query ibc channel end transfer channel-0

---

Dual-Path USDC Strategy

Monolythium supports two forms of USDC, each serving a distinct purpose within the ecosystem.

mUSDC (ERC-20 Wrapped)

mUSDC is a wrapped ERC-20 token created through the mUSDC Bridge. It is the primary stablecoin for EVM-native DeFi operations.

Property	Details
Type	ERC-20 token
Bridge Fee	0.1% deposit, no redemption fee
Use Cases	DEX trading, LP provision, MonoPump, lending
Tradeable	Yes, on MonoSwap DEX

IBC USDC

IBC USDC is the canonical USDC transferred via ICS-20 from a Cosmos chain. It retains its ibc/HASH denomination and is used for Cosmos-native operations.

Property	Details
Type	IBC voucher (ibc/HASH)
Transfer Fee	Standard IBC relay (gas only)
Use Cases	Cosmos staking, governance, IBC forwarding
Tradeable	Via Cosmos DEX modules

When to Use Which

Scenario	Use
Trading on MonoSwap	mUSDC
Providing DEX liquidity	mUSDC
MonoPump token launches	mUSDC
Transferring to another Cosmos chain	IBC USDC
Cosmos governance deposits	IBC USDC

tip

mUSDC and IBC USDC represent the same underlying asset (USDC). Users can convert between them via the mUSDC Bridge contract.

---

MonoHub IBC Interface

MonoHub provides a dedicated IBC interface at monohub.xyz with four tabs for managing cross-chain operations.

Transfer Form

Submit IBC transfers directly from the browser. Connect your wallet, select the destination chain and channel, enter the amount and recipient address, and sign the transaction.

Channel Browser

Explore all active IBC channels, their states, and connected counterparty chains. View channel details including port, ordering, and connection information.

Denom Explorer

Look up any ibc/HASH denomination to trace its origin chain and original denom. Useful for identifying unfamiliar tokens that arrived via IBC.

Transfer History

View your complete IBC transfer history, including pending transfers, completed transfers, and any timed-out packets awaiting refund.

---

Relayer Operations

Monolythium uses the Go Relayer (rly) v2.6.0 for packet relay between connected chains.

Go Relayer (rly)

The official relayer software for the Monolythium network:

# Install
git clone https://github.com/cosmos/relayer.git
cd relayer
git checkout v2.6.0
make install

# Initialize
rly config init

# Add chains
rly chains add monolythium --file monolythium-chain.json
rly chains add provider --file provider-chain.json

# Create keys
rly keys add monolythium default
rly keys add provider default

# Create path
rly paths new monolythium provider mono-provider

# Link (creates clients, connection, channel)
rly tx link mono-provider

# Start relaying
rly start mono-provider

Relayer Configuration

A minimal chain configuration for Monolythium:

{
  "type": "cosmos",
  "value": {
    "key": "default",
    "chain-id": "mono_6941-1",
    "rpc-addr": "http://localhost:26657",
    "account-prefix": "mono",
    "keyring-backend": "test",
    "gas-adjustment": 1.5,
    "gas-prices": "0.025alyth",
    "min-gas-amount": 0,
    "debug": false,
    "timeout": "20s",
    "output-format": "json",
    "sign-mode": "direct"
  }
}

info

The Monolythium team operates a relayer instance on Vortex for the core channels (channel-0, channel-1). Third-party relayer operators are welcome to run additional instances for redundancy.

---

IBC Activation Schedule

IBC is not available from genesis. It activates at a predetermined block height to allow the network to stabilize first.

Network	Activation Block	Status
Mainnet	500,000	Pending
Testnet	500,000	Pending
Sprintnet	270,000	Active

Before the activation block:

• IBC transactions will be rejected
• The ICS-20 precompile will revert
• Light client creation is not possible

After the activation block:

• All IBC functionality becomes available
• Channel handshakes can be initiated
• Token transfers can be submitted

---

IBC Middleware Stack

Monolythium employs a layered middleware stack for IBC processing:

┌──────────────────────────────────┐
│         IBC Callbacks            │  Application-level hooks
├──────────────────────────────────┤
│      ERC-20 Middleware           │  Auto-convert IBC tokens to ERC-20
├──────────────────────────────────┤
│        ICS-20 Base               │  Standard token transfer logic
└──────────────────────────────────┘

• ICS-20 Base -- Standard ICS-20 transfer logic handling escrow, mint, burn, and unescrow operations.
• ERC-20 Middleware -- Automatically registers incoming IBC tokens as ERC-20 contracts, making them compatible with EVM tooling (MetaMask, DEXes, etc.).
• IBC Callbacks -- Application-level hooks that fire on packet lifecycle events (send, receive, acknowledge, timeout), enabling smart contract automation.

---

API Endpoints

Cosmos REST (LCD)

# List all channels
GET /ibc/core/channel/v1/channels

# List all connections
GET /ibc/core/connection/v1/connections

# List all light clients
GET /ibc/core/client/v1/client_states

# Transfer module parameters
GET /ibc/apps/transfer/v1/params

# Query denom trace
GET /ibc/apps/transfer/v1/denom_traces/{hash}

# Query escrow address for a channel
GET /ibc/apps/transfer/v1/channels/{channel_id}/ports/{port_id}/escrow_address

CLI Queries

# Channel state
monod query ibc channel end transfer channel-0

# Connection state
monod query ibc connection end connection-0

# Client state
monod query ibc client state 07-tendermint-0

# Packet commitments
monod query ibc channel packet-commitments transfer channel-0

# Unreceived packets
monod query ibc channel unreceived-packets transfer channel-0

---

Troubleshooting

Transfer Stuck in Pending

1. Check relayer status -- Ensure at least one relayer is operational for the relevant channel.
2. Verify channel state -- The channel must be in STATE_OPEN. Query with monod query ibc channel end transfer channel-X.
3. Check for timeout -- If the timeout has passed, the relayer should automatically submit a timeout packet and refund the sender.
4. Manual relay -- If the relayer is down, you can manually relay a specific packet:

rly tx relay-packets mono-provider channel-0

Unknown IBC Denomination

If you receive tokens with an unfamiliar ibc/ prefix:

# Look up the denom trace
monod query ibc-transfer denom-trace <hash>

# Example output
# denom_trace:
#   path: transfer/channel-0
#   base_denom: uatom

Client Expired

Light clients expire if not updated within the trusting period. An expired client requires a governance proposal to update:

# Check client status
monod query ibc client state 07-tendermint-0

# If expired, submit a governance proposal to update
monod tx gov submit-proposal update-client 07-tendermint-0 <substitute-client-id>

---

Security Considerations

• Light client updates -- Relayers must keep light clients updated within the trusting period (typically 14 days). Expired clients halt all IBC operations on that channel.
• Frozen clients -- A client is frozen when evidence of misbehavior (e.g., double signing) is detected on the counterparty chain. Frozen clients require governance intervention.
• Channel ordering -- ICS-20 uses unordered channels, so packet delivery order is not guaranteed. Each packet is processed independently.
• Denomination verification -- Always verify the denom trace of IBC tokens before accepting them. Malicious channels could mint tokens with misleading names.

---

Further Reading

• IBC Protocol Specification
• IBC-Go Documentation
• Cosmos Network IBC
• Go Relayer Repository
• Fee Model -- Transaction fee structure
• Tokenomics -- Economic model