chore: x/mint docs and clean up, excluding mint keeper

Makefile

@@ -1,6 +1,5 @@
 #!/usr/bin/make -f
 
-PACKAGES_SIMTEST=$(shell go list ./... | grep '/simulation')
 VERSION := $(shell echo $(shell git describe --tags) | sed 's/^v//')
 COMMIT := $(shell git log -1 --format='%H')
 LEDGER_ENABLED ?= true

docs/core/proto-docs.md

@@ -2624,7 +2624,7 @@ GenesisState defines the mint module's genesis state.
 | ----- | ---- | ----- | ----------- |
 | `minter` | [Minter](#osmosis.mint.v1beta1.Minter) |  | minter is a space for holding current rewards information. |
 | `params` | [Params](#osmosis.mint.v1beta1.Params) |  | params defines all the paramaters of the module. |
-| `halven_started_epoch` | [int64](#int64) |  | current halven period start epoch |
+| `reduction_started_epoch` | [int64](#int64) |  | current reduction period start epoch |
 
 
 

proto/osmosis/mint/v1beta1/genesis.proto

@@ -8,13 +8,14 @@ option go_package = "github.com/osmosis-labs/osmosis/v7/x/mint/types";
 
 // GenesisState defines the mint module's genesis state.
 message GenesisState {
-  // minter is a space for holding current rewards information.
+  // minter is an abstraction for holding current rewards information.
   Minter minter = 1 [ (gogoproto.nullable) = false ];
 
-  // params defines all the paramaters of the module.
+  // params defines all the paramaters of the mint module.
   Params params = 2 [ (gogoproto.nullable) = false ];
 
-  // current halven period start epoch
-  int64 halven_started_epoch = 3
-      [ (gogoproto.moretags) = "yaml:\"halven_started_epoch\"" ];
+  // reduction_started_epoch the first epoch in which the reduction of mint
+  // begins.
+  int64 reduction_started_epoch = 3
+      [ (gogoproto.moretags) = "yaml:\"reduction_started_epoch\"" ];
 }

proto/osmosis/mint/v1beta1/mint.proto

@@ -10,14 +10,17 @@ import "google/protobuf/duration.proto";
 
 // Minter represents the minting state.
 message Minter {
-  // current epoch provisions
+  // epoch_provisions represent rewards for the current epoch.
   string epoch_provisions = 1 [
     (gogoproto.moretags) = "yaml:\"epoch_provisions\"",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable) = false
   ];
 }
 
+// WeightedAddress represents an address with a weight assigned to it.
+// The weight is used to determine the proportion of the total minted
+// tokens to be minted to the address.
 message WeightedAddress {
   string address = 1 [ (gogoproto.moretags) = "yaml:\"address\"" ];
   string weight = 2 [
@@ -27,29 +30,32 @@ message WeightedAddress {
   ];
 }
 
+// DistributionProportions defines the distribution proportions of the minted
+// denom. In other words, defines which stakeholders will receive the minted
+// denoms and how much.
 message DistributionProportions {
-  // staking defines the proportion of the minted minted_denom that is to be
+  // staking defines the proportion of the minted mint_denom that is to be
   // allocated as staking rewards.
   string staking = 1 [
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.moretags) = "yaml:\"staking\"",
     (gogoproto.nullable) = false
   ];
-  // pool_incentives defines the proportion of the minted minted_denom that is
+  // pool_incentives defines the proportion of the minted mint_denom that is
   // to be allocated as pool incentives.
   string pool_incentives = 2 [
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.moretags) = "yaml:\"pool_incentives\"",
     (gogoproto.nullable) = false
   ];
-  // developer_rewards defines the proportion of the minted minted_denom that is
+  // developer_rewards defines the proportion of the minted mint_denom that is
   // to be allocated to developer rewards address.
   string developer_rewards = 3 [
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.moretags) = "yaml:\"developer_rewards\"",
     (gogoproto.nullable) = false
   ];
-  // community_pool defines the proportion of the minted minted_denom that is
+  // community_pool defines the proportion of the minted mint_denom that is
   // to be allocated to the community pool.
   string community_pool = 4 [
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
@@ -58,39 +64,47 @@ message DistributionProportions {
   ];
 }
 
-// Params holds parameters for the mint module.
+// Params holds parameters for the x/mint module.
 message Params {
   option (gogoproto.goproto_stringer) = false;
 
-  // type of coin to mint
+  // mint_denom the denom of the coin to mint.
   string mint_denom = 1;
-  // epoch provisions from the first epoch
+  // genesis_epoch_provisions epoch provisions from the first epoch.
   string genesis_epoch_provisions = 2 [
     (gogoproto.moretags) = "yaml:\"genesis_epoch_provisions\"",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable) = false
   ];
-  // mint epoch identifier
+  // epoch_identifier mint epoch identifier e.g. (day, week).
   string epoch_identifier = 3
       [ (gogoproto.moretags) = "yaml:\"epoch_identifier\"" ];
-  // number of epochs take to reduce rewards
+  // reduction_period_in_epochs the number of epochs it takes
+  // to reduce the rewards.
   int64 reduction_period_in_epochs = 4
       [ (gogoproto.moretags) = "yaml:\"reduction_period_in_epochs\"" ];
-  // reduction multiplier to execute on each period
+  // reduction_factor is the reduction multiplier to execute
+  // at the end of each period set by reduction_period_in_epochs.
   string reduction_factor = 5 [
     (gogoproto.moretags) = "yaml:\"reduction_factor\"",
     (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
     (gogoproto.nullable) = false
   ];
-  // distribution_proportions defines the proportion of the minted denom
+  // distribution_proportions defines the distribution proportions of the minted
+  // denom. In other words, defines which stakeholders will receive the minted
+  // denoms and how much.
   DistributionProportions distribution_proportions = 6
       [ (gogoproto.nullable) = false ];
-  // address to receive developer rewards
+  // weighted_developer_rewards_receivers the address to receive developer
+  // rewards with weights assignedt to each address. The final amount that each
+  // address receives is: epoch_provisions *
+  // distribution_proportions.developer_rewards * Address's Weight.
   repeated WeightedAddress weighted_developer_rewards_receivers = 7 [
     (gogoproto.moretags) = "yaml:\"developer_rewards_receiver\"",
     (gogoproto.nullable) = false
   ];
-  // start epoch to distribute minting rewards
+  // minting_rewards_distribution_start_epoch start epoch to distribute minting
+  // rewards
   int64 minting_rewards_distribution_start_epoch = 8
       [ (gogoproto.moretags) =
             "yaml:\"minting_rewards_distribution_start_epoch\"" ];

proto/osmosis/mint/v1beta1/query.proto

@@ -14,7 +14,7 @@ service Query {
     option (google.api.http).get = "/osmosis/mint/v1beta1/params";
   }
 
-  // EpochProvisions current minting epoch provisions value.
+  // EpochProvisions returns the current minting epoch provisions value.
   rpc EpochProvisions(QueryEpochProvisionsRequest)
       returns (QueryEpochProvisionsResponse) {
     option (google.api.http).get = "/osmosis/mint/v1beta1/epoch_provisions";

x/mint/spec/README.md → x/mint/README.md

@@ -1,11 +1,13 @@
 # Mint
 
-The ```mint``` module is responsible for creating tokens in a flexible way to reward 
-validators, incentivize providing pool liquidity, provide funds for Osmosis governance, and pay developers to maintain and improve Osmosis.
+The `mint` module is responsible for creating tokens in a flexible way to reward 
+validators, incentivize providing pool liquidity, provide funds for Osmosis governance,
+and pay developers to maintain and improve Osmosis.
 
-The module is also responsible for reducing the token creation and distribution by a set amount and a set period of time until it reaches its maximum supply (see ```reduction_factor``` and ```reduction_period_in_epochs```)
+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`)
 
-Module uses time basis epochs supported by ```epochs``` module.
+The module uses time basis epochs supported by the `epochs` module.
 
 ## Contents
 
@@ -23,19 +25,19 @@ The `x/mint` module is designed to handle the regular printing of new
 tokens within a chain. The design taken within Osmosis is to
 
 - Mint new tokens once per epoch (default one week)
-- To have a "Reductioning factor" every period, which reduces the
-    amount of rewards per epoch. (default: period is 3 years, where a
+- To have a "Reductioning factor" every period, which reduces the number of
+    rewards per epoch. (default: period is 3 years, where a
     year is 52 epochs. The next period's rewards are 2/3 of the prior
     period's rewards)
 
-### Reductioning factor
+### Reduction factor
 
-This is a generalization over the Bitcoin style halvenings. Every year,
-the amount of rewards issued per week will reduce by a governance
-specified factor, instead of a fixed `1/2`. So
+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 `2/3`, and thus reduce rewards
+default to having a reduction factor of `2/3` and thus reduce rewards
 at the end of every year by `33%`.
 
 The implication of this is that the total supply is finite, according to
@@ -47,7 +49,7 @@ the following formula:
 
 ### Minter
 
-The minter is a space for holding current rewards information.
+The [`Minter`](https://github.com/osmosis-labs/osmosis/blob/cbb683e8395655042b4421355cd54a8c96bfa507/x/mint/types/mint.pb.go#L30) is an abstraction for holding current rewards information.
 
 ```go
 type Minter struct {
@@ -57,65 +59,33 @@ type Minter struct {
 
 ### Params
 
-Minting params are held in the global params store.
+Minting [`Params`](https://github.com/osmosis-labs/osmosis/blob/cbb683e8395655042b4421355cd54a8c96bfa507/x/mint/types/mint.pb.go#L168) are held in the global params store.
 
-```go
-type Params struct {
-    MintDenom               string                  // type of coin to mint
-    GenesisEpochProvisions  sdk.Dec                 // initial epoch provisions at genesis
-    EpochIdentifier         string                  // identifier of epoch
-    ReductionPeriodInEpochs int64                   // number of epochs between reward reductions
-    ReductionFactor         sdk.Dec                 // reduction multiplier to execute on each period
- DistributionProportions DistributionProportions // distribution_proportions defines the proportion of the minted denom
- WeightedDeveloperRewardsReceivers    []WeightedAddress // address to receive developer rewards
- MintingRewardsDistributionStartEpoch int64             // start epoch to distribute minting rewards
-}
-```
+### LastReductionEpoch
 
-### LastHalvenEpoch
-
-Last halven epoch stores the epoch number when the last reduction of
+Last reduction epoch stores the epoch number when the last reduction of
 coin mint amount per epoch has happened.
 
-**TODO:**
-
-- Update the name to LastReductionEpoch as the reduction amount could
-    be set by governance.
-
 ## Begin-Epoch
 
-Minting parameters are recalculated and inflation paid at the beginning
-of each epoch. An epoch is signalled by x/epochs
+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 3 years). At the time of reduction, the current provision is
-multiplied by reduction factor (default `2/3`), to calculate the
+(default 3 years). At the time of the reduction, the current provision is
+multiplied by the reduction factor (default `2/3`), to calculate the
 provisions for the next epoch. Consequently, the rewards of the next
-period will be lowered by `1 - reduction factor`.
-
-``` go
-func (m Minter) NextEpochProvisions(params Params) sdk.Dec {
-    return m.EpochProvisions.Mul(params.ReductionFactor)
-}
-```
+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 chains
-needs. (See TODO.md for details) This fee collector is specified as the
-`auth` module's `FeeCollector` `ModuleAccount`.
-
-``` go
-func (m Minter) EpochProvision(params Params) sdk.Coin {
-    provisionAmt := m.EpochProvisions.QuoInt(sdk.NewInt(int64(params.EpochsPerYear)))
-    return sdk.NewCoin(params.MintDenom, provisionAmt.TruncateInt())
-}
-```
+`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
 
@@ -139,10 +109,10 @@ The minting module contains the following parameters:
 Below are all the network parameters for the ```mint``` module:
 
 - **```mint_denom```** - Token type being minted
-- **```genesis_epoch_provisions```** - Amount of tokens generated at epoch to the distribution categories (see distribution_proportions)
+- **```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 reduction period passes (if set to 66.66%, token issuance will reduce by 1/3)
+- **```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 OSMO
   - **```pool_incentives```** - Proportion of minted funds to incentivize pools on Osmosis
@@ -154,21 +124,16 @@ Below are all the network parameters for the ```mint``` module:
 **Notes**
 
 1. `mint_denom` defines denom for minting token - uosmo
-2. `genesis_epoch_provisions` provides minting tokens per epoch at
-    genesis.
-3. `epoch_identifier` defines the epoch identifier to be used for mint
-    module e.g. "weekly"
-4. `reduction_period_in_epochs` defines the number of epochs to pass to
-    reduce 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, when developer rewards address is empty, it distribute
-    tokens to community pool.
-7. `weighted_developer_rewards_receivers` provides the addresses that
-    receives developer rewards by weight
-8. `minting_rewards_distribution_start_epoch` defines the start epoch
-    of minting to make sure minting start after initial pools are set
+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. "weekly"
+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, when the developer 
+    rewards address is empty, it distributes tokens to the community pool.
+7. `weighted_developer_rewards_receivers` provides the addresses that receive developer 
+    rewards by weight
+8. `minting_rewards_distribution_start_epoch` defines the start epoch of minting to make sure
+    minting start after initial pools are set
 
 ## Events
 

x/mint/client/cli/cli_test.go

@@ -1,5 +1,4 @@
 //go:build norace
-// +build norace
 
 package cli_test
 

x/mint/client/rest/grpc_query_test.go

@@ -1,5 +1,4 @@
 //go:build norace
-// +build norace
 
 package rest_test
 

x/mint/keeper/genesis.go

@@ -19,13 +19,13 @@ func (k Keeper) InitGenesis(ctx sdk.Context, ak types.AccountKeeper, bk types.Ba
 		bk.AddSupplyOffset(ctx, data.Params.MintDenom, sdk.NewInt(225_000_000_000_000).Neg())
 	}
 
-	k.SetLastHalvenEpochNum(ctx, data.HalvenStartedEpoch)
+	k.SetLastReductionEpochNum(ctx, data.ReductionStartedEpoch)
 }
 
 // ExportGenesis returns a GenesisState for a given context and keeper.
 func (k Keeper) ExportGenesis(ctx sdk.Context) *types.GenesisState {
 	minter := k.GetMinter(ctx)
 	params := k.GetParams(ctx)
-	lastHalvenEpoch := k.GetLastHalvenEpochNum(ctx)
-	return types.NewGenesisState(minter, params, lastHalvenEpoch)
+	lastReductionEpoch := k.GetLastReductionEpochNum(ctx)
+	return types.NewGenesisState(minter, params, lastReductionEpoch)
 }

x/mint/keeper/genesis_test.go

@@ -25,5 +25,5 @@ func TestMintInitGenesis(t *testing.T) {
 	expectedVestingCoins, ok := sdk.NewIntFromString("225000000000000")
 	require.True(t, ok)
 	require.Equal(t, expectedVestingCoins, initialVestingCoins.Amount)
-	require.Equal(t, int64(0), app.MintKeeper.GetLastHalvenEpochNum(ctx))
+	require.Equal(t, int64(0), app.MintKeeper.GetLastReductionEpochNum(ctx))
 }