github.com/cosmos/cosmos-sdk@v0.50.10/x/mint/README.md (about) 1 --- 2 sidebar_position: 1 3 --- 4 5 # `x/mint` 6 7 ## Contents 8 9 * [State](#state) 10 * [Minter](#minter) 11 * [Params](#params) 12 * [Begin-Block](#begin-block) 13 * [NextInflationRate](#nextinflationrate) 14 * [NextAnnualProvisions](#nextannualprovisions) 15 * [BlockProvision](#blockprovision) 16 * [Parameters](#parameters) 17 * [Events](#events) 18 * [BeginBlocker](#beginblocker) 19 * [Client](#client) 20 * [CLI](#cli) 21 * [gRPC](#grpc) 22 * [REST](#rest) 23 24 ## Concepts 25 26 ### The Minting Mechanism 27 28 The minting mechanism was designed to: 29 30 * allow for a flexible inflation rate determined by market demand targeting a particular bonded-stake ratio 31 * effect a balance between market liquidity and staked supply 32 33 In order to best determine the appropriate market rate for inflation rewards, a 34 moving change rate is used. The moving change rate mechanism ensures that if 35 the % bonded is either over or under the goal %-bonded, the inflation rate will 36 adjust to further incentivize or disincentivize being bonded, respectively. Setting the goal 37 %-bonded at less than 100% encourages the network to maintain some non-staked tokens 38 which should help provide some liquidity. 39 40 It can be broken down in the following way: 41 42 * If the actual percentage of bonded tokens is below the goal %-bonded the inflation rate will 43 increase until a maximum value is reached 44 * If the goal % bonded (67% in Cosmos-Hub) is maintained, then the inflation 45 rate will stay constant 46 * If the actual percentage of bonded tokens is above the goal %-bonded the inflation rate will 47 decrease until a minimum value is reached 48 49 50 ## State 51 52 ### Minter 53 54 The minter is a space for holding current inflation information. 55 56 * Minter: `0x00 -> ProtocolBuffer(minter)` 57 58 ```protobuf reference 59 https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/mint/v1beta1/mint.proto#L10-L24 60 ``` 61 62 ### Params 63 64 The mint module stores its params in state with the prefix of `0x01`, 65 it can be updated with governance or the address with authority. 66 67 * Params: `mint/params -> legacy_amino(params)` 68 69 ```protobuf reference 70 https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/proto/cosmos/mint/v1beta1/mint.proto#L26-L59 71 ``` 72 73 ## Begin-Block 74 75 Minting parameters are recalculated and inflation paid at the beginning of each block. 76 77 ### Inflation rate calculation 78 79 Inflation rate is calculated using an "inflation calculation function" that's 80 passed to the `NewAppModule` function. If no function is passed, then the SDK's 81 default inflation function will be used (`NextInflationRate`). In case a custom 82 inflation calculation logic is needed, this can be achieved by defining and 83 passing a function that matches `InflationCalculationFn`'s signature. 84 85 ```go 86 type InflationCalculationFn func(ctx sdk.Context, minter Minter, params Params, bondedRatio math.LegacyDec) math.LegacyDec 87 ``` 88 89 #### NextInflationRate 90 91 The target annual inflation rate is recalculated each block. 92 The inflation is also subject to a rate change (positive or negative) 93 depending on the distance from the desired ratio (67%). The maximum rate change 94 possible is defined to be 13% per year, however, the annual inflation is capped 95 as between 7% and 20%. 96 97 ```go 98 NextInflationRate(params Params, bondedRatio math.LegacyDec) (inflation math.LegacyDec) { 99 inflationRateChangePerYear = (1 - bondedRatio/params.GoalBonded) * params.InflationRateChange 100 inflationRateChange = inflationRateChangePerYear/blocksPerYr 101 102 // increase the new annual inflation for this next block 103 inflation += inflationRateChange 104 if inflation > params.InflationMax { 105 inflation = params.InflationMax 106 } 107 if inflation < params.InflationMin { 108 inflation = params.InflationMin 109 } 110 111 return inflation 112 } 113 ``` 114 115 ### NextAnnualProvisions 116 117 Calculate the annual provisions based on current total supply and inflation 118 rate. This parameter is calculated once per block. 119 120 ```go 121 NextAnnualProvisions(params Params, totalSupply math.LegacyDec) (provisions math.LegacyDec) { 122 return Inflation * totalSupply 123 ``` 124 125 ### BlockProvision 126 127 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`. 128 129 ```go 130 BlockProvision(params Params) sdk.Coin { 131 provisionAmt = AnnualProvisions/ params.BlocksPerYear 132 return sdk.NewCoin(params.MintDenom, provisionAmt.Truncate()) 133 ``` 134 135 136 ## Parameters 137 138 The minting module contains the following parameters: 139 140 | Key | Type | Example | 141 |---------------------|-----------------|------------------------| 142 | MintDenom | string | "uatom" | 143 | InflationRateChange | string (dec) | "0.130000000000000000" | 144 | InflationMax | string (dec) | "0.200000000000000000" | 145 | InflationMin | string (dec) | "0.070000000000000000" | 146 | GoalBonded | string (dec) | "0.670000000000000000" | 147 | BlocksPerYear | string (uint64) | "6311520" | 148 149 150 ## Events 151 152 The minting module emits the following events: 153 154 ### BeginBlocker 155 156 | Type | Attribute Key | Attribute Value | 157 |------|-------------------|--------------------| 158 | mint | bonded_ratio | {bondedRatio} | 159 | mint | inflation | {inflation} | 160 | mint | annual_provisions | {annualProvisions} | 161 | mint | amount | {amount} | 162 163 164 ## Client 165 166 ### CLI 167 168 A user can query and interact with the `mint` module using the CLI. 169 170 #### Query 171 172 The `query` commands allows users to query `mint` state. 173 174 ```shell 175 simd query mint --help 176 ``` 177 178 ##### annual-provisions 179 180 The `annual-provisions` command allows users to query the current minting annual provisions value 181 182 ```shell 183 simd query mint annual-provisions [flags] 184 ``` 185 186 Example: 187 188 ```shell 189 simd query mint annual-provisions 190 ``` 191 192 Example Output: 193 194 ```shell 195 22268504368893.612100895088410693 196 ``` 197 198 ##### inflation 199 200 The `inflation` command allows users to query the current minting inflation value 201 202 ```shell 203 simd query mint inflation [flags] 204 ``` 205 206 Example: 207 208 ```shell 209 simd query mint inflation 210 ``` 211 212 Example Output: 213 214 ```shell 215 0.199200302563256955 216 ``` 217 218 ##### params 219 220 The `params` command allows users to query the current minting parameters 221 222 ```shell 223 simd query mint params [flags] 224 ``` 225 226 Example: 227 228 ```yml 229 blocks_per_year: "4360000" 230 goal_bonded: "0.670000000000000000" 231 inflation_max: "0.200000000000000000" 232 inflation_min: "0.070000000000000000" 233 inflation_rate_change: "0.130000000000000000" 234 mint_denom: stake 235 ``` 236 237 ### gRPC 238 239 A user can query the `mint` module using gRPC endpoints. 240 241 #### AnnualProvisions 242 243 The `AnnualProvisions` endpoint allows users to query the current minting annual provisions value 244 245 ```shell 246 /cosmos.mint.v1beta1.Query/AnnualProvisions 247 ``` 248 249 Example: 250 251 ```shell 252 grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/AnnualProvisions 253 ``` 254 255 Example Output: 256 257 ```json 258 { 259 "annualProvisions": "1432452520532626265712995618" 260 } 261 ``` 262 263 #### Inflation 264 265 The `Inflation` endpoint allows users to query the current minting inflation value 266 267 ```shell 268 /cosmos.mint.v1beta1.Query/Inflation 269 ``` 270 271 Example: 272 273 ```shell 274 grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Inflation 275 ``` 276 277 Example Output: 278 279 ```json 280 { 281 "inflation": "130197115720711261" 282 } 283 ``` 284 285 #### Params 286 287 The `Params` endpoint allows users to query the current minting parameters 288 289 ```shell 290 /cosmos.mint.v1beta1.Query/Params 291 ``` 292 293 Example: 294 295 ```shell 296 grpcurl -plaintext localhost:9090 cosmos.mint.v1beta1.Query/Params 297 ``` 298 299 Example Output: 300 301 ```json 302 { 303 "params": { 304 "mintDenom": "stake", 305 "inflationRateChange": "130000000000000000", 306 "inflationMax": "200000000000000000", 307 "inflationMin": "70000000000000000", 308 "goalBonded": "670000000000000000", 309 "blocksPerYear": "6311520" 310 } 311 } 312 ``` 313 314 ### REST 315 316 A user can query the `mint` module using REST endpoints. 317 318 #### annual-provisions 319 320 ```shell 321 /cosmos/mint/v1beta1/annual_provisions 322 ``` 323 324 Example: 325 326 ```shell 327 curl "localhost:1317/cosmos/mint/v1beta1/annual_provisions" 328 ``` 329 330 Example Output: 331 332 ```json 333 { 334 "annualProvisions": "1432452520532626265712995618" 335 } 336 ``` 337 338 #### inflation 339 340 ```shell 341 /cosmos/mint/v1beta1/inflation 342 ``` 343 344 Example: 345 346 ```shell 347 curl "localhost:1317/cosmos/mint/v1beta1/inflation" 348 ``` 349 350 Example Output: 351 352 ```json 353 { 354 "inflation": "130197115720711261" 355 } 356 ``` 357 358 #### params 359 360 ```shell 361 /cosmos/mint/v1beta1/params 362 ``` 363 364 Example: 365 366 ```shell 367 curl "localhost:1317/cosmos/mint/v1beta1/params" 368 ``` 369 370 Example Output: 371 372 ```json 373 { 374 "params": { 375 "mintDenom": "stake", 376 "inflationRateChange": "130000000000000000", 377 "inflationMax": "200000000000000000", 378 "inflationMin": "70000000000000000", 379 "goalBonded": "670000000000000000", 380 "blocksPerYear": "6311520" 381 } 382 } 383 ```