From 1294f9040481935a91bc50a9af4fb08e31e7c3b8 Mon Sep 17 00:00:00 2001 From: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> Date: Tue, 14 May 2024 15:02:20 +0200 Subject: [PATCH] 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 * Update docs/docs/features/power-shaping.md Co-authored-by: insumity * 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 <57488781+p-offtermatt@users.noreply.github.com> * Update docs/docs/validators/partial-set-security-for-validators.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@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> * Update docs/docs/validators/partial-set-security-for-validators.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> * Update docs/docs/frequently-asked-questions.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> * Update docs/docs/validators/partial-set-security-for-validators.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> * 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 <57488781+p-offtermatt@users.noreply.github.com> 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 --- docs/docs/consumer-development/onboarding.md | 33 +++- docs/docs/features/partial-set-security.md | 28 ++++ docs/docs/features/power-shaping.md | 52 ++++++ docs/docs/features/proposals.md | 11 +- docs/docs/features/slashing.md | 3 + docs/docs/frequently-asked-questions.md | 68 +++++--- docs/docs/introduction/overview.md | 13 +- docs/docs/introduction/terminology.md | 6 +- .../partial-set-security-for-validators.md | 149 ++++++++++++++++++ 9 files changed, 329 insertions(+), 34 deletions(-) create mode 100644 docs/docs/features/partial-set-security.md create mode 100644 docs/docs/features/power-shaping.md create mode 100644 docs/docs/validators/partial-set-security-for-validators.md diff --git a/docs/docs/consumer-development/onboarding.md b/docs/docs/consumer-development/onboarding.md index f4f022c946..703fd56335 100644 --- a/docs/docs/consumer-development/onboarding.md +++ b/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) diff --git a/docs/docs/features/partial-set-security.md b/docs/docs/features/partial-set-security.md new file mode 100644 index 0000000000..6f8cb3897e --- /dev/null +++ b/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. +::: diff --git a/docs/docs/features/power-shaping.md b/docs/docs/features/power-shaping.md new file mode 100644 index 0000000000..44b7582c98 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/docs/features/proposals.md b/docs/docs/features/proposals.md index f2d2e3d4b2..2343f019ae 100644 --- a/docs/docs/features/proposals.md +++ b/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). diff --git a/docs/docs/features/slashing.md b/docs/docs/features/slashing.md index 6db4c3ee0e..718c3cbad0 100644 --- a/docs/docs/features/slashing.md +++ b/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. diff --git a/docs/docs/frequently-asked-questions.md b/docs/docs/frequently-asked-questions.md index ce76e4e24d..e31123a9cf 100644 --- a/docs/docs/frequently-asked-questions.md +++ b/docs/docs/frequently-asked-questions.md @@ -4,13 +4,9 @@ title: "Frequently Asked Questions" slug: /faq --- -## What is the meaning of Validator Set Replication? - -VSR simply means that the same validator set is used to secure both the provider and consumer chains. VSR is ensured through ICS protocol which keeps consumers up to date with the validator set of the provider. - ## What is a consumer chain? -Consumer chain is blockchain operated by the same validator operators as the provider chain. The ICS protocol ensures the validator set replication properties (informs consumer chain about the current state of the validator set on the provider) +Consumer chain is a blockchain operated by (a subset of) the validators of the provider chain. The ICS protocol ensures that the consumer chain gets information about which validators should run it (informs consumer chain about the current state of the validator set and the opted in validators for this consumer chain on the provider). Consumer chains are run on infrastructure (virtual or physical machines) distinct from the provider, have their own configurations and operating requirements. @@ -29,7 +25,7 @@ At the very least, the consumer chain could replace the validator set, remove th ## What happens to provider if consumer is down? Consumer chains do not impact the provider chain. -The ICS protocol is concerned only with validator set replication and the only communication that the provider requires from the consumer is information about validator activity (essentially keeping the provider informed about slash events). +The ICS protocol is concerned only with validator set management, and the only communication that the provider requires from the consumer is information about validator activity (essentially keeping the provider informed about slash events). ## Can I run the provider and consumer chains on the same machine? @@ -66,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? - -At present, the validators cannot opt-out of validating consumer chains. +## Can validators opt out of validating a consumer chain? -There are multiple opt-out mechanisms under active research. +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. -## How does Equivocation Governance Slashing work? +## How does 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? @@ -102,8 +91,47 @@ 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? You can check the [Key Assignment Guide](./features/key-assignment.md) for specific instructions. + +## How does Partial Set Security work? + +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. + +## Can validators assign a consensus keys while a consumer-addition proposal is in voting period? +Yes, see the [Key Assignment Guide](./features/key-assignment.md) for more information. + +## 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? +Yes. + +## Can validators opt in to an Opt-in chain after the spawn time if nobody else opted in? +No, the consumer chain will not be added if nobody opted in by the spawn time. At least one validator, regardless of its voting power, must opt in before the spawn time arrives in order for the chain can start. + +## Can all validators opt out of an Opt-in chain? +Yes, the consumer chain will halt with an ERR CONSENSUS FAILURE error after the opt-out message for the last validator is received. + +## 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/introduction/overview.md b/docs/docs/introduction/overview.md index aba31751e1..b9f870bfab 100644 --- a/docs/docs/introduction/overview.md +++ b/docs/docs/introduction/overview.md @@ -4,16 +4,19 @@ sidebar_position: 1 # Overview :::info -Replicated security (aka interchain security V1) is an open sourced IBC application which allows cosmos blockchains to lease their proof-of-stake security to one another. +Interchain Security is an open sourced IBC application which allows cosmos blockchains to lease their proof-of-stake security to one another.

-Replicated security allows anyone to launch a "consumer" blockchain using the same validator set as the "provider" blockchain by creating a governance proposal. If the proposal is accepted, provider chain validators start validating the consumer chain as well. Consumer chains will therefore inherit the full security and decentralization of the provider. +Interchain Security allows anyone to launch a "consumer" blockchain using a subset, or even the entire, validator set from the "provider" blockchain by creating a governance proposal. If the proposal is accepted, provider chain validators start validating the consumer chain as well. Consumer chains will therefore inherit security and decentralization from the provider. ::: -## Why Replicated Security? -- Full provider security. At launch, consumer chains are secured by the full validator set and market cap of the provider chain. + + +## Why Interchain Security? + +- The right amount of security for each application. Consumer chains can choose to inherit the whole validator set from the provider, or they can launch as an opt in chain where only a subset of the provider validators validate the consumer chain. This allows for a wide range of security tradeoffs. - Independent block-space. Transactions on consumer chains do not compete with any other applications. This means that there will be no unexpected congestion, and performance will generally be much better than on a shared smart contract platform such as Ethereum. - Projects keep majority of gas fees. Depending on configuration, these fees either go to the project’s community DAO, or can be used in the protocol in other ways. -- No validator search. Consumer chains do not have their own validator sets, and so do not need to find validators one by one. A governance vote will take place for a chain to get adopted by the provider validators which will encourage participation and signal strong buy-in into the project's long-term success. +- No validator search. Consumer chains do not have their own validator sets, and so do not need to find validators one by one. Validators from the provider chain validate on the consumer chain with their stake on the provider chain, earning additional rewards. For the consumer chain, this comes with the benefit of exposing their chain to the wider audience of the provider chain. - Instant sovereignty. Consumers can run arbitrary app logic similar to standalone chains. At any time in the future, a consumer chain can elect to become a completely standalone chain, with its own validator set. ## Core protocol diff --git a/docs/docs/introduction/terminology.md b/docs/docs/introduction/terminology.md index fd06174f92..dd9cd57602 100644 --- a/docs/docs/introduction/terminology.md +++ b/docs/docs/introduction/terminology.md @@ -16,7 +16,11 @@ Interchain Security is the Cosmos-specific category of Shared Security that uses ## Replicated Security -A particular protocol/implementation of Interchain Security that fully replicates the security and decentralization of a validator set across multiple blockchains. Replicated security has also been referred to as "Cross Chain Validation" or "Interchain Security V1", a legacy term for the same protocol. That is, a "provider chain" such as the Cosmos Hub can share its exact validator set with multiple consumer chains by communicating changes in its validator set over IBC. Note this documentation is focused on explaining the concepts from replicated security. +A particular protocol/implementation of Interchain Security that fully replicates the security and decentralization of a validator set across multiple blockchains. Replicated security has also been referred to as "Cross Chain Validation" or "Interchain Security V1", a legacy term for the same protocol. That is, a "provider chain" such as the Cosmos Hub can share its exact validator set with multiple consumer chains by communicating changes in its validator set over IBC. + +## Partial Set Security + +A major iteration of Interchain Security, also known as "Interchain Security V2". 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 more flexible security tradeoffs than Replicated Security. ## Mesh security 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..0d2fce211e --- /dev/null +++ b/docs/docs/validators/partial-set-security-for-validators.md @@ -0,0 +1,149 @@ +--- +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 +If a validator moves from the Top N to outside of the top N% of the validators on the provider, it will **not** +be automatically opted-out. The validator has to manually opt out. +::: + +:::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`). + +'''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. +''' + + +## 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 do you know how much voting power you need to have to be in the top N for a chain? +This can be seen as part of the `list-consumer-chains` query: +```bash +interchain-security-pd query provider list-consumer-chains +``` +where the `min_power_in_top_N` field shows the minimum voting power required to be +automatically opted in to the chain. + +:::tip +`list-consumer-chains` shows the minimal voting power *right now*, but +the automatic opt-in happens only when epochs end on the provider. +In consequence, a validators power might be large enough to be automatically opted in +during an epoch, but if their power is sufficiently decreased before the epoch ends, +they will not be opted in automatically. +::: + + +### 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