memo
field in the ICS20 and ICS721 transfer packets, as introduced in IBC v3.4.0.
EVM Contract Execution Format
Before we dive into the IBC metadata format, let’s take a look at the hook data format and address which fields we need to be setting. The EVMMsgCall
is defined here and other types are defined here.
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 evm module prefix. This is done by setting the sender toBech32(Hash(Hash("ibc-evm-hook-intermediary") + channelID/sender))
, where the channelId is the channel id on the local chain.ContractAddr
: This field should be directly obtained from the ICS-20 packet metadataInput
: 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"evm"
-
memo["evm"]["message"]
has exactly five entries,"contract_addr"
and"input"
-
receiver
== "" ||receiver
=="module_address::module_name::function_name"
memo
is not blankmemo
is valid JSONmemo
has at least one key, with name"evm"
Execution flow
Pre evm hooks:- Ensure the incoming IBC packet is cryptogaphically 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 evm message as defined before
- Execute evm message
- if evm 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['evm']['async_callback']['id']
: the async callback id is assigned from the contract. so later it will be passed as argument ofibc_ack
andibc_timeout
.memo['evm']['async_callback']['contract_addr']
: The address of module which defines the callback function.
Tutorials
This tutorial will guide you through the process of deploying a EVM contract and calling it from another chain using IBC hooks. We will use IBC hook from Initia chain to call a EVM contract on MiniEVM chain in this example.Step 1. Deploy a contract on MiniEVM chain
Write and deploy a simple counter 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. To update MiniEVM ACL, you need to useMsgExecuteMessages
in OPchild module.