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>

docs/docs/frequently-asked-questions.md

@@ -62,22 +62,15 @@ Validators can also be representatives but representatives are not required to r
 
 This feature discerns between validator operators (infrastructure) and governance representatives which further democratizes the ecosystem. This also reduces the pressure on validators to be involved in on-chain governance.
 
-## Can validators opt-out of replicated security?
+## Can validators opt out of validating a consumer chain?
 
-At present, the validators cannot opt-out of validating consumer chains.
+A validator can always opt out from an Opt-In consumer chain.
+A validator can only opt out from a Top N chain if the validator does not belong to the top N% validators.
 
-There are multiple opt-out mechanisms under active research.
+## How does Slashing work?
 
-## How does Equivocation Governance Slashing work?
-
-To avoid potential attacks directed at provider chain validators, a new mechanism was introduced:
-
-When a validator double-signs on the consumer chain, a special type of slash packet is relayed to the provider chain. The provider will store information about the double signing validator and allow a governance proposal to be submitted.
-If the double-signing proposal passes, the offending validator will be slashed on the provider chain and tombstoned. Tombstoning will permanently exclude the validator from the active set of the provider.
-
-:::caution
-An equivocation proposal cannot be submitted for a validator that did not double sign on any of the consumer chains.
-:::
+Validators that perform an equivocation or a light-client attack on a consumer chain are slashed on the provider chain.
+We achieve this by submitting the proof of the equivocation or the light-client attack to the provider chain (see [slashing](features/slashing.md)).
 
 ## Can Consumer Chains perform Software Upgrades?
 
@@ -98,7 +91,6 @@ To become a consumer chain use this [checklist](./consumer-development/onboardin
 Currently supported versions:
 
 - Hermes 1.4.1
-- Support for the CCV module was added to the Go [relayer](https://github.com/cosmos/relayer) in v2.2.0 but v2.4.0 has significant performance fixes which makes it the earliest suggested version to use.
 
 ## How does key delegation work in ICS?
 
@@ -109,3 +101,12 @@ You can check the [Key Assignment Guide](./features/key-assignment.md) for speci
 Partial Set Security allows a provider chain to share only a subset of its validator set with a consumer chain. This subset can be determined by the top N% validators by voting power, or by validators opting in to validate the consumer chain. Partial Set Security allows for flexible tradeoffs between security, decentralization, and the budget a consumer chain spends on rewards to validators.
 
 See the [Partial Set Security](./features/partial-set-security.md) section for more information.
+
+## How does a validator know which consumers chains it has to validate?
+
+In order for a validator to keep track of all the chains it has to validate, the validator can use the
+[`has-to-validate` query](validators/partial-set-security-for-validators.md#which-chains-does-a-validator-have-to-validate).
+
+## How many chains can a validator opt in to?
+
+There is **no** limit in the number of consumers chains a validator can choose to opt in to.

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

@@ -0,0 +1,124 @@
+---
+sidebar_position: 6
+---
+
+# Partial Set Security
+
+[Partial Set Security](../features/partial-set-security.md) allows consumer chains to join as Opt-In or Top N.
+Here, we show how a validator can opt in, opt out, or set a custom commission rate on a consumer chain, as well
+as useful queries that a validator can use to figure out which chains it has to validate, etc.
+
+## Messages
+### How to opt in to a consumer chain?
+
+:::warning
+A validator is automatically opted in to a Top N chain if the validator belongs to the top N% of the validators on the provider chain.
+:::
+
+In a Top N chain, a validator that does not belong to the top N% of the validators on the provider can still choose
+to opt in to a consumer chain. In other words, validators can opt in, in both Opt-In and Top N chains.
+
+A validator can opt in to a consumer chain by issuing the following message:
+```bash
+interchain-security-pd tx provider opt-in <consumer-chain-id> <optional consumer-pub-key>
+```
+
+where
+- `consumer-chain-id` is the string identifier of the consumer chain the validator wants to opt in to;
+- `consumer-pub-key` corresponds to the public key the validator wants to use on the consumer chain, and it has the
+following format `{"@type":"/cosmos.crypto.ed25519.PubKey","key":"<key>"}`.
+
+A validator can opt in to an existing consumer chain that is already running, or to a [proposed](../features/proposals.md)
+consumer chain that is still being voted on. A validator can use the following command to retrieve the currently existing
+consumer chains:
+```bash
+interchain-security-pd query provider list-consumer-chains
+```
+and this command to see the currently proposed consumer chains:
+```bash
+interchain-security-pd query provider list-proposed-consumer-chains
+```
+
+
+:::tip
+By setting the `consumer-pub-key`, a validator can both opt in to a chain and assign a
+public key on a consumer chain. Note that a validator can always [assign](../features/key-assignment.md)
+a new consumer key at a later stage. The key-assignment [rules](../features/key-assignment.md#rules)
+still apply when setting `consumer-pub-key` when opting in.
+:::
+
+:::info
+A validator is only eligible for consumer rewards from a consumer chain if the validator is opted into that chain.
+:::
+
+### How to opt out from a consumer chain?
+A validator can opt out from a consumer by issuing the following message:
+
+```bash
+interchain-security-pd tx provider opt-out <consumer-chain-id>
+```
+where
+- `consumer-chain-id` is the string identifier of the consumer chain.
+
+:::warning
+A validator cannot opt out from a Top N chain if it belongs to the top N% validators of the provider.
+:::
+
+:::warning
+A validator can stop its node on a consumer chain **only** after opting out and confirming through the `has-to-validate`
+query (see [below](./partial-set-security-for-validators.md#which-chains-does-a-validator-have-to-validate)) that it does
+not have to validate the consumer chain any longer.
+:::
+
+:::warning
+If all validators opt out from an Opt-In chain, the chain will halt with a consensus failure upon receiving the VSCPacket with an empty validator set.
+:::
+
+### 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.
+This can be done with the following command:
+```bash
+interchain-security-pd tx provider set-consumer-commission-rate <consumer-chain-id> <commission-rate>
+```
+where
+
+- `consumer-chain-id` is the string identifier of the consumer chain;
+- `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`).
+
+
+## Queries
+Partial Set Security introduces a number of queries to assist validators determine which consumer chains they have to
+validate, their commission rate per chain, etc.
+
+### Which chains does a validator have to validate?
+Naturally, a validator is aware of the Opt-In chains it has to validate because in order to validate an Opt-In chain,
+a validator has to manually opt in to the chain. This is not the case for Top N chains where a validator might be required
+to validate such a chain without explicitly opting in if it belongs to the top N% of the validators on the provider.
+
+We introduce the following query:
+```bash
+interchain-security-pd query provider has-to-validate <provider-validator-address>
+```
+that can be used by validator with `provider-validator-address` address to retrieve the list of chains that it has to validate.
+
+
+:::tip
+As a validator, the list of chains returned by `has-to-validate` is the list of chains you **should** be validating to avoid
+getting jailed for downtime.
+:::
+
+
+### How to get all the opted-in validators on a consumer chain?
+With the following query:
+```bash
+interchain-security-pd query provider consumer-opted-in-validators <consumer-chain-id>
+```
+we can see all the opted-in validators on `consumer-chain-id` that were manually or automatically opted in.
+
+### How can we see the commission rate a validator has set on a consumer chain?
+Using the following query:
+```bash
+interchain-security-pd query provider validator-consumer-commission-rate <consumer-chain-id> <provider-validator-address>
+```
+we retrieve the commission rate set by validator with `provider-validator-address` address on `consumer-chain-id`.