mint

x/mint

Abstract

celestia-app's x/mint is a fork of the Cosmos SDK x/mint module that makes some changes to the inflation mechanism. The changes were motivated by a desire for Celestia to have a pre-determined inflation schedule. See ADR-019 for more details.

Inflation Schedule

• Year indicates the number of years elapsed since chain genesis.
• Inflation (%) indicates the percentage of the total supply that will be minted in the next year.

Terms

• Inflation Rate: The percentage of the total supply that will be minted each year. The inflation rate is calculated once per year on the anniversary of chain genesis based on the number of years elapsed since genesis. The inflation rate is calculated as InitialInflationRate * ((1 - DisinflationRate) ^ YearsSinceGenesis). See ./types/constants.go for the constants used in this module.
• Annual Provisions: The total amount of tokens that will be minted each year. Annual provisions are calculated once per year on the anniversary of chain genesis based on the total supply and the inflation rate. Annual provisions are calculated as TotalSupply * InflationRate
• Block Provision: The amount of tokens that will be minted in the current block. Block provisions are calculated once per block based on the annual provisions and the number of nanoseconds elapsed between the current block and the previous block. Block provisions are calculated as AnnualProvisions * (NanosecondsSincePreviousBlock / NanosecondsPerYear)

State

See ./types/minter.go for the Minter struct which contains this module's state.

State Transitions

The Minter struct is updated every block via BeginBlocker.

Begin Block

See BeginBlocker in ./abci.go.

Events

An event is emitted every block when a block provision is minted. See mintBlockProvision in ./abci.go.

Client

CLI

$ celestia-appd query mint annual-provisions
80235005639941.760000000000000000

$ celestia-appd query mint genesis-time
2023-05-09 00:56:15.59304 +0000 UTC

$ celestia-appd query mint inflation
0.080000000000000000

Genesis State

The genesis state is defined in ./types/genesis.go.

Params

All params have been removed from this module because they should not be modifiable via governance. The constants used in this module are defined in ./types/constants.go and they are subject to change via hardforks.

Tests

See ./test/mint_test.go for an integration test suite for this module.

Assumptions and Considerations

For the Gregorian calendar, the average length of the calendar year (the mean year) across the complete leap cycle of 400 years is 365.2425 days (97 out of 400 years are leap years).

Source: https://en.wikipedia.org/wiki/Year#Calendar_year

This module assumes DaysPerYear = 365.2425 so when modifying tests, developers must define durations based on this assumption because ordinary durations won't return the expected results. In other words:

// oneYear is 31,556,952 seconds which will likely return expected results in tests
oneYear := time.Duration(minttypes.NanosecondsPerYear)

// oneYear is 31,536,000 seconds which will likely return unexpected results in tests
oneYear := time.Hour * 24 * 365

Implementation

See x/mint for the implementation of this module.

References

1. ADR-019