Update x/community spec (#1764)

* Update x/community spec

* Update reward details, remove old pool section

* Reward parameters typoish

Co-authored-by: Robert Pirtle <Astropirtle@gmail.com>

---------

Co-authored-by: Robert Pirtle <Astropirtle@gmail.com>

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.

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
+  ];
+}
+```

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

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
+    }
+  ]
+}
+```

x/community/spec/05_params.md

@@ -0,0 +1,13 @@
+<!--
+order: 5
+-->
+
+# 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"                    |

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.