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

ICS28: Remove dependency on Tendermint and ABCI #730

Merged
merged 101 commits into from
May 11, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
101 commits
Select commit Hold shift + click to select a range
604b3ae
Create README.md
mpoke Jan 17, 2022
a9b6dad
Add files with CCV spec
mpoke Jan 17, 2022
312d108
fix links to ICS 4
mpoke Jan 17, 2022
4f2b2f8
fix links to ICS 7
mpoke Jan 17, 2022
0f826ac
add ICS 28 to main README.md
mpoke Jan 17, 2022
4c4550a
adding tech spec for unbonding delegations
mpoke Jan 18, 2022
106afe0
add context on unbonding operations
mpoke Jan 18, 2022
06a2eb2
add unbonding operation diagram
mpoke Jan 19, 2022
6085697
Update spec/app/ics-028-cross-chain-validation/overview_and_basic_con…
mpoke Jan 25, 2022
d2b7377
Update spec/app/ics-028-cross-chain-validation/overview_and_basic_con…
mpoke Jan 25, 2022
b132122
Update spec/app/ics-028-cross-chain-validation/system_model_and_prope…
mpoke Jan 25, 2022
e470c84
Update spec/app/ics-028-cross-chain-validation/technical_specificatio…
mpoke Jan 25, 2022
28e7131
Update spec/app/ics-028-cross-chain-validation/README.md
mpoke Jan 25, 2022
4bdcd8b
Update spec/app/ics-028-cross-chain-validation/README.md
mpoke Jan 25, 2022
dee8d30
minor, remove confusing phrasing
mpoke Jan 25, 2022
db69640
child -> consumer; parent -> provider
mpoke Jan 25, 2022
35cdcd8
clarify which staking module
mpoke Jan 25, 2022
ab41f91
extend staking assumptions, remove redundant inv, prove staking props…
mpoke Jan 25, 2022
45b038c
modify staking hooks spec to cover other unbonding ops
mpoke Jan 20, 2022
faac42c
Merge branch 'marius/ccv-init-and-vsc' into marius/ccv-staking-hooks
mpoke Jan 25, 2022
9631aba
provider Staking module
mpoke Jan 25, 2022
4c3f2db
Merge branch 'marius/ccv-staking-hooks' of github.com:cosmos/ibc into…
mpoke Jan 25, 2022
9ef5aef
break long lines
mpoke Jan 25, 2022
bdf3c48
break long lines
mpoke Jan 25, 2022
0d9edad
remove dependecies to Cosmos SDK
mpoke Jan 26, 2022
6afb942
Merge branch 'marius/ccv-init-and-vsc' into marius/ccv-staking-hooks
mpoke Jan 26, 2022
08ceb8a
changes in the security model
mpoke Jan 27, 2022
5c7da62
specify multiple consumer chains
mpoke Jan 27, 2022
9d25746
channel init overview
mpoke Jan 27, 2022
270cae8
Merge branch 'marius/ccv-init-and-vsc' into marius/ccv-staking-hooks
mpoke Jan 27, 2022
69b0a1f
address issues #27 and #33 from cosmos/interchain-security repo
mpoke Feb 10, 2022
01b7a3b
Merge branch 'marius/ccv-staking-hooks' of github.com:cosmos/ibc into…
mpoke Feb 10, 2022
495c8db
resolve merge conflict
mpoke Feb 10, 2022
ff8c173
extend consumer InitGenesis
mpoke Feb 14, 2022
69763bc
describe mechanism to disseminate genesis state
mpoke Feb 15, 2022
7db4308
describe mapping heights provider <> consumer
mpoke Feb 15, 2022
5b0302b
remove ExportGenesis and restarted chains
mpoke Feb 16, 2022
fccb14d
add overview of consumer initiated slashing
mpoke Feb 16, 2022
51872a6
add slashing invariant
mpoke Feb 17, 2022
cb1707a
add assumptions needed by evidence
mpoke Feb 17, 2022
a09d008
Update spec/app/ics-028-cross-chain-validation/overview_and_basic_con…
mpoke Feb 17, 2022
9982f76
draft CCV props for slashing
mpoke Feb 17, 2022
744ea88
replace time w/ height; add HtoVSC and VSCtoH
mpoke Feb 17, 2022
16dc913
replace time with height in invariants and properties
mpoke Feb 17, 2022
5a873e1
validate channel IDs on provider genesis
mpoke Feb 21, 2022
263d890
prove Slashing Invariant
mpoke Feb 21, 2022
29babea
enable mapping from consumer to provider heights
mpoke Feb 21, 2022
5977701
fix conflic: merge with marius/ccv-init-genesis
mpoke Feb 21, 2022
4166744
technical spec for slashing
mpoke Feb 22, 2022
fcc1c14
minor changes
mpoke Feb 22, 2022
9902ecd
fix links to tendermint spec
mpoke Feb 23, 2022
0484d32
clarify Staking vs Slashing modules
mpoke Feb 23, 2022
bda9108
replace VSC acks w/ VSCMaturedPackets
mpoke Feb 23, 2022
ee33c48
fix some TODOs
mpoke Feb 23, 2022
c983620
fix properties
mpoke Feb 24, 2022
7283049
Merge branch 'marius/ccv' into marius/ccv-staking-hooks
mpoke Feb 24, 2022
078fa97
Merge branch 'marius/ccv-staking-hooks' into marius/ccv-init-genesis
mpoke Feb 24, 2022
44b058a
Merge branch 'marius/ccv-init-genesis' into marius/ccv-evidence
mpoke Feb 24, 2022
3221e79
HtoVSC and VSCtoH from () to []
mpoke Feb 25, 2022
7ecb10e
fix infraction height and add intuition diagram
mpoke Feb 28, 2022
110e799
resolve merge conflict
mpoke Feb 28, 2022
8b0915b
keep ValidatorSet in consumer CCV module state
mpoke Mar 7, 2022
c904c21
remove CCV channel status
mpoke Mar 7, 2022
6889441
add outstanding downtime flag and decouple from validatorSet
mpoke Mar 8, 2022
72ae68f
adressing Josef's comment
mpoke Mar 8, 2022
e4aac3e
update init methods and ics26 methods
mpoke Mar 9, 2022
754aefd
fix merge conflicts
mpoke Mar 10, 2022
4608ab5
updating ValSet Update methods
mpoke Mar 10, 2022
4b20b7a
Merge branch 'marius/ccv-evidence' into marius/668-ccv-channel-state
mpoke Mar 10, 2022
d0293b4
updating Consumer Initiated Slashing methods
mpoke Mar 10, 2022
f2fbb66
fix issues pointed by Simon
mpoke Mar 11, 2022
e0401ee
dealing with downtime slashing atomicity
mpoke Mar 11, 2022
974224c
Merge branch 'marius/ccv-evidence' into marius/668-ccv-channel-state
mpoke Mar 11, 2022
cabc738
resolve merge conflict
mpoke Mar 11, 2022
9791e36
resolve conflicts when merging base
mpoke Mar 23, 2022
1328fa4
handle pending proposals
mpoke Mar 23, 2022
31c4568
remove genesis hash
mpoke Mar 23, 2022
4f7652b
remove details of genesis state dissemination
mpoke Mar 30, 2022
b098826
add overview of reward distribution
mpoke Mar 31, 2022
043d7d9
add CCVHandshakeMetadata and update channel handshake methods signatures
mpoke Mar 31, 2022
5692d8d
initiate opening handshake for transfer channel
mpoke Mar 31, 2022
8a321e1
add DistributeRewards() method
mpoke Apr 4, 2022
2499584
resolve merge conflict
mpoke Apr 4, 2022
11b93c5
set initH in onChanOpenConfirm
mpoke Apr 4, 2022
ef06edd
address review comments
mpoke Apr 6, 2022
2a15d41
add distribution invariant
mpoke Apr 7, 2022
ed461e5
Merge branch 'marius/ccv-distribution' into marius/702-ccv-inith
mpoke Apr 7, 2022
24acf57
stopping a consumer chain
mpoke Apr 7, 2022
8ba5dc1
remove BeforeUnbondingOpCompleted hook
mpoke Apr 11, 2022
9ed8e8b
resolve merge conflict
mpoke Apr 20, 2022
ea6919b
deal with timeouts on the consumer side
mpoke Apr 20, 2022
704e9de
fix typo
mpoke Apr 29, 2022
e5e79aa
add note on how to shut down the consumer
mpoke Apr 29, 2022
3f24b4b
add note on safety implication of lockUnbondingOnTimeout
mpoke May 2, 2022
07f9243
Merge branch 'marius/651-ccv-remove-consumer' into marius/710-ccv-sta…
mpoke May 2, 2022
8c47588
update SlashPacket
mpoke May 2, 2022
dbe0590
remove mention of V2
mpoke May 2, 2022
6167bfa
remove ABCI dependency from overview; also small fixes
mpoke May 2, 2022
675a43e
remove dependencies from system model and README
mpoke May 2, 2022
42a8c9e
remove dependencies from tech spec
mpoke May 2, 2022
3728e23
resolve merge conflict
mpoke May 10, 2022
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
2 changes: 1 addition & 1 deletion spec/app/ics-028-cross-chain-validation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
[&uparrow; Back to Outline](#outline)
Expand All @@ -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).

Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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)).
Expand Down Expand Up @@ -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.
Expand All @@ -227,7 +226,7 @@ This approach is depicted in the following figure that shows an overview of the
[&uparrow; 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;
Expand All @@ -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.
Expand Down Expand Up @@ -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,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
## Assumptions
[&uparrow; 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).
Expand All @@ -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.
Expand Down
Loading