README
¶
sidebar_position: 1
x/mint
Contents
Concepts
The Minting Mechanism
The minting mechanism was designed to:
- allow for a flexible inflation rate determined by market demand targeting a particular bonded-stake ratio
- effect a balance between market liquidity and staked supply
In order to best determine the appropriate market rate for inflation rewards, a moving change rate is used. The moving change rate mechanism ensures that if the % bonded is either over or under the goal %-bonded, the inflation rate will adjust to further incentivize or disincentivize being bonded, respectively. Setting the goal %-bonded at less than 100% encourages the network to maintain some non-staked tokens which should help provide some liquidity.
It can be broken down in the following way:
- If the inflation rate is below the goal %-bonded the inflation rate will increase until a maximum value is reached
- If the goal % bonded (67% in Cosmos-Hub) is maintained, then the inflation rate will stay constant
- If the inflation rate is above the goal %-bonded the inflation rate will decrease until a minimum value is reached
State
Minter
The minter is a space for holding current inflation information.
- Minter:
0x00 -> ProtocolBuffer(minter)
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/mint/v1beta1/mint.proto#L10-L24
Params
The mint module stores it's params in state with the prefix of 0x01
,
it can be updated with governance or the address with authority.
- Params:
mint/params -> legacy_amino(params)
https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/mint/v1beta1/mint.proto#L26-L59
Begin-Block
Minting parameters are recalculated and inflation paid at the beginning of each block.
Inflation rate calculation
Inflation rate is calculated using an "inflation calculation function" that's
passed to the NewAppModule
function. If no function is passed, then the SDK's
default inflation function will be used (NextInflationRate
). In case a custom
inflation calculation logic is needed, this can be achieved by defining and
passing a function that matches InflationCalculationFn
's signature.
type InflationCalculationFn func(ctx sdk.Context, minter Minter, params Params, bondedRatio math.LegacyDec) math.LegacyDec
NextInflationRate
The target annual inflation rate is recalculated each block. The inflation is also subject to a rate change (positive or negative) depending on the distance from the desired ratio (67%). The maximum rate change possible is defined to be 13% per year, however the annual inflation is capped as between 7% and 20%.
NextInflationRate(params Params, bondedRatio math.LegacyDec) (inflation math.LegacyDec) {
inflationRateChangePerYear = (1 - bondedRatio/params.GoalBonded) * params.InflationRateChange
inflationRateChange = inflationRateChangePerYear/blocksPerYr
// increase the new annual inflation for this next block
inflation += inflationRateChange
if inflation > params.InflationMax {
inflation = params.InflationMax
}
if inflation < params.InflationMin {
inflation = params.InflationMin
}
return inflation
}
NextAnnualProvisions
Calculate the annual provisions based on current total supply and inflation rate. This parameter is calculated once per block.
NextAnnualProvisions(params Params, totalSupply math.LegacyDec) (provisions math.LegacyDec) {
return Inflation * totalSupply
BlockProvision
Calculate the provisions generated for each block based on current annual provisions. The provisions are then minted by the mint
module's ModuleMinterAccount
and then transferred to the auth
's FeeCollector
ModuleAccount
.
BlockProvision(params Params) sdk.Coin {
provisionAmt = AnnualProvisions/ params.BlocksPerYear
return sdk.NewCoin(params.MintDenom, provisionAmt.Truncate())
Parameters
The minting module contains the following parameters:
Key | Type | Example |
---|---|---|
MintDenom | string | "uatom" |
InflationRateChange | string (dec) | "0.130000000000000000" |
InflationMax | string (dec) | "0.200000000000000000" |
InflationMin | string (dec) | "0.070000000000000000" |
GoalBonded | string (dec) | "0.670000000000000000" |
BlocksPerYear | string (uint64) | "6311520" |
Events
The minting module emits the following events:
BeginBlocker
Type | Attribute Key | Attribute Value |
---|---|---|
mint | bonded_ratio | {bondedRatio} |
mint | inflation | {inflation} |
mint | annual_provisions | {annualProvisions} |
mint | amount | {amount} |
Client
CLI
A user can query and interact with the mint
module using the CLI.
Query
The query
commands allow users to query mint
state.
simd query mint --help
annual-provisions
The annual-provisions
command allow users to query the current minting annual provisions value
simd query mint annual-provisions [flags]
Example:
simd query mint annual-provisions
Example Output:
22268504368893.612100895088410693
inflation
The inflation
command allow users to query the current minting inflation value
simd query mint inflation [flags]
Example:
simd query mint inflation
Example Output:
0.199200302563256955
params
The params
command allow users to query the current minting parameters
simd query mint params [flags]
Example:
blocks_per_year: "4360000"
goal_bonded: "0.670000000000000000"
inflation_max: "0.200000000000000000"
inflation_min: "0.070000000000000000"
inflation_rate_change: "0.130000000000000000"
mint_denom: stake
gRPC
A user can query the mint
module using gRPC endpoints.
AnnualProvisions
The AnnualProvisions
endpoint allow users to query the current minting annual provisions value
/cosmos.mint.v1beta1.Query/AnnualProvisions
Example:
grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/AnnualProvisions
Example Output:
{
"annualProvisions": "1432452520532626265712995618"
}
Inflation
The Inflation
endpoint allow users to query the current minting inflation value
/cosmos.mint.v1beta1.Query/Inflation
Example:
grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Inflation
Example Output:
{
"inflation": "130197115720711261"
}
Params
The Params
endpoint allow users to query the current minting parameters
/cosmos.mint.v1beta1.Query/Params
Example:
grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Params
Example Output:
{
"params": {
"mintDenom": "stake",
"inflationRateChange": "130000000000000000",
"inflationMax": "200000000000000000",
"inflationMin": "70000000000000000",
"goalBonded": "670000000000000000",
"blocksPerYear": "6311520"
}
}
REST
A user can query the mint
module using REST endpoints.
annual-provisions
/cosmos/mint/v1beta1/annual_provisions
Example:
curl "localhost:1317/cosmos/mint/v1beta1/annual_provisions"
Example Output:
{
"annualProvisions": "1432452520532626265712995618"
}
inflation
/cosmos/mint/v1beta1/inflation
Example:
curl "localhost:1317/cosmos/mint/v1beta1/inflation"
Example Output:
{
"inflation": "130197115720711261"
}
params
/cosmos/mint/v1beta1/params
Example:
curl "localhost:1317/cosmos/mint/v1beta1/params"
Example Output:
{
"params": {
"mintDenom": "stake",
"inflationRateChange": "130000000000000000",
"inflationMax": "200000000000000000",
"inflationMin": "70000000000000000",
"goalBonded": "670000000000000000",
"blocksPerYear": "6311520"
}
}
Documentation
¶
Index ¶
- Constants
- func BeginBlocker(ctx context.Context, k keeper.Keeper, ic types.InflationCalculationFn) error
- type AppModule
- func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions
- func (am AppModule) BeginBlock(ctx context.Context) error
- func (AppModule) ConsensusVersion() uint64
- func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage
- func (AppModule) GenerateGenesisState(simState *module.SimulationState)
- func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, data json.RawMessage)
- func (am AppModule) IsAppModule()
- func (am AppModule) IsOnePerModuleType()
- func (AppModule) ProposalMsgs(simState module.SimulationState) []simtypes.WeightedProposalMsg
- func (am AppModule) RegisterServices(cfg module.Configurator)
- func (am AppModule) RegisterStoreDecoder(sdr simtypes.StoreDecoderRegistry)
- func (AppModule) WeightedOperations(_ module.SimulationState) []simtypes.WeightedOperation
- type AppModuleBasic
- func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage
- func (AppModuleBasic) Name() string
- func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)
- func (b AppModuleBasic) RegisterInterfaces(r cdctypes.InterfaceRegistry)
- func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)
- func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error
- type ModuleInputs
- type ModuleOutputs
Constants ¶
const ConsensusVersion = 2
ConsensusVersion defines the current x/mint module consensus version.
Variables ¶
This section is empty.
Functions ¶
func BeginBlocker ¶
BeginBlocker mints new tokens for the previous block.
Types ¶
type AppModule ¶
type AppModule struct { AppModuleBasic // contains filtered or unexported fields }
AppModule implements an application module for the mint module.
func NewAppModule ¶
func NewAppModule( cdc codec.Codec, keeper keeper.Keeper, ak types.AccountKeeper, ic types.InflationCalculationFn, ss exported.Subspace, ) AppModule
NewAppModule creates a new AppModule object. If the InflationCalculationFn argument is nil, then the SDK's default inflation function will be used.
func (AppModule) AutoCLIOptions ¶ added in v0.50.1
func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions
func (AppModule) BeginBlock ¶
BeginBlock returns the begin blocker for the mint module.
func (AppModule) ConsensusVersion ¶ added in v0.43.0
ConsensusVersion implements AppModule/ConsensusVersion.
func (AppModule) ExportGenesis ¶
ExportGenesis returns the exported genesis state as raw bytes for the mint module.
func (AppModule) GenerateGenesisState ¶
func (AppModule) GenerateGenesisState(simState *module.SimulationState)
GenerateGenesisState creates a randomized GenState of the mint module.
func (AppModule) InitGenesis ¶
InitGenesis performs genesis initialization for the mint module. It returns no validator updates.
func (AppModule) IsAppModule ¶ added in v0.47.0
func (am AppModule) IsAppModule()
IsAppModule implements the appmodule.AppModule interface.
func (AppModule) IsOnePerModuleType ¶ added in v0.47.0
func (am AppModule) IsOnePerModuleType()
IsOnePerModuleType implements the depinject.OnePerModuleType interface.
func (AppModule) ProposalMsgs ¶ added in v0.47.0
func (AppModule) ProposalMsgs(simState module.SimulationState) []simtypes.WeightedProposalMsg
ProposalMsgs returns msgs used for governance proposals for simulations.
func (AppModule) RegisterServices ¶ added in v0.40.0
func (am AppModule) RegisterServices(cfg module.Configurator)
RegisterServices registers a gRPC query service to respond to the module-specific gRPC queries.
func (AppModule) RegisterStoreDecoder ¶
func (am AppModule) RegisterStoreDecoder(sdr simtypes.StoreDecoderRegistry)
RegisterStoreDecoder registers a decoder for mint module's types.
func (AppModule) WeightedOperations ¶
func (AppModule) WeightedOperations(_ module.SimulationState) []simtypes.WeightedOperation
WeightedOperations doesn't return any mint module operation.
type AppModuleBasic ¶
type AppModuleBasic struct {
// contains filtered or unexported fields
}
AppModuleBasic defines the basic application module used by the mint module.
func (AppModuleBasic) DefaultGenesis ¶
func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage
DefaultGenesis returns default genesis state as raw bytes for the mint module.
func (AppModuleBasic) Name ¶
func (AppModuleBasic) Name() string
Name returns the mint module's name.
func (AppModuleBasic) RegisterGRPCGatewayRoutes ¶ added in v0.40.0
func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)
RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the mint module.
func (AppModuleBasic) RegisterInterfaces ¶ added in v0.40.0
func (b AppModuleBasic) RegisterInterfaces(r cdctypes.InterfaceRegistry)
RegisterInterfaces registers the module's interface types
func (AppModuleBasic) RegisterLegacyAminoCodec ¶ added in v0.40.0
func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)
RegisterLegacyAminoCodec registers the mint module's types on the given LegacyAmino codec.
func (AppModuleBasic) ValidateGenesis ¶
func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error
ValidateGenesis performs genesis state validation for the mint module.
type ModuleInputs ¶ added in v0.50.1
type ModuleInputs struct { depinject.In ModuleKey depinject.OwnModuleKey Config *modulev1.Module StoreService store.KVStoreService Cdc codec.Codec InflationCalculationFn types.InflationCalculationFn `optional:"true"` // LegacySubspace is used solely for migration of x/params managed parameters LegacySubspace exported.Subspace `optional:"true"` AccountKeeper types.AccountKeeper BankKeeper types.BankKeeper StakingKeeper types.StakingKeeper }
type ModuleOutputs ¶ added in v0.50.1
func ProvideModule ¶ added in v0.47.0
func ProvideModule(in ModuleInputs) ModuleOutputs
Directories
¶
Path | Synopsis |
---|---|
migrations
|
|
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages.
|
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages. |