From 84f84c4eeccb1b8bd75f7ab3a394c3b49cd1bc12 Mon Sep 17 00:00:00 2001 From: drklee3 Date: Mon, 30 Oct 2023 16:53:29 -0700 Subject: [PATCH] Update x/community spec (#1764) * Update x/community spec * Update reward details, remove old pool section * Reward parameters typoish Co-authored-by: Robert Pirtle --------- Co-authored-by: Robert Pirtle --- x/community/spec/01_concepts.md | 28 ++++++++++++- x/community/spec/02_state.md | 70 ++++++++++++++++++++++++++++++++- x/community/spec/03_messages.md | 17 +++++--- x/community/spec/04_events.md | 35 +++++++++++++++++ x/community/spec/05_params.md | 13 ++++++ x/community/spec/README.md | 2 +- 6 files changed, 155 insertions(+), 10 deletions(-) create mode 100644 x/community/spec/05_params.md diff --git a/x/community/spec/01_concepts.md b/x/community/spec/01_concepts.md index 34ef842c..8a520410 100644 --- a/x/community/spec/01_concepts.md +++ b/x/community/spec/01_concepts.md @@ -6,8 +6,32 @@ order: 1 ## Community Pool -The x/community module facilitates interactions with the community pool. In a future release, the community pool may be fully replaced by the x/community module account, but for now it is a place to keep things like proposals for interacting with the vanilla cosmos-sdk community pool (a portion of the auth fee pool held by the x/distribution module account). +The x/community module contains the community pool funds and provides proposal +handlers to manage community pool funds. ### Funding -The x/community module account can be funded by any account sending a community/FundCommunityPool message. These funds are not currently used for anything. The module account is also the transitory passthrough account for community pool funds that are deposited/withdrawn to lend via the CommunityPoolLendDepositProposal & CommunityPoolLendWithdrawProposal. +The x/community module account can be funded by any account sending a +community/FundCommunityPool message. These funds may be deposited/withdrawn to +lend via the CommunityPoolLendDepositProposal & +CommunityPoolLendWithdrawProposal. + +### Rewards + +Rewards payout behavior for staking depends on the module parameters, and will +change based on the "switchover" time parameter `upgrade_time_disable_inflation`. + +If the current block is *before* the switchover time and the +`staking_rewards_per_second` parameter is set to 0, no staking rewards will be +paid from the `x/community` module and will continue to come from other modules +such as `x/mint` and `x/distribution`. + +On the first block after the switchover time, the `staking_rewards_per_second` +parameter is updated to reflect the parameter +`upgrade_time_set_staking_rewards_per_second`, and staking rewards are paid out +every block from the community pool, instead of from minted coins from `x/mint` +and `x/kavadist`. The payout is calculated with the `staking_rewards_per_second` +parameter. + +In addition to these payout changes, inflation in `x/mint` and `x/kavadist` is +disabled after the switchover time. diff --git a/x/community/spec/02_state.md b/x/community/spec/02_state.md index d47420ae..14ca2dc3 100644 --- a/x/community/spec/02_state.md +++ b/x/community/spec/02_state.md @@ -4,4 +4,72 @@ order: 2 # State -The x/community module has no state. +## Parameters and Genesis State + +`Params` define the module parameters, containing the information required to +set the current staking rewards per second at a future date. When the +`upgrade_time_disable_inflation` time is reached, `staking_rewards_per_second` +will be set to `upgrade_time_set_staking_rewards_per_second`. + +```protobuf +// Params defines the parameters of the community module. +message Params { + option (gogoproto.equal) = true; + + // upgrade_time_disable_inflation is the time at which to disable mint and kavadist module inflation. + // If set to 0, inflation will be disabled from block 1. + google.protobuf.Timestamp upgrade_time_disable_inflation = 1 [ + (gogoproto.stdtime) = true, + (gogoproto.nullable) = false + ]; + + // staking_rewards_per_second is the amount paid out to delegators each block from the community account + string staking_rewards_per_second = 2 [ + (cosmos_proto.scalar) = "cosmos.Dec", + (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", + (gogoproto.nullable) = false + ]; + + // upgrade_time_set_staking_rewards_per_second is the initial staking_rewards_per_second to set + // and use when the disable inflation time is reached + string upgrade_time_set_staking_rewards_per_second = 3 [ + (cosmos_proto.scalar) = "cosmos.Dec", + (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", + (gogoproto.nullable) = false + ]; +} +``` + +`GenesisState` defines the state that must be persisted when the blockchain +stops/restarts in order for normal function of the module to resume. It contains +the parameters and staking rewards state to keep track of payout between blocks. + +```protobuf +// GenesisState defines the community module's genesis state. +message GenesisState { + // params defines all the paramaters related to commmunity + Params params = 1 [(gogoproto.nullable) = false]; + + // StakingRewardsState stores the internal staking reward data required to + // track staking rewards across blocks + StakingRewardsState staking_rewards_state = 2 [(gogoproto.nullable) = false]; +} + +// StakingRewardsState represents the state of staking reward accumulation between blocks. +message StakingRewardsState { + // last_accumulation_time represents the last block time which rewards where calculated and distributed. + // This may be zero to signal accumulation should start on the next interval. + google.protobuf.Timestamp last_accumulation_time = 1 [ + (gogoproto.stdtime) = true, + (gogoproto.nullable) = false + ]; + + // accumulated_truncation_error represents the sum of previous errors due to truncation on payout + // This value will always be on the interval [0, 1). + string last_truncation_error = 2 [ + (cosmos_proto.scalar) = "cosmos.Dec", + (gogoproto.customtype) = "cosmossdk.io/math.LegacyDec", + (gogoproto.nullable) = false + ]; +} +``` diff --git a/x/community/spec/03_messages.md b/x/community/spec/03_messages.md index 8e332ee2..90ecc05b 100644 --- a/x/community/spec/03_messages.md +++ b/x/community/spec/03_messages.md @@ -6,12 +6,17 @@ order: 3 ## FundCommunityPool -This message sends coins directly from the sender to the community module account. +Send coins directly from the sender to the community module account. The transaction fails if the amount cannot be transferred from the sender to the community module account. -```go -func (k Keeper) FundCommunityPool(ctx sdk.Context, sender sdk.AccAddress, amount sdk.Coins) error { - return k.bankKeeper.SendCoinsFromAccountToModule(ctx, sender, types.ModuleAccountName, amount) -} -``` +https://github.com/Kava-Labs/kava/blob/1d36429fe34cc5829d636d73b7c34751a925791b/proto/kava/community/v1beta1/tx.proto#L21-L30 + +## UpdateParams + +Update module parameters via gov proposal. + +The transaction fails if the message is not submitted through a gov proposal. +The message `authority` must be the x/gov module account address. + +https://github.com/Kava-Labs/kava/blob/1d36429fe34cc5829d636d73b7c34751a925791b/proto/kava/community/v1beta1/tx.proto#L35-L44 diff --git a/x/community/spec/04_events.md b/x/community/spec/04_events.md index 34674507..367693fd 100644 --- a/x/community/spec/04_events.md +++ b/x/community/spec/04_events.md @@ -16,3 +16,38 @@ The community module emits the following events: | message | action | fund_community_pool | | message | sender | {senderAddress} | | message | amount | {amountCoins} | + +## Keeper events + +In addition to handlers events, the bank keeper will produce events when the +following methods are called (or any method which ends up calling them) + +### CheckAndDisableMintAndKavaDistInflation + +```json +{ + "type": "inflation_stop", + "attributes": [ + { + "key": "inflation_disable_time", + "value": "{{RFC3339 formatted time inflation was disabled}}", + "index": true + } + ] +} +``` + +### PayoutAccumulatedStakingRewards + +```json +{ + "type": "staking_rewards_paid", + "attributes": [ + { + "key": "staking_reward_amount", + "value": "{{sdk.Coins being paid to validators}}", + "index": true + } + ] +} +``` diff --git a/x/community/spec/05_params.md b/x/community/spec/05_params.md new file mode 100644 index 00000000..e046e236 --- /dev/null +++ b/x/community/spec/05_params.md @@ -0,0 +1,13 @@ + + +# Parameters + +The community module contains the following parameters: + +| Key | Type | Example | +| ------------------------------------------- | ------------- | ---------------------- | +| upgrade_time_disable_inflation | string (time) | "2023-11-01T00:00:00Z" | +| staking_rewards_per_second | string | "744191" | +| upgrade_time_set_staking_rewards_per_second | string | "0" | diff --git a/x/community/spec/README.md b/x/community/spec/README.md index 92ae1567..16b3a581 100644 --- a/x/community/spec/README.md +++ b/x/community/spec/README.md @@ -16,4 +16,4 @@ parent: ## Abstract -`x/community` is an implementation of a Cosmos SDK Module that provides governance for the community pool of funds controlled by Kava DAO. The community pool is a subaccount of the fee pool held by the x/distribution module. +`x/community` is an implementation of a Cosmos SDK Module that provides governance for the community pool of funds controlled by Kava DAO.