Skip to content

Commit

Permalink
remove dependecies to Cosmos SDK
Browse files Browse the repository at this point in the history
  • Loading branch information
mpoke committed Jan 26, 2022
1 parent bdf3c48 commit 0d9edad
Show file tree
Hide file tree
Showing 3 changed files with 43 additions and 20 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,12 @@ This section defines the new terms and concepts introduced by CCV and provides a

> Note that in the current version 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 the [ABCI](https://docs.tendermint.com/v0.34/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).

**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 chain. For brevity, we use *provider CCV module* and *consumer CCV module* to refer to the CCV modules on the provider chain and on the consumer chain, respectively.

**CCV Channel**: A unique, ordered IBC channel (as defined in [ICS 4](../../core/ics-004-channel-and-packet-semantics)) that is used by the two CCV modules to exchange IBC packets (as defined in [ICS 4](../../core/ics-004-channel-and-packet-semantics)).
Expand All @@ -58,7 +64,9 @@ This section defines the new terms and concepts introduced by CCV and provides a
**Validator Set Change (VSC)**: A change in the validator set of the provider chain that must be reflected in the validator set of the consumer chain. 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 chain.

> **Background**: In the context of single-chain validation, the changes of the validator set are triggered by the Staking module. For more details, take a look at the [Cosmos SDK documentation](https://docs.cosmos.network/master/modules/staking/).
> **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 more details, take a look at the [Staking module documentation](https://docs.cosmos.network/master/modules/staking/) of Cosmos SDK.
**Matured VSC**: A VSC that has matured on the consumer chain, i.e., a certain period of time, known as the *unbonding period* (i.e., `UnbondingPeriod`) has elapsed since the VSC was applied by the consumer chain.

Expand All @@ -83,18 +91,22 @@ The following Figure shows an overview of the CCV Channel initialization.

![Channel Initialization Overview](./figures/ccv-init-overview.png?raw=true)

Consumer chains are created through governance proposals. For details on how governance proposals work, take a look at the [Cosmos SDK documentation](https://docs.cosmos.network/master/modules/gov/).
Consumer chains are created through governance proposals. For details on how governance proposals work, take a look at the [Governance module documentation](https://docs.cosmos.network/master/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. 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 `InitGenesis()` method of the consumer CCV module is invoked and a client of the provider chain is created (for more details on `InitGenesis()`, take a look at the [Cosmos SDK documentation](https://docs.cosmos.network/master/building-modules/genesis.html)).
For client creation, both a `ClientState` and a `ConsensusState` are necessary (as defined in [ICS 2](../../core/ics-002-client-semantics)); both are contained in the `GenesisState` of the consumer CCV module.
This `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).
Once the consumer chain starts, the application receives an `InitChain` message from the consensus engine
(for more details, take a look at the [ABCI documentation](https://docs.tendermint.com/v0.34/spec/abci/abci.html#initchain)).
The `InitChain` message triggers the call to the `InitGenesis()` method of the consumer CCV module, which creates a client of the provider chain.
For client creation, both a `ClientState` and a `ConsensusState` are necessary (as defined in [ICS 2](../../core/ics-002-client-semantics));
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 would entail the creator of the proposal to spawn the new consumer chain to distribute the `GenesisState` via the gossip network.
>
> Note that at genesis, the validator set of the consumer chain matches the validator set of the provider chain.
- **Connection handshake**: A relayer is responsible for initiating the connection handshake (as defined in [ICS 3](../../core/ics-003-connection-semantics)).
- **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)). The channel handshake must be initiated on the consumer chain. The handshake consists of four messages that need to be received for a channel built on top of the expected clients. We omit the `ChanOpenAck` message since it is not relevant for the overview.
- *OnChanOpenInit*: On receiving the *FIRST* `ChanOpenInit` message, the consumer CCV module sets the status of its end of the CCV channel to `INITIALIZING`.
- *OnChanOpenTry*: On receiving the *FIRST* `ChanOpenTry` message, the provider CCV module sets the status of its end of the CCV channel to `INITIALIZING`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,14 @@
## Assumptions
[↑ Back to Outline](#outline)

CCV lives between IBC, Cosmos SDK, and the Staking module.
As part of an ABCI application, CCV interacts with both the consensus engine (via ABCI) and other application modules, such as 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,
i.e., CCV relies on the following assumptions: *Valid Blockchain*, *Correct Relayer*, *Validator Update Provision*, and *Unbonding Safety*.

Intuitively, CCV safety relies on the *Valid Blockchain* assumption, and CCV liveness relies on the *Correct Relayer* assumption.
The *Validator Update Provision* and *Unbonding Safety* assumptions define what is needed from the provider Staking module.
A more thorough discussion of the environment in which CCV operates is given in the section [Placing CCV within Cosmos SDK](./technical_specification.md#placing-ccv-within-cosmos-sdk).
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-and-abci-application).

- ***Valid Blockchain***: Both the provider and the consumer chains are *valid*.
This means that the protocols are executed correctly and the underlying consensus algorithm satisfies both safety and liveness properties.
Expand Down
34 changes: 22 additions & 12 deletions spec/app/ics-028-cross-chain-validation/technical_specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

<!-- omit in toc -->
## Outline
- [Placing CCV within Cosmos SDK](#placing-ccv-within-cosmos-sdk)
- [Placing CCV within an ABCI Application](#placing-ccv-within-an-abci-application)
- [Data Structures](#data-structures)
- [External Data Structures](#external-data-structures)
- [CCV Data Structures](#ccv-data-structures)
Expand All @@ -16,28 +16,32 @@
- [Packet Relay](#packet-relay)
- [Validator Set Update](#validator-set-update)

## Placing CCV within Cosmos SDK
## Placing CCV within an ABCI Application
[&uparrow; Back to Outline](#outline)

Before describing the data structures and sub-protocols of the CCV protocol, we provide a short overview of the interfaces the CCV module implements and the interactions with the other Cosmos SDK modules.
Before describing the data structures and sub-protocols of the CCV protocol, we provide a short overview of the interfaces the CCV module implements and the interactions with the other ABCI application modules.

<!-- omit in toc -->
### Implemented Interfaces

- CCV is a **Cosmos SDK module**, which means it MUST implement the [AppModule interfaces](https://docs.cosmos.network/master/building-modules/module-manager.html#application-module-interfaces). Out of the methods of the AppModule interfaces, three are of particular interest to the CCV protocol:
- `InitGenesis()` -- Called at genesis, i.e., when a chain is first started.
- `ExportGenesis()` -- Called for each module when a new chain is started from the state of an existing chain.
- `EndBlock()` -- Contains logic that is automatically triggered at the end of each block. This is also where the module can inform the underlying consensus engine of changes in the validator set.
- 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 documentation](https://docs.tendermint.com/v0.34/spec/abci/abci.html)).
The following methods 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.
- `EndBlock()` -- Contains logic that is automatically triggered at the end of each block.
This is also where the module can inform the underlying consensus engine of changes in the validator set.

> TODO: `ExportGenesis()` and handling hard forks.
- CCV is an **IBC module**, which means it MUST implement the module callbacks interface defined in [ICS 26](../../core/ics-026-routing-module/README.md#module-callback-interface). The interface consists of a set of callbacks for
- channel opening handshake, which we describe in the [Initialization](#initialization) section;
- channel closing handshake, which we describe in the [Channel closing handshake](#channel-closing-handshake) section;
- channel closing handshake, which we describe in the [Channel Closing Handshake](#channel-closing-handshake) section;
- and packet relay, which we describe in the [Packet Relay](#packet-relay) section.

<!-- omit in toc -->
### Interfacing Other Modules

- As an SDK module, the CCV module interacts with the underlying consensus engine through ABCI:
- As an ABCI application module, the CCV module interacts with the underlying consensus engine through ABCI:
- On the provider chain,
- it initializes the application (e.g., binds to the expected IBC port) in the `InitGenesis()` method.
- On the consumer chain,
Expand All @@ -50,9 +54,14 @@ Before describing the data structures and sub-protocols of the CCV protocol, we
- connection semantics ([ICS 3](../../core/ics-003-connection-semantics)) via `connectionKeeper`;
- client semantics ([ICS 2](../../core/ics-002-client-semantics)) via `clientKeeper`.

- For the **Initialization** sub-protocol, the provider CCV module interacts with the [Governance module](https://docs.cosmos.network/master/modules/gov/) by handling governance proposals to spawn 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 the [Initialization sub-protocol](#initialization), the provider CCV module interacts with a Governance module by handling governance proposals to spawn 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/master/modules/gov/) of Cosmos SDK.

- For the **Validator Set Update** sub-protocol, the provider CCV module interacts with the provider [Staking module](https://docs.cosmos.network/master/modules/staking/). The interaction is defined by the following interface:
- For the [Validator Set Update sub-protocol](#validator-set-update), the provider CCV module interacts with a Staking module on the provider chain.
For an example of how staking works, take a look at the [Staking module documentation](https://docs.cosmos.network/master/modules/staking/) of Cosmos SDK.
The interaction is defined by the following interface:
```typescript
interface StakingKeeper {
// get UnbondingPeriod from the provider Staking module
Expand Down Expand Up @@ -82,7 +91,8 @@ 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 2](../../core/ics-002-client-semantics). Specifically for Tendermint clients, the data structures 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).
Specifically for Tendermint clients, the data structures are defined in [ICS 7](../../client/ics-007-tendermint-client).

### CCV Data Structures
[&uparrow; Back to Outline](#outline)
Expand Down

0 comments on commit 0d9edad

Please sign in to comment.