memo
field on every ICS20 and ICS721 transfer packet as of IBC v3.4.0. Move hooks is an IBC middleware that parses an ICS20 transfer, and if the memo field is of a particular form, executes a Move contract call. We now detail the memo format for Move contract calls, and the execution guarantees provided.
Move Contract Execution Format
Before exploring the IBC metadata format, it is crucial to understand the hook data format. The MoveMsgExecute
is defined here and other types are defined here as the following type:
Sender
: We cannot trust the sender of an IBC packet, the counter-party chain has full ability to lie about it. We cannot risk this sender being confused for a particular user or module address on Initia. So we replace the sender with an account to represent the sender prefixed by the channel and a Move module prefix. This is done by setting the sender toBech32(Hash(Hash("ibc-move-hook-intermediary") + channelID/sender))
, where the channelId is the channel id on the local chain.ModuleAddress
: This field should be directly obtained from the ICS-20 packet metadataModuleName
: This field should be directly obtained from the ICS-20 packet metadataFunctionName
: This field should be directly obtained from the ICS-20 packet metadataTypeArgs
: This field should be directly obtained from the ICS-20 packet metadataArgs
: This field should be directly obtained from the ICS-20 packet metadata.
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"move"
-
memo["move"]["message"]
has exactly five entries,"module_address"
,"module_name"
,"function_name"
,"type_args"
and"args"
-
receiver
== "" ||receiver
=="module_address::module_name::function_name"
-
memo
is not blank -
memo
is valid JSON -
memo
has at least one key, with name “move”
Execution Flow
Pre Move 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 move message as defined before
- Execute move message
- if move message has error, return ErrAck
- otherwise continue through middleware
Async Callback
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 contract, which wants to receive ack callback, have to implement two functions.- ibc_ack
- ibc_timeout
memo['move']['async_callback']['id']
: the async callback id is assigned from the contract. so later it will be passed as argument of ibc_ack and ibc_timeout.memo['move']['async_callback']['module_address']
: The address of module which defines the callback function.memo['move']['async_callback']['module_name']
: The name of module which defines the callback function.
Tutorials
This tutorial will guide you through the process of deploying a Move contract and calling it from another chain using IBC hooks. We will use IBC hook from chain to call a Move contract on Initia chain in this example (L2 -> L1).Step 1. Deploy a Move contract
Write and deploy a simple token transfer contract to Initia.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.MsgExecuteMessages
in OPchild module.