chore: x/mint docs and clean up, excluding mint keeper (#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]> (cherry picked from commit ee48cf5) # Conflicts: # go.mod # proto/osmosis/superfluid/query.proto # x/mint/keeper/genesis.go # x/mint/keeper/hooks_test.go # x/mint/keeper/keeper.go # x/mint/types/genesis.pb.go # x/mint/types/params.go # x/pool-incentives/keeper/hooks.go # x/superfluid/types/query.pb.go
osmosis-labs · Jul 14, 2022 · 1e7917e · 1e7917e
1 parent b0afc78
commit 1e7917e
Show file tree

Hide file tree

Showing 33 changed files with 688 additions and 219 deletions.
diff --git a/Makefile b/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

diff --git a/docs/core/proto-docs.md b/docs/core/proto-docs.md
@@ -2627,7 +2627,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 |
 
 
 

diff --git a/go.mod b/go.mod
@@ -4,7 +4,12 @@ go 1.18
 
 require (
 	github.com/CosmWasm/wasmd v0.24.0
+<<<<<<< HEAD
 	github.com/cosmos/cosmos-sdk v0.45.5
+=======
+	github.com/cosmos/cosmos-proto v1.0.0-alpha7
+	github.com/cosmos/cosmos-sdk v0.45.6
+>>>>>>> ee48cf58 (chore: x/mint docs and clean up, excluding mint keeper (#1857))
 	github.com/cosmos/go-bip39 v1.0.0
 	github.com/cosmos/iavl v0.17.3
 	github.com/cosmos/ibc-go/v3 v3.0.0

diff --git a/proto/osmosis/mint/v1beta1/genesis.proto b/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\"" ];
 }
diff --git a/proto/osmosis/mint/v1beta1/mint.proto b/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\"" ];

diff --git a/proto/osmosis/mint/v1beta1/query.proto b/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";

diff --git a/proto/osmosis/superfluid/query.proto b/proto/osmosis/superfluid/query.proto
@@ -112,6 +112,17 @@ service Query {
   //   option (google.api.http).get =
   //       "/osmosis/superfluid/v1beta1/superfluid_unbondings_by_validator_denom";
   // }
+<<<<<<< HEAD
+=======
+
+  // Returns the specified delegations for a specific delegator
+  rpc TotalDelegationByDelegator(QueryTotalDelegationByDelegatorRequest)
+      returns (QueryTotalDelegationByDelegatorResponse) {
+    option (google.api.http).get =
+        "/osmosis/superfluid/v1beta1/"
+        "total_delegation_by_delegator/{delegator_address}";
+  }
+>>>>>>> ee48cf58 (chore: x/mint docs and clean up, excluding mint keeper (#1857))
 }
 
 message QueryParamsRequest {}
@@ -256,4 +267,26 @@ message EstimateSuperfluidDelegatedAmountByValidatorDenomResponse {
 //     (gogoproto.nullable) = false,
 //     (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"
 //   ];
-// }
+<<<<<<< HEAD
+// }
+=======
+// }
+
+message QueryTotalDelegationByDelegatorRequest { string delegator_address = 1; }
+
+message QueryTotalDelegationByDelegatorResponse {
+  repeated SuperfluidDelegationRecord superfluid_delegation_records = 1
+      [ (gogoproto.nullable) = false ];
+
+  repeated cosmos.staking.v1beta1.DelegationResponse delegation_response = 2
+      [ (gogoproto.nullable) = false ];
+  repeated cosmos.base.v1beta1.Coin total_delegated_coins = 3 [
+    (gogoproto.nullable) = false,
+    (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"
+  ];
+  cosmos.base.v1beta1.Coin total_equivalent_staked_amount = 4 [
+    (gogoproto.nullable) = false,
+    (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coin"
+  ];
+}
+>>>>>>> ee48cf58 (chore: x/mint docs and clean up, excluding mint keeper (#1857))
diff --git a/x/mint/spec/README.md → x/mint/README.md b/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
 

diff --git a/x/mint/client/cli/cli_test.go b/x/mint/client/cli/cli_test.go
@@ -1,5 +1,4 @@
 //go:build norace
-// +build norace
 
 package cli_test