From 6321a5bc962f8eadfca6fb4797baadfb51773167 Mon Sep 17 00:00:00 2001 From: Shawn <44221603+smarshall-spitzbart@users.noreply.github.com> Date: Fri, 30 Jun 2023 16:53:01 -0700 Subject: [PATCH 1/5] Create adr-010-standalone-changeover.md --- .../adrs/adr-010-standalone-changeover.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/docs/adrs/adr-010-standalone-changeover.md diff --git a/docs/docs/adrs/adr-010-standalone-changeover.md b/docs/docs/adrs/adr-010-standalone-changeover.md new file mode 100644 index 0000000000..c2ab09579a --- /dev/null +++ b/docs/docs/adrs/adr-010-standalone-changeover.md @@ -0,0 +1,57 @@ +--- +sidebar_position: 11 +title: Standalone to Consumer Changeover +--- +## ADR 010: Standalone to Consumer Changeover + +## Changelog + +* 6/30/23: Feature completed, first draft of ADR. + +## Status + +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 replicated security protocol to support this changeover process. + +## Decision + + + +### Process + +Prior to the changeover, the consumer chain will have an existing staking keeper and validator set, these may be referred to as the "standalone staking keeper" and "standalone validator set respectively". + +The first step in the changeover process is to submit a ConsumerAdditionProposal. If the proposal passes, the provider will create a new IBC client for the consumer at spawn time, with the provider's validator set. A consumer genesis will also be constructed for validators to query. Within this consumer genesis contains the initial validator set for the consumer to apply after the changeover. + +The consumer will have to align it's upgrade height to happen after the provider has created the new IBC client. Any replicated security validators who will run the consumer binary, but are not a part of the sovereign validator set, must sync up a full node at this time. The disc state of said full node will be used to run the consumer chain after the changeover has completed. + +Next, the standalone consumer chain runs an upgrade which adds the CCV module, and is properly setup to execute changeover logic within endblocker. + +The meat of the changeover logic is that the consumer chain validator set is updated to that which was specified by the provider. Validators which were a part of the old set, but not the new set, are given zero power. Once these validator updates are given to Comet, the set is committed, and in effect 2 blocks later (see [FirstConsumerHeight](../../../x/ccv/consumer/keeper/changeover.go#L19)). + +A relayer then establishes the new IBC connection between the provider and consumer. The CCV channel handshake is then started on top of this new connection. Once the CCV channel is established and VSC packets are being relayed, the consumer chain is officially secured by the provider. + +### Changes to CCV Protocol + +* Consumer Genesis state is updated to include a `PreCCV` boolean. When this boolean is set true in the consumer genesis JSON, [special logic](../../../x/ccv/consumer/keeper/changeover.go) is executed on InitGenesis to trigger the changeover process on the consumer's first endblocker after the upgrade which adds the CCV module. Note that InitGenesis is not automatically called during chain upgrades, so the consumer must manually call the consumer's InitGenesis method in an upgrade handler. +* The `ConsumerAdditionProposal` type is updated to include a `DistributionTransmissionChannel` field. This field allows the consumer to use an existing IBC transfer channel to send rewards as a part of the CCV protocol. Consumers that're not changing over from a standalone chain will leave this field blank, indicating that a new transfer channel should be created on top of the same connection as the CCV channel. +* The CCV consumer keeper is updated to contain an optional reference to the standalone staking keeper. The standalone staking keeper is used to slash for infractions that happened before the changeover was completed. Ie. any infraction from a block height before the changeover, that is submitted after the changeover, will call the standalone staking keeper's slash method. Note that a changeover consumer's standalone staking keeper becomes a democracy module keeper, so it is possible for a governance token to be slashed. + +## Consequences + +### Positive + +* Existing cosmos chains are now able to onboard over to a consumer chain secured by a provider. +* The previous staking keepers for such chains can be transitioned to democracy staking module keepers. + +### Negative + +* The delineation between different types of consumers in this repo becomes less clear. Ie. there is code in the [democracy consumer's app.go](../../../app/consumer-democracy/app.go) that only applies to a previously standalone chain, but that file also serves as the base for a normal democracy consumer launched with RS from genesis. + +## References + +* EPIC: Standalone to Consumer Changeover [#756](https://github.com/cosmos/interchain-security/issues/756) +* [Changeover diagram from Stride](https://app.excalidraw.com/l/9UFOCMAZLAI/5EVLj0WJcwt) From aa1fc5f60dc5dd4423d91d8ba0f1f942f1f938b2 Mon Sep 17 00:00:00 2001 From: Shawn <44221603+smarshall-spitzbart@users.noreply.github.com> Date: Fri, 30 Jun 2023 16:54:31 -0700 Subject: [PATCH 2/5] Update adr-010-standalone-changeover.md --- docs/docs/adrs/adr-010-standalone-changeover.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/docs/adrs/adr-010-standalone-changeover.md b/docs/docs/adrs/adr-010-standalone-changeover.md index c2ab09579a..b96f9d9138 100644 --- a/docs/docs/adrs/adr-010-standalone-changeover.md +++ b/docs/docs/adrs/adr-010-standalone-changeover.md @@ -18,8 +18,6 @@ Implemented ## Decision - - ### Process Prior to the changeover, the consumer chain will have an existing staking keeper and validator set, these may be referred to as the "standalone staking keeper" and "standalone validator set respectively". From d50763b94dac2e7444ae8ae0a955d00f9fa4b9b0 Mon Sep 17 00:00:00 2001 From: Shawn <44221603+smarshall-spitzbart@users.noreply.github.com> Date: Fri, 30 Jun 2023 17:03:22 -0700 Subject: [PATCH 3/5] Update adr-010-standalone-changeover.md --- docs/docs/adrs/adr-010-standalone-changeover.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/adrs/adr-010-standalone-changeover.md b/docs/docs/adrs/adr-010-standalone-changeover.md index b96f9d9138..0d25778c4e 100644 --- a/docs/docs/adrs/adr-010-standalone-changeover.md +++ b/docs/docs/adrs/adr-010-standalone-changeover.md @@ -20,17 +20,17 @@ Implemented ### Process -Prior to the changeover, the consumer chain will have an existing staking keeper and validator set, these may be referred to as the "standalone staking keeper" and "standalone validator set respectively". +Prior to the changeover, the consumer chain will have an existing staking keeper and validator set, these may be referred to as the "standalone staking keeper" and "standalone validator set" respectively. -The first step in the changeover process is to submit a ConsumerAdditionProposal. If the proposal passes, the provider will create a new IBC client for the consumer at spawn time, with the provider's validator set. A consumer genesis will also be constructed for validators to query. Within this consumer genesis contains the initial validator set for the consumer to apply after the changeover. +The first step in the changeover process is to submit a ConsumerAdditionProposal. If the proposal passes, the provider will create a new IBC client for the consumer at spawn time, with the provider's validator set. A consumer genesis will also be constructed by the provider for validators to query. Within this consumer genesis contains the initial validator set for the consumer to apply after the changeover. -The consumer will have to align it's upgrade height to happen after the provider has created the new IBC client. Any replicated security validators who will run the consumer binary, but are not a part of the sovereign validator set, must sync up a full node at this time. The disc state of said full node will be used to run the consumer chain after the changeover has completed. +The consumer upgrade height must be reached after the provider has created the new IBC client. Any replicated security validators who will run the consumer, but are not a part of the sovereign validator set, must sync up a full node before the consumer upgrade height is reached. The disc state of said full node will be used to run the consumer chain after the changeover has completed. -Next, the standalone consumer chain runs an upgrade which adds the CCV module, and is properly setup to execute changeover logic within endblocker. +Next, the standalone consumer chain runs an upgrade which adds the CCV module, and is properly setup to execute changeover logic. -The meat of the changeover logic is that the consumer chain validator set is updated to that which was specified by the provider. Validators which were a part of the old set, but not the new set, are given zero power. Once these validator updates are given to Comet, the set is committed, and in effect 2 blocks later (see [FirstConsumerHeight](../../../x/ccv/consumer/keeper/changeover.go#L19)). +The meat of the changeover logic is that the consumer chain validator set is updated to that which was specified by the provider via the queried consumer genesis. Validators which were a part of the old set, but not the new set, are given zero voting power. Once these validator updates are given to Comet, the set is committed, and in effect 2 blocks later (see [FirstConsumerHeight](../../../x/ccv/consumer/keeper/changeover.go#L19)). -A relayer then establishes the new IBC connection between the provider and consumer. The CCV channel handshake is then started on top of this new connection. Once the CCV channel is established and VSC packets are being relayed, the consumer chain is officially secured by the provider. +A relayer then establishes the new IBC connection between the provider and consumer. The CCV channel handshake is started on top of this connection. Once the CCV channel is established and VSC packets are being relayed, the consumer chain is secured by the provider. ### Changes to CCV Protocol From f10e780df182158d95a30f7cf94588b2d0479309 Mon Sep 17 00:00:00 2001 From: Shawn <44221603+smarshall-spitzbart@users.noreply.github.com> Date: Mon, 3 Jul 2023 13:27:13 -0700 Subject: [PATCH 4/5] change order --- docs/docs/adrs/adr-010-standalone-changeover.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/adrs/adr-010-standalone-changeover.md b/docs/docs/adrs/adr-010-standalone-changeover.md index 0d25778c4e..640b80c96a 100644 --- a/docs/docs/adrs/adr-010-standalone-changeover.md +++ b/docs/docs/adrs/adr-010-standalone-changeover.md @@ -24,10 +24,10 @@ Prior to the changeover, the consumer chain will have an existing staking keeper The first step in the changeover process is to submit a ConsumerAdditionProposal. If the proposal passes, the provider will create a new IBC client for the consumer at spawn time, with the provider's validator set. A consumer genesis will also be constructed by the provider for validators to query. Within this consumer genesis contains the initial validator set for the consumer to apply after the changeover. -The consumer upgrade height must be reached after the provider has created the new IBC client. Any replicated security validators who will run the consumer, but are not a part of the sovereign validator set, must sync up a full node before the consumer upgrade height is reached. The disc state of said full node will be used to run the consumer chain after the changeover has completed. - Next, the standalone consumer chain runs an upgrade which adds the CCV module, and is properly setup to execute changeover logic. +The consumer upgrade height must be reached after the provider has created the new IBC client. Any replicated security validators who will run the consumer, but are not a part of the sovereign validator set, must sync up a full node before the consumer upgrade height is reached. The disc state of said full node will be used to run the consumer chain after the changeover has completed. + The meat of the changeover logic is that the consumer chain validator set is updated to that which was specified by the provider via the queried consumer genesis. Validators which were a part of the old set, but not the new set, are given zero voting power. Once these validator updates are given to Comet, the set is committed, and in effect 2 blocks later (see [FirstConsumerHeight](../../../x/ccv/consumer/keeper/changeover.go#L19)). A relayer then establishes the new IBC connection between the provider and consumer. The CCV channel handshake is started on top of this connection. Once the CCV channel is established and VSC packets are being relayed, the consumer chain is secured by the provider. From d5076870c16166a522fa538ec72a4502661c980f Mon Sep 17 00:00:00 2001 From: Shawn <44221603+smarshall-spitzbart@users.noreply.github.com> Date: Mon, 3 Jul 2023 13:30:04 -0700 Subject: [PATCH 5/5] permalinks --- docs/docs/adrs/adr-010-standalone-changeover.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/adrs/adr-010-standalone-changeover.md b/docs/docs/adrs/adr-010-standalone-changeover.md index 640b80c96a..17c192d1fe 100644 --- a/docs/docs/adrs/adr-010-standalone-changeover.md +++ b/docs/docs/adrs/adr-010-standalone-changeover.md @@ -28,13 +28,13 @@ Next, the standalone consumer chain runs an upgrade which adds the CCV module, a The consumer upgrade height must be reached after the provider has created the new IBC client. Any replicated security validators who will run the consumer, but are not a part of the sovereign validator set, must sync up a full node before the consumer upgrade height is reached. The disc state of said full node will be used to run the consumer chain after the changeover has completed. -The meat of the changeover logic is that the consumer chain validator set is updated to that which was specified by the provider via the queried consumer genesis. Validators which were a part of the old set, but not the new set, are given zero voting power. Once these validator updates are given to Comet, the set is committed, and in effect 2 blocks later (see [FirstConsumerHeight](../../../x/ccv/consumer/keeper/changeover.go#L19)). +The meat of the changeover logic is that the consumer chain validator set is updated to that which was specified by the provider via the queried consumer genesis. Validators which were a part of the old set, but not the new set, are given zero voting power. Once these validator updates are given to Comet, the set is committed, and in effect 2 blocks later (see [FirstConsumerHeight](https://github.com/cosmos/interchain-security/blob/f10e780df182158d95a30f7cf94588b2d0479309/x/ccv/consumer/keeper/changeover.go#L19)). A relayer then establishes the new IBC connection between the provider and consumer. The CCV channel handshake is started on top of this connection. Once the CCV channel is established and VSC packets are being relayed, the consumer chain is secured by the provider. ### Changes to CCV Protocol -* Consumer Genesis state is updated to include a `PreCCV` boolean. When this boolean is set true in the consumer genesis JSON, [special logic](../../../x/ccv/consumer/keeper/changeover.go) is executed on InitGenesis to trigger the changeover process on the consumer's first endblocker after the upgrade which adds the CCV module. Note that InitGenesis is not automatically called during chain upgrades, so the consumer must manually call the consumer's InitGenesis method in an upgrade handler. +* Consumer Genesis state is updated to include a `PreCCV` boolean. When this boolean is set true in the consumer genesis JSON, [special logic](https://github.com/cosmos/interchain-security/blob/f10e780df182158d95a30f7cf94588b2d0479309/x/ccv/consumer/keeper/changeover.go) is executed on InitGenesis to trigger the changeover process on the consumer's first endblocker after the upgrade which adds the CCV module. Note that InitGenesis is not automatically called during chain upgrades, so the consumer must manually call the consumer's InitGenesis method in an upgrade handler. * The `ConsumerAdditionProposal` type is updated to include a `DistributionTransmissionChannel` field. This field allows the consumer to use an existing IBC transfer channel to send rewards as a part of the CCV protocol. Consumers that're not changing over from a standalone chain will leave this field blank, indicating that a new transfer channel should be created on top of the same connection as the CCV channel. * The CCV consumer keeper is updated to contain an optional reference to the standalone staking keeper. The standalone staking keeper is used to slash for infractions that happened before the changeover was completed. Ie. any infraction from a block height before the changeover, that is submitted after the changeover, will call the standalone staking keeper's slash method. Note that a changeover consumer's standalone staking keeper becomes a democracy module keeper, so it is possible for a governance token to be slashed. @@ -47,7 +47,7 @@ A relayer then establishes the new IBC connection between the provider and consu ### Negative -* The delineation between different types of consumers in this repo becomes less clear. Ie. there is code in the [democracy consumer's app.go](../../../app/consumer-democracy/app.go) that only applies to a previously standalone chain, but that file also serves as the base for a normal democracy consumer launched with RS from genesis. +* The delineation between different types of consumers in this repo becomes less clear. Ie. there is code in the [democracy consumer's app.go](https://github.com/cosmos/interchain-security/blob/f10e780df182158d95a30f7cf94588b2d0479309/app/consumer-democracy/app.go) that only applies to a previously standalone chain, but that file also serves as the base for a normal democracy consumer launched with RS from genesis. ## References