diff --git a/.github/PULL_REQUEST_TEMPLATE/production.md b/.github/PULL_REQUEST_TEMPLATE/production.md index d8151fe707..dc614480b4 100644 --- a/.github/PULL_REQUEST_TEMPLATE/production.md +++ b/.github/PULL_REQUEST_TEMPLATE/production.md @@ -23,7 +23,7 @@ I have... * [ ] Confirmed this PR does not introduce changes requiring state migrations, OR migration code has been added to consumer and/or provider modules * [ ] Targeted the correct branch (see [PR Targeting](https://github.com/cosmos/interchain-security/blob/main/CONTRIBUTING.md#pr-targeting)) * [ ] Provided a link to the relevant issue or specification -* [ ] Followed the guidelines for [building SDK modules](https://github.com/cosmos/cosmos-sdk/blob/main/docs/docs/building-modules) +* [ ] Followed the guidelines for [building SDK modules](https://github.com/cosmos/cosmos-sdk/blob/main/docs/build/building-modules/00-intro.md) * [ ] Included the necessary unit and integration [tests](https://github.com/cosmos/interchain-security/blob/main/CONTRIBUTING.md#testing) * [ ] Added a changelog entry to `CHANGELOG.md` * [ ] Included comments for [documenting Go code](https://blog.golang.org/godoc) diff --git a/.github/workflows/md-link-checker.yml b/.github/workflows/md-link-checker.yml index 981bc1b601..136475f428 100644 --- a/.github/workflows/md-link-checker.yml +++ b/.github/workflows/md-link-checker.yml @@ -2,12 +2,26 @@ name: Check Markdown links on: pull_request: paths: - - "**.md" - - "!.github/**" - - "!.changelog/**" + - "*.md" + - "docs/docs/**.md" jobs: - markdown-link-check: + repo-root: runs-on: ubuntu-latest steps: + # Check out the latest version of the code - uses: actions/checkout@v4 - - uses: gaurav-nelson/github-action-markdown-link-check@1.0.15 \ No newline at end of file + # Checks the status of hyperlinks in *.md files in the repo root + - uses: gaurav-nelson/github-action-markdown-link-check@1.0.15 + with: + folder-path: '.' + max-depth: 1 + + docs: + runs-on: ubuntu-latest + steps: + # Check out the latest version of the code + - uses: actions/checkout@v4 + # Checks the status of hyperlinks in *.md files in the docs/docs folder + - uses: gaurav-nelson/github-action-markdown-link-check@1.0.15 + with: + folder-path: 'docs/docs' diff --git a/CHANGELOG.md b/CHANGELOG.md index aa1db086d1..ea360f3039 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -161,9 +161,9 @@ Date: June 1st, 2023 Unlike prior releases, the ICS `v2.0.0` release will be based on the main branch. `v2.0.0` will contain all the accumulated PRs from the various releases below, along with other PRs that were merged, but not released to production. After `v2.0.0`, we plan to revamp release practices, and how we modularize the repo for consumer/provider. -Upgrading a provider from `v1.1.0-multiden` to `v2.0.0` will require state migrations. See [migration.go](./x/ccv/provider/keeper/migration.go). See the provider module's `ConsensusVersion` in [module](./x/ccv/provider/module.go) +Upgrading a provider from `v1.1.0-multiden` to `v2.0.0` will require state migrations. See [migration.go](x/ccv/provider/keeper/migration.go). See the provider module's `ConsensusVersion` in [module](x/ccv/provider/module.go) -Upgrading a consumer from `v1.2.0-multiden` to `v2.0.0` will NOT require state migrations. See the consumer module's `ConsensusVersion` in [module](./x/ccv/consumer/module.go) +Upgrading a consumer from `v1.2.0-multiden` to `v2.0.0` will NOT require state migrations. See the consumer module's `ConsensusVersion` in [module](x/ccv/consumer/module.go) Some PRs from v2.0.0 may reappear from other releases below. This is due to the fact that ICS v1.1.0 deviates from the commit ordering of the main branch, and other releases thereafter are based on v1.1.0. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 90456c842f..1e6643bbeb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -109,7 +109,7 @@ If your architecture decision is a simple change, you may contribute directly wi In certain circumstances, the architecture decision may require changes to the ICS spec. Note that the spec is responsible for defining language-agnostic, implementation-agnostic behaviors for the ICS protocol. Whereas ADRs are responsible for communicating implementation decisions contained within this repo. -To create an ADR, follow the [template](./docs/docs/adrs/adr-template.md) and [doc](./docs/docs/adrs/Readme.md). If you would like to see examples of how these are written, please refer to the current [ADRs](https://github.com/cosmos/interchain-security/tree/main/docs/architecture). +To create an ADR, follow the [template](docs/docs/adrs/adr-template.md) and [doc](docs/docs/adrs/intro.md). If you would like to see examples of how these are written, please refer to the current [ADRs](docs/docs/adrs). ### ADR Proposals @@ -149,7 +149,7 @@ will do it anyway using a pre-configured setup of the programming language mode) ### Testing -Appropriate tests should be written with a new feature, and all existing tests should pass. See [docs/testing.md](./docs/old/testing.md) for more information. +Appropriate tests should be written with a new feature, and all existing tests should pass. See [docs/testing.md](TESTING.md) for more information. ### Pull Requests diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index a09f9a4ba7..67c8bec990 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -14,12 +14,16 @@ ❗ ***Note this release is ONLY relevant to *** ## 📝 Changelog +** REMOVE THE LINE BELOW TO ENABLE THE MARKDOWN LINK CHECKER FOR RELEASE ** + Check out the [changelog](https://github.com/cosmos/interchain-security/blob//CHANGELOG.md) for a list of relevant changes or [compare all changes](https://github.com/cosmos/interchain-security/compare/release/...) from last release. Refer to the [upgrading guide](https://github.com/cosmos/interchain-security/blob/release//UPGRADING.md) when migrating from `` to ``. +** REMOVE THE LINE BELOW TO ENABLE THE MARKDOWN LINK CHECKER FOR RELEASE ** + ## 🚀 Highlights diff --git a/STATE-COMPATIBILITY.md b/STATE-COMPATIBILITY.md index b62c00c7a4..a68d813be2 100644 --- a/STATE-COMPATIBILITY.md +++ b/STATE-COMPATIBILITY.md @@ -86,7 +86,7 @@ in CometBFT [v0.34.29](https://github.com/cometbft/cometbft/releases/tag/v0.34.2 > This is an error code that is returned by the transaction flow. In the case of > success, it is `0`. On a general error, it is `1`. Additionally, each module > defines its custom error codes. - > For example, `x/provider` currently has [these error codes](./x/ccv/provider/types/errors.go) defined. + > For example, `x/provider` currently has [these error codes](x/ccv/provider/types/errors.go) defined. > > As a result, it is important to avoid changing custom error codes or change > the semantics of what is valid logic in transaction flows. diff --git a/TESTING.md b/TESTING.md index 40117f9127..bb05ff9f1c 100644 --- a/TESTING.md +++ b/TESTING.md @@ -6,21 +6,21 @@ To increase confidence in the correctness of the Interchain Security code we con Unit tests are useful for simple standalone functionality, and CRUD operations. Unit tests should use golang's standard testing package, and be defined in files formatted as ```_test.go``` in the same directory as the file being tested, following standard conventions. -[Mocked external keepers](../../testutil/keeper/mocks.go) (implemented with [gomock](https://github.com/golang/mock)) are available for testing code that briefly interacts with external modules, but still only a single function/method relevant to ccv, and a single chain. Ie. do not use mocked external keepers to test the integration of the ccv module with external modules, or integration between consumer and provider. +[Mocked external keepers](testutil/keeper/mocks.go) (implemented with [gomock](https://github.com/golang/mock)) are available for testing code that briefly interacts with external modules, but still only a single function/method relevant to ccv, and a single chain. Ie. do not use mocked external keepers to test the integration of the ccv module with external modules, or integration between consumer and provider. ## Integration Tests -[integration-tests](../../tests/integration/) utilize the [IBC Testing Package](https://github.com/cosmos/ibc-go/tree/main/testing), and test functionality that is wider in scope than a unit test, but still able to be validated in-memory. Ie. code where advancing blocks would be useful, simulated handshakes, simulated packet relays, etc. +[integration-tests](tests/integration/) utilize the [IBC Testing Package](https://github.com/cosmos/ibc-go/tree/main/testing), and test functionality that is wider in scope than a unit test, but still able to be validated in-memory. Ie. code where advancing blocks would be useful, simulated handshakes, simulated packet relays, etc. -To run integration tests against your own consumer/provider implementations, use [instance_test.go](../../tests/integration/instance_test.go) as an example. All you'll need to do is make sure your applications implement the necessary interfaces defined in [interfaces.go](../../testutil/integration/interfaces.go), pattern match [specific_setup.go](../../testutil/ibc_testing/specific_setup.go), then pass in the appropriate types and parameters to the suite, as is done in `instance_test.go` for the dummy provider/consumer implementations. +To run integration tests against your own consumer/provider implementations, use [instance_test.go](tests/integration/instance_test.go) as an example. All you'll need to do is make sure your applications implement the necessary interfaces defined in [interfaces.go](testutil/integration/interfaces.go), pattern match [specific_setup.go](testutil/ibc_testing/specific_setup.go), then pass in the appropriate types and parameters to the suite, as is done in `instance_test.go` for the dummy provider/consumer implementations. ## Differential Tests (WIP) -[Differential tests](../../tests/difference/) is similar to integration tests, but they compare the system state to an expected state generated from a model implementation. +[Differential tests](tests/difference/) is similar to integration tests, but they compare the system state to an expected state generated from a model implementation. ## End-to-End (E2E) Tests -[E2E tests](../../tests/e2e/) run true consumer and provider chain binaries within a docker container and are relevant to the highest level of functionality. E2E tests use queries/transactions invoked from CLI to drive and validate the code. +[E2E tests](tests/e2e/) run true consumer and provider chain binaries within a docker container and are relevant to the highest level of functionality. E2E tests use queries/transactions invoked from CLI to drive and validate the code. ## Running Tests Tests can be run using `make`: @@ -103,7 +103,7 @@ gofmt -w -s -e . go vet ./... ``` -Some useful tools are included in the repository using [pre-commit](https://pre-commit.com/hooks.html). pre-commit lets you run developer tools either on every git commit, or manually with `pre-commit run --all-files`. See the [config](../../.pre-commit-config.yaml) for details. In this repo the hooks are not installed to git, as that can be cumbersome, but it is still possible to benefit from them. +Some useful tools are included in the repository using [pre-commit](https://pre-commit.com/hooks.html). pre-commit lets you run developer tools either on every git commit, or manually with `pre-commit run --all-files`. See the [config](.pre-commit-config.yaml) for details. In this repo the hooks are not installed to git, as that can be cumbersome, but it is still possible to benefit from them. ```bash ## Prerequisites diff --git a/UPGRADING.md b/UPGRADING.md index 588a135bdb..347511a902 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -10,7 +10,7 @@ The following should be considered as complementary to [Cosmos SDK v0.47 UPGRADI #### Protobuf -Protobuf code generation, linting and formatting have been updated to leverage the `ghcr.io/cosmos/proto-builder:0.11.5` docker container. Replicated Security protobuf definitions are now packaged and published to [buf.build/cosmos/interchain-security](buf.build/cosmos/interchain-security) via CI workflows. The `third_party/proto` directory has been removed in favour of dependency management using [buf.build](https://docs.buf.build/introduction). +Protobuf code generation, linting and formatting have been updated to leverage the `ghcr.io/cosmos/proto-builder:0.11.5` docker container. Replicated Security protobuf definitions are now packaged and published to [buf.build/cosmos/interchain-security](https://buf.build/cosmos/interchain-security) via CI workflows. The `third_party/proto` directory has been removed in favour of dependency management using [buf.build](https://docs.buf.build/introduction). #### App modules @@ -66,8 +66,8 @@ import ( ### Provider -Upgrading a provider from `v1.1.0-multiden` to `v2.0.0` will require state migrations. See [migration.go](./x/ccv/provider/keeper/migration.go). See the provider module's `ConsensusVersion` in [module](./x/ccv/provider/module.go). +Upgrading a provider from `v1.1.0-multiden` to `v2.0.0` will require state migrations. See [migration.go](x/ccv/provider/keeper/migration.go). See the provider module's `ConsensusVersion` in [module](x/ccv/provider/module.go). ### Consumer -Upgrading a consumer from `v1.2.0-multiden` to `v2.0.0` will NOT require state migrations. See the consumer module's `ConsensusVersion` in [module](./x/ccv/consumer/module.go). \ No newline at end of file +Upgrading a consumer from `v1.2.0-multiden` to `v2.0.0` will NOT require state migrations. See the consumer module's `ConsensusVersion` in [module](x/ccv/consumer/module.go). \ No newline at end of file diff --git a/tests/difference/core/README.md b/tests/difference/core/README.md deleted file mode 100644 index 1d9bbf04e2..0000000000 --- a/tests/difference/core/README.md +++ /dev/null @@ -1,135 +0,0 @@ -# Differential testing for Interchain Security 'core' protocol - -This directory contains model and trace generation code for the differential approach to testing Interchain Security. In particular, this work is used to test 'core' (normal operation) features of the protocol. - -At a high level, the model consists of one Provider chain and one Consumer chain. There is a single delegator account on the Provider, whose actions will change the delegation and thus the tokens and voting power of the validators. The voting power changes are relayed to the Consumer chain. The entire cycle of unbonding operation maturity is captured, because the Consumer will send unbonding maturity packets. Moreoever, slashing is modelled, as the Consumer can initiate slashing actions. - -## Scope - -### Tested (Unchecked means that work is in progress. Checked means the work is complete.) - -The following aspects of the system are tested - -- [x] Sending VSC packets from provider to one consumer -- [x] Sending VSC maturities from one consumer to provider -- [x] Slashing logic (not including actual token burning) -- [x] Validator power change -- [x] Validators leaving or joining the active validor set -- [x] Consumer initiated slashing -- [x] Delegation operations -- [x] Undelegation operations -- [x] Validator unbonding -- [x] Valiator jailing -- [x] Validator tombstoning -- [x] Packet acknowledgements -- [x] The 'Bond Based Consumer Voting Power' property ([link](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/system_model_and_properties.md#system-properties)) -- [x] The 'Validator Set Replication' property ([link](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/system_model_and_properties.md#system-properties)) -- [ ] The 'Slashable Consumer Misbehavior' property ([link](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/system_model_and_properties.md#system-properties)) (_maybe_) -- [ ] PendingVSC when consumer start (_maybe_) -- [ ] Redelegation operations -- [ ] Unjailing operations - -### NOT Tested - -The following aspects of the system are not tested by this work. - -- Completing the IBC handshakes -- Repairing an expired IBC channel through governance -- Slashing with non-zero slash factors -- Submitting proposals -- Executing proposals -- Adding a new consumer chain -- Removing a consumer chain for any reason -- Distribution of rewards -- Provider Governance -- Consumer Governance/Democracy -- Anything to do with cosmwasm -- Client expiry -- Packet timeouts -- Restarting any chain from exported state -- Any logic that deals with having _more than one consumer chain_ -- Multiple delegator accounts - -## Usage - -### Overview - -This typescript project contains code for - -- Modelling the aspects of the system listed under TESTED above -- Generating and executing actions against a model system based on those aspects, in order to explore various behaviors. The actions are generated using heuristics and randomness. -- Recording traces of executions to file -- Choosing a set of traces in a manner convenient for testing the SUT. -- Replaying a given existing trace against a new model instance, for debugging purposes. - -### Usage prerequisities - -```bash -# nodejs version 16 is required. -node --version -# yarn package manager is required -yarn --version -# setup the project -yarn install -``` - -### Commands - -There are several top level yarn project scripts which can be run via - -```bash -yarn -``` - -as per the `scripts` entry in [package.json](./package.json). The most important of these are - -```bash -# install the project -yarn install; -# build in watch mode. Repeatedly build the project when the src changes -# recommended to run in background process -yarn build:watch -# start main.ts - the entry point to the program -yarn start -# test - run the tests in __tests__ -yarn test -``` - -The actual functionality has entrypoint in [src/main.ts](./src/main.ts). Please see the file for details. The available functionalities are - -```bash -# generate traces for x seconds -yarn start gen -# check properties for x seconds -yarn start properties -# create a subset of traces -yarn start subset -# replay a trace from a file (for debugging) -yarn start replay -``` - -### Workflow - -A workflow of updating the model and generating new traces for testing against the SUT might look like - -```bash -# Generate traces for 30 seconds -yarn start gen 30 -# Collect and compact a subset of these traces -yarn start subset 200 -``` - -### Extending the model - -All of the semantic logic of the model that relates to how the system is supposed to work is contained in [src/model.ts](./src/model.ts). All of the logic for generating actions (and thus traces) against the model is contained in [src/main.ts](./src/main.ts). The remaining files are less important. - -### Ensuring a consistent Trace format - -The golang test driver must be able to parse the traces output by this Typescript project. Several tools exist to generate golang type definitions from json files. I strongly suggest using [gojsonstruct](https://github.com/twpayne/go-jsonstruct) to generate a new golang definition whenever the json trace format changes. The steps to do this are - -```bash -# Pass the content of traces.json to gojsonstruct binary which will output a golang type definition -gojsonstruct < > trace.go -``` - -The `trace.go` file output from the above command should be reconciled with the content in `difftest/trace.go`.