var img = document.createElement('img'); img.src = "https://terradocs.matomo.cloud//piwik.php?idsite=2&rec=1&url=https://alliance.money" + location.pathname; img.style = "border:0"; img.alt = "tracker"; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(img,s);
Skip to main content

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:

Configuring and Adding Alliance to a Cosmos SDK Chain​

Implementation example

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

  1. Add the Alliance package to the go.mod file with the latest released version and install it.
go.mod
Copy
require (
...
github.com/terra-money/alliance v<LATEST-VERSION>
...
)
  1. Add the following modules to app.go
app.go
Copy
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"
  1. Register the AllianceKeeper in App struct.
app.go
Copy
type App struct {
...
AllianceKeeper alliancemodulekeeper.Keeper
...
}
  1. Add the Alliance module into the BasicManager instantiation.
app.go
Copy
ModuleBasics = module.NewBasicManager(
...
alliancemodule.AppModuleBasic{},
...
)
  1. Add the Alliance module to the app. The Alliance module needs to be specified after the stakingKeeper is instantiated.
app.go
Copy
...

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,
)
  1. Add the Alliance staking hooks to app.StakingKeeper.
app.go
Copy

app.StakingKeeper = *stakingKeeper.SetHooks(
stakingtypes.NewMultiStakingHooks(app.DistrKeeper.Hooks(),
app.SlashingKeeper.Hooks(), app.AllianceKeeper.StakingHooks()),
)
  1. Add the requisite Alliance module types to the module account permissions.
app.go
Copy
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,
}
  1. Add the alliance storekey to the KVStore.
app.go
Copy
keys := sdk.NewKVStoreKeys(
...
alliancemoduletypes.StoreKey,
...
)
  1. Add the Alliance module to the app manager and simulation manager instantiations.
app.go
Copy
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),
...
)
  1. Add the module as the final element to the following:
  • SetOrderBeginBlockers
  • SetOrderEndBlockers
  • SetOrderInitGenesis
app.go
Copy
app.mm.SetOrderBeginBlockers(
...
alliancemoduletypes.ModuleName,
)

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

app.mm.SetOrderInitGenesis(
...
alliancemoduletypes.ModuleName,
)
  1. Add the Alliance proposal handler route to the governance module.
app.go
Copy
govRouter.

AddRoute(govtypes.RouterKey, govv1beta1.ProposalHandler).

...

AddRoute(ibcclienttypes.RouterKey, ibcclient.NewClientProposalHandler(app.IBCKeeper.ClientKeeper)).

AddRoute(alliancemoduletypes.RouterKey, alliancemodule.NewAllianceProposalHandler(app.AllianceKeeper))
  1. Add the governance proposal handlers.
app.go
Copy
govProposalHandlers = append(govProposalHandlers,

...

ibcclientclient.UpgradeProposalHandler,

alliancemoduleclient.CreateAllianceProposalHandler,

alliancemoduleclient.UpdateAllianceProposalHandler,

alliancemoduleclient.DeleteAllianceProposalHandler,

)
  1. Block the module account address.
app.go
Copy
func (app *App) BlockedModuleAccountAddrs() map[string]bool {

...

delete(modAccAddrs, authtypes.NewModuleAddress(alliancemoduletypes.ModuleName).String())

return modAccAddrs

}
  1. Add the init params keepers.
app.go
Copy
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.

  1. Update the imports to use a custom wrapper over the Bank module.
app.go
Copy
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"
...
)
  1. Add a line to register the keepers that the custom Bank module needs.
app.go
Copy
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)
  1. Add the following keeper to allow the Alliance module access to transfer tokens directly to accounts.
app.go
Copy
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.

  1. Add authtypes.FeeCollectorName, to the AllianceKeeper in app.go.
app.go
Copy
app.AllianceKeeper = alliancemodulekeeper.NewKeeper(
appCodec,
keys[alliancemoduletypes.StoreKey],
app.GetSubspace(alliancemoduletypes.ModuleName),
app.AccountKeeper,
app.BankKeeper,
app.StakingKeeper,
app.DistrKeeper,
authtypes.FeeCollectorName,
)
  1. 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
Copy
type App struct {
...
feeCollectorName string // name of the FeeCollector ModuleAccount
...
}