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.

To connect with a member of the Alliance team for questions regarding integration, setting Alliance asset parameters, or other items, please complete this form.

caution

Follow all of the steps in this guide carefully.

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

Alliance-compatible assets

The Alliance module leverages the IBC module to bridge foreign tokens and the Token Factory module to mint native tokens. Alliance allows any native token recognized by the bank module to be staked as long as it has been whitelisted. CW-20 tokens sent via IBC from other chains can be used in the Alliance module if they are minted as native tokens.

Prerequisites

The Alliance Module requires:

Cosmos SDK v0.47.x or greater
The following fully-operational modules:
- x/auth
- x/bank
- x/staking
- x/distribution
- x/gov

Configuring and Adding Alliance to a Cosmos SDK 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

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"

app.go

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

Add the Alliance module into the BasicManager instantiation.

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.

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.

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.

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.

app.go

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

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

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

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.

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.

app.go

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

Block the module account address.

app.go

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

Add the init params keepers.

app.go

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

Configuring the Bank Module

caution

Make sure all three of the following steps are implemented.

Because the Alliance module mints and burns native staking tokens when rebalancing reward 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)

Add the following keeper to allow the Alliance module access to transfer tokens directly to accounts.

app.go

app.BankKeeper = custombankkeeper.NewBaseKeeper(
	appCodec,
	keys[banktypes.StoreKey],
	app.AccountKeeper,
	app.GetSubspace(banktypes.ModuleName),
	app.BlockedModuleAccountAddrs(),
)
//Then add the following function below the previous section
func (app *App) BlockedModuleAccountAddrs() map[string]bool {
	modAccAddrs := app.ModuleAccountAddrs()
	delete(modAccAddrs, authtypes.NewModuleAddress(govtypes.ModuleName).String())
	delete(modAccAddrs, authtypes.NewModuleAddress(alliancemoduletypes.ModuleName).String())
	return modAccAddrs
}

Specify the fee collector module account

The following steps allow you to specify a fee collector account, allowing for more flexibility in configuration. If you don't want to specify a custom fee collector, specify the default fee collector.

Add authtypes.FeeCollectorName, to the AllianceKeeper in app.go.

app.go

app.AllianceKeeper = alliancemodulekeeper.NewKeeper(
	appCodec,
	keys[alliancemoduletypes.StoreKey],
	app.GetSubspace(alliancemoduletypes.ModuleName),
	app.AccountKeeper,
	app.BankKeeper,
	app.StakingKeeper,
	app.DistrKeeper,
	authtypes.FeeCollectorName,
)

Add the following line to specify the fee collector. If you don't want to specify a custom fee collector, specify the default FeeCollector.

app.go

type App struct {
    ...
    feeCollectorName string // name of the FeeCollector ModuleAccount
    ...
}

Integrate the Alliance module

Prerequisites​

Configuring and Adding Alliance to a Cosmos SDK Chain​

Configuring the Bank Module​

Specify the fee collector module account​

Prerequisites

Configuring and Adding Alliance to a Cosmos SDK Chain

Configuring the Bank Module

Specify the fee collector module account