cosmos-sdk/docs/build/building-modules/15-depinject.md

sidebar_position
1

Modules depinject-ready

:::note Pre-requisite Readings

• Depinject Documentation

:::

depinject is used to wire any module in app.go. All core modules are already configured to support dependency injection.

To work with depinject a module must define its configuration and requirements so that depinject can provide the right dependencies.

In brief, as a module developer, the following steps are required:

1. Define the module configuration using Protobuf
2. Define the module dependencies in x/{moduleName}/module.go

A chain developer can then use the module by following these two steps:

1. Configure the module in app_config.go or app.yaml
2. Inject the module in app.go

Module Configuration

The module available configuration is defined in a Protobuf file, located at {moduleName}/module/v1/module.proto.

https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/proto/cosmos/group/module/v1/module.proto

• go_import must point to the Go package of the custom module.

• Message fields define the module configuration. That configuration can be set in the app_config.go / app.yaml file for a chain developer to configure the module.
  Taking group as example, a chain developer is able to decide, thanks to uint64 max_metadata_len, what the maximum metadata length allowed for a group proposal is.

  https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/simapp/app_config.go#L228-L234
  

That message is generated using pulsar (by running make proto-gen). In the case of the group module, this file is generated here: https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/api/cosmos/group/module/v1/module.pulsar.go.

The part that is relevant for the module configuration is:

https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/api/cosmos/group/module/v1/module.pulsar.go#L515-L527

:::note Pulsar is optional. The official protoc-gen-go can be used as well. :::

Dependency Definition

Once the configuration proto is defined, the module's module.go must define what dependencies are required by the module. The boilerplate is similar for all modules.

:::warning All methods, structs and their fields must be public for depinject. :::

1. Import the module configuration generated package:

   https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/group/module/module.go#L12-L14
   

   Define an init() function for defining the providers of the module configuration:
   This registers the module configuration message and the wiring of the module.

   https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/group/module/module.go#L194-L199
   

2. Ensure that the module implements the appmodule.AppModule interface:

   https://github.com/cosmos/cosmos-sdk/blob/v0.47.0/x/group/module/module.go#L58-L64
   

3. Define a struct that inherits depinject.In and define the module inputs (i.e. module dependencies):

   • depinject provides the right dependencies to the module.
   • depinject also checks that all dependencies are provided.

   :::tip For making a dependency optional, add the optional:"true" struct tag.
   :::

   https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/group/module/module.go#L201-L211
   

4. Define the module outputs with a public struct that inherits depinject.Out: The module outputs are the dependencies that the module provides to other modules. It is usually the module itself and its keeper.

   https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/group/module/module.go#L213-L218
   

5. Create a function named ProvideModule (as called in 1.) and use the inputs for instantiating the module outputs.

   https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/group/module/module.go#L220-L235
   

   The ProvideModule function should return an instance of cosmossdk.io/core/appmodule.AppModule which implements one or more app module extension interfaces for initializing the module.

   Following is the complete app wiring configuration for group:

   https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/x/group/module/module.go#L194-L235
   

6. All modules must implement depinject.OnePerModuleType interface. This is used in order to tell the dependency injection framework that the module can only be instantiated once.

   https://github.com/cosmos/cosmos-sdk/blob/f4bdec3433373cc4950f4680743e969495763fbb/x/group/module/module.go#L64-L65
   

The module is now ready to be used with depinject by a chain developer.

Integrate in an application

The App Wiring is done in app_config.go / app.yaml and app_di.go and is explained in detail in the overview of app_di.go.