From 29666f3d55f3f0b3f95a30e07aa4949298dfdf53 Mon Sep 17 00:00:00 2001 From: mpoke Date: Fri, 8 Dec 2023 11:40:05 +0100 Subject: [PATCH 1/9] update docs on reward distribution --- docs/docs/features/proposals.md | 23 +++++-- docs/docs/features/reward-distribution.md | 74 ++++++++++------------- docs/docs/frequently-asked-questions.md | 4 +- docs/docs/introduction/params.md | 38 +++++++++++- 4 files changed, 90 insertions(+), 49 deletions(-) diff --git a/docs/docs/features/proposals.md b/docs/docs/features/proposals.md index 70077944ea..50d37e176e 100644 --- a/docs/docs/features/proposals.md +++ b/docs/docs/features/proposals.md @@ -75,18 +75,33 @@ 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 +`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`), please use the `ibc/*` denom trace format. +For example, use `ibc/0025F8A87464A471E66B234C4F93AEC5B4DA3D42D7986451A059273426290DD5`, +for `untrn` transferred on the channel `transfer/channel-569`, 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 index 31b3f9e54e..3294da0827 100644 --- 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 provider chain is handled by the `Reward Distribution` sub-protocol. +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). -## 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 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 chain 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 - validators and delegators receive a fraction of the consumer chain tokens as staking rewards. +## 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 out 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 +``` +::: \ No newline at end of file diff --git a/docs/docs/frequently-asked-questions.md b/docs/docs/frequently-asked-questions.md index dc0745807e..ce76e4e24d 100644 --- 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 index 9b89a1d038..5a9e8462c7 100644 --- 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 From 96db60ffcb192091e87f74e4462e9028b294b901 Mon Sep 17 00:00:00 2001 From: mpoke Date: Fri, 8 Dec 2023 11:54:17 +0100 Subject: [PATCH 2/9] sovereign -> standalone --- docs/docs/consumer-development/onboarding.md | 2 +- docs/docs/features/proposals.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/consumer-development/onboarding.md b/docs/docs/consumer-development/onboarding.md index 893af0a3b1..4c417b3a2e 100644 --- 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 index 50d37e176e..35dc2e9ee6 100644 --- 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" } From 615edb58dc8435114eb36791e5601cf23b87374a Mon Sep 17 00:00:00 2001 From: mpoke Date: Fri, 8 Dec 2023 11:57:40 +0100 Subject: [PATCH 3/9] typo --- docs/docs/validators/changeover-procedure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/validators/changeover-procedure.md b/docs/docs/validators/changeover-procedure.md index 4149d9b412..4b21d23cbe 100644 --- 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). From 78f3c9ec81992c7b382c2ecbf74ae3e6890ed37f Mon Sep 17 00:00:00 2001 From: mpoke Date: Fri, 8 Dec 2023 18:37:18 +0100 Subject: [PATCH 4/9] add example of denom-hash query --- docs/docs/features/proposals.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/docs/features/proposals.md b/docs/docs/features/proposals.md index 35dc2e9ee6..93877ec452 100644 --- a/docs/docs/features/proposals.md +++ b/docs/docs/features/proposals.md @@ -93,9 +93,14 @@ Minimal example: ``` :::tip -Besides native provider denoms (e.g., `uatom`), please use the `ibc/*` denom trace format. -For example, use `ibc/0025F8A87464A471E66B234C4F93AEC5B4DA3D42D7986451A059273426290DD5`, -for `untrn` transferred on the channel `transfer/channel-569`, e.g., +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", From e99e0ddd5bcde92f0bcc6df26536c5b10724c326 Mon Sep 17 00:00:00 2001 From: Marius Poke Date: Fri, 8 Dec 2023 18:38:27 +0100 Subject: [PATCH 5/9] Update docs/docs/features/reward-distribution.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> --- docs/docs/features/reward-distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/features/reward-distribution.md b/docs/docs/features/reward-distribution.md index 3294da0827..fdf4e00d57 100644 --- a/docs/docs/features/reward-distribution.md +++ b/docs/docs/features/reward-distribution.md @@ -14,7 +14,7 @@ For more details, see the [reward distribution parameters](../introduction/param :::tip 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 chain transitioning to become consumer chains. +This is especially important for standalone chains transitioning to become consumer chains. For more details, see the [changeover procedure](../consumer-development/changeover-procedure.md). ::: From 5000cdfc195d08fccb5796029f4172e1145c3fdb Mon Sep 17 00:00:00 2001 From: Marius Poke Date: Fri, 8 Dec 2023 18:39:35 +0100 Subject: [PATCH 6/9] Update docs/docs/features/reward-distribution.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> --- docs/docs/features/reward-distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/features/reward-distribution.md b/docs/docs/features/reward-distribution.md index fdf4e00d57..af1adbc302 100644 --- a/docs/docs/features/reward-distribution.md +++ b/docs/docs/features/reward-distribution.md @@ -18,7 +18,7 @@ This is especially important for standalone chains transitioning to become consu For more details, see the [changeover procedure](../consumer-development/changeover-procedure.md). ::: -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. +Reward distribution on the provider is handled by the distribution module. ## Whitelisting Reward Denoms From aaffbad011fc8d258b5b0eed85cfe3d18dbc672a Mon Sep 17 00:00:00 2001 From: Marius Poke Date: Fri, 8 Dec 2023 18:40:10 +0100 Subject: [PATCH 7/9] Update docs/docs/features/reward-distribution.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> --- docs/docs/features/reward-distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/features/reward-distribution.md b/docs/docs/features/reward-distribution.md index af1adbc302..a9beda76cb 100644 --- a/docs/docs/features/reward-distribution.md +++ b/docs/docs/features/reward-distribution.md @@ -7,7 +7,7 @@ sidebar_position: 2 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). -Consumer chains have the option of sharing their block rewards (inflation tokens and fees) with the provider chain validators and delegators. +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). From 7c9d600d8992195adbbf0b115032b0138c201bd0 Mon Sep 17 00:00:00 2001 From: Marius Poke Date: Fri, 8 Dec 2023 18:40:38 +0100 Subject: [PATCH 8/9] Update docs/docs/features/proposals.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> --- docs/docs/features/proposals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/features/proposals.md b/docs/docs/features/proposals.md index 93877ec452..f57029f519 100644 --- a/docs/docs/features/proposals.md +++ b/docs/docs/features/proposals.md @@ -79,7 +79,7 @@ Minimal example: Proposal type used to mutate the set of denoms accepted by the provider as rewards. :::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. +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: From 66be2ca6c0ddf6fb3b4d485fd4754fbb88273ab0 Mon Sep 17 00:00:00 2001 From: Marius Poke Date: Fri, 8 Dec 2023 18:41:10 +0100 Subject: [PATCH 9/9] Update docs/docs/features/reward-distribution.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> --- docs/docs/features/reward-distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/features/reward-distribution.md b/docs/docs/features/reward-distribution.md index a9beda76cb..cc055107c9 100644 --- a/docs/docs/features/reward-distribution.md +++ b/docs/docs/features/reward-distribution.md @@ -24,7 +24,7 @@ Reward distribution on the provider is handled by the distribution module. 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 out to delegators and validators. +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: