Middleware Developer and Integration Guide (#477)

* write handshake docs

* initial docs

* fix links

* remove since

* Update docs/ibc/middleware/integration.md

Co-authored-by: Damian Nolan <damiannolan@gmail.com>

* Apply suggestions from code review

Co-authored-by: colin axnér <25233464+colin-axner@users.noreply.github.com>

* address suggestions

* add in-code interfaces and clarify cap docs

* fix carlos nit

* Module -> IBCModule

Co-authored-by: Damian Nolan <damiannolan@gmail.com>
Co-authored-by: colin axnér <25233464+colin-axner@users.noreply.github.com>

docs/ibc/middleware/develop.md

@@ -0,0 +1,239 @@
+<!--
+order: 1
+-->
+
+# IBC Middleware
+
+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 {synopsis}.
+
+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.
+
+## Pre-requisite Readings
+
+- [IBC Overview](../overview.md) {prereq}
+- [IBC Integration](../integration.md) {prereq}
+- [IBC Application Developer Guide](../apps.md) {prereq}
+
+## 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
+
+```go
+// Middleware implements the ICS26 Module interface
+type Middleware interface {
+    porttypes.IBCModule // middleware has acccess 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.
+}
+```
+
+```typescript
+// 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, packet exported.Packet) error
+    WriteAcknowledgement(ctx sdk.Context, chanCap *capabilitytypes.Capability, packet exported.Packet, ack []byte) error
+}
+```
+
+### Implement `IBCModule` interface and callbacks
+
+The IBCModule is struct that implements the ICS26Interface (`porttypes.IBCModule`). It is recommended to separate these callbacks into a separate file `ibc_module.go`. As will be mentioned in the [integration doc](./integration.md), 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 the following format: `{mw-version}:{app-version}`.
+
+During the handshake callbacks, the middleware can split the version into: `mw-version`, `app-version`. It can do its negotiation logic on `mw-version`, and pass the `app-version` 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.
+
+### Handshake callbacks
+
+```go
+func (im IBCModule) OnChanOpenInit(ctx sdk.Context,
+    order channeltypes.Order,
+    connectionHops []string,
+    portID string,
+    channelID string,
+    channelCap *capabilitytypes.Capability,
+    counterparty channeltypes.Counterparty,
+    version string,
+) error {
+    // core/04-channel/types contains a helper function to split middleware and underlying app version
+    middlewareVersion, appVersion = channeltypes.SplitChannelVersion(version)
+    doCustomLogic()
+    im.app.OnChanOpenInit(
+        ctx,
+        order,
+        connectionHops,
+        portID,
+        channelID,
+        channelCap,
+        counterparty,
+        appVersion, // note we only pass app version here
+    )
+}
+
+func OnChanOpenTry(
+    ctx sdk.Context,
+    order channeltypes.Order,
+    connectionHops []string,
+    portID,
+    channelID string,
+    channelCap *capabilitytypes.Capability,
+    counterparty channeltypes.Counterparty,
+    version,
+    counterpartyVersion string,
+) error {
+      // core/04-channel/types contains a helper function to split middleware and underlying app version
+      cpMiddlewareVersion, cpAppVersion = channeltypes.SplitChannelVersion(counterpartyVersion)
+      middlewareVersion, appVersion = channeltypes.SplitChannelVersion(version)
+      if !isCompatible(cpMiddlewareVersion, middlewareVersion) {
+          return error
+      }
+      doCustomLogic()
+
+      // call the underlying applications OnChanOpenTry callback
+      app.OnChanOpenTry(
+          ctx,
+          order,
+          connectionHops,
+          portID,
+          channelID,
+          channelCap,
+          counterparty,
+          cpAppVersion, // note we only pass counterparty app version here
+          appVersion, // only pass app version
+      )
+}
+
+func OnChanOpenAck(
+    ctx sdk.Context,
+    portID,
+    channelID string,
+    counterpartyVersion string,
+) error {
+      // core/04-channel/types contains a helper function to split middleware and underlying app version
+      middlewareVersion, appVersion = channeltypes.SplitChannelVersion(version)
+      if !isCompatible(middlewareVersion) {
+          return error
+      }
+      doCustomLogic()
+
+      // call the underlying applications OnChanOpenTry callback
+      app.OnChanOpenAck(ctx, portID, channelID, appVersion)
+}
+
+func OnChanOpenConfirm(
+    ctx sdk.Context,
+    portID,
+    channelID string,
+) error {
+    doCustomLogic()
+
+    app.OnChanOpenConfirm(ctx, portID, channelID)
+}
+
+OnChanCloseInit(
+    ctx sdk.Context,
+    portID,
+    channelID string,
+) error {
+    doCustomLogic()
+
+    app.OnChanCloseInit(ctx, portID, channelID)
+}
+
+OnChanCloseConfirm(
+    ctx sdk.Context,
+    portID,
+    channelID string,
+) error {
+    doCustomLogic()
+
+    app.OnChanCloseConfirm(ctx, portID, channelID)
+}
+```
+
+NOTE: Middleware that does not need to negotiate with a counterparty middleware on the remote stack will not implement the version splitting and negotiation, and will simply perform its own custom logic on the callbacks without relying on the counterparty behaving similarly.
+
+### Packet callbacks
+
+The packet callbacks just like the handshake callbacks wrap the application's packet callbacks. The packet callbacks are where the middleware performs most of its custom logic. The middleware may read the packet flow data and perform some additional packet handling, or it may modify the incoming data before it reaches the underlying application. This enables a wide degree of usecases, as a simple base application like token-transfer can be transformed for a variety of usecases by combining it with custom middleware.
+
+```go
+OnRecvPacket(
+    ctx sdk.Context,
+    packet channeltypes.Packet,
+) ibcexported.Acknowledgement {
+    doCustomLogic(packet)
+
+    ack := app.OnRecvPacket(ctx, packet)
+
+    doCustomLogic(ack) // middleware may modify outgoing ack
+    return ack
+}
+
+OnAcknowledgementPacket(
+    ctx sdk.Context,
+    packet channeltypes.Packet,
+    acknowledgement []byte,
+) (*sdk.Result, error) {
+    doCustomLogic(packet, ack)
+
+    app.OnAcknowledgementPacket(ctx, packet, ack)
+}
+
+OnTimeoutPacket(
+    ctx sdk.Context,
+    packet channeltypes.Packet,
+) (*sdk.Result, error) {
+    doCustomLogic(packet)
+
+    app.OnTimeoutPacket(ctx, packet)
+}
+```
+
+### ICS-4 Wrappers
+
+Middleware must also wrap ICS-4 so that any communication from the application to the channelKeeper goes through the middleware first. Similar to the packet callbacks, the middleware may modify outgoing acknowledgements and packets in any way it wishes.
+
+```go
+// only called for async acks
+func WriteAcknowledgement(
+  packet channeltypes.Packet,
+  acknowledgement []bytes) {
+    // middleware may modify acknowledgement
+    ack_bytes = doCustomLogic(acknowledgement)
+
+    return ics4Keeper.WriteAcknowledgement(packet, ack_bytes)
+}
+
+func SendPacket(appPacket channeltypes.Packet) {
+    // middleware may modify packet
+    packet = doCustomLogic(app_packet)
+
+    return ics4Keeper.SendPacket(packet)
+}
+```

docs/ibc/middleware/integration.md

@@ -0,0 +1,69 @@
+<!--
+order: 2
+-->
+
+# Integrating IBC Middleware into a Chain
+
+Learn how to integrate IBC middleware(s) with a base application to your chain. The following document only applies for Cosmos SDK chains.
+
+If the middleware is maintaining its own state and/or processing SDK messages, then it should create and register its SDK module **only once** with the module manager in `app.go`.
+
+All middleware must be connected to the IBC router and wrap over an underlying base IBC application. An IBC application may be wrapped by many layers of middleware, only the top layer middleware should be hooked to the IBC router, with all underlying middlewares and application getting wrapped by it.
+
+The order of middleware **matters**, function calls from IBC to the application travel from top-level middleware to the bottom middleware and then to the application. Function calls from the application to IBC goes through the bottom middleware in order to the top middleware and then to core IBC handlers. Thus the same set of middleware put in different orders may produce different effects.
+
+### Example integration
+
+```go
+// app.go
+
+// middleware 1 and middleware 3 are stateful middleware, 
+// perhaps implementing separate sdk.Msg and Handlers
+mw1Keeper := mw1.NewKeeper(storeKey1)
+mw3Keeper := mw3.NewKeeper(storeKey3)
+
+// Only create App Module **once** and register in app module
+// if the module maintains independent state and/or processes sdk.Msgs
+app.moduleManager = module.NewManager(
+    ...
+    mw1.NewAppModule(mw1Keeper),
+    mw3.NewAppModule(mw3Keeper),
+    transfer.NewAppModule(transferKeeper),
+    custom.NewAppModule(customKeeper)
+)
+
+mw1IBCModule := mw1.NewIBCModule(mw1Keeper)
+mw2IBCModule := mw2.NewIBCModule() // middleware2 is stateless middleware
+mw3IBCModule := mw3.NewIBCModule(mw3Keeper)
+
+scopedKeeperTransfer := capabilityKeeper.NewScopedKeeper("transfer")
+scopedKeeperCustom1 := capabilityKeeper.NewScopedKeeper("custom1")
+scopedKeeperCustom2 := capabilityKeeper.NewScopedKeeper("custom2")
+
+// NOTE: IBC Modules may be initialized any number of times provided they use a separate
+// scopedKeeper and underlying port.
+
+// initialize base IBC applications
+// if you want to create two different stacks with the same base application,
+// they must be given different scopedKeepers and assigned different ports.
+transferIBCModule := transfer.NewIBCModule(transferKeeper, scopedKeeperTransfer)
+customIBCModule1 := custom.NewIBCModule(customKeeper, scopedKeeperCustom1, "portCustom1")
+customIBCModule2 := custom.NewIBCModule(customKeeper, scopedKeeperCustom2, "portCustom2")
+
+// create IBC stacks by combining middleware with base application
+// NOTE: since middleware2 is stateless it does not require a Keeper
+// stack 1 contains mw1 -> mw3 -> transfer
+stack1 := mw1.NewIBCModule(mw1Keeper, mw3.NewIBCModule(mw3Keeper, transferIBCModule))
+// stack 2 contains mw3 -> mw2 -> custom1
+stack2 := mw3.NewIBCModule(mw3Keeper, mw3.NewIBCModule(customIBCModule1))
+// stack 3 contains mw2 -> mw1 -> custom2
+stack3 := mw2.NewIBCModule(mw1.NewIBCModule(mw1Keeper, customIBCModule2))
+
+// associate each stack with the moduleName provided by the underlying scopedKeeper
+ibcRouter := porttypes.NewRouter()
+ibcRouter.AddRoute("transfer", stack1)
+ibcRouter.AddRoute("custom1", stack2)
+ibcRouter.AddRoute("custom2", stack3)
+app.IBCKeeper.SetRouter(ibcRouter)
+```
+

modules/core/04-channel/keeper/keeper.go

@@ -20,6 +20,8 @@ import (
 	"github.com/cosmos/ibc-go/v2/modules/core/exported"
 )
 
+var _ porttypes.ICS4Wrapper = Keeper{}
+
 // Keeper defines the IBC channel keeper
 type Keeper struct {
 	// implements gRPC QueryServer interface

modules/core/05-port/types/module.go

@@ -95,3 +95,26 @@ type IBCModule interface {
 		proposedVersion string,
 	) (version string, err error)
 }
+
+// ICS4Wrapper implements the ICS4 interfaces that IBC applications use to send packets and acknolwedgements.
+type ICS4Wrapper interface {
+	SendPacket(
+		ctx sdk.Context,
+		chanCap *capabilitytypes.Capability,
+		packet exported.PacketI,
+	) error
+
+	WriteAcknowledgement(
+		ctx sdk.Context,
+		chanCap *capabilitytypes.Capability,
+		packet exported.PacketI,
+		ack []byte,
+	) error
+}
+
+// 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
+	ICS4Wrapper
+}