docs: Add PSS docs (#1859)

* Add params to proposals

* Start rewriting intro

* Finish overview and terminology

* Write up generics about PSS and power shaping

* Add more info about top N and optin

* Nit: apostrophe

* Clarify governance proposal process for Opt In chains

* Apply suggestions from code review

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Add missing newlines

* Update docs/docs/features/partial-set-security.md

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

* Update docs/docs/features/power-shaping.md

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

* Use Interchain Security instead of ICSv2

* docs: Add PSS docs (Part 2) (#1861)

* first version

* first commit

* one more warning on having all validators opt out

* 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]>

* Update docs/docs/validators/partial-set-security-for-validators.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update docs/docs/validators/partial-set-security-for-validators.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/frequently-asked-questions.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update docs/docs/validators/partial-set-security-for-validators.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* took into account some comments

* small comment changes

---------

Co-authored-by: Philip Offtermatt <[email protected]>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Add warning that vals have to manually opt out if going out of top N

* Add short PSS FAQ

* Add FAQ on how many chains vals can opt in on

* Change first to third person

* Fix typo

* Add missing comma

* added a warning

* Add more guidelines to 'how to choose the power shaping parameters'

* Mention list-consumer-chains query

* Add tip about default commission rate

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: insumity <[email protected]>

docs/docs/consumer-development/onboarding.md

@@ -41,12 +41,15 @@ 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
 - [ ] describe the purpose and benefits of running your chain
+- [ ] determine whether your chain should be an Opt-In chain or a Top N chain (see [Partial Set Security](../features/partial-set-security.md))
+- [ ] if desired, decide on power-shaping parameters (see [Power Shaping](../features/power-shaping.md))
 
 Example of a consumer chain addition proposal.
 
 ```js
 // ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain.
-// If it passes, then all validators on the provider chain are expected to validate the consumer chain at spawn time.
+// If it passes, if the top_N parameter is not equal to 0, the top N% of validators by voting power on the provider chain are expected to validate the consumer chain at spawn time.
+// Otherwise, only validators that opted in during the proposal period are expected to validate the consumer chain at spawn time.
 // It is recommended that spawn time occurs after the proposal end time.
 {
     // Title of the proposal
@@ -69,7 +72,7 @@ Example of a consumer chain addition proposal.
     // Hash of the consumer chain binary that should be run by validators on chain initialization.
     // It is used for off-chain confirmation of binary validity by validators and other parties.
     "binary_hash": "376cdbd3a222a3d5c730c9637454cd4dd925e2f9e2e0d0f3702fc922928583f1",
-    // Time on the provider chain at which the consumer chain genesis is finalized and all validators
+    // Time on the provider chain at which the consumer chain genesis is finalized and validators
     // will be responsible for starting their consumer chain validator node.
     "spawn_time": "2023-02-28T20:40:00.000000Z",
     // Unbonding period for the consumer chain.
@@ -97,13 +100,35 @@ Example of a consumer chain addition proposal.
 	// Note that transfer_channel_id is the ID of the channel end on the consumer chain.
     // 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"
+    "distribution_transmission_channel": "channel-123",
+    // 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": []
 }
 ```
 
 ## 4. Launch
 
-The consumer chain starts after at least 66.67% of all provider's voting power comes online. 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
+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 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)
 - [ ] genesis.json with ccv data populated (MUST contain the initial validator set)

docs/docs/features/partial-set-security.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 5
+---
+
+# Partial Set Security
+
+Partial Set Security (PSS) allows consumer chains to leverage only a subset of validators from the provider chain, which offers more flexibility than the traditional 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.
+
+Opt-In chains, on the other hand, are more flexible. While for technical reasons, they are also currently added via governance proposals, since validators are never forced to validate these chains and simply opt in if they want to, they should typically expect to get their proposals approved much more easily compared to Top N chains, since validators that do not want to validate the chain can simply choose not to opt in.
+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.
+
+:::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
+Both Opt In and Top N chains currently require a governance proposal to be added to the provider chain.
+
+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.
+:::

docs/docs/features/power-shaping.md

@@ -0,0 +1,52 @@
+# Power Shaping
+
+To give consumer chains more flexibility in choosing their validator set, Interchain Security offers
+several "power shaping" mechanisms for consumer chains.
+
+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).
+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.
+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%).
+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
+Note that if denylisting is used in a Top N consumer chain, then the chain might not be secured by N% of the total provider's
+power. For example, consider that the top validator `V` on the provider chain has 10% of the voting power, and we have a Top 50% consumer chain,
+then if `V` is denylisted, the consumer chain would only be secured by at least 40% of the provider's power.
+:::
+
+All these mechanisms are set by the consumer chain in the `ConsumerAdditionProposal`. They operate *solely on the provider chain*, meaning the consumer chain simply receives the validator set after these rules have been applied and does not have any knowledge about whether they are applied.
+
+Each of these mechanisms is *set during the consumer addition proposal* (see [Onboarding](../consumer-development/onboarding.md#3-submit-a-governance-proposal)), and is currently *immutable* after the chain has been added.
+
+The values can be seen by querying the list of consumer chains:
+```bash
+interchain-security-pd query provider list-consumer-chains
+```
+
+## Guidelines for setting power shaping parameters
+
+When setting power shaping parameters, please consider the following guidelines:
+* Do not cap the validator set size too low: Notice that this number is the **maximum* number of validators that will ever validate the consumer chain. If this number is too low, the chain will be very limited in the
+amount of stake that secures it. The validator set size cap should only be used if there are strong reasons to prefer fewer validators. Consider that setting the cap will mean that
+even if the whole validator set of the provider wants to validate on the chain, some validators will simply not be able to.
+* Capping the fraction of power any single validator can have is a decent security measure, but it's good to be aware of the interactions with the size of the validator set.
+For example, if there are only 3 validators, and the cap is 20%, this will not be possible (since even splitting the power fairly would mean that each validator has 33% of the power, so is above the cap).
+However, the cap can be a good measure to prevent a single large validator from essentially taking over the chain.
+In general, values under 33% make sense (since a validator that has 33% of the chains power would halt the chain if they go offline).
+Notice that the smaller this value is, the more the original voting power gets distorted, which could discourage large validators from deciding to opt in to the chain.
+* If the allowlist is *empty*, all validators can validate the chain. If it is *non empty*, then *only* validators on the allowlist can validate the chain.
+Thus, an allowlist containing too few validators is a security risk. In particular, consider that if the validators on the allowlist lose a lot of stake or stop being validators,
+an allowlist that is too short can very quickly become outdated and leave too few validators, or validators with too little stake, to secure the chain in a decentralized way.
+* If the denylist is too full, this can likewise be problematic. If too many large validators are denylisted, the chain might not be secured by a large enough fraction of the provider's power, in particular when
+the power distribution on the provider shifts and the denylisted validators gain more power.
+
+In general, when setting these parameters, consider that the voting power distribution in the future might be very different from the one right now,
+and that the chain should be secure even if the power distribution changes significantly.

docs/docs/features/proposals.md

@@ -42,10 +42,13 @@ Minimal example:
     "blocks_per_distribution_transmission": 1000,
     "historical_entries": 10000,
     "genesis_hash": "d86d756e10118e66e6805e9cc476949da2e750098fcc7634fd0cc77f57a0b2b0",
-    "binary_hash": "376cdbd3a222a3d5c730c9637454cd4dd925e2f9e2e0d0f3702fc922928583f1"
-    // relevant for chains performing a standalone to consumer changeover
-    // in order to maintain the existing ibc transfer channel
-    "distribution_transmission_channel": "channel-123"
+    "binary_hash": "376cdbd3a222a3d5c730c9637454cd4dd925e2f9e2e0d0f3702fc922928583f1",
+    "distribution_transmission_channel": "channel-123",
+    "top_N": 95,
+    "validators_power_cap": 0,
+    "validator_set_cap": 0,
+    "allowlist": [],
+    "denylist": []
 }
 ```
 More examples can be found in the interchain security testnet repository [here](https://github.com/cosmos/testnets/blob/master/interchain-security/stopped/baryon-1/proposal-baryon-1.json) and [here](https://github.com/cosmos/testnets/blob/master/interchain-security/stopped/noble-1/start-proposal-noble-1.json).

docs/docs/features/slashing.md

@@ -21,6 +21,9 @@ Instead of slashing, the provider will only jail offending validator for the dur
 [Slash throttling](../adrs/adr-002-throttle.md) (sometimes called jail throttling) mechanism ensures that only a fraction of the validator set can be jailed at any one time to prevent malicious consumer chains from harming the provider.
 :::
 
+Note that validators are only jailed for downtime on consumer chains that they opted-in to validate on,
+or in the case of Top N chains, where they are automatically opted in by being in the Top N% of the validator set on the provider.
+
 ## Equivocation Infractions
 
 Equivocation infractions are reported by external agents (e.g., relayers) that can submit to the provider evidence of light client or double signing attacks observed on a consumer chain.