Integrate the Alliance module

Alliance can be integrated into both new and existing blockchains. It is an isolated module that doesn’t modify any existing CosmosSDK code. New blockchains can simply import the module and existing chains can perform a software upgrade.

Chains that want to create an Alliance must enable the following modules:

x/auth: retrieve information about internal blockchain accounts
x/bank: mint, burn or send coins
x/staking: bond, unbond, delegate tokens and hooks
x/distribution: withdraw rewards
x/gov: create Alliances through governance

Since Interchain Security is based on the IBC standard, the Alliance module has an indirect dependency on x/ibc to bridge foreign tokens. Alliance allows any ADR 024 compliant token to be staked as long as it has been whitelisted.

Prerequisites

The Alliance Module requires:

CosmosSDK v0.46.x or greater
The following fully-operational modules:
- x/auth
- x/bank
- x/staking
- x/distribution
- x/gov

Configuring and Adding Alliance to a CosmosSDK Chain

Implementation example

Refer to the example pull request for an implementation of the following steps.

Add the Alliance package to the go.mod file with the latest released version and install it.

go.mod

require (
    ...
    github.com/terra-money/alliance v<LATEST-VERSION>
    ...
)

Add the following modules to app.go

go.mod

app.go

alliancemodule "github.com/terra-money/alliance/x/alliance"
alliancemoduleclient "github.com/terra-money/alliance/x/alliance/client"
alliancemodulekeeper "github.com/terra-money/alliance/x/alliance/keeper"
alliancemoduletypes "github.com/terra-money/alliance/x/alliance/types"

go.mod

app.go

type App struct {
    ...
    AllianceKeeper   alliancemodulekeeper.Keeper
    ...
}

Add the Alliance module into the BasicManager instantiation.

go.mod

app.go

ModuleBasics = module.NewBasicManager(
    ...
    alliancemodule.AppModuleBasic{},
    ...
)

Add the Alliance module to the app. The Alliance module needs to be specified after the stakingKeeper is instantiated.

go.mod

app.go

...
stakingKeeper := stakingkeeper.NewKeeper(
    appCodec,
    keys[stakingtypes.StoreKey],
    app.AccountKeeper,
    app.BankKeeper,
    app.GetSubspace(stakingtypes.ModuleName),
)
...
app.AllianceKeeper = alliancemodulekeeper.NewKeeper(
    appCodec,
    keys[alliancemoduletypes.StoreKey],
    app.GetSubspace(alliancemoduletypes.ModuleName),
    app.AccountKeeper,
    app.BankKeeper,
    &app.StakingKeeper,
    app.DistrKeeper,

Add the Alliance staking hooks to app.StakingKeeper.

go.mod

app.go

app.StakingKeeper = *stakingKeeper.SetHooks(
    stakingtypes.NewMultiStakingHooks(app.DistrKeeper.Hooks(),
    app.SlashingKeeper.Hooks(), app.AllianceKeeper.StakingHooks()),
)

Add the requisite Alliance module types to the module account permissions.

go.mod

app.go

maccPerms = map[string][]string{
	authtypes.FeeCollectorName:          nil,
	distrtypes.ModuleName:               nil,
	icatypes.ModuleName:                 nil,
	minttypes.ModuleName:                {authtypes.Minter},
	stakingtypes.BondedPoolName:         {authtypes.Burner, authtypes.Staking},
	stakingtypes.NotBondedPoolName:      {authtypes.Burner, authtypes.Staking},
	govtypes.ModuleName:                 {authtypes.Burner},
	ibctransfertypes.ModuleName:         {authtypes.Minter, authtypes.Burner},
	alliancemoduletypes.ModuleName:      {authtypes.Minter, authtypes.Burner},
	alliancemoduletypes.RewardsPoolName: nil,
}

Add the alliance storekey to the KVStore.

go.mod

app.go

keys := sdk.NewKVStoreKeys(
...
alliancemoduletypes.StoreKey,
...
)

Add the Alliance module to the app manager and simulation manager instantiations.

go.mod

app.go

app.mm = module.NewManager(
    ...
    icaModule,
    alliancemodule.NewAppModule(appCodec, app.AllianceKeeper, app.StakingKeeper, app.AccountKeeper, app.BankKeeper, app.interfaceRegistry),
    ...
)
app.sm = module.NewSimulationManager(
    ...
    transferModule,
    alliancemodule.NewAppModule(appCodec, app.AllianceKeeper, app.StakingKeeper, app.AccountKeeper, app.BankKeeper, app.interfaceRegistry),
    ...
)

Add the module as the final element to the following:

SetOrderBeginBlockers
SetOrderEndBlockers
SetOrderInitGenesis

go.mod

app.go

app.mm.SetOrderBeginBlockers(
    ...
    alliancemoduletypes.ModuleName,
)
app.mm.SetOrderEndBlockers(
    ...
    alliancemoduletypes.ModuleName,
)
app.mm.SetOrderInitGenesis(
    ...
    alliancemoduletypes.ModuleName,
)

Add the Alliance proposal handler route to the governance module.

go.mod

app.go

govRouter.
    AddRoute(govtypes.RouterKey, govv1beta1.ProposalHandler).
    ...
    AddRoute(ibcclienttypes.RouterKey, ibcclient.NewClientProposalHandler(app.IBCKeeper.ClientKeeper)).
    AddRoute(alliancemoduletypes.RouterKey, alliancemodule.NewAllianceProposalHandler(app.AllianceKeeper))

Add the governance proposal handlers.

go.mod

app.go

govProposalHandlers = append(govProposalHandlers,
    ...
    ibcclientclient.UpgradeProposalHandler,
    alliancemoduleclient.CreateAllianceProposalHandler,
    alliancemoduleclient.UpdateAllianceProposalHandler,
    alliancemoduleclient.DeleteAllianceProposalHandler,
)

Block the module account address.

go.mod

app.go

func (app *App) BlockedModuleAccountAddrs() map[string]bool {
    ...
    delete(modAccAddrs, authtypes.NewModuleAddress(alliancemoduletypes.ModuleName).String())
    return modAccAddrs
}

Add the init params keepers.

go.mod

app.go

func initParamsKeeper(appCodec codec.BinaryCodec, legacyAmino *codec.LegacyAmino, key, tkey storetypes.StoreKey) paramskeeper.Keeper {
    ...
    paramsKeeper.Subspace(alliancemoduletypes.ModuleName)
    return paramsKeeper
}

Add the Alliance package to the go.mod file with the latest released version and install it.

Add the following modules to app.go

Add the Alliance module into the BasicManager instantiation.

Add the Alliance module to the app. The Alliance module needs to be specified after the stakingKeeper is instantiated.

Add the Alliance staking hooks to app.StakingKeeper.

Add the requisite Alliance module types to the module account permissions.

Add the alliance storekey to the KVStore.

Add the Alliance module to the app manager and simulation manager instantiations.

Add the module as the final element to the following:

SetOrderBeginBlockers
SetOrderEndBlockers
SetOrderInitGenesis

Add the Alliance proposal handler route to the governance module.

Add the governance proposal handlers.

Block the module account address.

Add the init params keepers.

go.mod

require (
    ...
    github.com/terra-money/alliance v<LATEST-VERSION>
    ...
)

Configuring the Bank Module

Because the Alliance module mints and burns native staking tokens when rebalancing voting power, a chain's Total Supply API needs to be updated to return accurate results. This custom wrapper only affects the following APIs: /cosmos/bank/v1beta1/supply & /cosmos/bank/v1beta1/supply/by_denom. Follow these instructions to update your API for supply accuracy.

Update the imports to use a custom wrapper over the Bank module.

app.go

import (
    ...
    // Delete or comment the native bank module imports
    // 	"github.com/cosmos/cosmos-sdk/x/bank"
    // bankkeeper "github.com/cosmos/cosmos-sdk/x/bank/keeper"
    // Replace the imports from the Alliance module
    bank "github.com/terra-money/alliance/custom/bank"
    bankkeeper "github.com/terra-money/alliance/custom/bank/keeper"
    ...
)

Add a line to register the keepers that the custom Bank module needs

app.go

app.AllianceKeeper = alliancemodulekeeper.NewKeeper(
    appCodec,
    keys[alliancemoduletypes.StoreKey],
    app.GetSubspace(alliancemoduletypes.ModuleName),
    app.AccountKeeper,
    app.BankKeeper,
    &stakingKeeper,
    app.DistrKeeper,
)
// Add this after instantiating the `Alliance keeper`
app.BankKeeper.RegisterKeepers(app.AllianceKeeper, &stakingKeeper)

Update the imports to use a custom wrapper over the Bank module.

Add a line to register the keepers that the custom Bank module needs

app.go

import (
    ...
    // Delete or comment the native bank module imports
    // 	"github.com/cosmos/cosmos-sdk/x/bank"
    // bankkeeper "github.com/cosmos/cosmos-sdk/x/bank/keeper"
    // Replace the imports from the Alliance module
    bank "github.com/terra-money/alliance/custom/bank"
    bankkeeper "github.com/terra-money/alliance/custom/bank/keeper"
    ...
)

Integrate the Alliance module

Prerequisites​

Configuring and Adding Alliance to a CosmosSDK Chain​

Configuring the Bank Module​

Prerequisites

Configuring and Adding Alliance to a CosmosSDK Chain

Configuring the Bank Module