# Integrate IBC Middleware Into a Chain
Learn how to integrate Inter-Blokchain Communication Protocol (IBC) middleware(s) with a base application to your chain. The following only applies to Cosmos SDK chains.
You have now seen how to develop an IBC middleware, and the final step in order to use it is to integrate it into the chain. You can distinguish between a single piece of middleware and a stack of middleware, and between middleware that is stateful or stateless.
To integrate middleware (or a middleware stack) you must do the following in
If the middleware is maintaining its state, processing SDK messages, or both, then it should create and register its SDK module with the module manager. Make sure not to create multiple
moduleManagers but to register all modules in the same one.
As mentioned in the previous section, if the middleware wishes to send a packet or acknowledgement without the involvement of the underlying application, it should be given access to the same
scopedKeeperas the base application so that it can retrieve the capabilities by itself.
For example, if the middleware
mw1needs the ability to send a packet on custom2's port without involving the underlying application
custom2, it would require access to the latter's
If no middleware (or other modules for that matter) need access to the
scopedKeeper, there is no need to define them.
Each application stack must reserve its own unique port with core IBC. Thus, two stacks with the same base application must bind to separate ports.
The order of middleware matters. Function calls from IBC to the application travel from top-level middleware through to bottom-level middleware and then to the application. Function calls from the application to IBC rise from the bottom middleware to the top middleware and then to core IBC handlers. Thus the same set of middleware arranged in different orders may produce different effects.
In addition to the diagram shown in the introduction, also note the direction of information flow through the middleware by looking at the interface:
The packet and channel callbacks defined by
IBCModulerun from IBC Core to the base application; the methods defined by
ICS4Wrapperrun from the base application to IBC Core.
In the code snippet below, three different stacks are defined:
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, but only the top-layer middleware should be hooked to the IBC router, with all underlying middlewares and application getting wrapped by it.
Next, take a look at a full example integration, combining all of the above code snippets.
# Example integration
To summarize, this section has explored:
- How to integrate IBC middleware(s) with a base application to Cosmos SDK blockchains.
- Creating and registering a middleware's SDK module with the module manager, if the middleware is maintaining its state, processing SDK messages, or both.
- The importance of registering all modules to the same
moduleMangerrather than creating multiple ones.
- How middleware needing to send packets or acknowledgements without involving the underlying application will need access to the same
scopedKeeperas the base application.
- How each application stack must reserve a unique port with core IBC, even if two stacks share the same base application.
- The importance of middleware ordering within a stack, since changes in the position of middlewares may produce different effects as function calls from and to the application transition up or down through the layers of the stack.
- How only the top-layer middleware should be hooked to the IBC router, regardless of how many underlying middlewares are wrapped by it along with the application.