Skip to main content
Version: v0.52

Introduction to Cosmos SDK Modules

Synopsis

Modules define most of the logic of Cosmos SDK applications. Developers compose modules together using the Cosmos SDK to build their custom application-specific blockchains. This document outlines the basic concepts behind SDK modules and how to approach module management.

Pre-requisite Readings

Role of Modules in a Cosmos SDK Application​

The Cosmos SDK can be thought of as the Next.js or Ruby-on-Rails of blockchain development. It comes with a core that provides the basic functionalities every blockchain application needs, like a boilerplate implementation of the ABCI to communicate with the underlying consensus engine, a multistore to persist state, a server to form a full-node and interfaces to handle queries.

On top of this core, the Cosmos SDK enables developers to build modules that implement the business logic of their application. In other words, SDK modules implement the bulk of the logic of applications, while the core does the wiring (via runtime) and enables modules to be composed together. The end goal is to build a robust ecosystem of open-source Cosmos SDK modules, making it increasingly easier to build complex blockchain applications.

Cosmos SDK modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more KVStores in the main multistore, as well as a subset of message types. These messages are routed by one of the main components of Cosmos SDK core, BaseApp, to a module Protobuf Msg service that defines them.

As a result of this architecture, building a Cosmos SDK application usually revolves around writing modules to implement the specialized logic of the application and composing them with existing modules to complete the application. Developers will generally work on modules that implement logic needed for their specific use case that do not exist yet, and will use existing modules for more generic functionalities like staking, accounts, or token management.

Modules as super-users​

Modules have the ability to perform actions that are not available to regular users. This is because modules are given sudo permissions by the state machine. Modules can reject another modules desire to execute a function but this logic must be explicit. Examples of this can be seen when modules create functions to modify parameters:

x/bank/keeper/msg_server.go
loading...

How to Approach Building Modules as a Developer​

While there are no definitive guidelines for writing modules, here are some important design principles developers should keep in mind when building them:

  • Composability: Cosmos SDK applications are almost always composed of multiple modules. This means developers need to carefully consider the integration of their module not only with the core of the Cosmos SDK, but also with other modules. The former is achieved by following standard design patterns outlined here, while the latter is achieved by properly exposing the store(s) of the module via the keeper.
  • Specialization: A direct consequence of the composability feature is that modules should be specialized. Developers should carefully establish the scope of their module and not batch multiple functionalities into the same module. This separation of concerns enables modules to be re-used in other projects and improves the upgradability of the application. Specialization also plays an important role in the object-capabilities model of the Cosmos SDK.
  • Capabilities: Most modules need to read and/or write to the store(s) of other modules. However, in an open-source environment, it is possible for some modules to be malicious. That is why module developers need to carefully think not only about how their module interacts with other modules, but also about how to give access to the module's store(s). The Cosmos SDK takes a capabilities-oriented approach to inter-module security. This means that each store defined by a module is accessed by a key, which is held by the module's keeper. This keeper defines how to access the store(s) and under what conditions. Access to the module's store(s) is done by passing a reference to the module's keeper.

Core APIs for Modules​

The SDK provides a set of APIs that a module can implement, and a set of services that a module can use. Those APIs are defined in the cosmossdk.io/core/appmodule package, and are used to defined the module capabilities, which is used by runtime during the wiring of the application.

Whenever possible, a module should strive to use only the core APIs (cosmossdk.io/core) and not import the github.com/cosmos/cosmos-sdk module. This makes modules reusable across SDK versions and reduces the risk of breaking changes.

Learn more about the core APIs for modules here.

Main Components of Cosmos SDK Modules​

Modules are by convention defined in the ./x/ subfolder (e.g. the bank module will be defined in the ./x/bank folder). They generally share the same core components:

  • A keeper, used to access the module's store(s) and update the state.
  • A Msg service, used to process messages when they are routed to the module by BaseApp and trigger state-transitions.
  • A query service, used to process user queries when they are routed to the module by BaseApp.
  • Interfaces, for end users to query the subset of the state defined by the module and create messages of the custom types defined in the module.

In addition to these components, modules implement the AppModule interface in order to be managed by the module manager.

Please refer to the structure document to learn about the recommended structure of a module's directory.