diff --git a/spec/app/ics-028-cross-chain-validation/README.md b/spec/app/ics-028-cross-chain-validation/README.md index dc7698860..7f25ae9ba 100644 --- a/spec/app/ics-028-cross-chain-validation/README.md +++ b/spec/app/ics-028-cross-chain-validation/README.md @@ -3,7 +3,7 @@ ics: 28 title: Cross-Chain Validation stage: draft category: IBC/APP -requires: 25, 26, 7, 20 +requires: 25, 26, 20 author: created: modified: 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 57a0eef78..af67dd034 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 @@ -44,7 +44,6 @@ Similarly to the single-chain approach, when a validator starts unbonding some o yet, due to delays in the communication over the IBC protocol (e.g., due to relaying packets), the voting power is not reduced immediately on the consumer chains. A further consequence of CCV is that the tokens are unbonded only after the unbonding period has elapsed on all chains starting from the moment the corresponding voting power was reduced. Thus, CCV may delay the unbonding of tokens validators bonded on the provider chain. -For more details, take a look at the [Interchain Security light paper](https://github.com/cosmos/gaia/blob/main/docs/interchain-security.md). ## Motivation [↑ Back to Outline](#outline) @@ -55,8 +54,8 @@ CCV is a primitive (i.e., a building block) that enables arbitrary shared securi Moreover, CCV enables *hub minimalism*. In a nutshell, hub minimalism entails keeping a hub in the Cosmos network (e.g., the Cosmos Hub) as simple as possible, with as few features as possible in order to decrease the attack surface. CCV enables moving distinct features (e.g., DEX) to independent chains that are validated by the same set of validators as the hub. > **Versioning**: Note that CCV will be developed progressively. -> - The V1 release will require the validator set of a consumer chain to be entirely provided by the provider chain. In other words, once a provider chain agrees to provide security to a consumer chain, the entire validator set of the provider chain MUST validate also on the consumer chain. -> - The V2 release will allow the provider chain validators to opt-in to participate as validators on the consumer chain. It is up to each consumer chain to establish the benefits that provider chain validators receive for their participation. +> This standard document specifies the V1 release, which will require the validator set of a consumer chain to be entirely provided by the provider chain. +> In other words, once a provider chain agrees to provide security to a consumer chain, the entire validator set of the provider chain MUST validate also on the consumer chain. > > For more details on the planned releases, take a look at the [Interchain Security light paper](https://github.com/cosmos/gaia/blob/main/docs/interchain-security.md#the-interchain-security-stack). @@ -69,13 +68,15 @@ This section defines the new terms and concepts introduced by CCV. - **Consumer Chain**: The blockchain that consumes security, i.e., enables the provider chain to manage its validator set. -> Note that in the current version the validator set of the consumer chain is entirely provided by the provider chain. +> **Note**: In this specification, the validator set of the consumer chain is entirely provided by the provider chain. Both the provider and the consumer chains are [application-specific blockchains](https://docs.cosmos.network/v0.44/intro/why-app-specific.html), -i.e., the state-machine is typically connected to the underlying consensus engine via an interface called [ABCI](https://github.com/tendermint/spec/tree/v0.7.1/spec/abci). -Thus, we refer to the state-machine as an ABCI application. -For ease of presentation, this specification considers a modular paradigm, -i.e., the functionality of the ABCI application is separated into multiple modules, like the approach adopted by [Cosmos SDK](https://docs.cosmos.network/v0.44/basics/app-anatomy.html#modules). +i.e., each blockchain's state machine is typically connected to the underlying consensus engine via a *blockchain interface*, such as [ABCI](https://github.com/tendermint/spec/tree/v0.7.1/spec/abci). +The blockchain interface MUST enable the state machine to provide to the underlying consensus engine a set of validator updates, i.e., changes in the voting power granted to validators. +Although this specification is not dependent on ABCI, for ease of presentation, we refer to the state machines as ABCI applications. +Also, this specification considers a modular paradigm, +i.e., the functionality of each ABCI application is separated into multiple modules, like the approach adopted by [Cosmos SDK](https://docs.cosmos.network/v0.44/basics/app-anatomy.html#modules). + - **CCV Module**: The module that implements the CCV protocol. Both the provider and the consumer chains have each their own CCV module. Furthermore, the functionalities provided by the CCV module differ between the provider chain and the consumer chains. @@ -84,16 +85,16 @@ For brevity, we use *provider CCV module* and *consumer CCV module* to refer to - **CCV Channel**: A unique, ordered IBC channel that is used by the provider CCV module to exchange IBC packets with a consumer CCV module. Note that there is a separate CCV channel for every consumer chain. -> Note that the IBC handler interface, the IBC relayer module interface, and both IBC channels and IBC packets are as defined in [ICS 25](../../core/ics-025-handler-interface), [ICS 26](../../core/ics-026-routing-module), and [ICS 4](../../core/ics-004-channel-and-packet-semantics), respectively. +The IBC handler interface, the IBC relayer module interface, and both IBC channels and IBC packets are as defined in [ICS 25](../../core/ics-025-handler-interface), [ICS 26](../../core/ics-026-routing-module), and [ICS 4](../../core/ics-004-channel-and-packet-semantics), respectively. - **Validator Set Change (VSC)**: A change in the validator set of the provider chain that must be reflected in the validator sets of the consumer chains. -A VSC consists of a batch of validator updates, i.e., changes in the voting power granted to validators on the provider chain and, due to CCV, also on the consumer chains. +Every VSC consists of a batch of validator updates provided to the consensus engine of the provider chain. > **Background**: In the context of single-chain validation, the changes of the validator set are triggered by the *Staking module*, > i.e., a module of the ABCI application that implements the proof of stake mechanism needed by the [security model](#security-model). > For an example, take a look at the [Staking module documentation](https://docs.cosmos.network/v0.44/modules/staking/) of Cosmos SDK. -Every VSC consists of a batch of validator updates, some of which can decrease the voting power granted to validators. +Some of the validator updates can decrease the voting power granted to validators. These decreases may be a consequence of unbonding operations (e.g., unbonding delegations) on the provider chain. which MUST NOT complete before reaching maturity on both the provider and all the consumer chains, i.e., the *unbonding period* (denoted as `UnbondingPeriod`) has elapsed on both the provider and all the consumer chains. @@ -116,7 +117,7 @@ Thus, a *VSC reaching maturity* on a consumer chain means that all the unbonding - **Slash Request**: A request by a consumer chain to *slash* the tokens bonded by a validator on the provider chain as a consequence of that validator misbehavior on the consumer chain. A slash request MAY also result in the misbehaving validator being *jailed* for a period of time, during which it cannot be part of the validator set. > **Background**: In the context of single-chain validation, slashing and jailing misbehaving validators is handled by the *Slashing module*, -> i.e., a module of the ABCI application that enables the application to decentivize misbehaving validators. +> i.e., a module of the ABCI application that enables the application to discourage misbehaving validators. > For an example, take a look at the [Slashing module documentation](https://docs.cosmos.network/v0.44/modules/slashing/) of Cosmos SDK. ## Overview @@ -150,8 +151,6 @@ The channel initialization consists of four phases: both are contained in the `GenesisState` of the consumer CCV module. The `GenesisState` is distributed to all operators that need to start a full node of the consumer chain (the mechanism of distributing the `GenesisState` is outside the scope of this specification). - > Note that although the mechanism of distributing the `GenesisState` is outside the scope of this specification, a possible approach is described in the [technical specification](./technical_specification.md#ccv-ccf-initg1). - > > Note that at genesis, the validator set of the consumer chain matches the validator set of the provider chain. - **Connection handshake**: A relayer (as defined in [ICS 18](../../relayer/ics-018-relayer-algorithms)) is responsible for initiating the connection handshake (as defined in [ICS 3](../../core/ics-003-connection-semantics)). - **Channel handshake**: A relayer is responsible for initiating the channel handshake (as defined in [ICS 4](../../core/ics-004-channel-and-packet-semantics)). @@ -201,10 +200,10 @@ In the context of CCV, the completion MUST require also the unbonding operation Therefore, the provider Staking module needs to be aware of the VSC maturity notifications registered by the provider CCV module. The ***provider chain*** achieves this through the following approach: -- The provider Staking module is notifying the CCV module when any unbonding operation is initiated. +- The Staking module is notifying the CCV module when any unbonding operation is initiated. As a result, the CCV module maps all the unbonding operations to the corresponding VSCs. -- When the CCV module registers maturity notifications for a VSC from all consumer chains, it notifies the provider Staking module of the maturity of all unbonding operations mapped to this VSC. - This enables the provider Staking module to complete the unbonding operations only when they reach maturity on both the provider chain and on all the consumer chains. +- When the CCV module registers maturity notifications for a VSC from all consumer chains, it notifies the Staking module of the maturity of all unbonding operations mapped to this VSC. + This enables the Staking module to complete the unbonding operations only when they reach maturity on both the provider chain and on all the consumer chains. This approach is depicted in the following figure that shows an overview of the interface between the provider CCV module and the provider Staking module in the context of the Validator Set Update operation of CCV: - In `Block 1`, two unbonding operations are initiated (i.e., `undelegate-1` and `redelegate-1`) in the provider Staking module. @@ -227,7 +226,7 @@ This approach is depicted in the following figure that shows an overview of the [↑ Back to Outline](#outline) For the [Security Model](#security-model) to be preserved, misbehaving validators MUST be slashed (and MAY be jailed, i.e., removed from the validator set). -A prerequisite to slash validators is to receive valid evidence of their misbehavior. +A prerequisite to slashing validators is to receive valid evidence of their misbehavior. Thus, when slashing a validator, we distinguish between three events and the heights when they occur: - `infractionHeight`, the height at which the misbehavior (or infraction) happened; - `evidenceHeight`, the height at which the evidence of misbehavior is received; @@ -237,8 +236,7 @@ Thus, when slashing a validator, we distinguish between three events and the hei The [Security Model](#security-model) guarantees that any misbehaving validator can be slashed for at least the unbonding period, i.e., as long as that validator's tokens are not unbonded yet, they can be slashed. -However, if the tokens start unbonding before `infractionHeight`, i.e., the tokens did not contribute to the voting power that committed the infraction, -then the tokens MUST NOT be slashed. +However, if the tokens start unbonding before `infractionHeight` (i.e., the tokens did not contribute to the voting power that committed the infraction) then the tokens MUST NOT be slashed. In the context of CCV, validators (with tokens bonded on the provider chain) MUST be slashed for infractions committed on the consumer chains at heights for which they have voting power. Thus, although the infractions are committed on the consumer chains and evidence of these infractions is submitted to the consumer chains, the slashing happens on the provider chain. As a result, the Consumer Initiated Slashing operation requires, for every consumer chain, a mapping from consumer chain block heights to provider chain block heights. @@ -299,7 +297,7 @@ The operation consists of two steps that are depicted in the following figure: ![Reward Distribution](./figures/ccv-distribution-overview.png?raw=true) - At the beginning of every block on the consumer chain, a fraction of the rewards are transferred to an account on the consumer CCV module. -- At regular intervals (e.g., every `100` blocks), the consumer CCV module sends the accumulated rewards to the distribution module account on the provider chain through an IBC token transfer packet (as defined in [ICS 20](../ics-020-fungible-token-transfer/README.md)). +- At regular intervals (e.g., every `1000` blocks), the consumer CCV module sends the accumulated rewards to the distribution module account on the provider chain through an IBC token transfer packet (as defined in [ICS 20](../ics-020-fungible-token-transfer/README.md)). Note that the IBC transfer packet is sent over a separate unordered channel. As a result, the reward distribution is not synchronized with the other CCV operations, e.g., some validators may miss out on some rewards by unbonding before an IBC transfer packet is received, diff --git a/spec/app/ics-028-cross-chain-validation/system_model_and_properties.md b/spec/app/ics-028-cross-chain-validation/system_model_and_properties.md index fb0e8c040..17c5772e0 100644 --- a/spec/app/ics-028-cross-chain-validation/system_model_and_properties.md +++ b/spec/app/ics-028-cross-chain-validation/system_model_and_properties.md @@ -18,7 +18,7 @@ ## Assumptions [↑ Back to Outline](#outline) -As part of an ABCI application, CCV interacts with both the consensus engine (via ABCI) and other application modules (e.g, the Staking module). +As part of a modular ABCI application, CCV interacts with both the consensus engine (via ABCI) and other application modules (e.g, the Staking module). As an IBC application, CCV interacts with external relayers (defined in [ICS 18](../../relayer/ics-018-relayer-algorithms)). In this section we specify what we assume about these other components. A more thorough discussion of the environment in which CCV operates is given in the section [Placing CCV within an ABCI Application](./technical_specification.md#placing-ccv-within-an-abci-application). @@ -30,13 +30,13 @@ i.e., neither *Live Blockchain* and *Correct Relayer* are required for safety. Note though that CCV liveness relies on both *Live Blockchain* and *Correct Relayer* assumptions; furthermore, the *Correct Relayer* assumption relies on both *Safe Blockchain* and *Live Blockchain* assumptions. > -> The *Validator Update Provision*, *Unbonding Safety*, and *Slashing Warranty* assumptions define what is needed from the ABCI application of the provider chain. +> The *Validator Update Provision*, *Unbonding Safety*, *Slashing Warranty*, and *Distribution Warranty* assumptions define what is needed from the ABCI application of the provider chain. > > The *Evidence Provision* assumptions defines what is needed from the ABCI application of the consumer chains. - ***Safe Blockchain***: Both the provider and the consumer chains are *safe*. This means that, for every chain, the underlying consensus engine satisfies safety (e.g., the chain does not fork) and the execution of the state machine follows the described protocol. - ***Live Blockchain***: Both the provider and the consumer chains are *live*. This means that, for every chain, the underlying consensus engine satisfies liveness (i.e., new blocks are eventually added to the chain). - > **Note**: Both *Safe Blockchain* and *Live Blockchain* assumptions require the consensus engine's assumptions to hold, e.g., less than a third of the voting power is Byzantine. For more details, take a look at the [Tendermint Paper](https://arxiv.org/pdf/1807.04938.pdf). + > **Note**: Both *Safe Blockchain* and *Live Blockchain* assumptions require the consensus engine's assumptions to hold, e.g., less than a third of the voting power is Byzantine. For an example, take a look at the [Tendermint Paper](https://arxiv.org/pdf/1807.04938.pdf). - ***Correct Relayer***: There is at least one *correct*, *live* relayer between the provider and consumer chains. This assumption has two implications. - First, every packet sent on the CCV channel is relayed to the receiving end before the packet timeout elapses. 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 f8c451e5b..824610ce7 100644 --- a/spec/app/ics-028-cross-chain-validation/technical_specification.md +++ b/spec/app/ics-028-cross-chain-validation/technical_specification.md @@ -26,8 +26,8 @@ Before describing the data structures and sub-protocols of the CCV protocol, we ### Implemented Interfaces -- CCV is an **ABCI application module**, which means it MUST implement the logic to handle some of the messages received from the consensus engine via ABCI, e.g., `InitChain`, `EndBlock` - (for more details, take a look at the [ABCI specification](https://github.com/tendermint/spec/tree/v0.7.1/spec/abci)). +- CCV is an **ABCI application module**, which means it MUST implement the logic to handle some of the messages received from the consensus engine via ABCI, + e.g., `InitChain`, `BeginBlock`, `EndBlock` (for more details, take a look at the [ABCI specification](https://github.com/tendermint/spec/tree/v0.7.1/spec/abci)). In this specification we define the following methods that handle messages that are of particular interest to the CCV protocol: - `InitGenesis()` -- Called when the chain is first started, on receiving an `InitChain` message from the consensus engine. This is also where the application can inform the underlying consensus engine of the initial validator set. @@ -140,7 +140,11 @@ interface ValidatorUpdate { ``` The provider chain sends to the consumer chain a list of `ValidatorUpdate`s, containing an entry for every validator that had its power updated. -The data structures required for creating clients (i.e., `ClientState`, `ConsensusState`) are defined in [ICS 7](../../client/ics-007-tendermint-client). +The data structures required for creating clients (i.e., `ClientState`, `ConsensusState`) are defined in [ICS 2](../../core/ics-002-client-semantics). +In the context of CCV, every chain is uniquely defined by their chain ID and the validator set. +Thus, CCV requires the `ClientState` to contain the chain ID and the `ConsensusState` for a particular height to contain the validator set at that height. +In addition, the `ClientState` should contain the `UnbondingPeriod`. +For an example, take a look at the `ClientState` and `ConsensusState` defined in [ICS 7](../../client/ics-007-tendermint-client). ### CCV Data Structures [↑ Back to Outline](#outline) @@ -181,7 +185,8 @@ this specification expects the following fields to be part of the proposals to s } ``` - `chainId` is the proposed chain ID of the new consumer chain. It must be different from all other consumer chain IDs of the executing provider chain. - - `initialHeight` is the proposed initial height of new consumer chain. Note that `Height` is defined in [ICS 7](../../client/ics-007-tendermint-client). For a completely new chain, `initialHeight = {0,1}`; however, it may be different if the chain converts to a consumer chain. + - `initialHeight` is the proposed initial height of new consumer chain. + For an example, take a look at the `Height` defined in [ICS 7](../../client/ics-007-tendermint-client). - `spawnTime` is the time on the provider chain at which the consumer chain genesis is finalized and all validators are responsible to start their consumer chain validator node. - `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. In case `lockUnbondingOnTimeout == true`, a governance proposal to stop the timed out consumer chain would be necessary to release the locked funds. ```typescript @@ -476,29 +481,22 @@ function SpawnConsumerChainProposalHandler(p: SpawnConsumerChainProposal) { // PCF: Provider Chain Function // Utility method function CreateConsumerClient(p: SpawnConsumerChainProposal) { - // get UnbondingPeriod from provider Staking module - // TODO governance and CCV params - // see https://github.com/cosmos/ibc/issues/673 - unbondingTime = stakingKeeper.UnbondingTime() - - // create client state as defined in ICS 7 + // create client state clientState = ClientState{ chainId: p.chainId, - trustLevel: DefaultTrustLevel, // i.e., 1/3 - trustingPeriod: unbondingTime/2, - unbondingPeriod: unbondingTime, + // get UnbondingPeriod from provider Staking module + // TODO governance and CCV params + // see https://github.com/cosmos/ibc/issues/673 + unbondingPeriod: stakingKeeper.UnbondingTime(), + // the height when the client was last updated latestHeight: p.initialHeight, } - // create consensus state as defined in ICS 7; - // SentinelRoot is used as a stand-in root value for - // the consensus state set at the upgrade height; + // create consensus state; // the validator set is the same as the validator set // from own consensus state at current height ownConsensusState = getConsensusState(getCurrentHeight()) consensusState = ConsensusState{ - timestamp: currentTimestamp(), - commitmentRoot: SentinelRoot, validatorSet: ownConsensusState.validatorSet, } @@ -517,15 +515,14 @@ function CreateConsumerClient(p: SpawnConsumerChainProposal) { - **Precondition** - `currentTimestamp() > p.spawnTime`. - **Postcondition** - - `UnbondingPeriod` is retrieved from the provider Staking module. - - A client state is created (as defined in [ICS 7](../../client/ics-007-tendermint-client)). - - A consensus state is created (as defined in [ICS 7](../../client/ics-007-tendermint-client)). + - A client state is created with `chainId = p.chainId` and `unbondingPeriod` set to the `UnbondingPeriod` obtained from the provider Staking module. + - A consensus state is created with `validatorSet` set to the validator set the provider chain own consensus state at current height. - A client of the consumer chain is created and the client ID is added to `chainToClient`. - `lockUnbondingOnTimeout[p.chainId]` is set to `p.lockUnbondingOnTimeout`. - **Error Condition** - None. -> **Note:** Creating a client of a remote chain requires a `ClientState` and a `ConsensusState` (as defined in [ICS 7](../../client/ics-007-tendermint-client)). +> **Note:** 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. @@ -795,7 +792,7 @@ function InitGenesis(gs: ConsumerGenesisState): [ValidatorUpdate] { // - contains a non-empty initial validator set abortSystemUnless(gs.initialValSet NOT empty) // - contains an initial validator set that matches - // the validator set in the providerConsensusState (see ICS 7) + // the validator set in the providerConsensusState (e.g., ICS 7) abortSystemUnless(gs.initialValSet == gs.providerConsensusState.validatorSet) // bind to ConsumerPortId port @@ -837,8 +834,8 @@ function InitGenesis(gs: ConsumerGenesisState): [ValidatorUpdate] { - The `validatorSet` mapping is populated with the initial validator set. - The initial validator set is returned to the consensus engine. - **Error Condition** - - The genesis state contains no valid provider client state, where the validity is defined as in [ICS 7](../../client/ics-007-tendermint-client). - - The genesis state contains no valid provider consensus state, where the validity is defined as in [ICS 7](../../client/ics-007-tendermint-client). + - The genesis state contains no valid provider client state, where the validity is defined in the corresponding client specification (e.g., [ICS 7](../../client/ics-007-tendermint-client)). + - The genesis state contains no valid provider consensus state, where the validity is defined in the corresponding client specification (e.g., [ICS 7](../../client/ics-007-tendermint-client)).. - The genesis state contains an empty initial validator set. - The genesis state contains an initial validator set that does not match the validator set in the provider consensus state. - The capability for the port `ConsumerPortId` cannot be claimed. @@ -2039,10 +2036,10 @@ function SendSlashRequest( - None. > **Note**: The ABCI application MUST subtract `ValidatorUpdateDelay` from the infraction height before invoking `SendSlashRequest`, -> where `ValidatorUpdateDelay` is a delay (in blocks) between when validator updates are returned to the consensus-engine and when they are applied -> (for more details, take a look at the [ABCI specification](https://github.com/tendermint/spec/blob/v0.7.1/spec/abci/abci.md#endblock)). +> where `ValidatorUpdateDelay` is a delay (in blocks) between when validator updates are returned to the consensus-engine and when they are applied. > For example, if `ValidatorUpdateDelay = x` and a validator set update is returned with new validators at the end of block `10`, -> then the new validators are expected to sign blocks beginning at block `11+x`. +> then the new validators are expected to sign blocks beginning at block `11+x` +> (for more details, take a look at the [ABCI specification](https://github.com/tendermint/spec/blob/v0.7.1/spec/abci/abci.md#endblock)). > > Consequently, the consumer CCV module expects the `infractionHeight` parameter of the `SendSlashRequest()` to be set accordingly.