docs: Minor improvements (backport #1882) (#1885)

docs: Minor improvements (#1882) * Fix typo in tip * Minor improvements around commission rate * Mention soft opt-out * Link to normal consumer addition prop * Remove confusing line from changeover prop * Remove instructions about not assigning keys * Clarify starting condition for top N chains * Incorporate comments * Update docs/docs/validators/joining-testnet.md Co-authored-by: insumity <[email protected]> * Reformulate opting out --------- Co-authored-by: insumity <[email protected]> (cherry picked from commit 0b24c30) Co-authored-by: Philip Offtermatt <[email protected]>
cosmos · May 16, 2024 · 1d00458 · 1d00458
1 parent 3e0dd07
commit 1d00458
Show file tree

Hide file tree

Showing 10 changed files with 44 additions and 22 deletions.
diff --git a/docs/docs/consumer-development/app-integration.md b/docs/docs/consumer-development/app-integration.md
@@ -28,5 +28,6 @@ This allows the consumer chain to leverage those modules while also using the `x
 With these modules enabled, the consumer chain can mint its own governance tokens, which can then be delegated to prominent community members which are referred to as "representatives" (as opposed to "validators" in standalone chains). The token may have different use cases besides just voting on governance proposals.
 
 ## Standalone chain to consumer chain changeover
-This feature is being actively worked on. Information will be provided at a later time.
+
+See the [standalone chain to consumer chain changeover guide](./changeover-procedure.md) for more information on how to transition your standalone chain to a consumer chain.
 
diff --git a/docs/docs/consumer-development/changeover-procedure.md b/docs/docs/consumer-development/changeover-procedure.md
@@ -150,7 +150,7 @@ Additionally, reach out to the community via the [forum](https://forum.cosmos.ne
 - [ ] determine consumer chain parameters to be put in the proposal
 - [ ] take note to include a link to your onboarding repository
 
-Example of a consumer chain addition proposal.
+Example of a consumer chain addition proposal (compare with the [ConsumerAdditionProposal](./onboarding.md#3-submit-a-governance-proposal) in the ICS Provider Proposals section for chains that *launch* as consumers):
 
 ```js
 // ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain or add a standalone chain.
@@ -167,7 +167,6 @@ Example of a consumer chain addition proposal.
     // Must be unique from all other consumer chain ids of the executing provider chain.
     "chain_id": "standalone-1",
     // Initial height of new consumer chain.
-    // For a completely new chain, this will be {0,1}.
     "initial_height" : {
         // must correspond to current revision number of standalone chain
         // e.g. standalone-1 => "revision_number": 1

diff --git a/docs/docs/consumer-development/onboarding.md b/docs/docs/consumer-development/onboarding.md
@@ -125,9 +125,8 @@ Example of a consumer chain addition proposal.
 
 ## 4. Launch
 
-The consumer chain starts after at least 66.67% of its voting power comes online,
-i.e. a Top N chain, the consumer chain starts after at least 66.67% of the `top_N`% of the provider chain's voting power comes online;
-for an Opt-In chain, it starts after 66.67% of the validators that opted-in while the consumer chain was being proposed come online.
+The consumer chain starts after at least 66.67% of its voting power comes online.
+Note that this means 66.67% of the voting power in the *consumer* validator set, which will be comprised of all validators that either opted in to the chain or are part of the top N% of the provider chain (and are thus automatically opted in).
 The consumer chain is considered interchain secured once the appropriate CCV channels are established and the first validator set update is propagated from the provider to the consumer
 
 - [ ] provide a repo with onboarding instructions for validators (it should already be listed in the proposal)

diff --git a/docs/docs/features/key-assignment.md b/docs/docs/features/key-assignment.md
@@ -81,6 +81,11 @@ 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
@@ -24,5 +24,5 @@ Both Opt In and Top N chains currently require a governance proposal to be added
 
 For Top N chains, this is also the long term vision for how they are launched.
 
-For Opt In chains, this is a temporary measure to prevent issues around chain ID squatting. Eventually, 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.
+For Opt In chains, this is a temporary measure 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. Eventually, 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.
 :::
diff --git a/docs/docs/features/power-shaping.md b/docs/docs/features/power-shaping.md
@@ -7,13 +7,21 @@ These are:
 1) **Capping the size of the validator set**: The consumer chain can specify a maximum number of validators it
 wants to have in its validator set. This can be used to limit the number of validators in the set, which can
 be useful for chains that want to have a smaller validator set for faster blocks or lower overhead.
-*Note*: This is only applicable to Opt In chains (chains with Top N = 0).
+:::info
+This is only applicable to Opt In chains (chains with Top N = 0).
+:::
 1) **Capping the fraction of power any single validator can have**: The consumer chain can specify a maximum fraction
 of the total voting power that any single validator in its validator set should have.
-This is a security measure with the intention of making it harder for a single large validator to take over a consumer chain. This mitigates the risk of an Opt In chain with only a few validators being dominated by a validator with a large amount of voting power opting in.
+This is a security measure with the intention of making it harder for a single large validator to take over a consumer chain. This mitigates the risk of an Opt In chain with only a few validators being dominated by a validator with a large amount of stake opting in.
 For example, setting this fraction to e.g. 33% would mean that no single validator can have more than 33% of the total voting power,
 and thus there is no single validator who would stop the chain by going offline.
-Note that this is a soft cap, and the actual power of a validator can exceed this fraction if the validator set is small (e.g. there are only 3 validators and the cap is 20%).
+:::info
+This is a soft cap, and the actual power of a validator can exceed this fraction if the validator set is small (e.g. there are only 3 validators and the cap is 20%).
+:::
+:::info
+Rewards are distributed proportionally to validators with respect to their capped voting power on the consumer,
+not their total voting power on the provider.
+:::
 1) **Allowlist and denylist**: The consumer chain can specify a list of validators that are allowed or disallowed from participating in the validator set. If an allowlist is set, all validators not on the allowlist cannot validate the consumer chain. If a validator is on both lists, the denylist takes precedence, that is, they cannot validate the consumer chain. If neither list is set, all validators are able to validate the consumer chain.
 
 :::warning

diff --git a/docs/docs/features/proposals.md b/docs/docs/features/proposals.md
@@ -77,6 +77,13 @@ Minimal example:
 }
 ```
 
+:::warning
+Before the introduction of Partial Set Security, consumer chains typically included a "soft opt-out mechanism"
+which allows the bottom N% of the provider's validators to not validate the consumer chain, without being jailed for downtime on the provider.
+After the introduction of Partial Set Security, the use of the soft opt-out mechanism is discouraged, and consumer chains are
+encouraged to use the topN parameter to not force validators with little stake to validate the chain.
+:::
+
 ## ChangeRewardDenomProposal
 
 Proposal type used to mutate the set of denoms accepted by the provider as rewards.

diff --git a/docs/docs/frequently-asked-questions.md b/docs/docs/frequently-asked-questions.md
@@ -90,7 +90,7 @@ To become a consumer chain use this [checklist](./consumer-development/onboardin
 
 Currently supported versions:
 
-- Hermes 1.4.1
+- Hermes 1.8.0
 
 ## How does key delegation work in ICS?
 
@@ -117,7 +117,7 @@ Yes, see the [Key Assignment Guide](./features/key-assignment.md) for more infor
 ## Can validators assign a consensus key during the voting period for a consumer-addition proposal if they are not in the top N?
 Yes.
 
-## Can validators opt in to an Opt-in chain after its consumer-addition proposal voting period is over but before the spawn time?
+## Can validators opt in to an Opt-in or Top N chain after its consumer-addition proposal voting period is over but before the spawn time?
 Yes.
 
 ## Can validators opt in to an Opt-in chain after the spawn time if nobody else opted in?
@@ -129,9 +129,3 @@ Yes, the consumer chain will halt with an ERR CONSENSUS FAILURE error after the
 ## Can validators set a commission rate for chains they have not opted in to?
 Yes, and this is useful for validators that are not in the top N% of the provider chain, but might move into the top N% in the future.
 By setting the commission rate ahead of time, they can make sure that they immediately have a commission rate of their choosing as soon as they are in the top N%.
-
-## On how many consumer chains can a validator opt-in at the same time?
-
-There is no limit to the number of consumer chains a validator can opt in to.
-However, some consumer chains may restrict the validators actually getting to validate there, for example consumer chains can set up denylists to stop certain validators from validating there.
-See the [Power Shaping](./features/power-shaping.md) section for more information. 
diff --git a/docs/docs/validators/joining-testnet.md b/docs/docs/validators/joining-testnet.md
@@ -133,7 +133,7 @@ Additional scripts to setup your nodes are available [here](https://github.com/c
 :::tip
 Once you reach the active set on the provider chain, you will be required to validate all available consumer chains.
 
-You can use the same consensus key on all consumer chains, or opt to use a different key on each consumer chain.
+We strongly recommend that you assign a separate key for each consumer chain.
 Check out this [guide](../features/key-assignment.md) to learn more about key assignment in interchain security.
 :::
 

diff --git a/docs/docs/validators/partial-set-security-for-validators.md b/docs/docs/validators/partial-set-security-for-validators.md
@@ -80,7 +80,7 @@ If all validators opt out from an Opt-In chain, the chain will halt with a conse
 :::
 
 ### How to set specific per consumer chain commission rate?
-A validator can choose to set a different commission rate on each of the consumer chains it validates.
+A validator can choose to set a different commission rate on each of the consumer chains.
 This can be done with the following command:
 ```bash
 interchain-security-pd tx provider set-consumer-commission-rate <consumer-chain-id> <commission-rate>
@@ -91,9 +91,18 @@ where
 - `comission-rate` decimal in `[minRate, 1]` where `minRate` corresponds to the minimum commission rate set on the
 provider chain (see `min_commission_rate` in `interchain-security-pd query staking params`).
 
-'''tip
+
 If a validator does not set a commission rate on a consumer chain, the commission rate defaults to their commission rate on the provider chain.
-'''
+
+:::tip
+Validators can set their commission rate even for consumer chains that they are not currently opted in on, and the commission rate will be applied when they opt in. This is particularly useful for Top N chains, where validators might be opted in automatically,
+so validators can set the commission rate in advance.
+:::
+
+:::tip
+If a validator opts out and then back in, this will *not* reset their commission rate back to the default. Instead, their
+set commission rate still applies.
+:::
 
 
 ## Queries