Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: mention PSS in changeover procedure and replace Replicated Security with Interchain Security #1981

Merged
merged 3 commits into from
Jun 24, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
added PSS info box in the changeover procedure
  • Loading branch information
insumity committed Jun 21, 2024
commit b56650a1058548913e5bccadba799c87ac5b8c08
2 changes: 1 addition & 1 deletion docs/docs/adrs/adr-010-standalone-changeover.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Implemented

## Context

[Stride](https://github.com/Stride-Labs/stride) will be the first consumer to "changeover" from a standalone cosmos blockchain, to a consumer chain secured by the Cosmos Hub. This document will outline the changes made to the interchain security protocol to support this changeover process.
[Stride](https://github.com/Stride-Labs/stride) will be the first consumer to "changeover" from a standalone cosmos blockchain, to a consumer chain secured by the Cosmos Hub. This document outlines the changes made to support this changeover process.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider enhancing the introduction of Stride's role.

The introduction of Stride as the first consumer to changeover is crucial. It might be beneficial to expand slightly on why Stride was chosen or its significance in this context to provide a clearer picture to the readers.


## Decision

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/consumer-development/app-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The source code for the example app can be found [here](https://github.com/cosmo

Please note that consumer chains do not implement the staking module - part of the validator set of the provider is replicated over to the consumer,
meaning that the consumer uses a subset of provider validator set and the stake of the validators on the provider determines their stake on the consumer.
Note that after the introduction of [Partial Set Security](../adrs/adr-015-partial-set-security.md), not all the provider validators have to validate a consumer chain (e.g., if `TopN != 100`).
Note that after the introduction of [Partial Set Security](../adrs/adr-015-partial-set-security.md), not all the provider validators have to validate a consumer chain (e.g., if `top_N != 100`).

Your chain should import the consumer module from `x/consumer` and register it in the correct places in your `app.go`.
The `x/consumer` module will allow your chain to communicate with the provider using the ICS protocol. The module handles all IBC communication with the provider, and it is a simple drop-in.
Expand Down
31 changes: 28 additions & 3 deletions docs/docs/consumer-development/changeover-procedure.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,9 +154,9 @@ Example of a consumer chain addition proposal (compare with the [ConsumerAdditio

```js
// ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain or add a standalone chain.
// If it passes, then all validators on the provider chain are expected to validate the consumer chain at spawn time.
// It is recommended that spawn time occurs after the proposal end time and that it is scheduled to happen before the standalone chain upgrade
// that sill introduce the ccv module.
// If it passes, then a subset (i.e., depends on `top_N` and on the power shaping parameters) of validators on the provider chain are expected
// to validate the consumer chain at spawn time. It is recommended that spawn time occurs after the proposal end time and that it is
// scheduled to happen before the standalone chain upgrade that sill introduce the ccv module.
{
// Title of the proposal
"title": "Changeover Standalone chain",
Expand Down Expand Up @@ -212,9 +212,34 @@ Example of a consumer chain addition proposal (compare with the [ConsumerAdditio
// 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" // NOTE: use existing transfer channel if available
// 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": []
}
```

:::info
As seen in the `ConsumerAdditionProposal` example above, the changeover procedure can be used together with [Partial Set Security](../adrs/adr-015-partial-set-security.md).
This means, that a standalone chain can choose to only be validated by some of the validators of the provider chain by setting `top_N` appropriately, or by
additionally setting a validators-power cap, validator-set cap, etc. by using the [power-shaping parameters](../features/power-shaping.md).
:::
Comment on lines +238 to +241
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarify Use of Power-Shaping Parameters

The section mentions using power-shaping parameters to limit validator participation. It's a complex concept that might require a more detailed explanation or a dedicated section to help readers understand the implications and usage.

Tools
LanguageTool

[typographical] ~239-~239: Usually, there’s no comma before “that”. (THAT_NO_COMMA)
Context: ...015-partial-set-security.md). This means, that a standalone chain can choose to only b...


## 3. Submit an Upgrade Proposal & Prepare for Changeover

This proposal should add the ccv `consumer` module to your chain.
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/validators/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ We advise that you join the [Interchain Security testnet](https://github.com/cos
:::

At present, Interchain Security requires some or all the validators of the provider chain (ie. Cosmos Hub) to run validator nodes for a consumer chain.
Whether a validator has to run a validator node for a consumer chain depends on the consumer chain's on whether the chain is a Top N or an
Whether a validator has to run a validator node for a consumer chain depends on whether the consumer chain is a Top N or an
Opt-In chain and also on the [power-shaping features](../features/power-shaping.md). A validator can use the
[`has-to-validate` query](validators/partial-set-security-for-validators.md#which-chains-does-a-validator-have-to-validate)
[`has-to-validate` query](./partial-set-security-for-validators.md#which-chains-does-a-validator-have-to-validate)
to keep track of all the chains it has to validate.


Expand Down
Loading