memo
field on every ICS20 or ICS721 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. We now detail the memo format for wasm contract calls, and the execution guarantees provided.
Cosmwasm Contract Execution Format
Before we dive into the IBC metadata format, we show the CosmWasm execute message format, so the reader has a sense of what are the fields we need to be setting in. The CosmWasmMsgExecuteContract
is defined here as the following type:
Sender
: We cannot trust the sender of an IBC packet, the counterparty chain has full ability to lie about it. We cannot risk this sender being confused for a particular user or module address on Osmosis. So we replace the sender with an account to represent the sender prefixed by the channel and a wasm module prefix. This is done by setting the sender to Bech32(Hash(“ibc-wasm-hook-intermediary” || channelID || sender)), where the channelId is the channel id on the local chain.Contract
: This field should be directly obtained from the ICS-20 packet metadataMsg
: This field should be directly obtained from the ICS-20 packet metadata.Funds
: This field is set to the amount of funds being sent over in the ICS 20 packet. One detail is that the denom in the packet is the counterparty chains representation of the denom, so we have to translate it to Osmosis’ representation.
ICS20 packet structure
So given the details above, we propagate the implied ICS20 packet data structure. ICS20 is JSON native, so we use JSON for the memo format.-
memo
is not blank -
memo
is valid JSON -
memo
has at least one key, with value"wasm"
-
memo["wasm"]["message"]
has exactly two entries,"contract"
,"msg"
and"fund"
-
memo["wasm"]["message"]["msg"]
is a valid JSON object -
receiver
== "" ||receiver
==memo["wasm"]["contract"]
-
memo
is not blank -
memo
is valid JSON -
memo
has at least one key, with name"wasm"
Execution flow
Pre Wasm hooks:- Ensure the incoming IBC packet is cryptographically valid
- Ensure the incoming IBC packet is not timed out.
- Ensure the packet is correctly formatted (as defined above)
- Edit the receiver to be the hardcoded IBC module account
- 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.Design
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.Use case
The crosschain swaps implementation sends an IBC transfer. If the transfer were to fail, we want to allow the sender to be able to retrieve their funds (which would otherwise be stuck in the contract). To do this, we allow users to retrieve the funds after the timeout has passed, but without the ack information, we cannot guarantee that the send hasn’t failed (i.e.: returned an error ack notifying that the receiving change didn’t accept it)Implementation
Callback information in memo
For the callback to be processed, the transfer packet’s memo should contain the following in its JSON:Interface for receiving the Acks and Timeouts
The contract that awaits the callback should implement the following interface for a sudo message:Tutorials
This tutorial will guide you through the process of deploying a Wasm contract and calling it from another chain using IBC hooks. We will use IBC hook from Initia chain to call a Wasm contract on MiniWasm chain in this example.Step 1. Deploy a Wasm contract
Step 2. Update IBC hook ACL for the contract
IBC hook has strong power to execute any functions in counterparty chain and this can be used for fishing easily. So, we need to set the ACL for the contract to prevent unauthorized access. To update MiniWasm ACL, you need to useMsgExecuteMessages
in OPchild module.