0g-chain/x/kavamint/spec/01_concepts.md
Robert Pirtle f37321839b
add x/kavamint & x/community modules (#1400)
* add `x/kavamint` module (#1376)

* stub out the x/kavamint module

* mint staking rewards in x/kavamint BeginBlocker

* calculate cumulative inflation from x/kavamint

* cleanup, abstract bond denom, grpc query tests

* store & use previous block time to calculate mints

* move test suite to testutil

* add test of x/kavamint BeginBlocker

* cleanup & comments from @DracoLi review

* fix x/incentive integration test

* remove rest client grpc test

* add x/kavamint module spec

* track previous block time in genesis

* suggested cleanup from PR review

* bugfix incorrect module account check

* add x/community module (#1388)

* add x/community module

* refactor and setup fund-community-pool tx

* remove unused features (params, genesis state)

* test x/community query and message

* update with master branch deps

* updates from review

* indicate deprecated methods on module (still needed to fulfill interface)
* remove legacy querier
* derive msg Route() and Type() from sdk.MsgTypeURL(&msg)

* use module name for message Route()

* mint community pool inflation in x/kavamint (#1389)

* mint community pool inflation in x/kavamint

* refactor x/kavamint abci inflation test

* test inflation from x/kavamint

* default kavamint rates to 0%

* rename kavamint account name variables

* panic if genesis kavamint previous block time not set

* emit event on kavamint begin blocker

* add kavamint year of inflation sanity check test

* update fund_community_pool message event

* add x/community spec

* refactor inflation accumulation into single func

* use new comm pool in kavadist multispend proposal (#1403)

the x/community module houses the new community pool. this commit
points the CommunityPoolMultiSpendProposal at the new community pool
so that multispend proposals can continue to be processed once original
fee pool funds are move to x/community

* updates from proto lint changes

* update earn proposals to use new community pool

originally the CommunityPoolDepositProposal & CommunityPoolWithdrawProposal
used the vanilla community pool fee pool. this commit updates them both
to use the new x/community module account.

* spec formatting update

* add x/community & x/kavamint to internal testnet genesis

* increase test coverage of x/kavamint

* increase test coverage of x/community

* use string type for sdk.Dec proto fields; disable generation of getters
for genesis and params (and other store objects)

* follow sdk conventions for params endpoint naming

* add kavamint to swagger; update swagger & proto docs

* remove legacy querier; touch up module to match others

* reduce max minting rate; refactor genesis to allow nil/zero block time;
repace proto stringers and remove getters; keep sdk.Dec values strings
in protos; increase validation of sdk.Dec values in params; increase
coverage; add module account permission checks; ensure import and export
of genesis does not change state

* fix scaling of rate values -- should be yearly rates

* revert key change

* fix typo in test name

* fix regression in running tests -- rename method

Co-authored-by: Nick DeLuca <nickdeluca08@gmail.com>
2022-12-09 13:24:35 -08:00

46 lines
3.2 KiB
Markdown

<!--
order: 1
-->
# Concepts
## Singular Source of Inflation
The kavamint module mints new tokens each block. How many tokens are minted is determined by rates set in kavamint's parameters. Where the newly minted tokens are transferred to is dictated by which parameter. The kavamint module supports minting for the following purposes:
| Purpose | Parameter | Rate Based On | Transferred To |
| --------------- | ------------------------ | ----------------------- | --------------- |
| Community Pool | `CommunityPoolInflation` | TotalSupply | x/community |
| Staking Rewards | `StakingRewardsApy` | TotalSupply*BondedRatio | x/auth fee pool |
`TotalSupply` is the total number of tokens. `BondedRatio` is the percentage of those tokens that are delegated to a bonded validator.
### How Amount is Calculated
The number of seconds since the previous block is determined: `secondsSinceLastBlock`.
For each yearly rate set in the parameters, an equivalent rate for the number of seconds passed is determined assuming the rate compounds every second and, for simplicity, there are a fixed number of seconds per year (`365 x 24 x 60 x 60 = 31,536,000`). The rate compounded over `secondsSinceLastBlock` seconds is the `31,536,000`th root of `rate + 1` to the `secondsSinceLastBlock` power (minus 100% to determine number of new tokens). This number is truncated to an `sdk.Int`.
**example**:
Assume `CommunityPoolInflation` is 20%, the `TotalSupply` is 1e10 tokens and `secondsSinceLastBlock` is 5 seconds. The number of tokens minted is determined to be 289 tokens.
```math
({\sqrt[secondsPerYear]{1 + CommunityPoolInflation}}^{secondsSinceLastBlock} - 1)*TotalSupply
= ({\sqrt[31,536,000]{1.2}}^{5} - 1)*1e10
\approx 289
```
## Staking Reward Distribution
It helps to understand how newly minted tokens are created and distributed as validator rewards by default in a Cosmos SDK blockchain. In the standard Cosmos SDK mint module, tokens are minted each block based on a variable inflation rate determined by the parameters and the desired bonded token ratio. The tokens are then transferred to the auth module's fee pool to be distributed as staking rewards after a portion of the total fee pool is transferred to the community pool (determined by the CommunityTax parameter of the distribution module).
The kavamint module separates the default community pool inflation from staking rewards. For staking rewards, it uses an APY determined by StakingRewardsApy. The basis is the total bonded tokens. The tokens are distributed to the same fee pool as above so they can be distributed as rewards to delegators with the default distribution module.
## Community Pool Inflation
Every block, tokens are distributed to KAVA's community pool, the module account of x/community. The number of tokens distributed is determined by the total supply.
## Disabling Default Inflation
The intention of this module is to replace the default minting of the x/mint module. To make that the case, the minimum and maximum inflation parameters of the mint module should be set to 0. Additionally, it's recommended that the community tax parameter of the distribution module should be set to 0 as the logic for funding the community pool is controlled by kavamint.