IBC Middleware for packet forwarding

[aeryz]

Introduction

We need to do packet forwarding to enable seemless IBC connection between Ethereum and the Cosmos chains. Since there isn't any built-in multihop mechanism exist in the IBC protocol yet, we need to create a custom protocol on top of IBC to enable this functionality.

Design

This protocol is planned to be built as an IBC Middleware because this mechanism provides the lowest level access to the IBC protocol stack. And it's better to handle packet forwarding at the routing phase instead of handling it at the app level.

Our end goal is to be able to forward any IBC packet which means this protocol shouldn't be specific to any use case or apps such as ics20 or ucs01.

IBC Middleware

How it works?

IBC middlewares have the ability to hook into the IBC module callbacks such as OnChanOpenInit, OnRecvPacket, etc. They implement the same interface as a regular IBC module so they have access to any data that is passed around during an execution. This means that they can alter or save any data they need and then they are expected to pass the execution to the next middleware.

The IBC Middleware interface

// Middleware must implement IBCModule to wrap communication from core IBC to underlying application
// and ICS4Wrapper to wrap communication from underlying application to core IBC.
type Middleware interface {
	IBCModule // IBC hooks such as `OnChanOpenInit, OnRecvPacket, etc`
	ICS4Wrapper // Additional functions for sending packets and writing acks
}

Our IBC Middleware

Our module will not interfere with the channel opening or closing mechanisms so it will just pass the execution to the next layer.

Eg.

func (im IBCMiddleware) OnChanOpenAck(
	ctx sdk.Context,
	portID, channelID string,
	counterpartyChannelID string,
	counterpartyVersion string,
) error {
	return im.ics4Wrapper.OnChanOpenAck(ctx, portID, channelID, counterpartyChannelID, counterpartyVersion)
}

When it receives a packet, it will try to parse the data to figure out if the middleware is targeted or not. The data type will be opaque over the underlying data and it will contain the necessary information to forward the packet.

Here is the definition of the middleware's packet.

type ForwardPacket struct {
    // Opaque data
    Packet           byte[]
    // Channel to be used as the source to jump from middle chain to the destination chain
    HopChannel string
}

Receiving a packet

func (im IBCMiddleware) OnRecvPacket(
	ctx sdk.Context,
	packet channeltypes.Packet,
	relayer sdk.AccAddress,
) ibcexported.Acknowledgement {
    forwardPacket, err := packet.decode()

    if err != nil {
        // The packet is either incorrectly encoded or this packet is not meant to be forwarded
        return im.ics4Wrapper.OnRecvPacket(ctx, packet, relayer)
    }

    if fowardPacket.HopChannel == "" {
        // We can choose to support empty hop data. This would mean that the packet won't be forwarded and handled by
       // this chain. But imo, the source app should handle this and if the packet is not meant to be forwarded, it should
       // not be wrapped by a `ForwardPacket`.
        panic!("error")
    }

    channel, found := k.GetChannel(ctx, packet.GetDestPort(), forwardPacket.HopChannel)

    if !found {
        panic("error")
    }

    sequence, err = im.SendPacket(ctx, /* capability */, packet.GetDestPort(), forwardPacket.HopChannel, packet.TimeoutHeight, packet.TimeoutTimestamp, packet.Data)

    // We need to defer the ack until we get ack from the destination chain, hence we save the packet metadata
    // to be later used in `OnAcknowledgePacket`
    im.DeferAck(packet, forwardPacket.HopChannel, sequence)

    if err != nil {
        panic("error")
    }

    // We return nil as the acknowledgement. This will result in the ack not to be written.
    return nil
}

Getting an acknowledgement

func (im IBCMiddleware) OnAcknowledgementPacket(
	ctx sdk.Context,
	packet channeltypes.Packet,
	acknowledgement []byte,
	relayer sdk.AccAddress,
) error {
    forwardPacket, err := packet.decode()

    if err != nil {
        // We don't mess with other packets
        return im.ics4Wrapper.OnAcknowledgementPacket(ctx, packet, relayer)
    }

     originalPacket := im.ProcessAck(ctx, packet.SourcePort, forwardPacket.HopChannel, packet.Sequence)

    if originalPacket != nil {
        // we need to acknowledge the original file that we got
        return im.ics4Wrapper.WriteAcknowledgement(ctx, /* capability */, originalPacket, acknowledgement)
    }

    return im.ics4Wrapper.OnAcknowledgementPacket(ctx, packet, acknowledgement, relayer)
}

[benluelo]

is it required to do this in a go module, or is it possible to do it in a cosmwasm contract?

[aeryz]

Just saw this, I'll take a look at it to see if it would work for our case. https://medium.com/the-interchain-foundation/introducing-the-callbacks-middleware-compose-smart-contracts-and-modules-with-ibc-6f3fb527e44a

[hussein-aitlahcen]

I agree with this, we should try to push as much code as we can to cosmwasm

[aeryz]

Yeah I agree too