Create a custom IBC middleware

IBC middleware will wrap over an underlying IBC application (a base application or downstream middleware) and sits between core IBC and the base application.

middleware developers must use the same serialization and deserialization method as in ibc-go’s codec: transfertypes.ModuleCdc.[Must]MarshalJSON

For middleware builders this means:

import transfertypes "github.com/cosmos/ibc-go/v11/modules/apps/transfer/types"
transfertypes.ModuleCdc.[Must]MarshalJSON
func MarshalAsIBCDoes(ack channeltypes.Acknowledgement) ([]byte, error) {
    return transfertypes.ModuleCdc.MarshalJSON(&ack)
}

The interfaces a middleware must implement are found here.

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

  // SetUnderlyingModule sets the underlying IBC module. This function may be used after
	// the middleware's initialization to set the ibc module which is below this middleware.
	SetUnderlyingApplication(IBCModule)
}

An IBCMiddleware struct implementing the Middleware interface can be defined with its constructor as follows. Note that the constructor does not accept the underlying app or ics4Wrapper — those are wired up later by IBCStackBuilder via SetUnderlyingApplication and SetICS4Wrapper:

// @ x/module_name/ibc_middleware.go

// IBCMiddleware implements the ICS26 callbacks and ICS4Wrapper for the middleware given its keeper.
type IBCMiddleware struct {
    app         porttypes.IBCModule
    ics4Wrapper porttypes.ICS4Wrapper
    keeper      *keeper.Keeper
}

// NewIBCMiddleware creates a new IBCMiddleware given the keeper.
// The underlying app and ICS4Wrapper are set later by IBCStackBuilder.
func NewIBCMiddleware(k *keeper.Keeper) *IBCMiddleware {
    return &IBCMiddleware{
        keeper: k,
    }
}

// SetUnderlyingApplication sets the underlying IBC module.
func (im *IBCMiddleware) SetUnderlyingApplication(app porttypes.IBCModule) {
    if im.app != nil {
        panic("underlying application already set")
    }
    im.app = app
}

// SetICS4Wrapper sets the ICS4Wrapper.
func (im *IBCMiddleware) SetICS4Wrapper(wrapper porttypes.ICS4Wrapper) {
    if wrapper == nil {
        panic("ICS4Wrapper cannot be nil")
    }
    im.ics4Wrapper = wrapper
}

Implement `IBCModule` interface

IBCMiddleware is a struct that implements the ICS-26 IBCModule interface (porttypes.IBCModule). It is recommended to separate these callbacks into a separate file ibc_middleware.go.

Note how this is analogous to implementing the same interfaces for IBC applications that act as base applications.

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 it 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.

The IBCModule interface consists of the channel handshake callbacks and packet callbacks. Most of the custom logic will be performed in the packet callbacks, in the case of the channel handshake callbacks, introducing the middleware requires consideration to the version negotiation.

Channel handshake callbacks

Version negotiation

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.

NOTE: Middleware that does not need to negotiate with a counterparty middleware on the remote stack will not implement the version unmarshalling and negotiation, and will simply perform its own custom logic on the callbacks without relying on the counterparty behaving similarly.