docs: update docs for reward denom change (#1489)

* update docs on reward distribution * sovereign -> standalone * typo * add example of denom-hash query * Update docs/docs/features/reward-distribution.md Co-authored-by: Philip Offtermatt <[email protected]> * Update docs/docs/features/reward-distribution.md Co-authored-by: Philip Offtermatt <[email protected]> * Update docs/docs/features/reward-distribution.md Co-authored-by: Philip Offtermatt <[email protected]> * Update docs/docs/features/proposals.md Co-authored-by: Philip Offtermatt <[email protected]> * Update docs/docs/features/reward-distribution.md Co-authored-by: Philip Offtermatt <[email protected]> --------- Co-authored-by: Philip Offtermatt <[email protected]>
cosmos · Dec 15, 2023 · f1a6129 · f1a6129
1 parent ebf0620
commit f1a6129
Show file tree

Hide file tree

Showing 6 changed files with 98 additions and 52 deletions.
diff --git a/docs/docs/consumer-development/onboarding.md b/docs/docs/consumer-development/onboarding.md
@@ -95,7 +95,7 @@ Example of a consumer chain addition proposal.
 	// sub-protocol. If DistributionTransmissionChannel == "", a new transfer
 	// channel is created on top of the same connection as the CCV channel.
 	// Note that transfer_channel_id is the ID of the channel end on the consumer chain.
-    // it is most relevant for chains performing a sovereign to consumer changeover
+    // it is most relevant for chains performing a standalone to consumer changeover
     // in order to maintain the existing ibc transfer channel
     "distribution_transmission_channel": "channel-123"
 }

diff --git a/docs/docs/features/proposals.md b/docs/docs/features/proposals.md
@@ -43,7 +43,7 @@ Minimal example:
     "historical_entries": 10000,
     "genesis_hash": "d86d756e10118e66e6805e9cc476949da2e750098fcc7634fd0cc77f57a0b2b0",
     "binary_hash": "376cdbd3a222a3d5c730c9637454cd4dd925e2f9e2e0d0f3702fc922928583f1"
-    // relevant for chains performing a sovereign to consumer changeover
+    // relevant for chains performing a standalone to consumer changeover
     // in order to maintain the existing ibc transfer channel
     "distribution_transmission_channel": "channel-123"
 }
@@ -75,18 +75,38 @@ Minimal example:
 ```
 
 ## ChangeRewardDenomProposal
-:::tip
-`ChangeRewardDenomProposal` will only be accepted on the provider chain if at least one of the denomsToAdd or denomsToRemove fields is populated with at least one denom. Also, a denom cannot be repeated in both sets.
-:::
 
 Proposal type used to mutate the set of denoms accepted by the provider as rewards.
 
+:::tip
+A `ChangeRewardDenomProposal` will only be accepted on the provider chain if at least one of the `denomsToAdd` or `denomsToRemove` fields is populated with at least one denom. Also, a denom cannot be repeated in both sets.
+:::
+
 Minimal example:
 ```js
+{
+  "title": "Add uatom as a reward denom",
+  "description": "Here is more information about the proposal",
+  "denomsToAdd": ["uatom"],
+  "denomsToRemove": []
+}
+```
+
+:::tip
+Besides native provider denoms (e.g., `uatom` for the Cosmos Hub), please use the `ibc/*` denom trace format.
+For example, for `untrn` transfered over the path `transfer/channel-569`, the denom trace 
+can be queried using the following command:
+```bash
+> gaiad query ibc-transfer denom-hash transfer/channel-569/untrn
+hash: 0025F8A87464A471E66B234C4F93AEC5B4DA3D42D7986451A059273426290DD5
+```
+Then use the resulting hash in the `ChangeRewardDenomProposal`, e.g., 
+```js
 {
   "title": "Add untrn as a reward denom",
   "description": "Here is more information about the proposal",
-  "denomsToAdd": ["untrn"],
+  "denomsToAdd": ["ibc/0025F8A87464A471E66B234C4F93AEC5B4DA3D42D7986451A059273426290DD5"],
   "denomsToRemove": []
 }
 ```
+:::
diff --git a/docs/docs/features/reward-distribution.md b/docs/docs/features/reward-distribution.md
@@ -3,55 +3,45 @@ sidebar_position: 2
 ---
 
 
-# Reward distribution
-Consumer chains have the option of sharing their block rewards (inflation tokens) and fees with provider chain validators and delegators.
-In replicated security block rewards and fees are periodically sent from the consumer to the provider according to consumer chain parameters using an IBC transfer channel that gets created during consumer chain initialization.
+# Reward Distribution
 
-Reward distribution on the provider is handled by the distribution module - validators and delegators receive a fraction of the consumer chain tokens as staking rewards.
-The distributed reward tokens are IBC tokens and therefore cannot be staked on the provider chain.
+Sending and distributing rewards from consumer chains to the provider chain is handled by the [Reward Distribution sub-protocol](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md#reward-distribution).
 
-Sending and distributing rewards from consumer chains to provider chain is handled by the `Reward Distribution` sub-protocol.
-
-## Note
-The ICS distribution system works by allowing consumer chains to send rewards to a module address on the provider called the `ConsumerRewardsPool`.
-There is a new transaction type called `RegisterConsumerRewardDenom`. This transaction allows consumer chains to register denoms to be used as consumer chain rewards on the provider.
-The cost to register a denom is configurable (`ConsumerRewardDenomRegistrationFee` chain param) and the full amount of this fee is transferred to the community pool of the provider chain. Only denoms registered through this transaction are then transferred from the `ConsumerRewardsPool` to the `FeePoolAddress`, to be distributed out to delegators and validators.
-
-### Instructions for adding a denom
-The transaction must be carried out on the provider chain. Please use the `ibc/*` denom trace format.
+Consumer chains have the option of sharing (a portion of) their block rewards (inflation tokens and fees) with the provider chain validators and delegators.
+In replicated security, block rewards are periodically sent from the consumer to the provider according to consumer chain parameters using an IBC transfer channel. 
+This channel is created during consumer chain initialization, unless it is provided via the `ConsumerAdditionProposal` when adding a new consumer chain. 
+For more details, see the [reward distribution parameters](../introduction/params.md#reward-distribution-parameters). 
 
 :::tip
-```
-# reward denoms must be registered on the provider chain (gaia in this example)
-gaiad tx provider register-consumer-reward-denom ibc/3C3D7B3BE4ECC85A0E5B52A3AEC3B7DFC2AA9CA47C37821E57020D6807043BE9 --from mykey
-```
+Providing an IBC transfer channel (see `DistributionTransmissionChannel`) enables a consumer chain to re-use one of the existing channels to the provider for consumer chain rewards distribution. This will preserve the `ibc denom` that may already be in use. 
+This is especially important for standalone chains transitioning to become consumer chains. 
+For more details, see the [changeover procedure](../consumer-development/changeover-procedure.md).
 :::
 
-## Parameters
-:::tip
-The following chain parameters dictate consumer chain distribution amount and frequency.
-They are set at consumer genesis and `blocks_per_distribution_transmission`, `consumer_redistribution_fraction`
-`transfer_timeout_period` must be provided in every `ConsumerChainAddition` proposal.
-:::
+Reward distribution on the provider is handled by the distribution module.
 
+## Whitelisting Reward Denoms
 
-### `consumer_redistribution_fraction`
-The fraction of tokens allocated to the consumer redistribution address during distribution events. The fraction is a string representing a decimal number. For example "0.75" would represent 75%.
+The ICS distribution system works by allowing consumer chains to send rewards to a module address on the provider called the `ConsumerRewardsPool`.
+To avoid spam, the provider must whitelist denoms before accepting them as ICS rewards. 
+Only whitelisted denoms are transferred from the `ConsumerRewardsPool` to the `FeePoolAddress`, to be distributed to delegators and validators.
+The whitelisted denoms can be adjusted through governance by sending a [`ChangeRewardDenomProposal`](./proposals.md#changerewarddenomproposal). 
+
+To query the list of whitelisted reward denoms on the Cosmos Hub, use the following command:
+```bash
+> gaiad q provider registered-consumer-reward-denoms
+denoms:
+- ibc/0025F8A87464A471E66B234C4F93AEC5B4DA3D42D7986451A059273426290DD5
+- ibc/6B8A3F5C2AD51CD6171FA41A7E8C35AD594AB69226438DB94450436EA57B3A89
+- uatom
+```
 
 :::tip
-Example:
-
-With `consumer_redistribution_fraction` set to `0.75` the consumer chain would send 75% of its block rewards and accumulated fees to the consumer redistribution address, and the remaining 25% to the provider chain every `n` blocks where `n == blocks_per_distribution_transmission`.
-:::
-
-### `blocks_per_distribution_transmission`
-The number of blocks between IBC token transfers from the consumer chain to the provider chain.
-
-### `transfer_timeout_period`
-Timeout period for consumer chain reward distribution IBC packets.
-
-### `distribution_transmission_channel`
-Provider chain IBC channel used for receiving consumer chain reward distribution token transfers. This is automatically set during the consumer-provider handshake procedure.
-
-### `provider_fee_pool_addr_str`
-Provider chain fee pool address used for receiving consumer chain reward distribution token transfers. This is automatically set during the consumer-provider handshake procedure.
+Use the following command to get a human readable denom from the `ibc/*` denom trace format:
+```bash
+>  gaiad query ibc-transfer denom-trace ibc/0025F8A87464A471E66B234C4F93AEC5B4DA3D42D7986451A059273426290DD5
+denom_trace:
+  base_denom: untrn
+  path: transfer/channel-569
+```
+:::
diff --git a/docs/docs/frequently-asked-questions.md b/docs/docs/frequently-asked-questions.md
@@ -50,10 +50,10 @@ The only thing that separates consumer chains from standalone chains is that the
 
 ## What's in it for the validators and stakers?
 
-The consumer chains sends a portion of its fees and inflation as reward to the provider chain as defined by `consumer_redistribution_fraction`. The rewards are distributed (sent to the provider) every `blocks_per_distribution_transmission`.
+The consumer chains sends a portion of its fees and inflation as reward to the provider chain as defined by `ConsumerRedistributionFraction`. The rewards are distributed (sent to the provider) every `BlocksPerDistributionTransmission`.
 
 :::note
-  `consumer_redistribution_fraction` and `blocks_per_distribution_transmission` are parameters defined in the `ConsumerAdditionProposal` used to create the consumer chain. These parameters can be changed via consumer chain governance.
+  `ConsumerRedistributionFraction` and `BlocksPerDistributionTransmission` are parameters defined in the `ConsumerAdditionProposal` used to create the consumer chain. These parameters can be changed via consumer chain governance.
 :::
 
 ## Can the consumer chain have its own governance?

diff --git a/docs/docs/introduction/params.md b/docs/docs/introduction/params.md
@@ -9,7 +9,7 @@ The parameters necessary for Interchain Security (ICS) are defined in
 - the `Params` structure in `proto/interchain_security/ccv/provider/v1/provider.proto` for the provider;
 - the `Params` structure in `proto/interchain_security/ccv/consumer/v1/consumer.proto` for the consumer.
 
-## Time-based parameters
+## Time-Based Parameters
 
 ICS relies on the following time-based parameters.
 
@@ -87,6 +87,42 @@ If this timeout expires, then the transfer is attempted again after `BlocksPerDi
 - `TransferPeriodTimeout` should be smaller than `BlocksPerDistributionTransmission x avg_block_time`
 
 
+## Reward Distribution Parameters
+
+:::tip
+The following chain parameters dictate consumer chain distribution amount and frequency.
+They are set at consumer genesis and `BlocksPerDistributionTransmission`, `ConsumerRedistributionFraction`
+`TransferTimeoutPeriod` must be provided in every `ConsumerChainAddition` proposal.
+:::
+
+
+### ConsumerRedistributionFraction
+
+`ConsumerRedistributionFraction` is the fraction of tokens allocated to the consumer redistribution address during distribution events. The fraction is a string representing a decimal number. For example `"0.75"` would represent `75%`.
+
+:::tip
+Example:
+
+With `ConsumerRedistributionFraction` set to `"0.75"` the consumer chain would send `75%` of its block rewards and accumulated fees to the consumer redistribution address, and the remaining `25%` to the provider chain every `BlocksPerDistributionTransmission` blocks.
+:::
+
+### BlocksPerDistributionTransmission
+
+`BlocksPerDistributionTransmission` is the number of blocks between IBC token transfers from the consumer chain to the provider chain.
+
+### TransferTimeoutPeriod
+
+`TransferTimeoutPeriod` is the timeout period for consumer chain reward distribution IBC packets.
+
+### DistributionTransmissionChannel
+
+`DistributionTransmissionChannel` is the provider chain IBC channel used for receiving consumer chain reward distribution token transfers. This is automatically set during the consumer-provider handshake procedure.
+
+### ProviderFeePoolAddrStr
+
+`ProviderFeePoolAddrStr` is the provider chain fee pool address used for receiving consumer chain reward distribution token transfers. This is automatically set during the consumer-provider handshake procedure.
+
+
 ## Slash Throttle Parameters
 
 ### SlashMeterReplenishPeriod

diff --git a/docs/docs/validators/changeover-procedure.md b/docs/docs/validators/changeover-procedure.md
@@ -2,7 +2,7 @@
 sidebar_position: 4
 ---
 
-# Validator instructions for Changeover Procedure
+# Validator Instructions for Changeover Procedure
 
 More details available in [Changeover Procedure documentation](../consumer-development/changeover-procedure.md).