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>
This commit is contained in:
drklee3 2023-10-30 16:53:29 -07:00 committed by GitHub
parent e4a2307a2a
commit 84f84c4eec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 155 additions and 10 deletions

View File

@ -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.

View File

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

View File

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

View File

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

View File

@ -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" |

View File

@ -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.