docs: several changes to the ICS docs (#2163)

* update FAQ * update overview * deprecate technical spec * clean up terminology * adding new fields to ConsumerAdditionProposal * update home cards * update docs to remove tips * coderabbitai suggestions * fix broken link * Update docs/docs/features/democracy-modules.md Co-authored-by: Philip Offtermatt <[email protected]> * Update docs/docs/frequently-asked-questions.md Co-authored-by: Philip Offtermatt <[email protected]> * Update docs/docs/validators/partial-set-security-for-validators.md Co-authored-by: Philip Offtermatt <[email protected]> * Update docs/docs/validators/partial-set-security-for-validators.md Co-authored-by: Philip Offtermatt <[email protected]> --------- Co-authored-by: Philip Offtermatt <[email protected]>
cosmos · Aug 23, 2024 · 5028765 · 5028765
1 parent e462a46
commit 5028765
Show file tree

Hide file tree

Showing 14 changed files with 352 additions and 364 deletions.
diff --git a/docs/docs/consumer-development/onboarding.md b/docs/docs/consumer-development/onboarding.md
@@ -119,7 +119,11 @@ Example of a consumer chain addition proposal.
     // the consumer chain.
     "allowlist": [],
     // Corresponds to a list of provider consensus addresses of validators that CANNOT validate the consumer chain.
-    "denylist": []
+    "denylist": [],
+    // Corresponds to the minimal amount of (provider chain) stake required to validate on the consumer chain.
+    "min_stake": 0,
+    // Corresponds to whether inactive validators are allowed to validate the consumer chain.
+    "allow_inactive_vals": false
 }
 ```
 

diff --git a/docs/docs/features/democracy-modules.md b/docs/docs/features/democracy-modules.md
@@ -6,7 +6,7 @@ sidebar_position: 5
 
 This section is relevant for chains transitioning from a standalone chain and new consumer chains that require some functionality from the `x/staking` module.
 
-The democracy modules comprise `x/staking`, `x/distribution` and `x/governance` with overrides and extensions required for normal operation when participating in interchain security.
+The democracy modules comprise `x/staking`, `x/distribution` and `x/governance` with overrides and extensions required for normal operation when participating in ICS.
 
 The modules are plug-and-play and only require small wiring changes to be enabled.
 
@@ -16,40 +16,30 @@ For a full integration check the `consumer-democracy` [example app](https://gith
 
 The democracy staking module allows the cosmos-sdk `x/staking` module to be used alongside the interchain security `consumer` module.
 
-The module uses overrides that allow the full `x/staking` functionality with one notable difference - the staking module will no longer be used to provide the consensus validator set.
+The module uses overrides that allow the full `x/staking` functionality with one notable difference - the staking module will no longer be used to provide the validator set to the consensus engine.
 
 ### Implications for consumer chains
 
-The `x/ccv/democracy/staking` allows consumer chains to separate governance from block production.
-
-:::info
+The `x/ccv/democracy/staking` allows consumer chains to **_separate governance from block production_**.
 The validator set coming from the provider chain does not need to participate in governance - they only provide infrastructure (create blocks and maintain consensus).
-:::
 
 #### Governators (aka. Governors)
 
-Validators registered with the `x/staking` module become "Governators".
-
-Unlike Validators, Governators are not required to run any chain infastructure since they are not signing any blocks.
-
-However, Governators retain a subset of the validator properties:
+Validators registered with the `x/staking` module become __Governators__.
+Unlike validators, governators are not required to run any chain infrastructure since they are not signing any blocks.
+However, governators retain a subset of the validator properties:
 
-- new Governators can be created (via `MsgCreateValidator`)
-- Governators can accept delegations
-- Governators can vote on governance proposals (with their self stake and delegations)
-- Governators earn token rewards
+- new governators can be created (via `MsgCreateValidator`)
+- governators can accept delegations
+- governators can vote on governance proposals (with their self stake and delegations)
+- governators earn block rewards -- the block rewards kept on the consumer (see the [ConsumerRedistributionFraction param](../introduction/params.md#consumerredistributionfraction)) are distributed to all governators and their delegators.
 
-With these changes, Governators can become community advocates that can specialize in chain governance and they get rewarded for their participation the same way the validators do.
-
-Additionally, Governators can choose to provide additional infrastructure such as RPC/API access points, archive nodes, indexers and similar software.
+With these changes, governators can become community advocates that can specialize in chain governance and they get rewarded for their participation the same way the validators do.
+Additionally, governators can choose to provide additional infrastructure such as RPC/API access points, archive nodes, indexers and similar software.
 
 #### Tokenomics
 
-The consumer chain's token will remain a governance and reward token. The token's parameters (inflation, max supply, burn rate) are not affected.
-
-:::info
-Staking rewards are distributed to all Governators and their delegators after distributing the rewards to the provider chain's validator set.
-:::
+The consumer chain's token will remain a governance token. The token's parameters (inflation, max supply, burn rate) are completely under the control of the consumer chain.
 
 ### Integration
 
@@ -82,7 +72,7 @@ To integrate the `democracy/staking` follow this guide:
 
 #### 1. confirm that no modules are returning validator updates
 
-:::tip
+:::warning
 Only the `x/ccv/consumer` module should be returning validator updates.
 :::
 
@@ -231,12 +221,8 @@ func NewApp(...) {
 ## Governance
 
 The `x/ccv/democracy/governance` module extends the `x/governance` module with the functionality to filter proposals.
-
-:::tip
-Consumer chains can limit in the types of governance proposals that can be executed on chain to avoid inadvertent changes to interchain security protocol that could affect security properties.
-:::
-
 The module uses `AnteHandler` to limit the types of proposals that can be executed.
+As a result, consumer chains can limit the types of governance proposals that can be executed on chain to avoid inadvertent changes to the ICS protocol that could affect security properties.
 
 ### Integration
 
@@ -453,23 +439,14 @@ func NewApp(...) {
 
 ## Distribution
 
-:::tip
-The `democracy/distribution` module allows the consumer chain to send rewards to the provider chain while retaining the `x/distribution` module for internal reward distribution to Governators and stakers.
-:::
+The `democracy/distribution` module allows the consumer chain to send rewards to the provider chain while retaining the logic of the `x/distribution` module for internal reward distribution to governators and their delegators.
 
 ### How it works
 
-First, a % of rewards to be distributed to the provider chain's validator set is calculated and sent to the provider chain. Only opted-in validators from the provider chain will receive the consumer rewards.
-
-Second, the remaining rewards get distributed to the consumer chain's Governators and their delegators.
-
-:::info
-The % that is sent to the provider chain corresponds to `1 - ConsumerRedistributionFraction`.
-
-e.g. `ConsumerRedistributionFraction = "0.75"`
-
-means that the consumer chain retains 75% of the rewards, while 25% gets sent to the provider chain to be distributed as rewards to provider chain validators.
-:::
+First, a percentage of the block rewards is sent to the provider chain, where is distributed only to opted-in validators and their delegators. 
+Second, the remaining rewards get distributed to the consumer chain's governators and their delegators.
+The percentage that is sent to the provider chain corresponds to `1 - ConsumerRedistributionFraction`.
+For example, `ConsumerRedistributionFraction = "0.75"` means that the consumer chain retains 75% of the rewards, while 25% gets sent to the provider chain
 
 ### Integration
 

diff --git a/docs/docs/features/key-assignment.md b/docs/docs/features/key-assignment.md
@@ -11,23 +11,22 @@ The feature is outlined in this [ADR-001](../adrs/adr-001-key-assignment.md)
 
 By sending an `AssignConsumerKey` transaction, validators are able to indicate which consensus key they will be using to validate a consumer chain. On receiving the transaction, if the key assignment is valid, the provider will use the assigned consensus key when it sends future voting power updates to the consumer that involve the validator.
 
-:::tip
-Key assignment is handled only by the provider chain - the consumer chains are not aware of the fact that different consensus keys represent the same validator entity.
-:::
+Note that key assignment is handled only by the provider chain - the consumer chains are not aware of the fact that different consensus keys represent the same validator entity.
 
 ## Rules
 
-- a key can be assigned as soon as the consumer addition proposal is submitted to the provider
-- validator A cannot assign consumer key K to consumer chain X if there is already a validator B (B!=A) using K on the provider
-- validator A cannot assign consumer key K to consumer chain X if there is already a validator B using K on X
-- a new validator on the provider cannot use a consensus key K if K is already used by any validator on any consumer chain
-
-:::tip
-Validators can use a different key for each consumer chain.
-:::
+- A key can be assigned as soon as the consumer addition proposal is submitted to the provider.
+- Validator `A` cannot assign consumer key `K` to consumer chain `X` if there is already a validator `B` (`B!=A`) using `K` on the provider.
+- Validator `A` cannot assign consumer key `K` to consumer chain `X` if there is already a validator `B` using `K` on `X`.
+- A new validator on the provider cannot use a consensus key `K` if `K` is already used by any validator on any consumer chain.
 
 ## Adding a key
 
+:::warning
+Validators are strongly recommended to assign a separate key for each consumer chain
+and **not** reuse the provider key across consumer chains for security reasons.
+:::
+
 First, create a new node on the consumer chain using the equivalent:
 
 ```bash
@@ -81,11 +80,6 @@ To change your key, simply repeat all of the steps listed above. Take note that
 
 To remove a key, simply switch it back to the consensus key you have assigned on the provider chain by following steps in the `Adding a key` section and using your provider consensus key.
 
-:::warning
-Validators are strongly recommended to assign a separate key for each consumer chain
-and **not** reuse the provider key across consumer chains for security reasons.
-:::
-
 ## Querying proposed consumer chains
 
 To query the consumer addition proposals that are in the voting period, you can use the following command on the provider:

diff --git a/docs/docs/features/partial-set-security.md b/docs/docs/features/partial-set-security.md
@@ -4,31 +4,21 @@ sidebar_position: 6
 
 # Partial Set Security
 
-Partial Set Security (PSS) is a complete revamp of the Hub's security offering. It allows consumer chains to leverage only a subset of validators from the provider chain, which offers more flexibility than the previous Replicated Security model. By introducing the top_N parameter, each consumer chain can choose the extent of security needed:
+Partial Set Security (PSS) is a complete revamp of the Hub's security offering. It allows consumer chains to leverage only a subset of validators from the provider chain, which offers more flexibility than the previous Replicated Security model. By introducing the `top_N` parameter, each consumer chain can choose the extent of security needed:
 
     * Top N: Requires the top N% validators from the provider chain to secure the consumer chain. This guarantees that the validators with the most power on the provider will validate the consumer chain, while others can voluntarily opt in.
 
     * Opt-In: If the `top_N` parameter is set to zero, no validator is mandated to secure the consumer chain. Instead, any validator from the provider chain can opt in using a dedicated transaction.
 
-An advantage of a Top N chain is that the consumer chain is guaranteed to receive at least a certain fraction of the market cap of the provider chain in security. In turn, this chain needs to be approved by governance, since validators will be forced to run the chain. Thus, Top N chains should typically expect to need to provide a strong case for why they should be added to the provider chain, and they should make sure they offer enough rewards to incentivize validators and delegators to vote for their proposal.
+An advantage of Top N chains is that they are guaranteed to receive at least a certain fraction of the market cap of the provider chain in security. 
+In turn, Top N chains need to be approved by governance, since some validators will be forced to validate on them. 
+Thus, Top N chains should typically expect to need to provide a strong case for why they should be added to the provider chain, and they should make sure they offer enough rewards to incentivize validators and delegators to vote for their proposal.
 
-Opt-In chains, on the other hand, are more flexible. Validators are never forced to validate these chains and simply opt in if they want to. At the moment, opt-in chains still require a governance proposal, but this will be removed in the next release, allowing chains to launch completely permissionlessly. However, opt in chains do not get a fixed amount of security as a relation of the market cap of the provider as top N chains do, so opt in chains might want to keep an eye on how many validators have opted in to validate their chain and adjust their reward emissions accordingly to incentivize validators.
+Opt-In chains, on the other hand, are more flexible. 
+Validators are never forced to validate these chains and simply opt in if they want to. 
+Because of this, Opt-In chains can be **_launch completely permissionlessly_** by sending a transaction to the provider chain. 
+As a trade-off though, Opt-In chains do not get a fixed amount of security as a relation of the market cap of the provider as top N chains do, so Opt-In chains might want to keep an eye on how many validators have opted in to validate their chain and adjust their reward emissions accordingly to incentivize validators.
 
-:::tip
-Partial Set Security is handled only by the provider chain - the consumer chains are simply sent validator sets, and they are not aware that this represents only a subset of the provider chain's validator set.
-:::
-
-:::caution
-
-Top N chains always require a governance proposal because they force the top N
-validators to run the chain.
+Note that Top N consumer chains can become Opt-In chains or vice versa via a [`ConsumerModificationProposal`](./proposals.md#consumermodificationproposal).
 
-As a temporary measure, Opt In chains also require a governance proposal, but this will be removed in the next release, making Opt In chains completely permissionless.
-
-The reason Opt In chains currently require a governance prop is to prevent issues around chain ID squatting, i.e. someone could spuriously register many desirable chain IDs of upcoming consumer chain and simply deny legitimate consumer chains from using them. The plan is to allow launching Opt In chains permissionlessly without going through governance, with quality control being handled by the market of validators deciding which chains they would like to validate on.
-:::
-
-:::tip
-A running Top N consumer chain might want to become an Opt-In chain or vice versa. This can be achieved by issuing
-a [`ConsumerModificationProposal`](./proposals.md#consumermodificationproposal).
-:::
+Partial Set Security is handled only by the provider chain - the consumer chains are simply sent validator sets, and they are not aware that this represents only a subset of the provider chain's validator set.