Version: v7.4.x

IBC middleware

Synopsis

Learn how to write your own custom middleware to wrap an IBC application, and understand how to hook different middleware to IBC base applications to form different IBC application stacks :::.

This document serves as a guide for middleware developers who want to write their own middleware and for chain developers who want to use IBC middleware on their chains.

IBC applications are designed to be self-contained modules that implement their own application-specific logic through a set of interfaces with the core IBC handlers. These core IBC handlers, in turn, are designed to enforce the correctness properties of IBC (transport, authentication, ordering) while delegating all application-specific handling to the IBC application modules. However, there are cases where some functionality may be desired by many applications, yet not appropriate to place in core IBC.

Middleware allows developers to define the extensions as separate modules that can wrap over the base application. This middleware can thus perform its own custom logic, and pass data into the application so that it may run its logic without being aware of the middleware's existence. This allows both the application and the middleware to implement its own isolated logic while still being able to run as part of a single packet flow.

note

Pre-requisite readings

Definitions

Middleware: A self-contained module that sits between core IBC and an underlying IBC application during packet execution. All messages between core IBC and underlying application must flow through middleware, which may perform its own custom logic.

Underlying Application: An underlying application is the application that is directly connected to the middleware in question. This underlying application may itself be middleware that is chained to a base application.

Base Application: A base application is an IBC application that does not contain any middleware. It may be nested by 0 or multiple middleware to form an application stack.

Application Stack (or stack): A stack is the complete set of application logic (middleware(s) + base application) that gets connected to core IBC. A stack may be just a base application, or it may be a series of middlewares that nest a base application.

Create a custom IBC middleware

IBC middleware will wrap over an underlying IBC application and sits between core IBC and the application. It has complete control in modifying any message coming from IBC to the application, and any message coming from the application to core IBC. Thus, middleware must be completely trusted by chain developers who wish to integrate them, however this gives them complete flexibility in modifying the application(s) they wrap.

Interfaces

// Middleware implements the ICS26 Module interface
type Middleware interface {
    porttypes.IBCModule // middleware has access to an underlying application which may be wrapped by more middleware
    ics4Wrapper: ICS4Wrapper // middleware has access to ICS4Wrapper which may be core IBC Channel Handler or a higher-level middleware that wraps this middleware.
}

// This is implemented by ICS4 and all middleware that are wrapping base application.
// The base application will call `sendPacket` or `writeAcknowledgement` of the middleware directly above them
// which will call the next middleware until it reaches the core IBC handler.
type ICS4Wrapper interface {
    SendPacket(
        ctx sdk.Context,
        chanCap *capabilitytypes.Capability,
        sourcePort string,
        sourceChannel string,
        timeoutHeight clienttypes.Height,
        timeoutTimestamp uint64,
        data []byte,
    ) (sequence uint64, err error)

    WriteAcknowledgement(
        ctx sdk.Context,
        chanCap *capabilitytypes.Capability,
        packet exported.PacketI,
        ack exported.Acknowledgement,
    ) error

    GetAppVersion(
        ctx sdk.Context,
        portID,
        channelID string,
    ) (string, bool)
}

Implement `IBCModule` interface and callbacks

The IBCModule is a struct that implements the ICS-26 interface (porttypes.IBCModule). It is recommended to separate these callbacks into a separate file ibc_module.go. As will be mentioned in the integration section, this struct should be different than the struct that implements AppModule in case the middleware maintains its own internal state and processes separate SDK messages.

The middleware must have access to the underlying application, and be called before during all ICS-26 callbacks. It may execute custom logic during these callbacks, and then call the underlying application's callback. Middleware may choose not to call the underlying application's callback at all. Though these should generally be limited to error cases.

In the case where the IBC middleware expects to speak to a compatible IBC middleware on the counterparty chain, they must use the channel handshake to negotiate the middleware version without interfering in the version negotiation of the underlying application.

Middleware accomplishes this by formatting the version in a JSON-encoded string containing the middleware version and the application version. The application version may as well be a JSON-encoded string, possibly including further middleware and app versions, if the application stack consists of multiple milddlewares wrapping a base application. The format of the version is specified in ICS-30 as the following:

{
  "<middleware_version_key>": "<middleware_version_value>",
  "app_version": "<application_version_value>"
}

The <middleware_version_key> key in the JSON struct should be replaced by the actual name of the key for the corresponding middleware (e.g. fee_version).

During the handshake callbacks, the middleware can unmarshal the version string and retrieve the middleware and application versions. It can do its negotiation logic on <middleware_version_value>, and pass the <application_version_value> to the underlying application.

The middleware should simply pass the capability in the callback arguments along to the underlying application so that it may be claimed by the base application. The base application will then pass the capability up the stack in order to authenticate an outgoing packet/acknowledgement.

In the case where the middleware wishes to send a packet or acknowledgment without the involvement of the underlying application, it should be given access to the same scopedKeeper as the base application so that it can retrieve the capabilities by itself.