wasm_hooks

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2024 License: Apache-2.0 Imports: 18 Imported by: 0

README

IBC-hooks

Wasm Hooks

The wasm hook is an IBC middleware which is used to allow 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 usecases. 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 or ICS721 transfer packet as of IBC v3.4.0. Wasm hooks is an IBC middleware that parses an ICS20 transfer, and if the memo field is of a particular form, executes a wasm contract call. We now detail the memo format for wasm contract calls, and the execution guarantees provided.

Cosmwasm Contract Execution Format

Before we dive into the IBC metadata format, we show the cosmwasm execute message format, so the reader has a sense of what are the fields we need to be setting in. The cosmwasm MsgExecuteContract is defined here as the following type:

// HookData defines a wrapper for wasm execute message
// and async callback.
type HookData struct {
 // Message is a wasm execute message which will be executed
 // at `OnRecvPacket` of receiver chain.
 Message *wasmtypes.MsgExecuteContract `json:"message,omitempty"`

 // AsyncCallback is a contract address
 AsyncCallback string `json:"async_callback,omitempty"`
}

type MsgExecuteContract struct {
 // Contract is the address of the smart contract
 Contract string
 // Msg json encoded message to be passed to the contract
 Msg RawContractMessage
}

So we detail where we want to get each of these fields from:

  • Sender: We cannot trust the sender of an IBC packet, the counterparty chain has full ability to lie about it. We cannot risk this sender being confused for a particular user or module address on the chain. So we replace the sender with an account to represent the sender prefixed by the channel and a wasm module prefix. This is done by setting the sender to Bech32(Hash("ibc-wasm-hook-intermediary" || channelID || sender)), where the channelId is the channel id on the local chain.
  • Contract: This field should be directly obtained from the ICS-20 packet metadata
  • Msg: This field should be directly obtained from the ICS-20 packet metadata.

WARNING: Due to a bug in the packet forward middleware, we cannot trust the sender from chains that use PFM. Until that is fixed, we recommend chains to not trust the sender on contracts executed via IBC hooks.

So our constructed cosmwasm message that we execute will look like:

msg := MsgExecuteContract{
 // Contract is the address of the smart contract
 Contract: packet.data.memo["wasm"]["contract"],
 // Msg json encoded message to be passed to the contract
 Msg: packet.data.memo["wasm"]["msg"],
}
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.

{
    //... 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": "contract addr or blank",
        "memo": {
           "wasm": {
              "message": {
                "contract": "init1contractAddr",
                "msg": {
                  "raw_message_fields": "raw_message_data",
                }
              }
            }
        }
    }
}

An ICS20 packet is formatted correctly for wasmhooks iff the following all hold:

  • memo is not blank
  • memo is valid JSON
  • memo has at least one key, with value "wasm"
  • memo["wasm"]["message"] has exactly two entries, "contract" and "msg"
  • memo["wasm"]["message"]["msg"] is a valid JSON object
  • receiver == "" || receiver == memo["wasm"]["contract"]

We consider an ICS20 packet as directed towards wasmhooks iff all of the following hold:

  • memo is not blank
  • memo is valid JSON
  • memo has at least one key, with name "wasm"

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

Execution flow

Pre wasm hooks:

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

In Wasm hooks, pre packet execution:

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

In wasm hooks, post packet execution:

  • Construct wasm message as defined before
  • Execute wasm message
  • if wasm message has error, return ErrAck
  • otherwise continue through middleware

Ack callbacks

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.

Design

The sender of an IBC transfer packet may specify a callback for when the ack of that packet is received in the memo field of the transfer packet.

Crucially, only the IBC packet sender can set the callback.

Use case

The crosschain swaps implementation sends an IBC transfer. If the transfer were to fail, we want to allow the sender to be able to retrieve their funds (which would otherwise be stuck in the contract). To do this, we allow users to retrieve the funds after the timeout has passed, but without the ack information, we cannot guarantee that the send hasn't failed (i.e.: returned an error ack notifying that the receiving change didn't accept it)

Implementation
Callback information in memo

For the callback to be processed, the transfer packet's memo should contain the following in its JSON:

{
  "wasm": {
    "async_callback": "init1contractAddr"
  }
}

When an ack is received, it will notify the specified contract via a sudo message.

Interface for receiving the Acks and Timeouts

The contract that awaits the callback should implement the following interface for a sudo message:

#[cw_serde]
pub enum IBCLifecycleComplete {
    #[serde(rename = "ibc_ack")]
    IBCAck {
        /// The source channel (milkyway side) of the IBC packet
        channel: String,
        /// The sequence number that the packet was sent with
        sequence: u64,
        /// String encoded version of the ack as seen by OnAcknowledgementPacket(..)
        ack: String,
        /// Weather an ack is a success of failure according to the transfer spec
        success: bool,
    },
    #[serde(rename = "ibc_timeout")]
    IBCTimeout {
        /// The source channel (milkyway side) of the IBC packet
        channel: String,
        /// The sequence number that the packet was sent with
        sequence: u64,
    },
}

/// Message type for `sudo` entry_point
#[cw_serde]
pub enum SudoMsg {
    #[serde(rename = "ibc_lifecycle_complete")]
    IBCLifecycleComplete(IBCLifecycleComplete),
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DeriveIntermediateSender added in v1.2.0

func DeriveIntermediateSender(channel, originalSender string) string

DeriveIntermediateSender compute intermediate sender address Bech32(Hash(Hash("ibc-hook-intermediary") + channelID/sender))

func MustExtractDenomFromPacketOnRecv added in v1.2.0

func MustExtractDenomFromPacketOnRecv(packet ibcexported.PacketI) string

MustExtractDenomFromPacketOnRecv takes a packet with a valid ICS20 token data in the Data field and returns the denom as represented in the local chain. If the data cannot be unmarshalled this function will panic

Types

type HookData

type HookData struct {
	// Message is a wasm execute message which will be executed
	// at `OnRecvPacket` of receiver chain.
	Message *wasmtypes.MsgExecuteContract `json:"message,omitempty"`

	// AsyncCallback is a contract address
	AsyncCallback string `json:"async_callback,omitempty"`
}

HookData defines a wrapper for wasm execute message and async callback.

type WasmHooks

type WasmHooks struct {
	// contains filtered or unexported fields
}

func NewWasmHooks

func NewWasmHooks(codec codec.Codec, ac address.Codec, wasmKeeper *wasmkeeper.Keeper) *WasmHooks

func (WasmHooks) OnAcknowledgementPacketOverride

func (h WasmHooks) OnAcknowledgementPacketOverride(im ibchooks.IBCMiddleware, ctx sdk.Context, packet channeltypes.Packet, acknowledgement []byte, relayer sdk.AccAddress) error

func (WasmHooks) OnRecvPacketOverride

func (h WasmHooks) OnRecvPacketOverride(im ibchooks.IBCMiddleware, ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress) ibcexported.Acknowledgement

func (WasmHooks) OnTimeoutPacketOverride

func (h WasmHooks) OnTimeoutPacketOverride(im ibchooks.IBCMiddleware, ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL