mint

README

Mint

The mint module is responsible for creating tokens in a flexible way to reward validators, incentivize providing pool liquidity, provide funds for Quicksilver governance, and pay those who participate to the Quicksilver protocol.

The module is also responsible for reducing the token creation and distribution by a set period until it reaches its maximum supply (see reduction_factor and reduction_period_in_epochs)

The module uses time basis epochs supported by the epochs module.

Contents

1. Concept
2. State
3. Begin Epoch
4. Parameters
5. Events
6. Queries

Concepts

The x/mint module is designed to handle the regular printing of new tokens within a chain. The design taken within Quicksilver is to

• Mint new tokens once per epoch (default one week)
• To have a "Reductioning factor" every period, which reduces the number of rewards per epoch. (default: period is 1 years, where a year is 365 epochs. The next period's rewards are 3/4 of the prior period's rewards)

Reduction factor

This is a generalization over the Bitcoin-style halvenings. Every year, the number of rewards issued per week will reduce by a governance-specified factor, instead of a fixed 1/2. So RewardsPerEpochNextPeriod = ReductionFactor * CurrentRewardsPerEpoch). When ReductionFactor = 1/2, the Bitcoin halvenings are recreated. We default to having a reduction factor of 3/4 and thus reduce rewards at the end of every year by 25%.

The implication of this is that the total supply is finite, according to the following formula:

Total Supply = InitialSupply + EpochsPerPeriod * { {InitialRewardsPerEpoch} / {1 - ReductionFactor} }

State

Minter

The Minter is an abstraction for holding current rewards information.

type Minter struct {
    EpochProvisions sdk.Dec   // Rewards for the current epoch
}

Params

Minting Params are held in the global params store.

LastReductionEpoch

Last reduction epoch stores the epoch number when the last reduction of coin mint amount per epoch has happened.

Begin-Epoch

Minting parameters are recalculated and inflation is paid at the beginning of each epoch. An epoch is signaled by x/epochs.

NextEpochProvisions

The target epoch provision is recalculated on each reduction period (default 1 year). At the time of the reduction, the current provision is multiplied by the reduction factor (default 3/4), to calculate the provisions for the next epoch. Consequently, the rewards of the next period will be lowered by a 1 - reduction factor.

EpochProvision

Calculate the provisions generated for each epoch based on current epoch provisions. The provisions are then minted by the mint module's ModuleMinterAccount. These rewards are transferred to a FeeCollector, which handles distributing the rewards per the chain's needs. This fee collector is specified as the auth module's FeeCollector ModuleAccount.

Network Parameters

The minting module contains the following parameters:

Key	Type	Example
mint_denom	string	"ufury"
genesis_epoch_provisions	string (dec)	"500000000"
epoch_identifier	string	"weekly"
reduction_period_in_epochs	int64	156
reduction_factor	string (dec)	"0.6666666666666"
distribution_proportions.staking	string (dec)	"0.4"
distribution_proportions.pool_incentives	string (dec)	"0.3"
distribution_proportions.participation_rewards	string (dec)	"0.2"
distribution_proportions.community_pool	string (dec)	"0.1"
minting_rewards_distribution_start_epoch	int64	10

Below are all the network parameters for the mint module:

• mint_denom - Token type being minted
• genesis_epoch_provisions - Amount of tokens generated at the epoch to the distribution categories (see distribution_proportions)
• epoch_identifier - Type of epoch that triggers token issuance (day, week, etc.)
• reduction_period_in_epochs - How many epochs must occur before implementing the reduction factor
• reduction_factor - What the total token issuance factor will reduce by after the reduction period passes (if set to 66.66%, token issuance will reduce by 1/3)
• distribution_proportions - Categories in which the specified proportion of newly released tokens are distributed to
  • staking - Proportion of minted funds to incentivize staking FURY
  • pool_incentives - Proportion of minted funds to incentivize pools on Quicksilver
  • participation_rewards - Proportion of minted funds to pay those who participate in the Quicksilver protocol
  • community_pool - Proportion of minted funds to be set aside for the community pool
• minting_rewards_distribution_start_epoch - What epoch will start the rewards distribution to the aforementioned distribution categories

Notes

1. mint_denom defines denom for minting token - ufury
2. genesis_epoch_provisions provides minting tokens per epoch at genesis.
3. epoch_identifier defines the epoch identifier to be used for the mint module e.g. "day"
4. reduction_period_in_epochs defines the number of epochs to pass to reduce the mint amount
5. reduction_factor defines the reduction factor of tokens at every reduction_period_in_epochs
6. distribution_proportions defines distribution rules for minted tokens
7. minting_rewards_distribution_start_epoch defines the start epoch of minting to make sure minting start after initial pools are set

Events

The minting module emits the following events:

End of Epoch

Type	Attribute Key	Attribute Value
mint	epoch_number	{epochNumber}
mint	epoch_provisions	{epochProvisions}
mint	amount	{amount}

Queries

params

Query all the current mint parameter values

query mint params

::: details Example

List all current min parameters in json format by:

blackfuryd query mint params -o json

An example of the output:

{
  "mint_denom":"ufury",
  "genesis_epoch_provisions":"1639344.000000000000000000",
  "epoch_identifier":"day",
  "reduction_period_in_epochs":"365",
  "reduction_factor":"0.750000000000000000",
  "distribution_proportions":{
    "staking":"0.300000000000000000",
    "pool_incentives":"0.300000000000000000",
    "participation_rewards":"0.300000000000000000",
    "community_pool":"0.100000000000000000"
  },
  "minting_rewards_distribution_start_epoch":"0"
}

:::

epoch-provisions

Query the current epoch provisions

query mint epoch-provisions

::: details Example

List the current epoch provisions:

blackfuryd query mint epoch-provisions

As of this writing, this number will be equal to the genesis-epoch-provisions. Once the reduction_period_in_epochs is reached, the reduction_factor will be initiated and reduce the amount of FURY minted per epoch. :::

Appendix

Current Configuration

mint module: Network Parameter effects and current configuration

The following tables show overall effects on different configurations of the mint related network parameters:

	mint_denom	epoch_provisions	epoch_identifier
Type	string	string (dec)	string
Higher	N/A	Higher inflation rate	Increases time to reduction_period
Lower	N/A	Lower inflation rate	Decreases time to reduction_period
Constraints	N/A	Value has to be a positive integer	String must be day, week, month, or year
Current configuration	ufury	1639344.000 (163,9344 FURY)	day

	reduction_period_in_epochs	reduction_factor	staking
Type	string	string (dec)	string (dec)
Higher	Longer period of time until reduction_factor implemented	Reduces time until maximum supply is reached	More epoch provisions go to staking rewards than other categories
Lower	Shorter period of time until reduction_factor implemented	Increases time until maximum supply is reached	Less epoch provisions go to staking rewards than other categories
Constraints	Value has to be a whole number greater than or equal to 1	Value has to be less or equal to 1	Value has to be less or equal to 1 and all distribution categories combined must equal 1
Current configuration	365 (epochs)	0.75 (75%)	0.300000000000000000 (30%)

	pool_incentives	participation_rewards	community_pool
Type	string (dec)	string (dec)	string (dec)
Higher	More epoch provisions go to pool incentives than other categories	More epoch provisions go to participation rewards than other categories	More epoch provisions go to community pool than other categories
Lower	Less epoch provisions go to pool incentives than other categories	Less epoch provisions go to participation rewards than other categories	Less epoch provisions go to community pool than other categories
Constraints	Value has to be less or equal to 1 and all distribution categories combined must equal 1	Value has to be less or equal to 1 and all distribution categories combined must equal 1	Value has to be less or equal to 1 and all distribution categories combined must equal 1
Current configuration	0.300000000000000000 (30%)	0.300000000000000000 (30%)	0.100000000000000000 (10%)

Documentation

Index

• func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState
• func InitGenesis(ctx sdk.Context, k keeper.Keeper, ak types.AccountKeeper, ...)
• type AppModule
  • func NewAppModule(cdc codec.Codec, k keeper.Keeper, ak types.AccountKeeper, bk types.BankKeeper) AppModule
  • func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)
  • func (AppModule) ConsensusVersion() uint64
  • func (AppModule) EndBlock(_ sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate
  • 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) []abci.ValidatorUpdate
  • func (am AppModule) LegacyQuerierHandler(_ *codec.LegacyAmino) sdk.Querier
  • func (AppModule) Name() string
  • func (AppModule) ProposalContents(_ module.SimulationState) []simtypes.WeightedProposalContent
  • func (AppModule) QuerierRoute() string
  • func (AppModule) RandomizedParams(_ *rand.Rand) []simtypes.ParamChange
  • func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)
  • func (am AppModule) RegisterServices(cfg module.Configurator)
  • func (am AppModule) RegisterStoreDecoder(sdr sdk.StoreDecoderRegistry)
  • func (AppModule) Route() sdk.Route
  • func (AppModule) WeightedOperations(_ module.SimulationState) []simtypes.WeightedOperation
• type AppModuleBasic
  • func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage
  • func (AppModuleBasic) GetQueryCmd() *cobra.Command
  • func (AppModuleBasic) GetTxCmd() *cobra.Command
  • func (AppModuleBasic) Name() string
  • func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)
  • func (b AppModuleBasic) RegisterInterfaces(_ cdctypes.InterfaceRegistry)
  • func (AppModuleBasic) RegisterLegacyAminoCodec(_ *codec.LegacyAmino)
  • func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, _ client.TxEncodingConfig, bz json.RawMessage) error

Functions

func ExportGenesis

func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState

ExportGenesis returns a GenesisState for a given context and keeper.

func InitGenesis

func InitGenesis(ctx sdk.Context, k keeper.Keeper, ak types.AccountKeeper, data *types.GenesisState)

InitGenesis new mint genesis.

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, k keeper.Keeper, ak types.AccountKeeper, bk types.BankKeeper) AppModule

NewAppModule creates a new AppModule object.

func (AppModule) BeginBlock

func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)

BeginBlock returns the begin blocker for the mint module.

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements AppModule/ConsensusVersion.

func (AppModule) EndBlock

func (AppModule) EndBlock(_ sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock returns the end blocker for the mint module. It returns no validator updates.

func (AppModule) ExportGenesis

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

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

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, data json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs genesis initialization for the mint module. It returns no validator updates.

func (AppModule) LegacyQuerierHandler

func (am AppModule) LegacyQuerierHandler(_ *codec.LegacyAmino) sdk.Querier

LegacyQuerierHandler returns the x/mint module's sdk.Querier.

func (AppModule) Name

func (AppModule) Name() string

Name returns the mint module's name.

func (AppModule) ProposalContents

func (AppModule) ProposalContents(_ module.SimulationState) []simtypes.WeightedProposalContent

ProposalContents doesn't return any content functions for governance proposals.

func (AppModule) QuerierRoute

func (AppModule) QuerierRoute() string

QuerierRoute returns the mint module's querier route name.

func (AppModule) RandomizedParams

func (AppModule) RandomizedParams(_ *rand.Rand) []simtypes.ParamChange

RandomizedParams creates randomized mint param changes for the simulator.

func (AppModule) RegisterInvariants

func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants registers the mint module invariants.

func (AppModule) RegisterServices

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 sdk.StoreDecoderRegistry)

RegisterStoreDecoder registers a decoder for mint module's types.

func (AppModule) Route

func (AppModule) Route() sdk.Route

Route returns the message routing key for the mint module.

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) GetQueryCmd

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the root query command for the mint module.

func (AppModuleBasic) GetTxCmd

func (AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns no root tx command for the mint module.

func (AppModuleBasic) Name

func (AppModuleBasic) Name() string

Name returns the mint module's name.

func (AppModuleBasic) RegisterGRPCGatewayRoutes

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the mint module.

func (AppModuleBasic) RegisterInterfaces

func (b AppModuleBasic) RegisterInterfaces(_ cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types.

func (AppModuleBasic) RegisterLegacyAminoCodec

func (AppModuleBasic) RegisterLegacyAminoCodec(_ *codec.LegacyAmino)

RegisterLegacyAminoCodec registers the mint module's types on the given LegacyAmino codec.

func (AppModuleBasic) ValidateGenesis

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, _ client.TxEncodingConfig, bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the mint module.