Version: v9.0.x

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.

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

An IBCMiddleware struct implementing the Middleware interface, can be defined with its constructor as follows:

// @ x/module_name/ibc_middleware.go

// IBCMiddleware implements the ICS26 callbacks and ICS4Wrapper for the fee middleware given the
// fee keeper and the underlying application.
type IBCMiddleware struct {
  app    porttypes.IBCModule
  keeper keeper.Keeper
}

// NewIBCMiddleware creates a new IBCMiddleware given the keeper and underlying application
func NewIBCMiddleware(app porttypes.IBCModule, k keeper.Keeper) IBCMiddleware {
  return IBCMiddleware{
    app:    app,
    keeper: k,
  }
}

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.