Move IBC Hooks

The Move hook is an IBC middleware that allows 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 use cases. 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 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. The following sections 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 Move MsgExecute is defined here and other types are defined here as the following type:

// HookData defines a wrapper for Move execute message
// and async callback.
type HookData struct {
 // Message is a Move execute message which will be executed
 // at `OnRecvPacket` of receiver chain.
 Message movetypes.MsgExecute `json:"message"`

 // AsyncCallback is a callback message which will be executed
 // at `OnTimeoutPacket` and `OnAcknowledgementPacket` of
 // sender chain.
 AsyncCallback *AsyncCallback `json:"async_callback,omitempty"`
}

// AsyncCallback is data wrapper which is required
// when we implement async callback.
type AsyncCallback struct {
 // callback id should be issued from the executor contract
 Id            uint64 `json:"id"`
 ModuleAddress string `json:"module_address"`
 ModuleName    string `json:"module_name"`
}

type MsgExecute struct {
 // Sender is the actor that signed the messages
 Sender string `protobuf:"bytes,1,opt,name=sender,proto3" json:"sender,omitempty"`
 // ModuleAddress is the address of the module deployer
 ModuleAddress string `protobuf:"bytes,2,opt,name=module_address,json=moduleAddress,proto3" json:"module_address,omitempty"`
 // ModuleName is the name of module to execute
 ModuleName string `protobuf:"bytes,3,opt,name=module_name,json=moduleName,proto3" json:"module_name,omitempty"`
 // FunctionName is the name of a function to execute
 FunctionName string `protobuf:"bytes,4,opt,name=function_name,json=functionName,proto3" json:"function_name,omitempty"`
 // TypeArgs is the type arguments of a function to execute
 // ex) "0x1::BasicCoin::Initia", "bool", "u8", "u64"
 TypeArgs []string `protobuf:"bytes,5,rep,name=type_args,json=typeArgs,proto3" json:"type_args,omitempty"`
 // Args is the arguments of a function to execute
 // - number: little endian
 // - string: base64 bytes
 Args [][]byte `protobuf:"bytes,6,rep,name=args,proto3" json:"args,omitempty"`
}

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 a Move module prefix. This is done by setting the sender to Bech32(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 metadata
• ModuleName: This field should be directly obtained from the ICS-20 packet metadata
• FunctionName: This field should be directly obtained from the ICS-20 packet metadata
• TypeArgs: This field should be directly obtained from the ICS-20 packet metadata
• Args: This field should be directly obtained from the ICS-20 packet metadata.

The constructed move message looks like:

msg := MsgExecuteContract{
 // Sender is the actor that signed the messages
 Sender: "init1-hash-of-channel-and-sender",
 // ModuleAddress is the address of the module deployer
 ModuleAddress: packet.data.memo["move"]["message"]["module_address"],
    // ModuleName is the name of module to execute
 ModuleName: packet.data.memo["move"]["message"]["module_name"],
    // FunctionName is the name of a function to execute
 FunctionName: packet.data.memo["move"]["message"]["function_name"],
 // TypeArgs is the type arguments of a function to execute
 // ex) "0x1::BasicCoin::Initia", "bool", "u8", "u64"
 TypeArgs: packet.data.memo["move"]["message"]["type_args"],
 // Args is the arguments of a function to execute
 // - number: little endian
 // - string: base64 bytes
 Args: packet.data.memo["move"]["message"]["args"]
}

ICS20 Packet Structure

Given the details above, here is the implied ICS20 packet data structure. ICS20 is JSON native, so the memo format uses JSON.

{
  //... other ibc fields that we don't care about
  "data": {
    "denom": "denom on counterparty chain (e.g. uatom)", // will be transformed to the local denom (ibc/...)
    "amount": "1000",
    "sender": "addr on counterparty chain", // will be transformed
    "receiver": "ModuleAddr::ModuleName::FunctionName",
    "memo": {
      "move": {
        // execute message on receive packet
        "message": {
          "module_address": "0x1",
          "module_name": "dex",
          "function_name": "swap",
          "type_args": ["0x1::native_uinit::Coin", "0x1::native_uusdc::Coin"],
          "args": ["base64 encoded bytes array"]
        },
        // optional field to get async callback (ack and timeout)
        "async_callback": {
          "id": 1,
          "module_address": "0x1",
          "module_name": "dex"
        }
      }
    }
  }
}

An ICS20 packet is formatted correctly for movehooks if the following all hold:

• 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"

An ICS20 packet is considered directed towards movehooks if all of the following hold:

• memo is not blank
• memo is valid JSON
• memo has at least one key, with name “move”

If an ICS20 packet is not directed towards movehooks, movehooks doesn’t do anything. If an ICS20 packet is directed towards movehooks, and is formatted incorrectly, then movehooks returns an error.

Execution Flow

Pre Move hooks:

• Ensure the incoming IBC packet is cryptographically valid
• Ensure the incoming IBC packet is not timed out.

In Move hooks, pre packet execution:

• Ensure the packet is correctly formatted (as defined above)
• Edit the receiver to be the hardcoded IBC module account

In Move hooks, post packet execution:

• 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, the framework provides Ack callbacks. The contract, which wants to receive ack callback, has to implement two functions.

• ibc_ack
• ibc_timeout

public entry fun ibc_ack(
  account: &signer,
  callback_id: u64,
  success:     bool,
)

public entry fun ibc_timeout(
  account: &signer,
  callback_id: u64,
)

Also when a contract makes an IBC transfer request, it should provide async callback data through memo field.

• memo['move']['async_callback']['id']: the async callback id is assigned from the contract. so later it will be passed as an 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. This example uses an IBC hook from chain to call a Move contract on Initia chain (L2 -> L1).

Step 1. Deploy a Move Contract

Write and deploy a simple token transfer contract to Initia.

module deployer::example {
  use initia_std::coin;
  use initia_std::object::Object;
  use initia_std::fungible_asset::Metadata;
  public entry fun simple_transfer(
      account: &signer,
      receiver: address,
      metadata: Object<Metadata>,
      amount: u64
  ){
      let token = coin::withdraw(account, metadata, amount);
      coin::deposit(receiver, token);
  }
}

Step 2. Update IBC Hook ACL for the Contract

IBC hooks have the power to execute any function on the counterparty chain, which can easily be exploited for phishing. Therefore, you need to set the ACL for the contract to prevent unauthorized access.

// for initia L1, you can update ACL by submitting a proposal
const aclMsg = new MsgUpdateACL(
  'init10d07y265gmmuvt4z0w9aw880jnsr700j55nka3', // authority
  'init14qcr2mczuzlav8z2uqm3d0zdw04nuhf2jgndc3', // contract address
  true, // allow
)

const msgs = [
  new MsgSubmitProposal(
    [aclMsg],
    '100000000uinit', // deposit
    proposer.key.accAddress, // proposer
    'uinit', // metadata
    'awesome proposal', // title
    'it is awesome', // summary
    false, // expedited
  ),
]

const signedTx = await proposer.createAndSignTx({ msgs })
await proposer.rest.tx.broadcast(signedTx).then((res) => console.log(res))

If you want to update MiniMove ACL, you need to use MsgExecuteMessages in OPchild module.

const aclMsg = new MsgUpdateACL(
  'init10d07y265gmmuvt4z0w9aw880jnsr700j55nka3', // authority
  'init14qcr2mczuzlav8z2uqm3d0zdw04nuhf2jgndc3', // contract address
  true, // allow
)

const msgs = [new MsgExecuteMessages(proposer.key.accAddress, [aclMsg])]
const signedTx = await proposer.createAndSignTx({ msgs })
await proposer.rest.tx.broadcast(signedTx).then((res) => console.log(res))

You can check the ACL list using the following command.

curl -X GET "https://rest.testnet.initia.xyz/initia/ibchooks/v1/acls" -H "accept: application/json"

Response:

{
  "acls": [],
  "pagination": {
    "next_key": null,
    "total": "0"
  }
}

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.

import {
  bcs,
  Coin,
  Height,
  RESTClient,
  MnemonicKey,
  MsgTransfer,
  Wallet,
} from '@initia/initia.js'

function createHook(params: object) {
  const hook = { move: { message: params } }
  return JSON.stringify(hook)
}

async function main() {
  const l1RestClient = new RESTClient('https://rest.testnet.initia.xyz', {
    gasAdjustment: '1.75',
    gasPrices: '0.015uinit',
  })

  const l2RestClient = new RESTClient(
    'https://rest-move-1.anvil.asia-southeast.initia.xyz',
    {
      gasAdjustment: '1.75',
      gasPrices:
        '0.15l2/07b129ceb9c4b0bdef7db171ce1e22f90d34bc930058b23e21adf8cc938d8145', // set l2 gas price
    },
  )

  const sender = new Wallet(
    l2RestClient,
    new MnemonicKey({
      mnemonic: 'power elder gather acoustic ...',
    }),
  )

  const recipientAddress = 'init1wgl839zxdh5c89mvc4ps97wyx6ejjygxs4qmcx'
  const tokenPair = await l1RestClient.ophost.tokenPairByL1Denom(1458, 'uinit') // { l1_denom: 'uinit', l2_denom: 'l2/07b129ceb9c4b0bdef7db171ce1e22f90d34bc930058b23e21adf8cc938d8145' }

  const ibcTrace = 'transfer/' + 'channel-0/' + tokenPair.l2_denom // IBC denom trace = `port_id/channel_id/denom`
  const ibcDenomHash = await l1RestClient.ibcTransfer.denomHash(ibcTrace) // IBC denom = `ibc/${denom_hash}`
  const tokenMetadata = await l1RestClient.move.metadata('ibc/' + ibcDenomHash)
  const amount = 1000

  const msgs = [
    new MsgTransfer(
      'transfer',
      'channel-0',
      new Coin(tokenPair.l2_denom, 10),
      sender.key.accAddress,
      '0xA830356F02E0BFD61C4AE03716BC4D73EB3E5D2A::example::simple_transfer', // IBC hook receiver = `ModuleAddress::ModuleName::FunctionName`
      new Height(0, 0),
      ((new Date().valueOf() + 100000) * 1000000).toString(),
      createHook({
        module_address: '0xA830356F02E0BFD61C4AE03716BC4D73EB3E5D2A',
        module_name: 'example',
        function_name: 'simple_transfer',
        type_args: [],
        args: [
          bcs.address().serialize(recipientAddress).toBase64(),
          bcs.address().serialize(tokenMetadata).toBase64(),
          bcs.u64().serialize(amount).toBase64(),
        ],
      }),
    ),
  ]

  const signedTx = await sender.createAndSignTx({ msgs })
  await l2RestClient.tx.broadcastSync(signedTx).then((res) => console.log(res))
}

main()