> ## Documentation Index
> Fetch the complete documentation index at: https://docs.initia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/initia-labs/initia/blob/main/x/move/types/tx.pb.go)
and other types are defined
[here](https://github.com/initia-labs/initia/blob/main/x/ibc-hooks/move-hooks/message.go)
as the following type:

```go theme={null}
// 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:

```go theme={null}
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.

```json theme={null}
{
  //... 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:

* [x] `memo` is not blank
* [x] `memo` is valid JSON
* [x] `memo` has at least one key, with value `"move"`
* [x] `memo["move"]["message"]` has exactly five entries, `"module_address"`,
  `"module_name"`, `"function_name"`, `"type_args"` and `"args"`
* [x] `receiver` == "" || `receiver` ==
  `"module_address::module_name::function_name"`

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

* [x] `memo` is not blank
* [x] `memo` is valid JSON
* [x] `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

```rust theme={null}
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.

```move theme={null}
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.

```typescript theme={null}
// 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.

```typescript theme={null}
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.

```bash theme={null}
curl -X GET "https://rest.testnet.initia.xyz/initia/ibchooks/v1/acls" -H "accept: application/json"
```

Response:

```json theme={null}
{
  "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.

```typescript theme={null}
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()
```