Skip to content

Commit

Permalink
ICS28: Cross-Chain Validation V1 (#666)
Browse files Browse the repository at this point in the history
* ICS 28 CCV draft w/ init and validator set update (#640)

* Create README.md

* Add files with CCV spec

* fix links to ICS 4

* fix links to ICS 7

* add ICS 28 to main README.md

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/technical_specification.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* minor, remove confusing phrasing

* child -> consumer; parent -> provider

* clarify which staking module

* extend staking assumptions, remove redundant inv, prove staking props and sys inv

* break long lines

* break long lines

* remove dependecies to Cosmos SDK

* changes in the security model

* specify multiple consumer chains

* channel init overview

* split Valid Blockchain assumption

* minor changes after discussion w/ Josef

* make the split of Valid Blockchain consistent

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Aditya <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Aditya <[email protected]>

* resolve conversations

Co-authored-by: Sergio Mena <[email protected]>
Co-authored-by: Aditya <[email protected]>

* merge CODEOWNERS from master

* ICS28: CCV draft w/ complete unbonding (#646)

* Create README.md

* Add files with CCV spec

* fix links to ICS 4

* fix links to ICS 7

* add ICS 28 to main README.md

* adding tech spec for unbonding delegations

* add context on unbonding operations

* add unbonding operation diagram

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/technical_specification.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* minor, remove confusing phrasing

* child -> consumer; parent -> provider

* clarify which staking module

* extend staking assumptions, remove redundant inv, prove staking props and sys inv

* modify staking hooks spec to cover other unbonding ops

* provider Staking module

* break long lines

* break long lines

* remove dependecies to Cosmos SDK

* changes in the security model

* specify multiple consumer chains

* channel init overview

* address issues #27 and #33 from cosmos/interchain-security repo

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

Co-authored-by: Sergio Mena <[email protected]>
Co-authored-by: Josef Widder <[email protected]>

* ICS28: Extend consumer InitGenesis (#659)

* Create README.md

* Add files with CCV spec

* fix links to ICS 4

* fix links to ICS 7

* add ICS 28 to main README.md

* adding tech spec for unbonding delegations

* add context on unbonding operations

* add unbonding operation diagram

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/technical_specification.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* minor, remove confusing phrasing

* child -> consumer; parent -> provider

* clarify which staking module

* extend staking assumptions, remove redundant inv, prove staking props and sys inv

* modify staking hooks spec to cover other unbonding ops

* provider Staking module

* break long lines

* break long lines

* remove dependecies to Cosmos SDK

* changes in the security model

* specify multiple consumer chains

* channel init overview

* address issues #27 and #33 from cosmos/interchain-security repo

* extend consumer InitGenesis

* describe mechanism to disseminate genesis state

* remove ExportGenesis and restarted chains

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

* validate channel IDs on provider genesis

Co-authored-by: Sergio Mena <[email protected]>
Co-authored-by: Josef Widder <[email protected]>

* ICS28: Consumer Initiated Slashing (aka Evidence) (#663)

* Create README.md

* Add files with CCV spec

* fix links to ICS 4

* fix links to ICS 7

* add ICS 28 to main README.md

* adding tech spec for unbonding delegations

* add context on unbonding operations

* add unbonding operation diagram

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/technical_specification.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* minor, remove confusing phrasing

* child -> consumer; parent -> provider

* clarify which staking module

* extend staking assumptions, remove redundant inv, prove staking props and sys inv

* modify staking hooks spec to cover other unbonding ops

* provider Staking module

* break long lines

* break long lines

* remove dependecies to Cosmos SDK

* changes in the security model

* specify multiple consumer chains

* channel init overview

* address issues #27 and #33 from cosmos/interchain-security repo

* extend consumer InitGenesis

* describe mechanism to disseminate genesis state

* describe mapping heights provider <> consumer

* remove ExportGenesis and restarted chains

* add overview of consumer initiated slashing

* add slashing invariant

* add assumptions needed by evidence

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

* draft CCV props for slashing

* replace time w/ height; add HtoVSC and VSCtoH

* replace time with height in invariants and properties

* validate channel IDs on provider genesis

* prove Slashing Invariant

* enable mapping from consumer to provider heights

* technical spec for slashing

* minor changes

* fix links to tendermint spec

* clarify Staking vs Slashing modules

* replace VSC acks w/ VSCMaturedPackets

* fix some TODOs

* fix properties

* HtoVSC and VSCtoH from () to []

* fix infraction height and add intuition diagram

* keep ValidatorSet in consumer CCV module state

* add outstanding downtime flag and decouple from validatorSet

* fix issues pointed by Simon

* dealing with downtime slashing atomicity

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Aditya <[email protected]>

* addressing Aditya's comments

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/technical_specification.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/technical_specification.md

Co-authored-by: Josef Widder <[email protected]>

* addressing Josef's comments

* link TODOs with issues

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Aditya <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Aditya <[email protected]>

* apply suggestions from code review

* cleanup outdated note on restarted consumer chains

Co-authored-by: Sergio Mena <[email protected]>
Co-authored-by: Josef Widder <[email protected]>
Co-authored-by: Aditya <[email protected]>

* ICS28: Remove CCV channel state (#678)

* Create README.md

* Add files with CCV spec

* fix links to ICS 4

* fix links to ICS 7

* add ICS 28 to main README.md

* adding tech spec for unbonding delegations

* add context on unbonding operations

* add unbonding operation diagram

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/technical_specification.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/README.md

Co-authored-by: Sergio Mena <[email protected]>

* minor, remove confusing phrasing

* child -> consumer; parent -> provider

* clarify which staking module

* extend staking assumptions, remove redundant inv, prove staking props and sys inv

* modify staking hooks spec to cover other unbonding ops

* provider Staking module

* break long lines

* break long lines

* remove dependecies to Cosmos SDK

* changes in the security model

* specify multiple consumer chains

* channel init overview

* address issues #27 and #33 from cosmos/interchain-security repo

* extend consumer InitGenesis

* describe mechanism to disseminate genesis state

* describe mapping heights provider <> consumer

* remove ExportGenesis and restarted chains

* add overview of consumer initiated slashing

* add slashing invariant

* add assumptions needed by evidence

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

* draft CCV props for slashing

* replace time w/ height; add HtoVSC and VSCtoH

* replace time with height in invariants and properties

* validate channel IDs on provider genesis

* prove Slashing Invariant

* enable mapping from consumer to provider heights

* technical spec for slashing

* minor changes

* fix links to tendermint spec

* clarify Staking vs Slashing modules

* replace VSC acks w/ VSCMaturedPackets

* fix some TODOs

* fix properties

* HtoVSC and VSCtoH from () to []

* fix infraction height and add intuition diagram

* keep ValidatorSet in consumer CCV module state

* remove CCV channel status

* add outstanding downtime flag and decouple from validatorSet

* adressing Josef's comment

* fix issues pointed by Simon

* dealing with downtime slashing atomicity

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Aditya <[email protected]>

* addressing Aditya's comments

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/technical_specification.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/technical_specification.md

Co-authored-by: Josef Widder <[email protected]>

* addressing Josef's comments

* link TODOs with issues

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Aditya <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Aditya <[email protected]>

* apply suggestions from code review

* cleanup outdated note on restarted consumer chains

Co-authored-by: Sergio Mena <[email protected]>
Co-authored-by: Josef Widder <[email protected]>
Co-authored-by: Aditya <[email protected]>

* Update technical_specification.md

Fix typo: VSCtoH replaced with HtoVSC in SendSlashRequest

* ICS28: Replace "Initiator" w/ "Caller" and “Trigger Event” (#696)

* update init methods and ics26 methods

* updating ValSet Update methods

* updating Consumer Initiated Slashing methods

* ICS28: Handle pending proposals to spawn consumer chains (#697)

* handle pending proposals

* ICS28: Remove genesisHash from specification (#699)

* remove genesis hash

* remove details of genesis state dissemination

* ICS28: CCV Reward Distribution subprotocol (#704)

* add overview of reward distribution

* add CCVHandshakeMetadata and update channel handshake methods signatures

* initiate opening handshake for transfer channel

* add DistributeRewards() method

* address review comments

* add distribution invariant

* replace system invariants with system properties

Co-authored-by: Josef Widder <[email protected]>

* ICS28: Set initH in onChanOpenConfirm (#705)

* set initH in onChanOpenConfirm

* replace initH with initialHeights

* ICS28: Enable the removal of a consumer chain from the provider (#707)

* stopping a consumer chain

* deal with timeouts on the consumer side

* fix typo

* add note on how to shut down the consumer

* add note on safety implication of lockUnbondingOnTimeout

* ICS28: Remove BeforeUnbondingOpCompleted (#711)

* remove BeforeUnbondingOpCompleted hook

* cleanup method names

* ICS28: Update SlashPacketData (#728)

* update SlashPacket

* ICS28: Remove dependency on Tendermint and ABCI (#730)

* remove mention of V2

* remove ABCI dependency from overview; also small fixes

* remove dependencies from system model and README

* remove dependencies from tech spec

* call UnbondMaturePackets() earlier (#747)

* fix edge case enabled by aggregation (#746)

* Use `h < hp'` instead of `h <= hp'` in Bond-Based Consumer Voting Power (#749)

* replace slashRequests w/ downtimeSlashRequests (#745)

* ics28 update sendPacket (#756)

* ICS28: Restructure technical spec (#760)

* split technical spec into two files

* restructure methods and subprotocols

* add links to readme.md

* fix typo - initH replaced w/ initialHeights

* ICS28: Unbonding ops are put on hold even w/o consumer chains (#763)

* PutUnbondingOnHold only if consumer chains exist

* Use currentTimestamp() >= p.stopTime in StopConsumerChainProposalHandler (#769)

Tackle #768

* adding consumerUnbondingPeriod (#771)

* fix sendFungibleTokens signature

* add authors

* ICS28: Removing the only consumer chain (#770)

* remove unbonding op with no consumer chains

* add postcondition

* add conditions for CreateConsumerClient and StopConsumerChain (#775)

* update created date

* ICS28: Account for slashing in Bond-Based Consumer Voting Power property (#793)

* extend Bond-Based Consumer Voting Power w/ slashing

* fix Bond-Based Consumer Voting Power formula

* expand note for clarity

* add pUnbonding

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Josef Widder <[email protected]>

* clarify mathematical writeup of property

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Josef Widder <[email protected]>

* Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md

Co-authored-by: Josef Widder <[email protected]>

* make changes to sumUnbonding / sumSlash consistent

* add history

Co-authored-by: Josef Widder <[email protected]>

Co-authored-by: Sergio Mena <[email protected]>
Co-authored-by: Aditya <[email protected]>
Co-authored-by: Josef Widder <[email protected]>
Co-authored-by: Daniel T <[email protected]>
  • Loading branch information
5 people authored Aug 9, 2022
1 parent bb068ad commit f20ba86
Show file tree
Hide file tree
Showing 22 changed files with 16,654 additions and 1 deletion.
2 changes: 1 addition & 1 deletion .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Default owners for repository
# 2/n quorum required for merge

* @mpoke @adityasripal @cwgoes @colin-axner
* @mpoke @adityasripal @cwgoes @colin-axner
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ All standards at or past the "Draft" stage are listed here in order of their ICS
| -------------------------------------------------------- | ----------------------- | ----- | --------------- |
| [20](spec/app/ics-020-fungible-token-transfer/README.md) | Fungible Token Transfer | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/apps/transfer) |
| [27](spec/app/ics-027-interchain-accounts/README.md) | Interchain Accounts | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/apps/27-interchain-accounts) |
| [28](spec/app/ics-028-cross-chain-validation/README.md) | Cross-Chain Validation | Draft | |
| [29](spec/app/ics-029-fee-payment) | General Relayer Incentivisation Mechanism | Candidate | [ibc-go](https://github.com/cosmos/ibc-go/tree/main/modules/apps/29-fee) |
| [30](spec/app/ics-030-middleware) | IBC Application Middleware | N/A | N/A |
| [721](spec/app/ics-721-nft-transfer) | Non-Fungible Token Transfer | Candidate | [bianjieai](https://github.com/bianjieai/ibc-go/tree/ics-721-nft-transfer) |
60 changes: 60 additions & 0 deletions spec/app/ics-028-cross-chain-validation/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
ics: 28
title: Cross-Chain Validation
stage: draft
category: IBC/APP
requires: 25, 26, 20
author: Marius Poke <[email protected]>, Aditya Sripal <[email protected]>, Jovan Komatovic <[email protected]>, Cezara Dragoi <[email protected]>, Josef Widder <[email protected]>
created: 2022-06-27
modified: 2022-08-03
---

<!-- omit in toc -->
# Synopsis

This standard document specifies packet data structure, state machine handling logic, and encoding details for Cross-Chain Validation (CCV). CCV is the specific IBC level protocol that enables *Interchain Security*, a Cosmos-specific category of *Shared Security*.

At a high level, CCV enables a *provider chain* (e.g., the Cosmos Hub) to provide *security* to multiple *consumer chains*. This means that the validator sets on the consumer chains are chosen from the validator set of the provider chain (for more details, see the [Security Model](./overview_and_basic_concepts.md#security-model) section).

The communication between the provider and the consumer chains is done through the IBC protocol over a *unique*, *ordered* channel (one for each consumer chain).

> Throughout this document, we will use the terms chain and blockchain interchangeably.
## Contents
- [Overview and Basic Concepts](./overview_and_basic_concepts.md)
- [System Model and Properties](./system_model_and_properties.md)
- [Technical Specification: Data Structures and Methods](./technical_specification.md)
- [Data Structures](./data_structures.md)
- [Methods](./methods.md)

<!--
## Backwards Compatibility
(discussion of compatibility or lack thereof with previous standards)
## Forwards Compatibility
-->

## Example Implementation

Interchain Security [Go implementation](https://github.com/cosmos/interchain-security).


<!--
## Other Implementations
(links to or descriptions of other implementations)
-->

## History

Jun 27, 2022 - Draft written

Aug 3, 2022 - Revision of *Bond-Based Consumer Voting Power* property

## Copyright

All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
295 changes: 295 additions & 0 deletions spec/app/ics-028-cross-chain-validation/data_structures.md

Large diffs are not rendered by default.

Loading

0 comments on commit f20ba86

Please sign in to comment.