Depinject

DISCLAIMER: This is a beta package. The SDK team is actively working on this feature and we are looking for feedback from the community. Please try it out and let us know what you think.

Overview

depinject is a dependency injection (DI) framework for the Cosmos SDK, designed to streamline the process of building and configuring blockchain applications. It works in conjunction with the core/appconfig module to replace the majority of boilerplate code in app.go with a configuration file in Go, YAML, or JSON format.

depinject is particularly useful for developing blockchain applications:

• With multiple interdependent components, modules, or services. Helping manage their dependencies effectively.
• That require decoupling of these components, making it easier to test, modify, or replace individual parts without affecting the entire system.
• That are wanting to simplify the setup and initialisation of modules and their dependencies by reducing boilerplate code and automating dependency management.

By using depinject, developers can achieve:

• Cleaner and more organised code.

• Improved modularity and maintainability.

• A more maintainable and modular structure for their blockchain applications, ultimately enhancing development velocity and code quality.

• Go Doc

Usage

The depinject framework, based on dependency injection concepts, streamlines the management of dependencies within your blockchain application using its Configuration API. This API offers a set of functions and methods to create easy to use configurations, making it simple to define, modify, and access dependencies and their relationships.

A core component of the Configuration API is the Provide function, which allows you to register provider functions that supply dependencies. Inspired by constructor injection, these provider functions form the basis of the dependency tree, enabling the management and resolution of dependencies in a structured and maintainable manner. Additionally, depinject supports interface types as inputs to provider functions, offering flexibility and decoupling between components, similar to interface injection concepts.

By leveraging depinject and its Configuration API, you can efficiently handle dependencies in your blockchain application, ensuring a clean, modular, and well-organised codebase.

Example:

package main

import (
    
 "fmt"
    "cosmossdk.io/depinject"
)

type AnotherInt int

func GetInt()

int               {
    return 1
}

func GetAnotherInt()

AnotherInt {
    return 2
}

func main() {
    var (
  x int
  y AnotherInt
 )

fmt.Printf("Before (%v, %v)\n", x, y)

depinject.Inject(
  depinject.Provide(
   GetInt,
   GetAnotherInt,
  ),
  &x,
  &y,
 )

fmt.Printf("After (%v, %v)\n", x, y)
}

In this example, depinject.Provide registers two provider functions that return int and AnotherInt values. The depinject.Inject function is then used to inject these values into the variables x and y.

Provider functions serve as the basis for the dependency tree. They are analysed to identify their inputs as dependencies and their outputs as dependents. These dependents can either be used by another provider function or be stored outside the DI container (e.g., &x and &y in the example above). Provider functions must be exported.

Interface type resolution

depinject supports the use of interface types as inputs to provider functions, which helps decouple dependencies between modules. This approach is particularly useful for managing complex systems with multiple modules, such as the Cosmos SDK, where dependencies need to be flexible and maintainable.

For example, x/bank expects an AccountKeeper interface as input to ProvideModule. SimApp uses the implementation in x/auth, but the modular design allows for easy changes to the implementation if needed.

Consider the following example:

package duck

type Duck interface {
    quack()
}

type AlsoDuck interface {
    quack()
}

type Mallard struct{
}

type Canvasback struct{
}

func (duck Mallard)

quack() {
}

func (duck Canvasback)

quack() {
}

type Pond struct {
    Duck AlsoDuck
}

And the following provider functions:

func GetMallard()

duck.Mallard {
    return Mallard{
}
}

func GetPond(duck Duck)

Pond {
    return Pond{
    Duck: duck
}
}

func GetCanvasback()

Canvasback {
    return Canvasback{
}
}

In this example, there’s a Pond struct that has a Duck field of type AlsoDuck. The depinject framework can automatically resolve the appropriate implementation when there’s only one available, as shown below:

var pond Pond

depinject.Inject(
  depinject.Provide(
   GetMallard,
   GetPond,
  ),
   &pond)

This code snippet results in the Duck field of Pond being implicitly bound to the Mallard implementation because it’s the only implementation of the Duck interface in the container.

However, if there are multiple implementations of the Duck interface, as in the following example, you’ll encounter an error:

var pond Pond

depinject.Inject(
 depinject.Provide(
  GetMallard,
  GetCanvasback,
  GetPond,
 ),
 &pond)

A specific binding preference for Duck is required.

BindInterface API

In the above situation registering a binding for a given interface binding may look like:

depinject.Inject(
 depinject.Configs(
  depinject.BindInterface(
   "duck/duck.Duck",
   "duck/duck.Mallard",
  ),
  depinject.Provide(
   GetMallard,
   GetCanvasback,
   GetPond,
  ),
 ),
 &pond)

Now depinject has enough information to provide Mallard as an input to APond.

Full example in real app

When using depinject.Inject, the injected types must be pointers.

/go:build !app_v1

package simapp

import (
    
	"io"

	dbm "github.com/cosmos/cosmos-db"

	clienthelpers "cosmossdk.io/client/v2/helpers"
    "cosmossdk.io/depinject"
    "cosmossdk.io/log"
	storetypes "cosmossdk.io/store/types"
	circuitkeeper "cosmossdk.io/x/circuit/keeper"
	evidencekeeper "cosmossdk.io/x/evidence/keeper"
	feegrantkeeper "cosmossdk.io/x/feegrant/keeper"
	nftkeeper "cosmossdk.io/x/nft/keeper"
	upgradekeeper "cosmossdk.io/x/upgrade/keeper"
    "github.com/cosmos/cosmos-sdk/baseapp"
    "github.com/cosmos/cosmos-sdk/client"
    "github.com/cosmos/cosmos-sdk/codec"
	codectypes "github.com/cosmos/cosmos-sdk/codec/types"
    "github.com/cosmos/cosmos-sdk/runtime"
    "github.com/cosmos/cosmos-sdk/server"
    "github.com/cosmos/cosmos-sdk/server/api"
    "github.com/cosmos/cosmos-sdk/server/config"
	servertypes "github.com/cosmos/cosmos-sdk/server/types"
	testdata_pulsar "github.com/cosmos/cosmos-sdk/testutil/testdata/testpb"
    "github.com/cosmos/cosmos-sdk/types/module"
    "github.com/cosmos/cosmos-sdk/x/auth"
    "github.com/cosmos/cosmos-sdk/x/auth/ante"
	authkeeper "github.com/cosmos/cosmos-sdk/x/auth/keeper"
	authsims "github.com/cosmos/cosmos-sdk/x/auth/simulation"
	authtypes "github.com/cosmos/cosmos-sdk/x/auth/types"
	authzkeeper "github.com/cosmos/cosmos-sdk/x/authz/keeper"
	bankkeeper "github.com/cosmos/cosmos-sdk/x/bank/keeper"
	consensuskeeper "github.com/cosmos/cosmos-sdk/x/consensus/keeper"
	distrkeeper "github.com/cosmos/cosmos-sdk/x/distribution/keeper"
	epochskeeper "github.com/cosmos/cosmos-sdk/x/epochs/keeper"
	govkeeper "github.com/cosmos/cosmos-sdk/x/gov/keeper"
	groupkeeper "github.com/cosmos/cosmos-sdk/x/group/keeper"
	mintkeeper "github.com/cosmos/cosmos-sdk/x/mint/keeper"
	protocolpoolkeeper "github.com/cosmos/cosmos-sdk/x/protocolpool/keeper"
	slashingkeeper "github.com/cosmos/cosmos-sdk/x/slashing/keeper"
	stakingkeeper "github.com/cosmos/cosmos-sdk/x/staking/keeper"
)

/ DefaultNodeHome default home directories for the application daemon
var DefaultNodeHome string

var (
	_ runtime.AppI            = (*SimApp)(nil)
	_ servertypes.Application = (*SimApp)(nil)
)

/ SimApp extends an ABCI application, but with most of its parameters exported.
/ They are exported for convenience in creating helper functions, as object
/ capabilities aren't needed for testing.
type SimApp struct {
	*runtime.App
	legacyAmino       *codec.LegacyAmino
	appCodec          codec.Codec
	txConfig          client.TxConfig
	interfaceRegistry codectypes.InterfaceRegistry

	/ essential keepers
	AccountKeeper         authkeeper.AccountKeeper
	BankKeeper            bankkeeper.BaseKeeper
	StakingKeeper         *stakingkeeper.Keeper
	SlashingKeeper        slashingkeeper.Keeper
	MintKeeper            mintkeeper.Keeper
	DistrKeeper           distrkeeper.Keeper
	GovKeeper             *govkeeper.Keeper
	UpgradeKeeper         *upgradekeeper.Keeper
	EvidenceKeeper        evidencekeeper.Keeper
	ConsensusParamsKeeper consensuskeeper.Keeper
	CircuitKeeper         circuitkeeper.Keeper

	/ supplementary keepers
	FeeGrantKeeper     feegrantkeeper.Keeper
	GroupKeeper        groupkeeper.Keeper
	AuthzKeeper        authzkeeper.Keeper
	NFTKeeper          nftkeeper.Keeper
	EpochsKeeper       epochskeeper.Keeper
	ProtocolPoolKeeper protocolpoolkeeper.Keeper

	/ simulation manager
	sm *module.SimulationManager
}

func init() {
    var err error
	DefaultNodeHome, err = clienthelpers.GetNodeHomeDirectory(".simapp")
    if err != nil {
    panic(err)
}
}

/ NewSimApp returns a reference to an initialized SimApp.
func NewSimApp(
	logger log.Logger,
	db dbm.DB,
	traceStore io.Writer,
	loadLatest bool,
	appOpts servertypes.AppOptions,
	baseAppOptions ...func(*baseapp.BaseApp),
) *SimApp {
    var (
		app        = &SimApp{
}

appBuilder *runtime.AppBuilder

		/ merge the AppConfig and other configuration in one config
		appConfig = depinject.Configs(
			AppConfig,
			depinject.Supply(
				/ supply the application options
				appOpts,
				/ supply the logger
				logger,

				/ ADVANCED CONFIGURATION

				/
				/ AUTH
				/
				/ For providing a custom function required in auth to generate custom account types
				/ add it below. By default the auth module uses simulation.RandomGenesisAccounts.
				/
				/ authtypes.RandomGenesisAccountsFn(simulation.RandomGenesisAccounts),
				/
				/ For providing a custom a base account type add it below.
				/ By default the auth module uses authtypes.ProtoBaseAccount().
				/
				/ func()

sdk.AccountI {
    return authtypes.ProtoBaseAccount()
},
				/
				/ For providing a different address codec, add it below.
				/ By default the auth module uses a Bech32 address codec,
				/ with the prefix defined in the auth module configuration.
				/
				/ func()

address.Codec {
    return <- custom address codec type ->
}
				/
				/ STAKING
				/
				/ For provinding a different validator and consensus address codec, add it below.
				/ By default the staking module uses the bech32 prefix provided in the auth config,
				/ and appends "valoper" and "valcons" for validator and consensus addresses respectively.
				/ When providing a custom address codec in auth, custom address codecs must be provided here as well.
				/
				/ func()

runtime.ValidatorAddressCodec {
    return <- custom validator address codec type ->
}
				/ func()

runtime.ConsensusAddressCodec {
    return <- custom consensus address codec type ->
}

				/
				/ MINT
				/

				/ For providing a custom inflation function for x/mint add here your
				/ custom minting function that implements the mintkeeper.MintFn
				/ interface.
			),
		)
	)
    if err := depinject.Inject(appConfig,
		&appBuilder,
		&app.appCodec,
		&app.legacyAmino,
		&app.txConfig,
		&app.interfaceRegistry,
		&app.AccountKeeper,
		&app.BankKeeper,
		&app.StakingKeeper,
		&app.SlashingKeeper,
		&app.MintKeeper,
		&app.DistrKeeper,
		&app.GovKeeper,
		&app.UpgradeKeeper,
		&app.AuthzKeeper,
		&app.EvidenceKeeper,
		&app.FeeGrantKeeper,
		&app.GroupKeeper,
		&app.NFTKeeper,
		&app.ConsensusParamsKeeper,
		&app.CircuitKeeper,
		&app.EpochsKeeper,
		&app.ProtocolPoolKeeper,
	); err != nil {
    panic(err)
}

	/ Below we could construct and set an application specific mempool and
	/ ABCI 1.0 PrepareProposal and ProcessProposal handlers. These defaults are
	/ already set in the SDK's BaseApp, this shows an example of how to override
	/ them.
	/
	/ Example:
	/
	/ app.App = appBuilder.Build(...)
	/ nonceMempool := mempool.NewSenderNonceMempool()
	/ abciPropHandler := NewDefaultProposalHandler(nonceMempool, app.App.BaseApp)
	/
	/ app.App.BaseApp.SetMempool(nonceMempool)
	/ app.App.BaseApp.SetPrepareProposal(abciPropHandler.PrepareProposalHandler())
	/ app.App.BaseApp.SetProcessProposal(abciPropHandler.ProcessProposalHandler())
	/
	/ Alternatively, you can construct BaseApp options, append those to
	/ baseAppOptions and pass them to the appBuilder.
	/
	/ Example:
	/
	/ prepareOpt = func(app *baseapp.BaseApp) {
	/ 	abciPropHandler := baseapp.NewDefaultProposalHandler(nonceMempool, app)
	/ 	app.SetPrepareProposal(abciPropHandler.PrepareProposalHandler())
	/
}
	/ baseAppOptions = append(baseAppOptions, prepareOpt)

	/ create and set dummy vote extension handler
    voteExtOp := func(bApp *baseapp.BaseApp) {
    voteExtHandler := NewVoteExtensionHandler()

voteExtHandler.SetHandlers(bApp)
}

baseAppOptions = append(baseAppOptions, voteExtOp, baseapp.SetOptimisticExecution())

app.App = appBuilder.Build(db, traceStore, baseAppOptions...)

	/ register streaming services
    if err := app.RegisterStreamingServices(appOpts, app.kvStoreKeys()); err != nil {
    panic(err)
}

	/****  Module Options ****/

	/ RegisterUpgradeHandlers is used for registering any on-chain upgrades.
	app.RegisterUpgradeHandlers()

	/ add test gRPC service for testing gRPC queries in isolation
	testdata_pulsar.RegisterQueryServer(app.GRPCQueryRouter(), testdata_pulsar.QueryImpl{
})

	/ create the simulation manager and define the order of the modules for deterministic simulations
	/
	/ NOTE: this is not required apps that don't use the simulator for fuzz testing
	/ transactions
    overrideModules := map[string]module.AppModuleSimulation{
    authtypes.ModuleName: auth.NewAppModule(app.appCodec, app.AccountKeeper, authsims.RandomGenesisAccounts, nil),
}

app.sm = module.NewSimulationManagerFromAppModules(app.ModuleManager.Modules, overrideModules)

app.sm.RegisterStoreDecoders()

	/ A custom InitChainer can be set if extra pre-init-genesis logic is required.
	/ By default, when using app wiring enabled module, this is not required.
	/ For instance, the upgrade module will set automatically the module version map in its init genesis thanks to app wiring.
	/ However, when registering a module manually (i.e. that does not support app wiring), the module version map
	/ must be set manually as follow. The upgrade module will de-duplicate the module version map.
	/
	/ app.SetInitChainer(func(ctx sdk.Context, req *abci.RequestInitChain) (*abci.ResponseInitChain, error) {
	/ 	app.UpgradeKeeper.SetModuleVersionMap(ctx, app.ModuleManager.GetVersionMap())
	/ 	return app.App.InitChainer(ctx, req)
	/
})

	/ set custom ante handler
	app.setAnteHandler(app.txConfig)
    if err := app.Load(loadLatest); err != nil {
    panic(err)
}

return app
}

/ setAnteHandler sets custom ante handlers.
/ "x/auth/tx" pre-defined ante handler have been disabled in app_config.
func (app *SimApp)

setAnteHandler(txConfig client.TxConfig) {
    anteHandler, err := NewAnteHandler(
		HandlerOptions{
    ante.HandlerOptions{
    AccountKeeper:   app.AccountKeeper,
    BankKeeper:      app.BankKeeper,
    SignModeHandler: txConfig.SignModeHandler(),
    FeegrantKeeper:  app.FeeGrantKeeper,
    SigGasConsumer:  ante.DefaultSigVerificationGasConsumer,
},
			&app.CircuitKeeper,
},
	)
    if err != nil {
    panic(err)
}

	/ Set the AnteHandler for the app
	app.SetAnteHandler(anteHandler)
}

/ LegacyAmino returns SimApp's amino codec.
/
/ NOTE: This is solely to be used for testing purposes as it may be desirable
/ for modules to register their own custom testing types.
func (app *SimApp)

LegacyAmino() *codec.LegacyAmino {
    return app.legacyAmino
}

/ AppCodec returns SimApp's app codec.
/
/ NOTE: This is solely to be used for testing purposes as it may be desirable
/ for modules to register their own custom testing types.
func (app *SimApp)

AppCodec()

codec.Codec {
    return app.appCodec
}

/ InterfaceRegistry returns SimApp's InterfaceRegistry.
func (app *SimApp)

InterfaceRegistry()

codectypes.InterfaceRegistry {
    return app.interfaceRegistry
}

/ TxConfig returns SimApp's TxConfig
func (app *SimApp)

TxConfig()

client.TxConfig {
    return app.txConfig
}

/ GetKey returns the KVStoreKey for the provided store key.
/
/ NOTE: This is solely to be used for testing purposes.
func (app *SimApp)

GetKey(storeKey string) *storetypes.KVStoreKey {
    sk := app.UnsafeFindStoreKey(storeKey)

kvStoreKey, ok := sk.(*storetypes.KVStoreKey)
    if !ok {
    return nil
}

return kvStoreKey
}

func (app *SimApp)

kvStoreKeys()

map[string]*storetypes.KVStoreKey {
    keys := make(map[string]*storetypes.KVStoreKey)
    for _, k := range app.GetStoreKeys() {
    if kv, ok := k.(*storetypes.KVStoreKey); ok {
    keys[kv.Name()] = kv
}
	
}

return keys
}

/ SimulationManager implements the SimulationApp interface
func (app *SimApp)

SimulationManager() *module.SimulationManager {
    return app.sm
}

/ RegisterAPIRoutes registers all application module routes with the provided
/ API server.
func (app *SimApp)

RegisterAPIRoutes(apiSvr *api.Server, apiConfig config.APIConfig) {
    app.App.RegisterAPIRoutes(apiSvr, apiConfig)
	/ register swagger API in app.go so that other applications can override easily
    if err := server.RegisterSwaggerAPI(apiSvr.ClientCtx, apiSvr.Router, apiConfig.Swagger); err != nil {
    panic(err)
}
}

/ GetMaccPerms returns a copy of the module account permissions
/
/ NOTE: This is solely to be used for testing purposes.
func GetMaccPerms()

map[string][]string {
    dup := make(map[string][]string)
    for _, perms := range moduleAccPerms {
    dup[perms.Account] = perms.Permissions
}

return dup
}

/ BlockedAddresses returns all the app's blocked account addresses.
func BlockedAddresses()

map[string]bool {
    result := make(map[string]bool)
    if len(blockAccAddrs) > 0 {
    for _, addr := range blockAccAddrs {
    result[addr] = true
}
	
}

else {
    for addr := range GetMaccPerms() {
    result[addr] = true
}
	
}

return result
}

Debugging

Issues with resolving dependencies in the container can be done with logs and Graphviz renderings of the container tree. By default, whenever there is an error, logs will be printed to stderr and a rendering of the dependency graph in Graphviz DOT format will be saved to debug_container.dot.

Here is an example Graphviz rendering of a successful build of a dependency graph:

Rectangles represent functions, ovals represent types, rounded rectangles represent modules and the single hexagon represents the function which called Build. Black-colored shapes mark functions and types that were called/resolved without an error. Gray-colored nodes mark functions and types that could have been called/resolved in the container but were left unused.

Here is an example Graphviz rendering of a dependency graph build which failed:

Graphviz DOT files can be converted into SVG’s for viewing in a web browser using the dot command-line tool, ex:

dot -Tsvg debug_container.dot > debug_container.svg

Many other tools including some IDEs support working with DOT files.