chore: x/mint docs and clean up, excluding mint keeper (backport #1857)

* chore: mint module docs and clean up

* rename LasteHalvenEpoch to LastReductionEpoch

* lint

* revert proto comments

* spec

* try removing simulation

* client module changes

* client/rest

* more proto fixes

* avoid listing minting params in spec

* Update proto/osmosis/mint/v1beta1/mint.proto

Co-authored-by: Dev Ojha <[email protected]>

* update comment in hooks.go

* Revert "try removing simulation" w/o Makefile change

This reverts commit 5a06bf1.

* randomize mint gen state simulation

* fix full sim tests

* fix TestAppStateDeterminism

* fix TestAppStateDeterminism

* change expected epochIdentifier to day

* address Dev's comments to hardcode certain parameters

* Update x/mint/types/minter_test.go

Co-authored-by: Dev Ojha <[email protected]>

* remove unused variable

* Update proto/osmosis/mint/v1beta1/genesis.proto

Co-authored-by: Matt, Park <[email protected]>

* Update proto/osmosis/mint/v1beta1/mint.proto

Co-authored-by: Matt, Park <[email protected]>

* Update x/mint/types/hooks.go

Co-authored-by: Matt, Park <[email protected]>

* make prot-all

* remove unused

Co-authored-by: Dev Ojha <[email protected]>
Co-authored-by: Matt, Park <[email protected]>

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

@@ -2533,15 +2533,17 @@ Msg defines the Msg service.
 <a name="osmosis.mint.v1beta1.DistributionProportions"></a>
 
 ### DistributionProportions
-
+DistributionProportions defines the distribution proportions of the minted
+denom. In other words, defines which stakeholders will receive the minted
+denoms and how much.
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| `staking` | [string](#string) |  | staking defines the proportion of the minted minted_denom that is to be allocated as staking rewards. |
-| `pool_incentives` | [string](#string) |  | pool_incentives defines the proportion of the minted minted_denom that is to be allocated as pool incentives. |
-| `developer_rewards` | [string](#string) |  | developer_rewards defines the proportion of the minted minted_denom that is to be allocated to developer rewards address. |
-| `community_pool` | [string](#string) |  | community_pool defines the proportion of the minted minted_denom that is to be allocated to the community pool. |
+| `staking` | [string](#string) |  | staking defines the proportion of the minted mint_denom that is to be allocated as staking rewards. |
+| `pool_incentives` | [string](#string) |  | pool_incentives defines the proportion of the minted mint_denom that is to be allocated as pool incentives. |
+| `developer_rewards` | [string](#string) |  | developer_rewards defines the proportion of the minted mint_denom that is to be allocated to developer rewards address. |
+| `community_pool` | [string](#string) |  | community_pool defines the proportion of the minted mint_denom that is to be allocated to the community pool. |
 
 
 
@@ -2556,7 +2558,7 @@ Minter represents the minting state.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| `epoch_provisions` | [string](#string) |  | current epoch provisions |
+| `epoch_provisions` | [string](#string) |  | epoch_provisions represent rewards for the current epoch. |
 
 
 
@@ -2566,19 +2568,19 @@ Minter represents the minting state.
 <a name="osmosis.mint.v1beta1.Params"></a>
 
 ### Params
-Params holds parameters for the mint module.
+Params holds parameters for the x/mint module.
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| `mint_denom` | [string](#string) |  | type of coin to mint |
-| `genesis_epoch_provisions` | [string](#string) |  | epoch provisions from the first epoch |
-| `epoch_identifier` | [string](#string) |  | mint epoch identifier |
-| `reduction_period_in_epochs` | [int64](#int64) |  | number of epochs take to reduce rewards |
-| `reduction_factor` | [string](#string) |  | reduction multiplier to execute on each period |
-| `distribution_proportions` | [DistributionProportions](#osmosis.mint.v1beta1.DistributionProportions) |  | distribution_proportions defines the proportion of the minted denom |
-| `weighted_developer_rewards_receivers` | [WeightedAddress](#osmosis.mint.v1beta1.WeightedAddress) | repeated | address to receive developer rewards |
-| `minting_rewards_distribution_start_epoch` | [int64](#int64) |  | start epoch to distribute minting rewards |
+| `mint_denom` | [string](#string) |  | mint_denom is the denom of the coin to mint. |
+| `genesis_epoch_provisions` | [string](#string) |  | genesis_epoch_provisions epoch provisions from the first epoch. |
+| `epoch_identifier` | [string](#string) |  | epoch_identifier mint epoch identifier e.g. (day, week). |
+| `reduction_period_in_epochs` | [int64](#int64) |  | reduction_period_in_epochs the number of epochs it takes to reduce the rewards. |
+| `reduction_factor` | [string](#string) |  | reduction_factor is the reduction multiplier to execute at the end of each period set by reduction_period_in_epochs. |
+| `distribution_proportions` | [DistributionProportions](#osmosis.mint.v1beta1.DistributionProportions) |  | distribution_proportions defines the distribution proportions of the minted denom. In other words, defines which stakeholders will receive the minted denoms and how much. |
+| `weighted_developer_rewards_receivers` | [WeightedAddress](#osmosis.mint.v1beta1.WeightedAddress) | repeated | weighted_developer_rewards_receivers is 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. |
+| `minting_rewards_distribution_start_epoch` | [int64](#int64) |  | minting_rewards_distribution_start_epoch start epoch to distribute minting rewards |
 
 
 
@@ -2588,7 +2590,9 @@ Params holds parameters for the mint module.
 <a name="osmosis.mint.v1beta1.WeightedAddress"></a>
 
 ### WeightedAddress
-
+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.
 
 
 | Field | Type | Label | Description |
@@ -2625,9 +2629,9 @@ GenesisState defines the mint module's genesis state.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| `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 |
+| `minter` | [Minter](#osmosis.mint.v1beta1.Minter) |  | minter is an abstraction for holding current rewards information. |
+| `params` | [Params](#osmosis.mint.v1beta1.Params) |  | params defines all the paramaters of the mint module. |
+| `reduction_started_epoch` | [int64](#int64) |  | reduction_started_epoch is the first epoch in which the reduction of mint begins. |
 
 
 
@@ -2716,7 +2720,7 @@ Query provides defines the gRPC querier service.
 | Method Name | Request Type | Response Type | Description | HTTP Verb | Endpoint |
 | ----------- | ------------ | ------------- | ------------| ------- | -------- |
 | `Params` | [QueryParamsRequest](#osmosis.mint.v1beta1.QueryParamsRequest) | [QueryParamsResponse](#osmosis.mint.v1beta1.QueryParamsResponse) | Params returns the total set of minting parameters. | GET|/osmosis/mint/v1beta1/params|
-| `EpochProvisions` | [QueryEpochProvisionsRequest](#osmosis.mint.v1beta1.QueryEpochProvisionsRequest) | [QueryEpochProvisionsResponse](#osmosis.mint.v1beta1.QueryEpochProvisionsResponse) | EpochProvisions current minting epoch provisions value. | GET|/osmosis/mint/v1beta1/epoch_provisions|
+| `EpochProvisions` | [QueryEpochProvisionsRequest](#osmosis.mint.v1beta1.QueryEpochProvisionsRequest) | [QueryEpochProvisionsResponse](#osmosis.mint.v1beta1.QueryEpochProvisionsResponse) | EpochProvisions returns the current minting epoch provisions value. | GET|/osmosis/mint/v1beta1/epoch_provisions|
 
  <!-- end services -->
 

proto/osmosis/mint/v1beta1/genesis.proto

@@ -8,13 +8,14 @@ option go_package = "github.com/osmosis-labs/osmosis/v10/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 is 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 is 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 is 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";

proto/osmosis/superfluid/query.proto

@@ -256,4 +256,4 @@ message EstimateSuperfluidDelegatedAmountByValidatorDenomResponse {
 //     (gogoproto.nullable) = false,
 //     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"
 //   ];
-// }
+// }