Skip to main content
EVM hooks, implemented as IBC middleware, play a critical role in facilitating cross-chain contract calls that involve token transfers. This capability is particularly crucial for cross-chain swaps, providing a robust mechanism for decentralized trading across different blockchain networks. The key to this functionality is the memo field in the ICS20 and ICS721 transfer packets, as introduced in IBC v3.4.0.

EVM Contract Execution Format

Before diving into the IBC metadata format, take a look at the hook data format and the fields that need to be set. The EVM MsgCall is defined here and other types are defined here.
Here is where each of these fields comes from:
  • Sender: The sender of an IBC packet cannot be trusted, as the counter-party chain has full ability to lie about it. This sender must not be confused for a particular user or module address on Initia. So the sender is replaced with an account to represent the sender prefixed by the channel and an evm module prefix. This is done by setting the sender to Bech32(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 metadata
  • Input: This field should be directly obtained from the ICS-20 packet metadata.
The constructed EVM call message looks like:

ICS20 packet structure

Given the details above, here is the implied ICS20 packet data structure. ICS20 is JSON native, so we use JSON for the memo format.
An ICS20 packet is formatted correctly for evmhooks iff the following all hold:
  • memo is not blank
  • memo is valid JSON
  • memo has at least one key, with value "evm"
  • memo["evm"]["message"] has exactly two entries, "contract_addr" and "input"
  • receiver == "" || receiver == "module_address::module_name::function_name"
An ICS20 packet is considered directed towards evmhooks iff all of the following hold:
  • memo is not blank
  • memo is valid JSON
  • memo has at least one key, with name "evm"
If an ICS20 packet is not directed towards evmhooks, evmhooks doesn’t do anything. If an ICS20 packet is directed towards evmhooks, and is formatted incorrectly, then evmhooks returns an error.

Execution flow

Pre evm hooks:
  • Ensure the incoming IBC packet is cryptographically valid
  • Ensure the incoming IBC packet is not timed out.
In evm hooks, pre packet execution:
  • Ensure the packet is correctly formatted (as defined above)
  • Edit the receiver to be the hardcoded IBC module account
In evm hooks, post packet execution:
  • 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, the framework provides Ack callbacks. The contract that wants to receive ack callbacks must implement two functions.
  • ibc_ack
  • ibc_timeout
Also when a contract makes an IBC transfer request, it should provide async callback data through memo field.
  • memo['evm']['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['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 an EVM contract and calling it from another chain using IBC hooks. This example uses an IBC hook from Initia chain to call an EVM contract on MiniEVM chain.

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 hooks have the power to execute any functions on the counterparty chain and this can be used for phishing easily. So, you need to set the ACL for the contract to prevent unauthorized access. To update MiniEVM ACL, use MsgExecuteMessages in OPchild module.
Response:

Step 3. Execute IBC Hooks Message

After the contract is deployed and the ACL is set, you can execute the IBC hooks message to call the contract.