From 5028765e82c9da1a3fb0330d710bb3b5178598a7 Mon Sep 17 00:00:00 2001 From: Marius Poke Date: Fri, 23 Aug 2024 14:37:06 +0200 Subject: [PATCH] docs: several changes to the ICS docs (#2163) * update FAQ * update overview * deprecate technical spec * clean up terminology * adding new fields to ConsumerAdditionProposal * update home cards * update docs to remove tips * coderabbitai suggestions * fix broken link * Update docs/docs/features/democracy-modules.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/validators/partial-set-security-for-validators.md Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> --------- Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com> --- docs/docs/consumer-development/onboarding.md | 6 +- docs/docs/features/democracy-modules.md | 63 ++----- docs/docs/features/key-assignment.md | 26 +-- docs/docs/features/partial-set-security.md | 30 +-- docs/docs/features/power-shaping.md | 112 ++++++----- docs/docs/features/proposals.md | 60 +++--- docs/docs/features/reward-distribution.md | 20 +- docs/docs/features/slashing.md | 25 +-- docs/docs/frequently-asked-questions.md | 178 ++++++++++-------- docs/docs/introduction/overview.md | 67 ++++--- .../introduction/technical-specification.md | 7 - docs/docs/introduction/terminology.md | 30 +-- .../partial-set-security-for-validators.md | 62 +++--- .../components/Cards/card-data/home-cards.js | 30 +-- 14 files changed, 352 insertions(+), 364 deletions(-) delete mode 100644 docs/docs/introduction/technical-specification.md diff --git a/docs/docs/consumer-development/onboarding.md b/docs/docs/consumer-development/onboarding.md index 9f438dd8d4..a86aa00aa9 100644 --- a/docs/docs/consumer-development/onboarding.md +++ b/docs/docs/consumer-development/onboarding.md @@ -119,7 +119,11 @@ Example of a consumer chain addition proposal. // the consumer chain. "allowlist": [], // Corresponds to a list of provider consensus addresses of validators that CANNOT validate the consumer chain. - "denylist": [] + "denylist": [], + // Corresponds to the minimal amount of (provider chain) stake required to validate on the consumer chain. + "min_stake": 0, + // Corresponds to whether inactive validators are allowed to validate the consumer chain. + "allow_inactive_vals": false } ``` diff --git a/docs/docs/features/democracy-modules.md b/docs/docs/features/democracy-modules.md index a89466d863..2c3ea2b2d5 100644 --- a/docs/docs/features/democracy-modules.md +++ b/docs/docs/features/democracy-modules.md @@ -6,7 +6,7 @@ sidebar_position: 5 This section is relevant for chains transitioning from a standalone chain and new consumer chains that require some functionality from the `x/staking` module. -The democracy modules comprise `x/staking`, `x/distribution` and `x/governance` with overrides and extensions required for normal operation when participating in interchain security. +The democracy modules comprise `x/staking`, `x/distribution` and `x/governance` with overrides and extensions required for normal operation when participating in ICS. The modules are plug-and-play and only require small wiring changes to be enabled. @@ -16,40 +16,30 @@ For a full integration check the `consumer-democracy` [example app](https://gith The democracy staking module allows the cosmos-sdk `x/staking` module to be used alongside the interchain security `consumer` module. -The module uses overrides that allow the full `x/staking` functionality with one notable difference - the staking module will no longer be used to provide the consensus validator set. +The module uses overrides that allow the full `x/staking` functionality with one notable difference - the staking module will no longer be used to provide the validator set to the consensus engine. ### Implications for consumer chains -The `x/ccv/democracy/staking` allows consumer chains to separate governance from block production. - -:::info +The `x/ccv/democracy/staking` allows consumer chains to **_separate governance from block production_**. The validator set coming from the provider chain does not need to participate in governance - they only provide infrastructure (create blocks and maintain consensus). -::: #### Governators (aka. Governors) -Validators registered with the `x/staking` module become "Governators". - -Unlike Validators, Governators are not required to run any chain infastructure since they are not signing any blocks. - -However, Governators retain a subset of the validator properties: +Validators registered with the `x/staking` module become __Governators__. +Unlike validators, governators are not required to run any chain infrastructure since they are not signing any blocks. +However, governators retain a subset of the validator properties: -- new Governators can be created (via `MsgCreateValidator`) -- Governators can accept delegations -- Governators can vote on governance proposals (with their self stake and delegations) -- Governators earn token rewards +- new governators can be created (via `MsgCreateValidator`) +- governators can accept delegations +- governators can vote on governance proposals (with their self stake and delegations) +- governators earn block rewards -- the block rewards kept on the consumer (see the [ConsumerRedistributionFraction param](../introduction/params.md#consumerredistributionfraction)) are distributed to all governators and their delegators. -With these changes, Governators can become community advocates that can specialize in chain governance and they get rewarded for their participation the same way the validators do. - -Additionally, Governators can choose to provide additional infrastructure such as RPC/API access points, archive nodes, indexers and similar software. +With these changes, governators can become community advocates that can specialize in chain governance and they get rewarded for their participation the same way the validators do. +Additionally, governators can choose to provide additional infrastructure such as RPC/API access points, archive nodes, indexers and similar software. #### Tokenomics -The consumer chain's token will remain a governance and reward token. The token's parameters (inflation, max supply, burn rate) are not affected. - -:::info -Staking rewards are distributed to all Governators and their delegators after distributing the rewards to the provider chain's validator set. -::: +The consumer chain's token will remain a governance token. The token's parameters (inflation, max supply, burn rate) are completely under the control of the consumer chain. ### Integration @@ -82,7 +72,7 @@ To integrate the `democracy/staking` follow this guide: #### 1. confirm that no modules are returning validator updates -:::tip +:::warning Only the `x/ccv/consumer` module should be returning validator updates. ::: @@ -231,12 +221,8 @@ func NewApp(...) { ## Governance The `x/ccv/democracy/governance` module extends the `x/governance` module with the functionality to filter proposals. - -:::tip -Consumer chains can limit in the types of governance proposals that can be executed on chain to avoid inadvertent changes to interchain security protocol that could affect security properties. -::: - The module uses `AnteHandler` to limit the types of proposals that can be executed. +As a result, consumer chains can limit the types of governance proposals that can be executed on chain to avoid inadvertent changes to the ICS protocol that could affect security properties. ### Integration @@ -453,23 +439,14 @@ func NewApp(...) { ## Distribution -:::tip -The `democracy/distribution` module allows the consumer chain to send rewards to the provider chain while retaining the `x/distribution` module for internal reward distribution to Governators and stakers. -::: +The `democracy/distribution` module allows the consumer chain to send rewards to the provider chain while retaining the logic of the `x/distribution` module for internal reward distribution to governators and their delegators. ### How it works -First, a % of rewards to be distributed to the provider chain's validator set is calculated and sent to the provider chain. Only opted-in validators from the provider chain will receive the consumer rewards. - -Second, the remaining rewards get distributed to the consumer chain's Governators and their delegators. - -:::info -The % that is sent to the provider chain corresponds to `1 - ConsumerRedistributionFraction`. - -e.g. `ConsumerRedistributionFraction = "0.75"` - -means that the consumer chain retains 75% of the rewards, while 25% gets sent to the provider chain to be distributed as rewards to provider chain validators. -::: +First, a percentage of the block rewards is sent to the provider chain, where is distributed only to opted-in validators and their delegators. +Second, the remaining rewards get distributed to the consumer chain's governators and their delegators. +The percentage that is sent to the provider chain corresponds to `1 - ConsumerRedistributionFraction`. +For example, `ConsumerRedistributionFraction = "0.75"` means that the consumer chain retains 75% of the rewards, while 25% gets sent to the provider chain ### Integration diff --git a/docs/docs/features/key-assignment.md b/docs/docs/features/key-assignment.md index 85dcb8e074..b9f1496dde 100644 --- a/docs/docs/features/key-assignment.md +++ b/docs/docs/features/key-assignment.md @@ -11,23 +11,22 @@ The feature is outlined in this [ADR-001](../adrs/adr-001-key-assignment.md) By sending an `AssignConsumerKey` transaction, validators are able to indicate which consensus key they will be using to validate a consumer chain. On receiving the transaction, if the key assignment is valid, the provider will use the assigned consensus key when it sends future voting power updates to the consumer that involve the validator. -:::tip -Key assignment is handled only by the provider chain - the consumer chains are not aware of the fact that different consensus keys represent the same validator entity. -::: +Note that key assignment is handled only by the provider chain - the consumer chains are not aware of the fact that different consensus keys represent the same validator entity. ## Rules -- a key can be assigned as soon as the consumer addition proposal is submitted to the provider -- validator A cannot assign consumer key K to consumer chain X if there is already a validator B (B!=A) using K on the provider -- validator A cannot assign consumer key K to consumer chain X if there is already a validator B using K on X -- a new validator on the provider cannot use a consensus key K if K is already used by any validator on any consumer chain - -:::tip -Validators can use a different key for each consumer chain. -::: +- A key can be assigned as soon as the consumer addition proposal is submitted to the provider. +- Validator `A` cannot assign consumer key `K` to consumer chain `X` if there is already a validator `B` (`B!=A`) using `K` on the provider. +- Validator `A` cannot assign consumer key `K` to consumer chain `X` if there is already a validator `B` using `K` on `X`. +- A new validator on the provider cannot use a consensus key `K` if `K` is already used by any validator on any consumer chain. ## Adding a key +:::warning +Validators are strongly recommended to assign a separate key for each consumer chain +and **not** reuse the provider key across consumer chains for security reasons. +::: + First, create a new node on the consumer chain using the equivalent: ```bash @@ -81,11 +80,6 @@ To change your key, simply repeat all of the steps listed above. Take note that To remove a key, simply switch it back to the consensus key you have assigned on the provider chain by following steps in the `Adding a key` section and using your provider consensus key. -:::warning -Validators are strongly recommended to assign a separate key for each consumer chain -and **not** reuse the provider key across consumer chains for security reasons. -::: - ## Querying proposed consumer chains To query the consumer addition proposals that are in the voting period, you can use the following command on the provider: diff --git a/docs/docs/features/partial-set-security.md b/docs/docs/features/partial-set-security.md index b18de22b4e..eadb841e59 100644 --- a/docs/docs/features/partial-set-security.md +++ b/docs/docs/features/partial-set-security.md @@ -4,31 +4,21 @@ sidebar_position: 6 # Partial Set Security -Partial Set Security (PSS) is a complete revamp of the Hub's security offering. It allows consumer chains to leverage only a subset of validators from the provider chain, which offers more flexibility than the previous Replicated Security model. By introducing the top_N parameter, each consumer chain can choose the extent of security needed: +Partial Set Security (PSS) is a complete revamp of the Hub's security offering. It allows consumer chains to leverage only a subset of validators from the provider chain, which offers more flexibility than the previous 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. +An advantage of Top N chains is that they are guaranteed to receive at least a certain fraction of the market cap of the provider chain in security. +In turn, Top N chains need to be approved by governance, since some validators will be forced to validate on them. +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. Validators are never forced to validate these chains and simply opt in if they want to. At the moment, opt-in chains still require a governance proposal, but this will be removed in the next release, allowing chains to launch completely permissionlessly. 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. +Opt-In chains, on the other hand, are more flexible. +Validators are never forced to validate these chains and simply opt in if they want to. +Because of this, Opt-In chains can be **_launch completely permissionlessly_** by sending a transaction to the provider chain. +As a trade-off though, 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 - -Top N chains always require a governance proposal because they force the top N -validators to run the chain. +Note that Top N consumer chains can become Opt-In chains or vice versa via a [`ConsumerModificationProposal`](./proposals.md#consumermodificationproposal). -As a temporary measure, Opt In chains also require a governance proposal, but this will be removed in the next release, making Opt In chains completely permissionless. - -The reason Opt In chains currently require a governance prop is to prevent issues around chain ID squatting, i.e. someone could spuriously register many desirable chain IDs of upcoming consumer chain and simply deny legitimate consumer chains from using them. 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. -::: - -:::tip -A running Top N consumer chain might want to become an Opt-In chain or vice versa. This can be achieved by issuing -a [`ConsumerModificationProposal`](./proposals.md#consumermodificationproposal). -::: +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. diff --git a/docs/docs/features/power-shaping.md b/docs/docs/features/power-shaping.md index 514649a4a7..169872b9b2 100644 --- a/docs/docs/features/power-shaping.md +++ b/docs/docs/features/power-shaping.md @@ -5,70 +5,88 @@ sidebar_position: 7 # Power Shaping To give consumer chains more flexibility in choosing their validator set, Interchain Security offers -several "power shaping" mechanisms for consumer chains. +several ways to shape the powers of the validator sets on the 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. If more validators -than the maximum size have opted in on a consumer chain, only the validators with the highest power, up to the specified +## Power Shaping Configuration + +Currently, ICS supports the following power shaping parameters. + +### Capping the validator set size + +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. +If more validators than the maximum size have opted in on a consumer chain, only the validators with the highest power, up to the specified maximum, will validate the consumer chain. -:::info -This is only applicable to Opt In chains (chains with Top N = 0). -::: -2) **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 stake 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. -:::info -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%). -::: -:::info -Rewards are distributed proportionally to validators with respect to their capped voting power on the consumer, -not their total voting power on the provider. + +Note that this parameter only applies to Opt In consumer chains (i.e., with Top N = 0). + +### Capping the validator powers + +The consumer chain can specify a maximum fraction of the total voting power any of its validators should have. +This is a security measure that makes it harder for a single large validator to take over a consumer chain: +It mitigates the risk of an Opt In chain with only a few validators being dominated by a validator with a large amount of stake. +For example, setting this fraction to 33% would mean that no single validator can have more than 33% of the total voting power on the consumer, and thus no single validator would be able to stop the consumer by going offline. + +:::warning +This parameter 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%). ::: -3) **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. + +Note that rewards are distributed proportionally to validators with respect to their capped voting power on the consumer, not their total voting power on the provider. + +### 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. +By default, both lists are empty -- there are no restrictions on which validators are eligible to opt in. :::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, +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. ::: -4) **Minimum validator stake**: The consumer chain can specify a minimum amount of stake that a validator must have on the provider chain to be able to validate the consumer chain. This can be used to ensure that only validators with a certain amount of stake can validate the consumer chain. For example, setting this to 1000 would mean only validators with at least 1000 tokens staked on the provider chain can validate the consumer chain. +### Minimum validator stake -5) **Allow inactive validators**: The consumer chain can specify whether provider validators that are *not* active in consensus may validate on the consumer chain or not. If this is set to `false`, only active validators on the provider chain can validate the consumer chain. If this is set to `true`, inactive validators can also validate the consumer chain. This can be useful for chains that want to have a larger validator set than the active validators on the provider chain, or for chains that want to have a more decentralized validator set. Consumer chains that enable this feature should strongly consider setting a minimum validator stake to ensure that only validators with some reputation/stake can validate the chain. This parameter is set to `false` by default. +The consumer chains can specify a minimum amount of stake that any validator must have on the provider chain to be eligible to opt in. +For example, setting this to 1000 would mean only validators with at least 1000 tokens staked on the provider chain can validate the consumer chain. -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. +### Allow inactive validators -Each of these mechanisms is *set during the consumer addition proposal* (see [Onboarding](../consumer-development/onboarding.md#3-submit-a-governance-proposal)). +The consumer chains can specify whether validators outside of the provider's active set are eligible to opt in. +This can be useful for chains that want to have a larger validator set than the provider chain, or for chains that want to have a more decentralized validator set. +Consumer chains that enable this feature should strongly consider setting a minimum validator stake to ensure that only validators with some reputation/stake can validate the chain. +By default, this parameter is set to `false`, i.e., validators outside of the provider's active set are not eligible to opt in. -The values can be seen by querying the list of consumer chains: -```bash -interchain-security-pd query provider list-consumer-chains -``` +## Setting Power Shaping Parameters -## Guidelines for setting power shaping parameters +All the power shaping parameters can be set by the consumer chain in the `ConsumerAdditionProposal` (see [Onboarding](../consumer-development/onboarding.md#3-submit-a-governance-proposal)). +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. 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. + +* **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. +* **Be aware of the interaction between capping the validator powers capping the validator set size.** + 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). + Also note 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. +* **Do not have allowlist contain too few validators.** + If the allowlist is _non empty_, then _only_ validators on the allowlist can validate the chain. + Thus, an allowlist containing too few validators is a security risk, e.g., the validators on the allowlist get jailed on the provider. +* **Do not have denylist contain too many validators.** + If the denylist is *non empty*, then the validators on the denylist cannot validate the chain. + Thus, a denylist containing too many validators is a security risk, e.g., the validators on the denylist represents a large fraction of the provider's 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. -:::tip The power shaping parameters of a running consumer chain can be changed through a [`ConsumerModificationProposal`](./proposals.md#consumermodificationproposal). -::: \ No newline at end of file + +The power shaping parameters can be seen by querying the list of consumer chains: + +```bash +interchain-security-pd query provider list-consumer-chains +``` + diff --git a/docs/docs/features/proposals.md b/docs/docs/features/proposals.md index 44ea4f0298..2df217088e 100644 --- a/docs/docs/features/proposals.md +++ b/docs/docs/features/proposals.md @@ -2,21 +2,19 @@ sidebar_position: 3 --- - # ICS Provider Proposals -Interchain security module introduces new proposal types to the provider. - -The proposals are used to propose upcoming interchain security events through governance. +Interchain Security introduces the following new governance proposal types to the provider chain. ## `ConsumerAdditionProposal` -:::info + +:::tip If you are preparing a `ConsumerAdditionProposal` you can find more information in the [consumer onboarding checklist](../consumer-development/onboarding.md). ::: -Proposal type used to suggest adding a new consumer chain. - -When proposals of this type are passed and the `spawn_time` specified in the proposal is reached, all provider chain validators are expected to run infrastructure (validator nodes) for the proposed consumer chain. +`ConsumerAdditionProposal` is used to add new consumer chains. +When proposals of this type pass governance and the `spawn_time` specified in the proposal is reached, all opted in provider validators are expected to run infrastructure (validator nodes) for the proposed consumer chain. +Note that for TopN consumer chains, the validators in the top N% of the voting power are automatically opted in at spawn time. Minimal example: ```js @@ -48,22 +46,18 @@ Minimal example: "validators_power_cap": 0, "validator_set_cap": 0, "allowlist": [], - "denylist": [] + "denylist": [], + "min_stake": 0, + "allow_inactive_vals": false } ``` -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). -## `ConsumerRemovalProposal` -Proposal type used to suggest removing an existing consumer chain. +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). -When proposals of this type are passed, the consumer chain in question will be gracefully removed from interchain security and validators will no longer be required to run infrastructure for the specified chain. -After the consumer chain removal, the chain in question will no longer be secured by the provider's validator set. +## `ConsumerRemovalProposal` -:::info -The chain in question my continue to produce blocks, but the validator set can no longer be slashed for any infractions committed on that chain. -Additional steps are required to completely offboard a consumer chain, such as re-introducing the staking module and removing the provider's validators from the active set. -More information will be made available in the [Consumer Offboarding Checklist](../consumer-development/offboarding.md). -::: +`ConsumerRemovalProposal` is used to remove an existing consumer chain. +When proposals of this type pass governance, the consumer chain in question will be gracefully removed from Interchain Security and validators will no longer be required to run infrastructure for the specified chain. Minimal example: ```js @@ -77,15 +71,17 @@ Minimal example: } ``` +After the consumer chain removal, the consumer chain is no longer secured by the provider chain. +The consumer chain might continue to produce blocks using the last validator set received from the provider. +However, its validator set can no longer be slashed for any infractions committed on the consumer. +Additional steps are required to completely offboard a consumer chain, such as re-introducing the staking module and removing the provider's validators from the active set. + ## `ConsumerModificationProposal` -Proposal type used to change the power shaping parameters of a running consumer chain, as well as to change a Top N running -consumer chain to an Opt-In chain and vice versa. -When a `ConsumerModificationProposal` passes for a running consumer chain, the consumer chain would change all its -parameters to the ones passed in the `ConsumerModificationProposal`. +`ConsumerModificationProposal` is used to change the power shaping parameters of a running consumer chain, as well as to change a Top N running consumer chain to an Opt-In chain and vice versa. +When proposals of this type pass governance, the consumer chain in question would change all its parameters to the ones passed in the `ConsumerModificationProposal`. -Assume, a `chain-1` is a Top N chain. If the following `ConsumerModificationProposal` passes, then `chain-1` would become -an Opt-In chain with a 40% validators power cap, a maximum number of 30 validators, and one denylisted validator. +For example, given `chain-1` is a TopN consumer chain with, if the following `ConsumerModificationProposal` passes, then `chain-1` would become an Opt-In chain with a 40% validators power cap, a maximum number of 30 validators, and one denylisted validator. ```js { "title": "Modify consumer chain", @@ -108,13 +104,10 @@ from 35 to 40, then the `ConsumerModificationProposal` would still need to inclu To be **safe**, always include `top_N` and all the power shaping parameters in your `ConsumerModificationProposal`. ::: -## ChangeRewardDenomProposal - -Proposal type used to mutate the set of denoms accepted by the provider as rewards. +## `ChangeRewardDenomProposal` -:::tip -A `ChangeRewardDenomProposal` will only be accepted on the provider chain if at least one of the `denomsToAdd` or `denomsToRemove` fields is populated with at least one denom. Also, a denom cannot be repeated in both sets. -::: +`ChangeRewardDenomProposal` is used to update the set of denoms accepted by the provider as rewards. +Note that a `ChangeRewardDenomProposal` will only be accepted on the provider chain if at least one of the `denomsToAdd` or `denomsToRemove` fields is populated with at least one denom. Also, a denom cannot be repeated in both sets. Minimal example: ```js @@ -126,10 +119,8 @@ Minimal example: } ``` -:::tip Besides native provider denoms (e.g., `uatom` for the Cosmos Hub), please use the `ibc/*` denom trace format. -For example, for `untrn` transferred over the path `transfer/channel-569`, the denom trace -can be queried using the following command: +For example, for `untrn` transferred over the path `transfer/channel-569`, the denom trace can be queried using the following command: ```bash > gaiad query ibc-transfer denom-hash transfer/channel-569/untrn hash: 0025F8A87464A471E66B234C4F93AEC5B4DA3D42D7986451A059273426290DD5 @@ -143,4 +134,3 @@ Then use the resulting hash in the `ChangeRewardDenomProposal`, e.g., "denomsToRemove": [] } ``` -::: diff --git a/docs/docs/features/reward-distribution.md b/docs/docs/features/reward-distribution.md index e042605cdd..8535ebaca1 100644 --- a/docs/docs/features/reward-distribution.md +++ b/docs/docs/features/reward-distribution.md @@ -7,25 +7,23 @@ 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 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). +Consumer chains have the option of sharing _a portion of_ their block rewards (inflation tokens and fees) with the provider chain as ICS rewards. +These rewards are periodically sent from the consumer to the provider according to [consumer chain parameters](../introduction/params.md#reward-distribution-parameters) using an IBC transfer channel. +This channel is created during consumer chain initialization, unless it is provided when creating a new consumer chain (see the [DistributionTransmissionChannel param](../introduction/params.md#distributiontransmissionchannel)). -:::tip -Providing an IBC transfer channel (see `DistributionTransmissionChannel`) enables a consumer chain to re-use one of the existing channels to the provider for consumer chain rewards distribution. This will preserve the `ibc denom` that may already be in use. +Providing an IBC transfer channel enables a consumer chain to re-use one of the existing channels to the provider for consumer chain rewards distribution. +This will preserve the `ibc denom` that may already be in use. This is especially important for standalone chains transitioning to become consumer chains. For more details, see the [changeover procedure](../consumer-development/changeover-procedure.md). -::: -Reward distribution on the provider is handled by the distribution module. +Once on the provider, the ICS rewards are distributed to the opted in validators and their delegators. +To avoid spam, the provider must whitelist denoms before accepting them as ICS rewards. ## Whitelisting Reward Denoms The ICS distribution system works by allowing consumer chains to send rewards to a module address on the provider called the `ConsumerRewardsPool`. -To avoid spam, the provider must whitelist denoms before accepting them as ICS rewards. -Only whitelisted denoms are transferred from the `ConsumerRewardsPool` to the `FeePoolAddress`, to be distributed to delegators and validators. -The whitelisted denoms can be adjusted through governance by sending a [`ChangeRewardDenomProposal`](./proposals.md#changerewarddenomproposal). +Only whitelisted denoms are transferred from the `ConsumerRewardsPool` to the `FeePoolAddress`, to be distributed to validators and their delegators. +The whitelisted denoms can be adjusted through governance by sending a [`ChangeRewardDenomProposal`](./proposals.md#changerewarddenomproposal). To query the list of whitelisted reward denoms on the Cosmos Hub, use the following command: ```bash diff --git a/docs/docs/features/slashing.md b/docs/docs/features/slashing.md index 718c3cbad0..295e22cdca 100644 --- a/docs/docs/features/slashing.md +++ b/docs/docs/features/slashing.md @@ -3,27 +3,23 @@ sidebar_position: 4 --- # Consumer Initiated Slashing -A consumer chain is essentially a regular Cosmos-SDK based chain that uses the Interchain Security module to achieve economic security by stake deposited on the provider chain, instead of its own chain. -In essence, provider chain and consumer chains are different networks (different infrastructures) that are bound together by the provider's validator set. By being bound to the provider's validator set, a consumer chain inherits the economic security guarantees of the provider chain (in terms of total stake). +A consumer chain is essentially a regular Cosmos-SDK based chain that uses the ICS consumer module to achieve economic security by stake deposited on the provider chain, instead of its own chain. +In essence, the provider chain and consumer chains are different networks (different infrastructures) that share a subset of the provider's validator set. By being bound to the provider's validator set, a consumer chain inherits some of the economic security guarantees of the provider chain. To maintain the proof of stake model, the consumer chain is able to send evidence of infractions (double signing and downtime) to the provider chain so the offending validators can be penalized. Any infraction committed on any of the consumer chains is reflected on the provider and all other consumer chains. -In the current implementation there are two important changes brought by the Interchain Security module. +The ICS protocol differentiates between downtime and equivocation infractions. ## Downtime Infractions -Downtime infractions are reported by consumer chains and are acted upon on the provider as soon as the provider receives the infraction evidence. - -Instead of slashing, the provider will only jail offending validator for the duration of time established by the chain parameters. - -:::info -[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, +Downtime infractions are reported by consumer chains and are acted upon on the provider as soon as they are received. +Instead of slashing, the provider will **_only jail_** offending validator for the duration of time established by the provider chain parameters. +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. +For preventing malicious consumer chains from harming the provider, [slash throttling](../adrs/adr-002-throttle.md) (also known as _jail throttling_) ensures that only a fraction of the provider validator set can be jailed at any given time. + ## 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. @@ -600,7 +596,4 @@ The following command demonstrates how to run a Hermes instance in _evidence mod ```bash hermes evidence --chain ``` - -:::tip -`hermes evidence` takes a `--check-past-blocks` option giving the possibility to look for older evidence (default is 100). -::: +Note that `hermes evidence` takes a `--check-past-blocks` option giving the possibility to look for older evidence (default is 100). diff --git a/docs/docs/frequently-asked-questions.md b/docs/docs/frequently-asked-questions.md index 918e371897..379e0ecef2 100644 --- a/docs/docs/frequently-asked-questions.md +++ b/docs/docs/frequently-asked-questions.md @@ -4,145 +4,163 @@ title: "Frequently Asked Questions" slug: /faq --- -## What is a consumer chain? +## General -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). +### What is Interchain Security (ICS)? -Consumer chains are run on infrastructure (virtual or physical machines) distinct from the provider, have their own configurations and operating requirements. +ICS is an IBC protocol that enables a provider chain (e.g., the Cosmos Hub) to provide security to multiple [consumer chains](#what-are-consumer-chains). +This means that consumer chains will leverage the stake locked on the provider chain for block production (i.e., a cross-chain proof-of-stake system). +ICS allows anyone to launch a consumer chain using a subset, or even the entire, validator set from the provider chain. +Note that validators need to run separate infrastructure for the provider and consumer chains, resulting in different networks that only share (a subset of) the validator set. -## What happens to consumer if provider is down? +### What is the difference between ICS and Partial Set Security (PSS)? -In case the provider chain halts or experiences difficulties the consumer chain will keep operating - the provider chain and consumer chains represent different networks, which only share the validator set. +[ICS is a protocol](#what-is-interchain-security-ics). +PSS is a feature of ICS that allows a provider chain to share only a subset of its validator set with a consumer chain. +PSS differentiates between TopN and Opt-In consumer chains. +For TopN chains, the validator subset is determined by the top N% provider validators by voting power. +For Opt-In chains, the validator subset is determined by validators opting in to validate the consumer chains. +PSS allows for flexible tradeoffs between security, decentralization, and the budget a consumer chain spends on rewards to validators. -The consumer chain will not halt if the provider halts because they represent distinct networks and distinct infrastructures. Provider chain liveness does not impact consumer chain liveness. +For more details, see the [PSS feature](./features/partial-set-security.md). -However, if the `trusting_period` (currently 5 days for protocol safety reasons) elapses without receiving any updates from the provider, the consumer chain will essentially transition to a Proof of Authority chain. -This means that the validator set on the consumer will be the last validator set of the provider that the consumer knows about. +## Consumer Chains -Steps to recover from this scenario and steps to "release" the validators from their duties will be specified at a later point. -At the very least, the consumer chain could replace the validator set, remove the ICS module and perform a genesis restart. The impact of this on the IBC clients and connections is currently under careful consideration. +### What are consumer chains? -## What happens to provider if consumer is down? +Consumer chains are blockchains operated by (a subset of) the validators of the provider chain. +The ICS protocol ensures that consumer chains get information about which validators should validate on them. +This information consists of the opted in validators and their power on the consumer chains. +Note that the validators' power on the consumer chains is a function of their stake locked on the provider chain. -Consumer chains do not impact the provider chain. -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). +Consumer chains are run on infrastructure (virtual or physical machines) distinct from the provider chain, have their own configurations and operating requirements. -## Can I run the provider and consumer chains on the same machine? +Consumer chains are free to choose how they wish to operate and which modules to include. +For example, they can choose to use CosmWasm either in a permissioned or a permissionless way. +Also, consumer chains are free to perform software upgrades at any time without impacting the provider chain. -Yes, but you should favor running them in separate environments so failure of one machine does not impact your whole operation. +### How to become a consumer chain? -## Can the consumer chain have its own token? +To become a consumer chain use this [checklist](./consumer-development/onboarding.md) and check the [App integration section](./consumer-development/app-integration.md). -As any other cosmos-sdk chain the consumer chain can issue its own token, manage inflation parameters and use them to pay gas fees. +### What happens to consumers if the provider is down? -## How are Tx fees paid on consumer? +In case the provider chain halts or experiences difficulties, the consumer chains will keep operating - the provider chain and consumer chains represent different networks that only share (a subset of) the validator set. +As the validators run separate infrastructure on these networks, **_the provider chain liveness does not impact the liveness of consumer chains_**. -The consumer chain operates as any other cosmos-sdk chain. The ICS protocol does not impact the normal chain operations. +Every consumer chain communicates with the provider chain via a CCV channel -- an IBC ordered channel. +If any of the packets sent over the CCV channel timeout (see the [CCVTimeoutPeriod param](./introduction/params.md#ccvtimeoutperiod)), then the channel is closed and, consequently, the consumer chain transitions to a Proof of Authority (PoA) chain. +This means that the validator set on the consumer will no longer be updated with information from the provider. -## Are there any restrictions the consumer chains need to abide by? +### What happens to provider if any of the consumers are down? -No. Consumer chains are free to choose how they wish to operate, which modules to include, use CosmWASM in a permissioned or a permissionless way. -The only thing that separates consumer chains from standalone chains is that they share their validator set with the provider chain. +**_Consumer chains do not impact the livness of the provider chain._** +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). -## What's in it for the validators and stakers? +### Can consumer chains have their own token? -The consumer chains sends a portion of its fees and inflation as reward to the provider chain as defined by `ConsumerRedistributionFraction`. The rewards are distributed (sent to the provider) every `BlocksPerDistributionTransmission`. +As any other Cosmos SDK chains, **_consumer chains can issue their own token_** and manage inflation parameters. +Note that the ICS protocol does not impact the transaction fee system on the consumer chains. +This means consumer chains can use any token (including their own token) to pay gas fees. +For more details, see the [democracy modules](./features/democracy-modules.md#tokenomics). -:::note - `ConsumerRedistributionFraction` and `BlocksPerDistributionTransmission` are parameters defined in the `ConsumerAdditionProposal` used to create the consumer chain. These parameters can be changed via consumer chain governance. -::: +### Can consumer chains have their own governance? -## Can the consumer chain have its own governance? +Yes. ICS allows consumer chains to **_separate governance from block production_**. +Validator operators (with their stake locked on the provider) are responsible for block production, while _representatives_ (aka governators, governors) are responsible for on-chain governance. +For more details, see the [democracy modules](./features/democracy-modules.md). -**Yes.** +### Can a consumer chain modify its power shaping parameters? -In that case the validators are not necessarily part of the governance structure. Instead, their place in governance is replaced by "representatives" (governors). The representatives do not need to run validators, they simply represent the interests of a particular interest group on the consumer chain. +Yes, by issuing a [`ConsumerModificationProposal`](./features/proposals.md#consumermodificationproposal). -Validators can also be representatives but representatives are not required to run validator nodes. +### Can a Top N consumer chain become Opt-In or vice versa? -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. +Yes, by issuing a [`ConsumerModificationProposal`](./features/proposals.md#consumermodificationproposal). -## Can validators opt out of validating a consumer chain? +## Validators -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 can validators opt in to validate a consumer chain? -## How does Slashing work? +Check the [validator guide to Partial Set Security](./validators/partial-set-security-for-validators.md#how-to-opt-in-to-a-consumer-chain). -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)). +An important note is that validator the top N% of the provider chain validator set are automatically opted in on Top N consumer chains. -## Can Consumer Chains perform Software Upgrades? +### Can validators opt in to an Opt-in chain after the spawn time if nobody else opted in? -Consumer chains are standalone chains, in the sense that they can run arbitrary logic and use any modules they want (ie CosmWASM). +No, the consumer chain will be removed if nobody opted in by the spawn time. At least one validator, regardless of its voting power, must opt in before the spawn time in order for the chain can start. -Consumer chain upgrades are unlikely to impact the provider chain, as long as there are no changes to the ICS module. +### How does a validator know which consumers chains it has to validate? -## How can I connect to the testnets? +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). -Check out the [Joining Interchain Security testnet](./validators/joining-testnet.md) section. +### How many chains can a validator opt in to? -## How do I start using ICS? +There is **no** limit in the number of consumers chains a validator can choose to opt in to. -To become a consumer chain use this [checklist](./consumer-development/onboarding.md) and check the [App integration section](./consumer-development/app-integration.md) +### How can validators assign consumer keys? -## Which relayers are supported? +Check the [Key Assignment guide](./features/key-assignment.md) for specific instructions. -Currently supported versions: +Validators are strongly recommended to assign a separate key for each consumer chain and **not** reuse the provider key across consumer chains for security reasons. -- Hermes 1.8.0 +Also note that validators can assign consensus keys before a consumer chain is launched (e.g., during the voting period for Top N consumer chains). -## How does key delegation work in ICS? +### What are the benefits for validators running consumer chains? -You can check the [Key Assignment Guide](./features/key-assignment.md) for specific instructions. +The consumer chains sends a portion of its block rewards (e.g., transaction fees and inflation) to the provider chain as defined by the [ConsumerRedistributionFraction param](./introduction/params.md#consumerredistributionfraction). +These rewards are sent periodically to the provider (via IBC transfers), where they are distributed **ONLY** to the _opted in_ validators and their delegators. For more details, see the [Reward Distribution feature](./features/reward-distribution.md). -## How does Partial Set Security work? +### Can validators set per consumer chain commission rates? -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. +Yes. See the [validator guide to Partial Set Security](./validators/partial-set-security-for-validators.md#how-to-set-specific-per-consumer-chain-commission-rate). -See the [Partial Set Security](./features/partial-set-security.md) section for more information. +### What are the risks for validators running consumer chains? -## How does a validator know which consumers chains it has to validate? +Validators that perform an equivocation or a light-client attack on a consumer chain are slashed on the provider chain. This is done by submitting a proof of the equivocation or the light-client attack to the provider chain. -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). +In addition, consumer chains send IBC packets via the CCV channels informing the provider when opted in validators should be jailed for downtime. +It is important to notice that _validators are not slashed for downtime on consumer chains_. +The downtime logic is custom to the consumer chain. +For example, Cosmos SDK chains can use the [slashing module](https://docs.cosmos.network/v0.50/build/modules/slashing) to configure the downtime window. -## How many chains can a validator opt in to? +For more details, see the [slashing feature](features/slashing.md). -There is **no** limit in the number of consumers chains a validator can choose to opt in to. +### Can validators run the provider and consumer chains on the same machine? -## 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. +In theory yes. +In practice, we recommend validators to run the provider and consumer chains in separate environments for fault containment, i.e., failures of one machine do not impact the entire system. -## 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 out of validating a consumer chain? -## Can validators opt in to an Opt-in or Top N chain after its consumer-addition proposal voting period is over but before the spawn time? -Yes. +Validators can always opt out from an Opt-In consumer chain. +Validators can only opt out from a TopN chain if they do not belong to the top N% validators. -## 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? -## 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. +Note that if all validators opt out of an Opt-In consumer chain, then the chain will halt with a consensus failure upon receiving the `VSCPacket` with an empty validator set. -## 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%. +### How to connect to the testnets? -## Can a consumer chain modify its power shaping parameters? -Yes, by issuing a [`ConsumerModificationProposal`](./features/proposals.md#consumermodificationproposal). +Check out the [Joining Interchain Security testnet](./validators/joining-testnet.md) section. -## Can a Top N consumer chain become Opt-In or vice versa? -Yes, by issuing a [`ConsumerModificationProposal`](./features/proposals.md#consumermodificationproposal). +## Integrators + +### Which relayers are supported? + +Currently supported versions: + +- Hermes `v1.8.0+` + +### How to check when the next validator update will be sent to the consumer chains? -## How do I know when the next validator update will be sent to the consumer chain? -Validator updates are sent to the consumer chain every `BlocksPerEpoch` blocks. -Keep in mind that depending on the status of relayers between the Hub and the consumer chain, -it might take a while for the validator update to be processed and applied on the consumer chain. +Validator updates are sent to consumer chains every `BlocksPerEpoch` blocks. +Depending on the status of relayers between the Hub and the consumer chains, +it might take a while for the validator updates to be processed and applied on the consumer chains. To query how many blocks are left until the next epoch starts, run the following command: ```bash interchain-security-pd query provider blocks-until-next-epoch -``` \ No newline at end of file +``` diff --git a/docs/docs/introduction/overview.md b/docs/docs/introduction/overview.md index b9f870bfab..d8938a70fa 100644 --- a/docs/docs/introduction/overview.md +++ b/docs/docs/introduction/overview.md @@ -3,37 +3,54 @@ sidebar_position: 1 --- # Overview -:::info -Interchain Security is an open sourced IBC application which allows cosmos blockchains to lease their proof-of-stake security to one another. -

-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. -::: +Interchain Security (ICS) is an open source IBC application that allows Cosmos chains to lease their proof-of-stake security to one another. +ICS allows anyone to launch a _consumer_ chain using a subset, or even the entire, validator set from the _provider_ chain 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 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. 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. +- **Tailored security.** + Consumer chains can choose the right level of security based on their needs: + Chains can choose to inherit the whole validator set from the provider, or they can launch as an opt-in chain with a subset of the provider validators. + Additionally, consumer chains have the power to shape the validator set to their specific requirements by setting allow & deny lists, capping its size, etc. + This allows for a wide range of security tradeoffs. + For example, it enables emerging projects to deploy on consumer chains that don’t need high level of security. +- **Separation of governance from block production.** + Consumer chains can separate their governance mechanism from block production. + Block production is handled by provider validators, which means it is an extension of the proof-of-state (PoS) mechanism on the provider chain. + Governance on the consumer chains can rely on the same PoS mechanism (using the same stake locked on the provider), but it doesn't have to. + For example, consumer chains can have a governance system based on proof-of-authority (PoA) or on PoS using the consumer token (which would make the consumer token a governance token). + This also allows the governance to be more decentralized without affecting consensus (i.e., increasing the number of validators usually leads to slower block production). +- **Distribution of block rewards.** + Consumer chains can choose how to distribute the block rewards (i.e., inflation and fees), what percentage to send to the provider as payment for block production, and what percentage to keep on-chain. + The rewards kept on-chain can then be distributed to the community DAO (the consumer's governance) 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. + 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. +- **Block-space sharding.** + Consumer chains are Cosmos appchains, which means that transactions on these chains do not compete with any other applications. As a result, there will be no unexpected congestion, and performance will generally be much better than on a shared smart contract platform such as Ethereum. ## Core protocol -:::info -Protocol specification is available as [ICS-028](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md) in the IBC repository. -::: - -Once an IBC connection and proper channel is established between a provider and consumer chain, the provider will continually send validator set updates to the consumer over IBC. The consumer uses these validator set updates to update its own validator set in Comet. Thus, the provider validator set is effectively replicated on the consumer. - -To ensure the security of the consumer chain, provider delegators cannot unbond their tokens until the unbonding periods of each consumer chain has passed. In practice this will not be noticeable to the provider delegators, since consumer chains will be configured to have a slightly shorter unbonding period than the provider. - -### Downtime Slashing - -If downtime is initiated by a validator on a consumer chain, a downtime packet will be relayed to the provider to jail that validator for a set amount of time. The validator who committed downtime will then miss out on staking rewards for the configured jailing period. - -### Tokenomics and Rewards - -Consumer chains are free to create their own native token which can be used for fees, and can be created on the consumer chain in the form of inflationary rewards. These rewards can be used to incentivize user behavior, for example, LPing or staking. A portion of these fees and rewards will be sent to provider chain stakers, but that proportion is completely customizable by the developers, and subject to governance. +**Validator updates**. +Once an IBC connection and channel are established between a provider and consumer chain, the provider will continually send validator set updates to the consumer over IBC. Note the provider only sends updates for opted in validators. +The consumer uses these validator set updates to update its own validator set in the consensus engine (e.g., CometBFT). + +**Slashing and jailing.** +If the opted-in validators misbehave on the consumer chains, then they will be punished on the provider chain. +ICS currently differentiates between two types of infractions -- double signing and downtime. +Double signing on consumer chains results in the misbehaving validators having their provider stake slashed and being permanently jailed on the provider, +while downtime on consumer chains results in the misbehaving validators being temporarily jailed. +Note that jailing entails removing the validator from the provider active validator set and, consequently, from any of the consumer validato sets. +This entails the validator will miss out on both staking and ICS rewards. + +**Tokenomics and rewards.** +Consumer chains are free to create their own native token which can be used for fees, and can be created on the consumer chain in the form of inflationary rewards. +These rewards can be used to incentivize user behavior, for example, LPing or staking. +A percentage of these fees and rewards will be sent to provider chain to be distributed among the opted in validators and their delegators. +The percentage is completely customizable by the developers and subject to governance. diff --git a/docs/docs/introduction/technical-specification.md b/docs/docs/introduction/technical-specification.md deleted file mode 100644 index 581ce97137..0000000000 --- a/docs/docs/introduction/technical-specification.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Technical Specification - -For a technical deep dive into the replicated security protocol, see the [specification](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/README.md). diff --git a/docs/docs/introduction/terminology.md b/docs/docs/introduction/terminology.md index 63668c9b43..3ad5a3696a 100644 --- a/docs/docs/introduction/terminology.md +++ b/docs/docs/introduction/terminology.md @@ -4,27 +4,33 @@ sidebar_position: 2 # Terminology -You may have heard of one or multiple buzzwords thrown around in the cosmos and wider crypto ecosystem such shared security, interchain security, replicated security, cross chain validation, and mesh security. These terms will be clarified below, before diving into any introductions. +You may have heard of one or multiple buzzwords thrown around in the cosmos and wider crypto ecosystem such shared security, interchain security, replicated security, cross chain validation, and mesh security. These terms will be clarified below. ## Shared Security -Shared security is a family of technologies that include optimistic rollups, zk-rollups, sharding and Interchain Security. Ie. any protocol or technology that can allow one blockchain to lend/share its proof-of-stake security with another blockchain or off-chain process. +Shared Security is a family of technologies that include optimistic rollups, zk-rollups, sharding and Interchain Security. +Basically, any protocol or technology that can allow one blockchain to lend/share its proof-of-stake security with another blockchain or off-chain process. -## Interchain Security +## Interchain Security (ICS) -Interchain Security is the Cosmos-specific category of Shared Security that uses IBC (Inter-Blockchain Communication), i.e. any shared security protocol built with IBC. +Interchain Security is the Cosmos-specific category of Shared Security that uses IBC (Inter-Blockchain Communication). ## 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. +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 "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 that since the introduction of [Partial Set Security](#partial-set-security-pss), a TopN consumer chain with N 100% fully replicates the security and decentralization of the provider chain. -## Partial Set Security +## Partial Set Security (PSS) -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. +A major feature of Interchain Security (also referred to as "Interchain Security V2") that 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. +PSS allows for more flexible security tradeoffs than Replicated Security. -## Mesh security +## Mesh Security -A protocol built on IBC that allows delegators on a cosmos chain to re-delegate their stake to validators in another chain's own validator set, using the original chain's token (which remains bonded on the original chain). For a deeper exploration of mesh security, see [Replicated vs. Mesh Security on the Informal Blog](https://informal.systems/blog/replicated-vs-mesh-security). +A protocol built on IBC that allows delegators on a Cosmos chain to re-delegate their stake to validators in another chain's own validator set, using the original chain's token (which remains bonded on the original chain). For a deeper exploration of Mesh Security, see [Replicated vs. Mesh Security on the Informal Blog](https://informal.systems/blog/replicated-vs-mesh-security). ## Consumer Chain @@ -35,8 +41,8 @@ Interchain Security allows a subset of the provider chain's validator set to val 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 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. +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 ICS 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. diff --git a/docs/docs/validators/partial-set-security-for-validators.md b/docs/docs/validators/partial-set-security-for-validators.md index 2d6b2dd4a2..a87cf56482 100644 --- a/docs/docs/validators/partial-set-security-for-validators.md +++ b/docs/docs/validators/partial-set-security-for-validators.md @@ -4,11 +4,12 @@ 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. +The [Partial Set Security (PSS) feature](../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 @@ -39,19 +40,20 @@ and this command to see the currently proposed consumer chains: 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. +:::warning +Validators are strongly recommended to assign a separate key for each consumer chain +and **not** reuse the provider key across consumer chains for security reasons. ::: +Note that 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 @@ -60,26 +62,21 @@ 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. -::: +The opting out mechanism has the following rules: -:::warning -If a validator moves from the Top N to outside of the top N% of the validators on the provider, it will **not** +- A validator cannot opt out from a Top N chain if it belongs to the top N% validators of the provider. +- 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` +- A validator should 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. -::: +not have to validate the consumer chain any longer. Otherwise, the validator risks getting jailed for downtime. :::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. +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. This can be done with the following command: ```bash @@ -91,25 +88,20 @@ where - `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`). - 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. -:::tip Validators can set their commission rate even for consumer chains that they are not currently opted in on, and the commission rate will be applied when they opt in. This is particularly useful for Top N chains, where validators might be opted in automatically, so validators can set the commission rate in advance. -::: -:::tip If a validator opts out and then back in, this will *not* reset their commission rate back to the default. Instead, their set commission rate still applies. -::: - ## 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. + +PSS introduces a number of queries to assist validators in determining 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. @@ -120,13 +112,13 @@ interchain-security-pd query provider has-to-validate @@ -151,6 +141,7 @@ interchain-security-pd query provider consumer-opted-in-validators @@ -160,14 +151,13 @@ ones that are currently (or in the future, see warning) validating the consumer validator but not vice versa. For example, an opted-in validator `V` might not be a consumer validator because `V` is denylisted or because `V` is removed due to a validator-set cap. -:::warning -The returned consumer validators from this query do not necessarily correspond to the validator set that is +Note that the returned consumer validators from this query do not necessarily correspond to the validator set that is validating the consumer chain at this exact moment. This is because the `VSCPacket` sent to a consumer chain might be delayed and hence this query might return the validator set that the consumer chain would have at some future point in time. -::: ### 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 diff --git a/docs/src/components/Cards/card-data/home-cards.js b/docs/src/components/Cards/card-data/home-cards.js index fa2a7f4b69..8a90012c1c 100644 --- a/docs/src/components/Cards/card-data/home-cards.js +++ b/docs/src/components/Cards/card-data/home-cards.js @@ -1,23 +1,18 @@ const homeCards = [ { href: '/interchain-security/introduction/overview', - header: 'Basic concepts', + header: 'Basic Concepts', summary: 'Get started with the basic concepts and ideas.' }, { - href: '/interchain-security/consumer-development/app-integration', - header: 'Start building', - summary: 'Click here to start building with Interchain security' - }, - { - href: '/interchain-security/features/key-assignment', - header: 'Feature: Key Assignment', - summary: 'Learn about the key assignment feature', + href: '/interchain-security/faq', + header: 'FAQ', + summary: 'Frequently asked questions about the protocol and its implications' }, { - href: '/interchain-security/features/reward-distribution', - header: 'Feature: Reward Distribution', - summary: 'Learn about consumer chain rewards distribution', + href: '/interchain-security/consumer-development/app-integration', + header: 'Start Building', + summary: 'Click here to start building with Interchain Security' }, { href: '/interchain-security/consumer-development/onboarding', @@ -25,9 +20,14 @@ const homeCards = [ summary: 'Checklist to help you integrate Interchain Security, get support and onboard validators' }, { - href: '/interchain-security/faq', - header: 'FAQ', - summary: 'Frequently asked questions about the protocol and its implications' + href: 'interchain-security/validators/overview', + header: 'Become an ICS Validator', + summary: 'Start validating on consumer chains' + }, + { + href: '/interchain-security/features/key-assignment', + header: 'Assign Consumer Keys', + summary: 'Learn how to assign separate key on the consumer chains', }, ]