diff --git a/docs/docs/frequently-asked-questions.md b/docs/docs/frequently-asked-questions.md index 2da439d693..3fbb6ce104 100644 --- a/docs/docs/frequently-asked-questions.md +++ b/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. \ No newline at end of file diff --git a/docs/docs/validators/partial-set-security-for-validators.md b/docs/docs/validators/partial-set-security-for-validators.md new file mode 100644 index 0000000000..2c5b84b951 --- /dev/null +++ b/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 +``` + +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":""}`. + +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 +``` +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 +``` +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 +``` +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 +``` +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 +``` +we retrieve the commission rate set by validator with `provider-validator-address` address on `consumer-chain-id`. \ No newline at end of file