Skip to content

Commit

Permalink
Update docs (#2118)
Browse files Browse the repository at this point in the history
update docs
  • Loading branch information
ebuchman authored Jul 31, 2024
1 parent 8e38556 commit 38826fa
Show file tree
Hide file tree
Showing 2 changed files with 14 additions and 9 deletions.
15 changes: 8 additions & 7 deletions docs/docs/features/partial-set-security.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,31 @@ sidebar_position: 6

# Partial Set Security

Partial Set Security (PSS) allows consumer chains to leverage only a subset of validators from the provider chain, which offers more flexibility than the traditional Replicated Security model. By introducing the top_N parameter, each consumer chain can choose the extent of security needed:
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.

Opt-In chains, on the other hand, are more flexible. While for technical reasons, they are also currently added via governance proposals, since validators are never forced to validate these chains and simply opt in if they want to, they should typically expect to get their proposals approved much more easily compared to Top N chains, since validators that do not want to validate the chain can simply choose not to opt in.
However, opt in chains do not get a fixed amount of security as a relation of the market cap of the provider as top N chains do, so opt in chains might want to keep an eye on how many validators have opted in to validate their chain and adjust their reward emissions accordingly to incentivize validators.
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.

:::tip
Partial Set Security is handled only by the provider chain - the consumer chains are simply sent validator sets, and they are not aware that this represents only a subset of the provider chain's validator set.
:::

:::caution
Both Opt In and Top N chains currently require a governance proposal to be added to the provider chain.

For Top N chains, this is also the long term vision for how they are launched.
Top N chains always require a governance proposal because they force the top N
validators to run the chain.

For Opt In chains, this is a temporary measure 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. Eventually, the plan is to allow launching Opt In chains permissionlessly without going through governance, with quality control being handled by the market of validators deciding which chains they would like to validate on.
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).
:::
:::
8 changes: 6 additions & 2 deletions docs/docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,13 @@ import CardSection from '/src/components/Cards/CardSection';
import homeCards from '/src/components/Cards/card-data/home-cards';


# Interchain Security Docs
# Cosmos Hub - Interchain Security

Welcome to the official Interchain Security module documentation for Cosmos-SDK based chains.
Welcome to the official documentation for the Cosmos Hub's Interchain Security - a platform for launching Cosmos-SDK chains.

*The Cosmos Hub is the best place to launch a chain.*

With the recent launch of [Partial Set Security](/features/partial-set-security) (PSS), it's easier than ever to leverage the Cosmos Hub validators, stake, and community for your chain. PSS provides powerful new capabilities for permissionlessly launching your chain and [shaping your validator set](/features/power-shaping).

Here you can find information about Interchain Security, consumer chain development and instructions for validator onboarding.

Expand Down

0 comments on commit 38826fa

Please sign in to comment.