From 5fced86895da9402af6415c0265b8e8c7e071289 Mon Sep 17 00:00:00 2001 From: Marius Poke Date: Tue, 25 Oct 2022 12:04:44 +0200 Subject: [PATCH] refactor proposal names (#855) --- .../data_structures.md | 12 ++-- .../ics-028-cross-chain-validation/methods.md | 60 +++++++++---------- .../overview_and_basic_concepts.md | 2 +- .../technical_specification.md | 2 +- 4 files changed, 38 insertions(+), 38 deletions(-) diff --git a/spec/app/ics-028-cross-chain-validation/data_structures.md b/spec/app/ics-028-cross-chain-validation/data_structures.md index d0125eaac..d7c3f1261 100644 --- a/spec/app/ics-028-cross-chain-validation/data_structures.md +++ b/spec/app/ics-028-cross-chain-validation/data_structures.md @@ -75,11 +75,11 @@ The CCV module is initialized through the `InitGenesis` method when the chain is - `distributionChannelId` is the ID of a token transfer channel (as defined in [ICS 20](../../app/ics-020-fungible-token-transfer)) used for the Reward Distribution sub-protocol. If `distributionChannelId == ""`, a new token transfer channel is created on top of the same connection as the CCV channel. -The provider CCV module handles governance proposals to spawn new consumer chains and to stop existing consumer chains. +The provider CCV module handles governance proposals to add new consumer chains and to remove existing consumer chains. While the structure of governance proposals is specific to every ABCI application (for an example, see the `Proposal` interface in the [Governance module documentation](https://docs.cosmos.network/v0.45/modules/gov/) of Cosmos SDK), -this specification expects the following fields to be part of the proposals to spawn new consumer chains (i.e., `SpawnConsumerChainProposal`) and to stop existing ones (i.e., `StopConsumerChainProposal`): +this specification expects the following fields to be part of the proposals to add new consumer chains (i.e., `ConsumerAdditionProposal`) and to remove existing ones (i.e., `ConsumerRemovalProposal`): ```typescript - interface SpawnConsumerChainProposal { + interface ConsumerAdditionProposal { chainId: string spawnTime: Timestamp connId: Identifier @@ -102,7 +102,7 @@ this specification expects the following fields to be part of the proposals to s - `lockUnbondingOnTimeout` is a boolean value that indicates whether the funds corresponding to the outstanding unbonding operations are to be released in case of a timeout. If `lockUnbondingOnTimeout == true`, a governance proposal to stop the timed out consumer chain would be necessary to release the locked funds. ```typescript - interface StopConsumerChainProposal { + interface ConsumerRemovalProposal { chainId: string stopTime: Timestamp } @@ -187,8 +187,8 @@ This section describes the internal state of the CCV module. For simplicity, the [↑ Back to Outline](#outline) - `ProviderPortId = "provider"` is the port ID the provider CCV module is expected to bind to. -- `pendingSpawnProposals: [SpawnConsumerChainProposal]` is a list of pending governance proposals to spawn new consumer chains. -- `pendingStopProposals: [StopConsumerChainProposal]` is a list of pending governance proposals to stop existing consumer chains. +- `pendingConsumerAdditionProposals: [ConsumerAdditionProposal]` is a list of pending governance proposals to add new consumer chains. +- `pendingConsumerRemovalProposals: [ConsumerRemovalProposal]` is a list of pending governance proposals to remove existing consumer chains. Both lists of pending governance proposals expose the following interface: ```typescript interface [Proposal] { diff --git a/spec/app/ics-028-cross-chain-validation/methods.md b/spec/app/ics-028-cross-chain-validation/methods.md index 2e664a323..a08489d38 100644 --- a/spec/app/ics-028-cross-chain-validation/methods.md +++ b/spec/app/ics-028-cross-chain-validation/methods.md @@ -378,29 +378,29 @@ function InitGenesis(state: ProviderGenesisState): [ValidatorUpdate] { - For any consumer state in the `ProviderGenesisState`, the channel ID is not valid (cf. the validation function defined in [ICS 4](../../core/ics-004-channel-and-packet-semantics)). -#### **[CCV-PCF-SPCCPROP.1]** +#### **[CCV-PCF-HCAPROP.1]** ```typescript // PCF: Provider Chain Function // implements governance proposal Handler -function SpawnConsumerChainProposalHandler(p: SpawnConsumerChainProposal) { +function HandleConsumerAdditionProposal(p: ConsumerAdditionProposal) { if currentTimestamp() > p.spawnTime { CreateConsumerClient(p) } else { - // store the proposal as a pending spawn proposal - pendingSpawnProposals.Append(p) + // store the proposal as a pending addition proposal + pendingConsumerAdditionProposals.Append(p) } } ``` - **Caller** - `EndBlock()` method of Governance module. - **Trigger Event** - - A governance proposal `SpawnConsumerChainProposal` has passed (i.e., it got the necessary votes). + - A governance proposal `ConsumerAdditionProposal` has passed (i.e., it got the necessary votes). - **Precondition** - True. - **Postcondition** - - If the spawn time has already passed, `CreateConsumerClient(p)` is invoked, with `p` the `SpawnConsumerChainProposal`. - - Otherwise, the proposal is appended to the list of pending spawn proposals, i.e., `pendingSpawnProposals`. + - If the spawn time has already passed, `CreateConsumerClient(p)` is invoked, with `p` the `ConsumerAdditionProposal`. + - Otherwise, the proposal is appended to the list of pending addition proposals, i.e., `pendingConsumerAdditionProposals`. - **Error Condition** - None. @@ -409,7 +409,7 @@ function SpawnConsumerChainProposalHandler(p: SpawnConsumerChainProposal) { ```typescript // PCF: Provider Chain Function // Utility method -function CreateConsumerClient(p: SpawnConsumerChainProposal) { +function CreateConsumerClient(p: ConsumerAdditionProposal) { // check that no other consumer chain with the same chain ID exists if p.chainId IN chainToClient.Keys() { // ignore governance proposal @@ -498,9 +498,9 @@ function CreateConsumerClient(p: SpawnConsumerChainProposal) { } ``` - **Caller** - - Either `SpawnConsumerChainProposalHandler` (see [CCV-PCF-SPCCPROP.1](#ccv-pcf-spccprop1)) or `BeginBlockInit()` (see [CCV-PCF-BBLOCK-INIT.1](#ccv-pcf-bblock-init1)). + - Either `HandleConsumerAdditionProposal` (see [CCV-PCF-HCAPROP.1](#ccv-pcf-hcaprop1)) or `BeginBlockInit()` (see [CCV-PCF-BBLOCK-INIT.1](#ccv-pcf-bblock-init1)). - **Trigger Event** - - A governance proposal `SpawnConsumerChainProposal` `p` has passed (i.e., it got the necessary votes). + - A governance proposal `ConsumerAdditionProposal` `p` has passed (i.e., it got the necessary votes). - **Precondition** - `currentTimestamp() > p.spawnTime`. - **Postcondition** @@ -525,24 +525,24 @@ function CreateConsumerClient(p: SpawnConsumerChainProposal) { - **Error Condition** - None. -> **Note:** For the case when the `clientId` field of the `SpawnConsumerChainProposal` is not set, creating a client of a remote chain requires a `ClientState` and a `ConsensusState` (for an example, take a look at [ICS 7](../../client/ics-007-tendermint-client)). +> **Note:** For the case when the `clientId` field of the `ConsumerAdditionProposal` is not set, creating a client of a remote chain requires a `ClientState` and a `ConsensusState` (for an example, take a look at [ICS 7](../../client/ics-007-tendermint-client)). > `ConsensusState` requires setting a validator set of the remote chain. > The provider chain uses the fact that the validator set of the consumer chain is the same as its own validator set. > The rest of information to create a `ClientState` it receives through the governance proposal. -> **Note:** Bootstrapping the consumer CCV module requires a `ConsumerGenesisState` (see the [CCV Data Structures](./data_structures.md#ccv-data-structures) section). The provider CCV module creates such a `ConsumerGenesisState` when handling a governance proposal `SpawnConsumerChainProposal`. +> **Note:** Bootstrapping the consumer CCV module requires a `ConsumerGenesisState` (see the [CCV Data Structures](./data_structures.md#ccv-data-structures) section). The provider CCV module creates such a `ConsumerGenesisState` when handling a governance proposal `ConsumerAdditionProposal`. #### **[CCV-PCF-BBLOCK-INIT.1]** ```typescript // PCF: Provider Chain Function function BeginBlockInit() { - // iterate over the pending spawn proposals and create + // iterate over the pending addition proposals and create // the consumer client if the spawn time has passed - foreach p IN pendingSpawnProposals { + foreach p IN pendingConsumerAdditionProposals { if currentTimestamp() > p.spawnTime { CreateConsumerClient(p) - pendingSpawnProposals.Remove(p) + pendingConsumerAdditionProposals.Remove(p) } } } @@ -554,9 +554,9 @@ function BeginBlockInit() { - **Precondition** - True. - **Postcondition** - - For each `SpawnConsumerChainProposal` `p` in the list of pending spawn proposals `pendingSpawnProposals`, if `currentTimestamp() > p.spawnTime`, then + - For each `ConsumerAdditionProposal` `p` in the list of pending addition proposals `pendingConsumerAdditionProposals`, if `currentTimestamp() > p.spawnTime`, then - `CreateConsumerClient(p)` is invoked; - - `p` is removed from `pendingSpawnProposals`. + - `p` is removed from `pendingConsumerAdditionProposals`. - **Error Condition** - None. @@ -1060,30 +1060,30 @@ function BeginBlockInit() { [↑ Back to Outline](#outline) -#### **[CCV-PCF-STCCPROP.1]** +#### **[CCV-PCF-HCRPROP.1]** ```typescript // PCF: Provider Chain Function // implements governance proposal Handler -function StopConsumerChainProposalHandler(p: StopConsumerChainProposal) { +function HandleConsumerRemovalProposal(p: ConsumerRemovalProposal) { if currentTimestamp() >= p.stopTime { // stop the consumer chain and do not lock the unbonding StopConsumerChain(p.chainId, false) } else { - // store the proposal as a pending stop proposal - pendingStopProposals.Append(p) + // store the proposal as a pending removal proposal + pendingConsumerRemovalProposals.Append(p) } } ``` - **Caller** - `EndBlock()` method of Governance module. - **Trigger Event** - - A governance proposal `StopConsumerChainProposal` has passed (i.e., it got the necessary votes). + - A governance proposal `ConsumerRemovalProposal` has passed (i.e., it got the necessary votes). - **Precondition** - True. - **Postcondition** - - If the spawn time has already passed, `StopConsumerChain(p.chainId, false)` is invoked, with `p` the `StopConsumerChainProposal`. - - Otherwise, the proposal is appended to the list of pending stop proposals, i.e., `pendingStopProposals`. + - If the stop time has already passed, `StopConsumerChain(p.chainId, false)` is invoked, with `p` the `ConsumerRemovalProposal`. + - Otherwise, the proposal is appended to the list of pending removal proposals, i.e., `pendingConsumerRemovalProposals`. - **Error Condition** - None. @@ -1128,7 +1128,7 @@ function StopConsumerChain(chainId: string, lockUnbonding: Bool) { } ``` - **Caller** - - `StopConsumerChainProposalHandler` (see [CCV-PCF-STCCPROP.1](#ccv-pcf-stccprop1)) + - `HandleConsumerRemovalProposal` (see [CCV-PCF-HCRPROP.1](#ccv-pcf-hcrprop1)) or `BeginBlockCCR()` (see [CCV-PCF-BBLOCK-CCR.1](#ccv-pcf-bblock-ccr1)) or `onTimeoutVSCPacket()` (see [CCV-PCF-TOVSC.1](#ccv-pcf-tovsc1)). - **Trigger Event** @@ -1171,13 +1171,13 @@ function StopConsumerChain(chainId: string, lockUnbonding: Bool) { ```typescript // PCF: Provider Chain Function function BeginBlockCCR() { - // iterate over the pending stop proposals + // iterate over the pending removal proposals // and stop the consumer chain - foreach p IN pendingStopProposals { + foreach p IN pendingConsumerRemovalProposals { if currentTimestamp() > p.stopTime { // stop the consumer chain and do not lock the unbonding StopConsumerChain(p.chainId, false) - pendingStopProposals.Remove(p) + pendingConsumerRemovalProposals.Remove(p) } } } @@ -1189,9 +1189,9 @@ function BeginBlockCCR() { - **Precondition** - True. - **Postcondition** - - For each `StopConsumerChainProposal` `p` in the list of pending spawn proposals `pendingStopProposals`, if `currentTimestamp() > p.stopTime`, then + - For each `ConsumerRemovalProposal` `p` in the list of pending removal proposals `pendingConsumerRemovalProposals`, if `currentTimestamp() > p.stopTime`, then - `StopConsumerChain(p.chainId, false)` is invoked; - - `p` is removed from `pendingStopProposals`. + - `p` is removed from `pendingConsumerRemovalProposals`. - **Error Condition** - None. diff --git a/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md b/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md index 0756a3281..c9b1ae01b 100644 --- a/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md +++ b/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md @@ -143,7 +143,7 @@ The following figure shows an overview of the CCV Channel initialization. Consumer chains are created through governance proposals. For an example of how governance proposals work, take a look at the [Governance module documentation](https://docs.cosmos.network/v0.45/modules/gov/) of Cosmos SDK. The channel initialization consists of four phases: -- **Create clients**: The provider CCV module handles every passed proposal to spawn a new consumer chain. +- **Create clients**: The provider CCV module handles every passed proposal to add a new consumer chain. Once it receives a proposal, it creates a client of the consumer chain (as defined in [ICS 2](../../core/ics-002-client-semantics)). Then, the operators of validators in the validator set of the provider chain must each start a full node (i.e., a validator) of the consumer chain. Once the consumer chain starts, the application receives an `InitChain` message from the consensus engine diff --git a/spec/app/ics-028-cross-chain-validation/technical_specification.md b/spec/app/ics-028-cross-chain-validation/technical_specification.md index 82e28dc66..102e7078b 100644 --- a/spec/app/ics-028-cross-chain-validation/technical_specification.md +++ b/spec/app/ics-028-cross-chain-validation/technical_specification.md @@ -47,7 +47,7 @@ Before describing the data structures and sub-protocols of the CCV protocol, we - The consumer CCV module interacts with the IBC Token Transfer module ([ICS 20](../ics-020-fungible-token-transfer/README.md)) via `transferKeeper`. -- For the [Initialization sub-protocol](#initialization), the provider CCV module interacts with a Governance module by handling governance proposals to spawn new consumer chains. +- For the [Initialization sub-protocol](#initialization), the provider CCV module interacts with a Governance module by handling governance proposals to add new consumer chains. If such proposals pass, then all validators on the provider chain MUST validate the consumer chain at spawn time; otherwise they get slashed. For an example of how governance proposals work, take a look at the [Governance module documentation](https://docs.cosmos.network/v0.45/modules/gov/) of Cosmos SDK.