IBC Hooks Module

Forked from https://github.com/osmosis-labs/osmosis/tree/main/x/ibchooks

⚠️

This module was forked from https://github.com/osmosis-labs/osmosis/tree/main/x/ibchooks

Unfortunately the original version could not be directly used due to extensive osmosis references, an incompatible Cosmos SDK version, and lack of support for IBC v6.x. For additional documentation, please refer to the above link. This explains the logic behind the customization of this module in Provenance. Where not explicitly called out, the Provenance Module adheres to the osmosis module.

Summary

The x/ibchooks module is an IBC middleware that enables ICS-20 token transfers to initiate cross-chain contract calls through a memo field format, supporting wasm contract execution with callback mechanisms for acknowledgments and timeouts, and providing async ack capabilities for complex cross-chain operations that require waiting for responses from other chains before finalizing transactions.

Wasm Hooks

The wasm hook is an IBC middleware which is used to allow ICS-20 token transfers to initiate contract calls. This allows cross-chain contract calls, that involve token movement. This is useful for a variety of usecases. One of primary importance is cross-chain swaps, which is an extremely powerful primitive.

The mechanism enabling this is a memo field on every ICS20 transfer packet as of IBC v3.4.0.

Wasm hooks is an IBC middleware that parses an ICS20 transfer, and if the memo field is of a particular form, executes a wasm contract call.

Cosmwasm Contract Execution Format

The cosmwasm MsgExecuteContract is defined here as the following type:

go
type MsgExecuteContract struct {
    // Sender is the actor that committed the message in the sender chain
    Sender string
    // Contract is the address of the smart contract
    Contract string
    // Msg json encoded message to be passed to the contract
    Msg RawContractMessage
    // Funds coins that are transferred to the contract on execution
    Funds sdk.Coins
}

Field mappings:

Sender: Set to Bech32(Hash("ibc-wasm-hook-intermediary" || channelID || sender)) where channelId is the channel id on the local chain

Contract: Directly obtained from the ICS-20 packet metadata

Msg: Directly obtained from the ICS-20 packet metadata

Funds: Set to the amount of funds being sent over in the ICS 20 packet

WARNING: Due to a bug in the packet forward middleware, we cannot trust the sender from chains that use PFM. Until that is fixed, we recommend chains to not trust the sender on contracts executed via IBC hooks.

Constructed cosmwasm message:

go
msg := MsgExecuteContract{
    Sender: "osmo1-hash-of-channel-and-sender",
    Contract: packet.data.memo["wasm"]["ContractAddress"],
    Msg: packet.data.memo["wasm"]["Msg"],
    Funds: sdk.NewCoin{Denom: ibc.ConvertSenderDenomToLocalDenom(packet.data.Denom), Amount: packet.data.Amount}
}

ICS20 Packet Structure

json
{
    "data": {
        "denom": "denom on counterparty chain (e.g. uatom)",
        "amount": "1000",
        "sender": "addr on counterparty chain",
        "receiver": "contract addr or blank",
        "memo": {
            "wasm": {
                "contract": "osmo1contractAddr",
                "msg": {
                    "raw_message_fields": "raw_message_data"
                }
            }
        }
    }
}

Packet Requirements:

memo is not blank

memo is valid JSON

memo has at least one key, with value "wasm"

memo["wasm"] has exactly two entries, "contract" and "msg"

memo["wasm"]["msg"] is a valid JSON object

receiver == "" || receiver == memo["wasm"]["contract"]

Execution Flow

Pre wasm hooks:

Ensure the incoming IBC packet is cryptographically valid

Ensure the incoming IBC packet is not timed out

In Wasm hooks, pre packet execution:

Ensure the packet is correctly formatted

Edit the receiver to be the hardcoded IBC module account

In wasm hooks, post packet execution:

Construct wasm message as defined before

Execute wasm message

if wasm message has error, return ErrAck

otherwise continue through middleware

Ack Callbacks

A contract that sends an IBC transfer, may need to listen for the ACK from that packet. To allow contracts to listen on the ack of specific packets, we provide Ack callbacks.

The sender of an IBC transfer packet may specify a callback for when the ack of that packet is received in the memo field of the transfer packet. Crucially, only the IBC packet sender can set the callback.

Callback Information in Memo

For the callback to be processed, the transfer packet's memo should contain the following in its JSON:

json
{"ibc_callback": "osmo1contractAddr"}

Interface for Receiving the Acks and Timeouts

The contract that awaits the callback should implement the following interface for a sudo message:

rust
#[cw_serde]
pub enum IBCLifecycleComplete {
    #[serde(rename = "ibc_ack")]
    IBCAck {
        /// The source channel (osmosis side) of the IBC packet
        channel: String,
        /// The sequence number that the packet was sent with
        sequence: u64,
        /// String encoded version of the ack as seen by OnAcknowledgementPacket(..)
        ack: String,
        /// Weather an ack is a success of failure according to the transfer spec
        success: bool,
    },
    #[serde(rename = "ibc_timeout")]
    IBCTimeout {
        /// The source channel (osmosis side) of the IBC packet
        channel: String,
        /// The sequence number that the packet was sent with
        sequence: u64,
    },
}

/// Message type for `sudo` entry_point
#[cw_serde]
pub enum SudoMsg {
    #[serde(rename = "ibc_lifecycle_complete")]
    IBCLifecycleComplete(IBCLifecycleComplete),
}

Async Acks

IBC supports the ability to send an ack back to the sender of the packet asynchronously. This is useful for cases where the packet is received, but the ack is not immediately known.

Note this ACK does not imply full revertability. It is possible that unrevertable actions have occurred even if there is an Ack Error.

Making Contract Acks Async

To support this, contracts can return an IBCAsync response from the function being executed when the packet is received:

rust
#[cw_serde]
pub struct OnRecvPacketAsyncResponse {
    pub is_async_ack: bool,
}

Sending an Async Ack

To send the async ack, the contract needs to send the MsgEmitIBCAck message:

rust
#[derive(
    Clone,
    PartialEq,
    Eq,
    ::prost::Message,
    serde::Serialize,
    serde::Deserialize,
    schemars::JsonSchema,
    CosmwasmExt,
)]
#[proto_message(type_url = "/osmosis.ibchooks.MsgEmitIBCAck")]
pub struct MsgEmitIBCAck {
    #[prost(string, tag = "1")]
    pub sender: ::prost::alloc::string::String,
    #[prost(uint64, tag = "2")]
    pub packet_sequence: u64,
    #[prost(string, tag = "3")]
    pub channel: ::prost::alloc::string::String,
}

The contract should implement the following sudo message handler:

rust
#[cw_serde]
pub enum IBCAsyncOptions {
    #[serde(rename = "request_ack")]
    RequestAck {
        /// The source channel (osmosis side) of the IBC packet
        source_channel: String,
        /// The sequence number that the packet was sent with
        packet_sequence: u64,
    },
}

#[cw_serde]
pub enum SudoMsg {
    #[serde(rename = "ibc_async")]
    IBCAsync(IBCAsyncOptions),
}

The sudo call should return an IBCAckResponse:

rust
#[cw_serde]
#[serde(tag = "type", content = "content")]
pub enum IBCAck {
    AckResponse{
        packet: Packet,
        contract_ack: ContractAck,
    },
    AckError {
        packet: Packet,
        error_description: String,
        error_response: String,
    }
}