docs: mention PSS in changeover procedure and replace Replicated Secu…

…rity with Interchain Security (backport #1981) (#1986)

docs: mention PSS in changeover procedure and replace Replicated Security with Interchain Security (#1981)

* removed sentence that stated that "no opt-in mechanism available"

* changed replicated security to interchain security

* added PSS info box in the changeover procedure

(cherry picked from commit 590871b)

Co-authored-by: insumity <[email protected]>

docs/docs/adrs/adr-005-cryptographic-equivocation-verification.md

@@ -87,7 +87,7 @@ The application will, in turn, punish the malicious validator through jailing, t
 In the first part of the feature, we introduce a new endpoint: `HandleConsumerMisbehaviour(ctx sdk.Context, misbehaviour ibctmtypes.Misbehaviour)`.
 The main idea is to leverage the current IBC misbehaviour handling and update it to solely jail and slash the validators that
 performed a light client attack. Note that in this context, we assume that chains connected via a light client
-share the same validator set, as is the case with Replicated Security. 
+share a subset of the validator set of the provider.
 
 This endpoint reuses the IBC client libraries to verify that the misbehaviour headers would have fooled the light client.
 Additionally, it’s crucial that the endpoint logic results in the slashing and jailing of validators under the same conditions

docs/docs/adrs/adr-008-throttle-retries.md

@@ -19,7 +19,7 @@ Accepted
 
 For context on why the throttling mechanism exists, see [ADR 002](./adr-002-throttle.md).
 
-Note the terms slash throttling and jail throttling are synonymous, since in replicated security a `SlashPacket` simply jails a validator for downtime infractions.  
+Note the terms slash throttling and jail throttling are synonymous, since in Interchain Security a `SlashPacket` simply jails a validator for downtime infractions.
 
 Currently the throttling mechanism is designed so that provider logic (slash meter, etc.) dictates how many `SlashPackets` can be handled over time. 
 Throttled `SlashPackets` are persisted on the provider, leading to multiple possible issues. Namely:

docs/docs/adrs/adr-010-standalone-changeover.md

@@ -14,7 +14,7 @@ Implemented
 
 ## Context
 
-[Stride](https://github.com/Stride-Labs/stride) will be the first consumer to "changeover" from a standalone cosmos blockchain, to a consumer chain secured by the Cosmos Hub. This document will outline the changes made to the replicated security protocol to support this changeover process.
+[Stride](https://github.com/Stride-Labs/stride) will be the first consumer to "changeover" from a standalone cosmos blockchain, to a consumer chain secured by the Cosmos Hub. This document outlines the changes made to support this changeover process.
 
 ## Decision
 
@@ -26,7 +26,7 @@ The first step in the changeover process is to submit a ConsumerAdditionProposal
 
 Next, the standalone consumer chain runs an upgrade which adds the CCV module, and is properly setup to execute changeover logic.
 
-The consumer upgrade height must be reached after the provider has created the new IBC client. Any replicated security validators who will run the consumer, but are not a part of the sovereign validator set, must sync up a full node before the consumer upgrade height is reached. The disk state of said full node will be used to run the consumer chain after the changeover has completed.
+The consumer upgrade height must be reached after the provider has created the new IBC client. Any Interchain Security validators who will run the consumer, but are not a part of the sovereign validator set, must sync up a full node before the consumer upgrade height is reached. The disk state of said full node will be used to run the consumer chain after the changeover has completed.
 
 The meat of the changeover logic is that the consumer chain validator set is updated to that which was specified by the provider via the queried consumer genesis. Validators which were a part of the old set, but not the new set, are given zero voting power. Once these validator updates are given to Comet, the set is committed, and in effect 2 blocks later (see [FirstConsumerHeight](https://github.com/cosmos/interchain-security/blob/f10e780df182158d95a30f7cf94588b2d0479309/x/ccv/consumer/keeper/changeover.go#L19)).
 

docs/docs/consumer-development/app-integration.md

@@ -10,8 +10,9 @@ To help you on your journey, the ICS team has provided multiple examples of a mi
 
 The source code for the example app can be found [here](https://github.com/cosmos/interchain-security/tree/main/app/consumer).
 
-Please note that consumer chains do not implement the staking module - the validator set is replicated from the provider, meaning that the provider and the consumer use the same validator set and their stake on the provider directly determines their stake on the consumer.
-At present there is no opt-in mechanism available, so all validators of the provider must also validate on the provider chain.
+Please note that consumer chains do not implement the staking module - part of the validator set of the provider is replicated over to the consumer,
+meaning that the consumer uses a subset of provider validator set and the stake of the validators on the provider determines their stake on the consumer.
+Note that after the introduction of [Partial Set Security](../adrs/adr-015-partial-set-security.md), not all the provider validators have to validate a consumer chain (e.g., if `top_N != 100`).
 
 Your chain should import the consumer module from `x/consumer` and register it in the correct places in your `app.go`.
 The `x/consumer` module will allow your chain to communicate with the provider using the ICS protocol. The module handles all IBC communication with the provider, and it is a simple drop-in.

docs/docs/consumer-development/changeover-procedure.md

@@ -4,7 +4,7 @@ sidebar_position: 5
 
 # Changeover Procedure
 
-Chains that were not initially launched as consumers of replicated security can still participate in the protocol and leverage the economic security of the provider chain. The process where a standalone chain transitions to being a replicated consumer chain is called the **changeover procedure** and is part of the interchain security protocol. After the changeover, the new consumer chain will retain all existing state, including the IBC clients, connections and channels already established by the chain.
+Chains that were **not** initially launched as consumers of Interchain Security can still participate in the protocol and leverage the economic security of the provider chain. The process where a standalone chain transitions to being a replicated consumer chain is called the **changeover procedure** and is part of the interchain security protocol. After the changeover, the new consumer chain will retain all existing state, including the IBC clients, connections and channels already established by the chain.
 
 The relevant protocol specifications are available below:
 * [ICS-28 with existing chains](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md#channel-initialization-existing-chains).
@@ -90,7 +90,7 @@ This `ConsumerGenesis` must be available on the standalone chain during the on-c
 
 ### 4. standalone chain upgrade
 
-Performing the on-chain upgrade on the standalone chain will add the `ccv/consumer` module and allow the chain to become a `consumer` of replicated security.
+Performing the on-chain upgrade on the standalone chain will add the `ccv/consumer` module and allow the chain to become a `consumer` of Interchain Security.
 
 :::caution
 The `ConsumerGenesis` must be exported to a file and placed in the correct folder on the standalone chain before the upgrade.
@@ -154,9 +154,9 @@ Example of a consumer chain addition proposal (compare with the [ConsumerAdditio
 
 ```js
 // ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain or add a standalone chain.
-// If it passes, then all validators on the provider chain are expected to validate the consumer chain at spawn time.
-// It is recommended that spawn time occurs after the proposal end time and that it is scheduled to happen before the standalone chain upgrade
-// that sill introduce the ccv module.
+// If it passes, then a subset (i.e., depends on `top_N` and on the power shaping parameters) of validators on the provider chain are expected
+// to validate the consumer chain at spawn time. It is recommended that spawn time occurs after the proposal end time and that it is 
+// scheduled to happen before the standalone chain upgrade that sill introduce the ccv module.
 {
     // Title of the proposal
     "title": "Changeover Standalone chain",
@@ -212,9 +212,34 @@ Example of a consumer chain addition proposal (compare with the [ConsumerAdditio
     // 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"  // NOTE: use existing transfer channel if available
+    // Corresponds to the percentage of validators that have to validate the chain under the Top N case.
+    // For example, 53 corresponds to a Top 53% chain, meaning that the top 53% provider validators by voting power
+    // have to validate the proposed consumer chain. top_N can either be 0 or any value in [50, 100].
+    // A chain can join with top_N == 0 as an Opt In chain, or with top_N ∈ [50, 100] as a Top N chain.
+    "top_N": 95,
+    // Corresponds to the maximum power (percentage-wise) a validator can have on the consumer chain. For instance, if
+    // `validators_power_cap` is set to 32, it means that no validator can have more than 32% of the voting power on the
+    // consumer chain. Note that this might not be feasible. For example, think of a consumer chain with only
+    // 5 validators and with `validators_power_cap` set to 10%. In such a scenario, at least one validator would need
+    // to have more than 20% of the total voting power. Therefore, `validators_power_cap` operates on a best-effort basis.
+    "validators_power_cap": 0,
+    // Corresponds to the maximum number of validators that can validate a consumer chain.
+    // Only applicable to Opt In chains. Setting `validator_set_cap` on a Top N chain is a no-op.
+    "validator_set_cap": 0,
+    // Corresponds to a list of provider consensus addresses of validators that are the ONLY ones that can validate
+    // the consumer chain.
+    "allowlist": [],
+    // Corresponds to a list of provider consensus addresses of validators that CANNOT validate the consumer chain.
+    "denylist": []
 }
 ```
 
+:::info
+As seen in the `ConsumerAdditionProposal` example above, the changeover procedure can be used together with [Partial Set Security](../adrs/adr-015-partial-set-security.md).
+This means, that a standalone chain can choose to only be validated by some of the validators of the provider chain by setting `top_N` appropriately, or by
+additionally setting a validators-power cap, validator-set cap, etc. by using the [power-shaping parameters](../features/power-shaping.md).
+:::
+
 ## 3. Submit an Upgrade Proposal & Prepare for Changeover
 
 This proposal should add the ccv `consumer` module to your chain.

docs/docs/features/reward-distribution.md

@@ -8,7 +8,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 (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. 
+In Interchain 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). 
 

docs/docs/frequently-asked-questions.md

@@ -80,7 +80,7 @@ Consumer chain upgrades are unlikely to impact the provider chain, as long as th
 
 ## How can I connect to the testnets?
 
-Check out the [Joining Replicated Security testnet](./validators/joining-testnet.md) section.
+Check out the [Joining Interchain Security testnet](./validators/joining-testnet.md) section.
 
 ## How do I start using ICS?
 

docs/docs/index.mdx

@@ -10,6 +10,6 @@ import homeCards from '/src/components/Cards/card-data/home-cards';
 
 Welcome to the official Interchain Security module documentation for Cosmos-SDK based chains.
 
-Here you can find information about replicated security, consumer chain development and instructions for validator onboarding.
+Here you can find information about Interchain Security, consumer chain development and instructions for validator onboarding.
 
 <CardSection cards={homeCards} />

docs/docs/introduction/terminology.md

@@ -29,14 +29,14 @@ A protocol built on IBC that allows delegators on a cosmos chain to re-delegate
 ## Consumer Chain
 
 Chain that is secured by the validator set of the provider, instead of its own.
-Replicated security allows the provider chain validator set to validate blocks on the consumer chain.
+Interchain Security allows a subset of the provider chain's validator set to validate blocks on the consumer chain.
 
 ## Standalone Chain
 
-Chain that is secured by its own validator set. This chain does not participate in replicated security.
+Chain that is secured by its own validator set. This chain does not participate in Interchain Security.
 
 Standalone chains may sometimes be called "sovereign" - the terms are synonymous.
 
 ## Changeover Procedure
 
-Chains that were not initially launched as consumers of replicated security can still participate in the protocol and leverage the economic security of the provider chain. The process where a standalone chain transitions to being a replicated consumer chain is called the **changeover procedure** and is part of the interchain security protocol. After the changeover, the new consumer chain will retain all existing state, including the IBC clients, connections and channels already established by the chain.
+Chains that were not initially launched as consumers of Interchain Security can still participate in the protocol and leverage the economic security of the provider chain. The process where a standalone chain transitions to being a replicated consumer chain is called the **changeover procedure** and is part of the interchain security protocol. After the changeover, the new consumer chain will retain all existing state, including the IBC clients, connections and channels already established by the chain.

docs/docs/validators/changeover-procedure.md

@@ -73,16 +73,16 @@ Yes.
 
 Please assign your consensus key as stated above.
 
-### Can I set up a new node to validate the `standalone/consumer` chain after it transitions to replicated security?
+### Can I set up a new node to validate the `standalone/consumer` chain after it transitions to Interchain Security?
 
 Yes.
 
 If you are planning to do this please make sure that the node is synced with `standalone` network and to submit `AssignConsumerKey` tx before `spawn_time`.
 
 
-###  What happens to the `standalone` validator set after it transitions to replicated security?
+###  What happens to the `standalone` validator set after it transitions to Interchain Security?
 
-The `standalone` chain validators will stop being validators after the first 3 blocks are created while using replicated security. The `standalone` validators will become **governors** and still can receive delegations if the `consumer` chain is using the `consumer-democracy` module.
+The `standalone` chain validators will stop being validators after the first 3 blocks are created while using Interchain Security. The `standalone` validators will become **governors** and still can receive delegations if the `consumer` chain is using the `consumer-democracy` module.
 
 **Governors DO NOT VALIDATE BLOCKS**.
 

docs/docs/validators/overview.md

@@ -4,17 +4,22 @@ sidebar_position: 1
 
 # Overview
 :::tip
-We advise that you join the [Replicated Security testnet](https://github.com/cosmos/testnets/tree/master/interchain-security) to gain hands-on experience with running consumer chains.
+We advise that you join the [Interchain Security testnet](https://github.com/cosmos/testnets/tree/master/interchain-security) to gain hands-on experience with running consumer chains.
 :::
 
-At present, replicated security requires all validators of the provider chain (ie. Cosmos Hub) to run validator nodes for all governance-approved consumer chains.
+At present, Interchain Security requires some or all the validators of the provider chain (ie. Cosmos Hub) to run validator nodes for a consumer chain.
+Whether a validator has to run a validator node for a consumer chain depends on whether the consumer chain is a Top N or an
+Opt-In chain and also on the [power-shaping features](../features/power-shaping.md). A validator can use the
+[`has-to-validate` query](./partial-set-security-for-validators.md#which-chains-does-a-validator-have-to-validate)
+to keep track of all the chains it has to validate.
 
-Once a `ConsumerAdditionProposal` passes, validators need to prepare to run the consumer chain binaries (these will be linked in their proposals) and set up validator nodes on governance-approved consumer chains.
 
-Provider chain and consumer chains represent standalone chains that only share the validator set ie. the same validator operators are tasked with running all chains.
+Once a `ConsumerAdditionProposal` passes, relevant validators need to prepare to run the consumer chain binaries (these will be linked in their proposals) and set up validator nodes on governance-approved consumer chains.
+
+Provider chain and consumer chains represent standalone chains that only share part of the validator set.
 
 :::info
-To validate a consumer chain and be eligible for rewards validators are required to be in the active set of the provider chain (first 180 validators for Cosmos Hub).
+To validate a consumer chain and be eligible for rewards, validators are required to be in the active set of the provider chain (first 180 validators for Cosmos Hub).
 :::
 
 ## Startup sequence overview

docs/docs/validators/withdraw_rewards.md

@@ -16,7 +16,7 @@ the actual values of the `NumberOfEpochsToStartReceivingRewards` and `BlocksPerE
 Here are example steps for withdrawing rewards from consumer chains in the provider chain
 
 :::info
-The examples used are from `rs-testnet`, the replicated security persistent testnet.
+The examples used are from `rs-testnet`, the Interchain Security persistent testnet.
 
 Validator operator address: `cosmosvaloper1e5yfpc8l6g4808fclmlyd38tjgxuwshnmjkrq6`
 Self-delegation address: `cosmos1e5yfpc8l6g4808fclmlyd38tjgxuwshn7xzkvf`