Skip to content

Commit

Permalink
chore: x/mint docs and clean up, excluding mint keeper (#1857)
Browse files Browse the repository at this point in the history
* 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]>
  • Loading branch information
3 people authored Jun 30, 2022
1 parent b13fbff commit ee48cf5
Show file tree
Hide file tree
Showing 33 changed files with 605 additions and 345 deletions.
1 change: 0 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/core/proto-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -2626,7 +2626,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 |



Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ go 1.18
require (
github.com/CosmWasm/wasmd v0.24.0
github.com/cosmos/cosmos-proto v1.0.0-alpha7
github.com/cosmos/cosmos-sdk v0.45.5
github.com/cosmos/cosmos-sdk v0.45.6
github.com/cosmos/go-bip39 v1.0.0
github.com/cosmos/iavl v0.17.3
github.com/cosmos/ibc-go/v3 v3.0.0
Expand Down
11 changes: 6 additions & 5 deletions proto/osmosis/mint/v1beta1/genesis.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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 is the first epoch in which the reduction of mint
// begins.
int64 reduction_started_epoch = 3
[ (gogoproto.moretags) = "yaml:\"reduction_started_epoch\"" ];
}
42 changes: 28 additions & 14 deletions proto/osmosis/mint/v1beta1/mint.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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 [
Expand All @@ -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",
Expand All @@ -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\"" ];
Expand Down
2 changes: 1 addition & 1 deletion proto/osmosis/mint/v1beta1/query.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down
19 changes: 9 additions & 10 deletions proto/osmosis/superfluid/query.proto
Original file line number Diff line number Diff line change
Expand Up @@ -114,10 +114,12 @@ service Query {
// "/osmosis/superfluid/v1beta1/superfluid_unbondings_by_validator_denom";
// }

// 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}";
// 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}";
}
}

Expand Down Expand Up @@ -265,17 +267,14 @@ message EstimateSuperfluidDelegatedAmountByValidatorDenomResponse {
// ];
// }

message QueryTotalDelegationByDelegatorRequest {
string delegator_address = 1;
}
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.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"
Expand Down
107 changes: 36 additions & 71 deletions x/mint/spec/README.md → x/mint/README.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand All @@ -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 {
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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

Expand Down
1 change: 0 additions & 1 deletion x/mint/client/cli/cli_test.go
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
//go:build norace
// +build norace

package cli_test

Expand Down
1 change: 0 additions & 1 deletion x/mint/client/rest/grpc_query_test.go
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
//go:build norace
// +build norace

package rest_test

Expand Down
Loading

0 comments on commit ee48cf5

Please sign in to comment.