> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# x/mint

> The x/mint module handles the regular minting of new tokens in a configurable manner.

The `x/mint` module handles the regular minting of new tokens in a configurable manner.

## Contents

* [State](#state)
  * [Minter](#minter)
  * [Params](#params)
* [Begin-Block](#begin-block)
  * [NextInflationRate](#nextinflationrate)
  * [NextAnnualProvisions](#nextannualprovisions)
  * [BlockProvision](#blockprovision)
* [Parameters](#parameters)
* [Events](#events)
  * [BeginBlocker](#beginblocker)
* [Client](#client)
  * [CLI](#cli)
  * [gRPC](#grpc)
  * [REST](#rest)

## Concepts

### The Minting Mechanism

The default 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 actual percentage of bonded tokens 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 actual percentage of bonded tokens is above the goal %-bonded the inflation rate will
  decrease until a minimum value is reached

### Custom Minters

As of Cosmos SDK v0.53.0, developers can set a custom `MintFn` for the module for specialized token minting logic.

The function signature that a `MintFn` must implement is as follows:

```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// MintFn defines the function that needs to be implemented in order to customize the minting process.
type MintFn func(ctx sdk.Context, k *Keeper)

error
```

This can be passed to the `Keeper` upon creation with an additional `Option`:

```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
app.MintKeeper = mintkeeper.NewKeeper(
		appCodec,
		runtime.NewKVStoreService(keys[minttypes.StoreKey]),
		app.StakingKeeper,
		app.AccountKeeper,
		app.BankKeeper,
		authtypes.FeeCollectorName,
		authtypes.NewModuleAddress(govtypes.ModuleName).String(),
		// mintkeeper.WithMintFn(CUSTOM_MINT_FN), // custom mintFn can be added here
	)
```

#### Custom Minter DI Example

Below is a simple approach to creating a custom mint function with extra dependencies in DI configurations.
For this basic example, we will make the minter simply double the supply of `foo` coin.

First, we will define a function that takes our required dependencies, and returns a `MintFn`.

```go expandable theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// MyCustomMintFunction is a custom mint function that doubles the supply of `foo` coin.
func MyCustomMintFunction(bank bankkeeper.BaseKeeper)

mintkeeper.MintFn {
    return func(ctx sdk.Context, k *mintkeeper.Keeper)

error {
    supply := bank.GetSupply(ctx, "foo")
    err := k.MintCoins(ctx, sdk.NewCoins(supply.Add(supply)))
    if err != nil {
    return err
}

return nil
}
}
```

Then, pass the function defined above into the `depinject.Supply` function with the required dependencies.

```go expandable theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// NewSimApp returns a reference to an initialized SimApp.
func NewSimApp(
    logger log.Logger,
    db dbm.DB,
    traceStore io.Writer,
    loadLatest bool,
    appOpts servertypes.AppOptions,
    baseAppOptions ...func(*baseapp.BaseApp),
) *SimApp {
    var (
        app        = &SimApp{
}

appBuilder *runtime.AppBuilder
        appConfig = depinject.Configs(
            AppConfig,
            depinject.Supply(
                appOpts,
                logger,
                // our custom mint function with the necessary dependency passed in.
                MyCustomMintFunction(app.BankKeeper),
            ),
        )
	)
	// ...
}
```

## State

### Minter

The minter is a space for holding current inflation information.

* Minter: `0x00 -> ProtocolBuffer(minter)`

```protobuf theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// Reference: https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/mint/v1beta1/mint.proto#L10-L24
```

### Params

The mint module stores its params in state with the prefix of `0x01`,
it can be updated with governance or the address with authority.

**Note:** The `MaxSupply` parameter controls the maximum supply of tokens the module can mint. A value of `0` indicates an unlimited supply.

* Params: `mint/params -> legacy_amino(params)`

```protobuf theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// Reference: 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.

```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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%.

```go expandable theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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.

```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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`.

```go theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
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"              |
| MaxSupply           | string (math.Int) | "0"                    |

A `MaxSupply` value of `0` means no maximum supply is enforced. Minting stops automatically once the total supply reaches the configured `MaxSupply`. For legacy Amino JSON compatibility, `max_supply` is encoded even when set to `"0"`.

## 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 allows users to query `mint` state.

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd query mint --help
```

##### annual-provisions

The `annual-provisions` command allows users to query the current minting annual provisions value

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd query mint annual-provisions [flags]
```

Example:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd query mint annual-provisions
```

Example Output:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
22268504368893.612100895088410693
```

##### inflation

The `inflation` command allows users to query the current minting inflation value

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd query mint inflation [flags]
```

Example:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd query mint inflation
```

Example Output:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
0.199200302563256955
```

##### params

The `params` command allows users to query the current minting parameters

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
simd query mint params [flags]
```

Example:

```yml theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
blocks_per_year: "4360000"
goal_bonded: "0.670000000000000000"
inflation_max: "0.200000000000000000"
inflation_min: "0.070000000000000000"
inflation_rate_change: "0.130000000000000000"
max_supply: "0"
mint_denom: stake
```

### gRPC

A user can query the `mint` module using gRPC endpoints.

#### AnnualProvisions

The `AnnualProvisions` endpoint allows users to query the current minting annual provisions value

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
/cosmos.mint.v1beta1.Query/AnnualProvisions
```

Example:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/AnnualProvisions
```

Example Output:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "annualProvisions": "1432452520532626265712995618"
}
```

#### Inflation

The `Inflation` endpoint allows users to query the current minting inflation value

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
/cosmos.mint.v1beta1.Query/Inflation
```

Example:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Inflation
```

Example Output:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "inflation": "130197115720711261"
}
```

#### Params

The `Params` endpoint allows users to query the current minting parameters

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
/cosmos.mint.v1beta1.Query/Params
```

Example:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Params
```

Example Output:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "params": {
    "mintDenom": "stake",
    "inflationRateChange": "130000000000000000",
    "inflationMax": "200000000000000000",
    "inflationMin": "70000000000000000",
    "goalBonded": "670000000000000000",
    "blocksPerYear": "6311520",
    "maxSupply": "0"
  }
}
```

### REST

A user can query the `mint` module using REST endpoints.

#### annual-provisions

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
/cosmos/mint/v1beta1/annual_provisions
```

Example:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl "localhost:1317/cosmos/mint/v1beta1/annual_provisions"
```

Example Output:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "annualProvisions": "1432452520532626265712995618"
}
```

#### inflation

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
/cosmos/mint/v1beta1/inflation
```

Example:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl "localhost:1317/cosmos/mint/v1beta1/inflation"
```

Example Output:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "inflation": "130197115720711261"
}
```

#### params

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
/cosmos/mint/v1beta1/params
```

Example:

```shell theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl "localhost:1317/cosmos/mint/v1beta1/params"
```

Example Output:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "params": {
    "mintDenom": "stake",
    "inflationRateChange": "130000000000000000",
    "inflationMax": "200000000000000000",
    "inflationMin": "70000000000000000",
    "goalBonded": "670000000000000000",
    "blocksPerYear": "6311520",
    "maxSupply": "0"
  }
}
```