* Merge branch 'main' into sainoe/refactor-key-assignment

* Fix integration tests which assigns key for unexistent consumer chains

.changelog/epilogue.md

@@ -23,6 +23,28 @@ Interchain Security v3 uses SDK 0.47 and IBC 7.
 * `[x/ccv/provider]` (fix) [#977](https://github.com/cosmos/interchain-security/pull/977) Avoids panicking the provider when an unbonding delegation was removed through a `CancelUnbondingDelegation` message.
 * `[x/ccv/democracy]` (feat) [#1019](https://github.com/cosmos/interchain-security/pull/1019) Whitelisting non-legacy params in the "democracy module" require the entire module to be whitelisted. 
 
+## v2.4.0-lsm
+
+*November 20, 2023*
+
+* (fix) [#1439](https://github.com/cosmos/interchain-security/pull/1439) Fix unmarshaling for the CLI consumer double vote cmd.
+* (feat!) [#1435](https://github.com/cosmos/interchain-security/pull/1435) Add height-base filter for consumer equivocation evidence.
+
+## v2.3.0-provider-lsm
+
+*November 15, 2023*
+
+❗ *This release is deprecated and should not be used in production.*
+
+* (fix!) [#1422](https://github.com/cosmos/interchain-security/pull/1422) Fix the misbehaviour handling by verifying the signatures of byzantine validators.
+
+## v2.2.0-provider-lsm
+
+❗ *This release is deprecated and should not be used in production.*
+
+### Cryptographic verification of equivocation
+* New feature enabling the provider chain to verify equivocation evidence on its own instead of trusting consumer chains, see [EPIC](https://github.com/cosmos/interchain-security/issues/732).
+
 ## v2.1.0-provider-lsm
 
 Date: September 15th, 2023

.changelog/unreleased/api-breaking/provider/1340-add-cryptographic-verification-of-equivocation-feature.md

@@ -0,0 +1,2 @@
+- Deprecate equivocation proposals.  
+([\#1340](https://github.com/cosmos/interchain-security/pull/1340))

.changelog/unreleased/features/provider/1340-cryptographic-equivocation-feature.md

@@ -0,0 +1,4 @@
+- Introduce the cryptographic verification of equivocation feature to the provider
+  (cf. [ADR-005](/docs/docs/adrs/adr-005-cryptographic-equivocation-verification.md)
+  & [ADR-013](/docs/docs/adrs/adr-013-equivocation-slashing.md)).  
+  ([\#1340](https://github.com/cosmos/interchain-security/pull/1340))

.changelog/unreleased/state-breaking/provider/1340-cryptographic-equivocation-feature.md

@@ -0,0 +1,4 @@
+- Introduce the cryptographic verification of equivocation feature to the provider
+  (cf. [ADR-005](/docs/docs/adrs/adr-005-cryptographic-equivocation-verification.md)
+  & [ADR-013](/docs/docs/adrs/adr-013-equivocation-slashing.md)).  
+  ([\#1340](https://github.com/cosmos/interchain-security/pull/1340))

.github/workflows/proto-registry.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: bufbuild/[email protected].0
+      - uses: bufbuild/[email protected].1
       - uses: bufbuild/buf-push-action@v1
         with:
           input: "proto"

.github/workflows/proto.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: bufbuild/[email protected].0
+      - uses: bufbuild/[email protected].1
       - uses: bufbuild/buf-breaking-action@v1
         with:
           input: "proto"

CHANGELOG.md

@@ -25,6 +25,28 @@ Interchain Security v3 uses SDK 0.47 and IBC 7.
 * `[x/ccv/provider]` (fix) [#977](https://github.com/cosmos/interchain-security/pull/977) Avoids panicking the provider when an unbonding delegation was removed through a `CancelUnbondingDelegation` message.
 * `[x/ccv/democracy]` (feat) [#1019](https://github.com/cosmos/interchain-security/pull/1019) Whitelisting non-legacy params in the "democracy module" require the entire module to be whitelisted. 
 
+## v2.4.0-lsm
+
+*November 20, 2023*
+
+* (fix) [#1439](https://github.com/cosmos/interchain-security/pull/1439) Fix unmarshaling for the CLI consumer double vote cmd.
+* (feat!) [#1435](https://github.com/cosmos/interchain-security/pull/1435) Add height-base filter for consumer equivocation evidence.
+
+## v2.3.0-provider-lsm
+
+*November 15, 2023*
+
+❗ *This release is deprecated and should not be used in production.*
+
+* (fix!) [#1422](https://github.com/cosmos/interchain-security/pull/1422) Fix the misbehaviour handling by verifying the signatures of byzantine validators.
+
+## v2.2.0-provider-lsm
+
+❗ *This release is deprecated and should not be used in production.*
+
+### Cryptographic verification of equivocation
+* New feature enabling the provider chain to verify equivocation evidence on its own instead of trusting consumer chains, see [EPIC](https://github.com/cosmos/interchain-security/issues/732).
+
 ## v2.1.0-provider-lsm
 
 Date: September 15th, 2023
@@ -175,3 +197,4 @@ In addition, RS has the following features:
 
 - **Key Assignment**: Enables validator operators to use different consensus keys for each consumer chain validator node that they operate.
 - **Jail Throttling**: Enables the provider to slow down a "worst case scenario" attack where a malicious consumer binary attempts to jail a significant amount (> 2/3) of the voting power, effectively taking control of the provider.
+

CONTRIBUTING.md

@@ -14,11 +14,10 @@
     - [Pull Request Templates](#pull-request-templates)
     - [Requesting Reviews](#requesting-reviews)
     - [Updating Documentation](#updating-documentation)
+    - [Changelog](#changelog)
   - [Dependencies](#dependencies)
   - [Protobuf](#protobuf)
   - [Branching Model and Release](#branching-model-and-release)
-    - [Semantic Versioning](#semantic-versioning)
-    - [Backwards Compatibility](#backwards-compatibility)
     - [PR Targeting](#pr-targeting)
 
 Thank you for considering making contributions to the Interchain Security (ICS) repository! 🎉👍
@@ -216,6 +215,63 @@ items. In addition, use the following review explanations:
 
 If you open a PR in ICS, it is mandatory to update the relevant documentation in `/docs`.
 
+### Changelog
+
+To manage and generate our changelog, we currently use [unclog](https://github.com/informalsystems/unclog).
+
+Every PR with types `fix`, `feat`, `deps`, and `refactor` should include a file 
+`.changelog/unreleased/${section}/[${component}/]${pr-number}-${short-description}.md`,
+where:
+
+- `section` is one of 
+  `dependencies`, `improvements`, `features`, `bug-fixes`, `state-breaking`, `api-breaking`, 
+  and _**if multiple apply, create multiple files**_, 
+  not necessarily with the same `short-description` or content;
+- `pr-number` is the PR number;
+- `short-description` is a short (4 to 6 word), hyphen separated description of the change;
+- `component` is used for changes that affect one of the components defined in the [config](.changelog/config.toml), e.g., `provider`, `consumer`.
+
+For examples, see the [.changelog](.changelog) folder.
+
+Use `unclog` to add a changelog entry in `.changelog` (check the [requirements](https://github.com/informalsystems/unclog#requirements) first): 
+```bash
+# add a general entry
+unclog add \
+   -i "${pr-number}-${short-description}" \
+   -p "${pr-number}" \
+   -s "${section}" \
+   -m "${description}" \
+
+# add a entry to a component 
+unclog add 
+   -i "${pr-number}-${short-description}" \
+   -p "${pr-number}" \
+   -c "${component}" \
+   -s "${section}" \
+   -m "${description}" \
+```
+where `${description}` is a detailed description of the changelog entry.
+
+For example, 
+```bash
+# add an entry for bumping IBC to v7.2.0
+unclog add -i "1196-bump-ibc" -p 1196 -s dependencies -m "Bump [ibc-go](https://github.com/cosmos/ibc-go) to [v7.2.0](https://github.com/cosmos/ibc-go/releases/tag/v7.2.0)" 
+
+# add an entry for changing the consumer module;
+# note that the entry is added to both state-breaking and features sections
+unclog add -i "1024-jail-throttling-v2" -p 1024 -c consumer -s state-breaking -m "Add the consumer-side changes for jail throttling with retries (cf. ADR 008)." 
+unclog add -i "1024-jail-throttling-v2" -p 1024 -c consumer -s features -m "Add the consumer-side changes for jail throttling with retries (cf. ADR 008)." 
+```
+
+**Note:** `unclog add` requires an editor. This can be set either by configuring 
+an `$EDITOR` environment variable or by manually specify an editor binary path 
+via the `--editor` flag. 
+
+**Note:** Changelog entries should answer the question: "what is important about this
+change for users to know?" or "what problem does this solve for users?". It
+should not simply be a reiteration of the title of the associated PR, unless the
+title of the PR _very_ clearly explains the benefit of a change to a user.
+
 ## Dependencies
 
 We use [Go Modules](https://github.com/golang/go/wiki/Modules) to manage
@@ -243,18 +299,6 @@ To generate the protobuf stubs, you can run `make proto-gen`.
 
 ICS adheres to the [trunk based development branching model](https://trunkbaseddevelopment.com/). User branches should start with a user name, example: `{moniker}/{issue#}-branch-name`.
 
-### Semantic Versioning
-
-ICS follows [semantic versioning](https://semver.org), but with the following deviations (similar to [IBC-Go](https://github.com/cosmos/ibc-go/blob/main/RELEASES.md)):
-
-- A library API breaking change will result in an increase of the MAJOR version number (X.y.z | x > 0). 
-- A state breaking change (change requiring coordinated upgrade and/or state migration for the consumer, the provider, or both) will result in an increase of the MINOR version number (x.Y.z | x > 0).
-- Any other changes (including node API breaking changes) will result in an increase of the PATCH version number (x.y.Z | x > 0).
-
-### Backwards Compatibility
-
-A MAJOR version of ICS will always be backwards compatible with the previous MAJOR version of ICS. Versions before that are not supported. For example, a provider chain could run ICS at version 3.4.5, and would be compatible with consumers running ICS at 2.0.0, 2.1.2, 3.2.1, but not 1.2.7.
-
 ### PR Targeting
 
 Ensure that you base and target your PRs on either `main` or a feature branch.

Dockerfile

@@ -29,7 +29,7 @@ RUN go mod tidy
 RUN make install
 
 # Get Hermes build
-FROM ghcr.io/informalsystems/hermes:1.4.1 AS hermes-builder
+FROM otacrew/hermes-ics:evidence-cmd AS hermes-builder
 
 # Get CometMock
 FROM ghcr.io/informalsystems/cometmock:v0.37.x as cometmock-builder

FEATURES.md

@@ -0,0 +1,18 @@
+# Features
+
+The following table indicates the major ICS features available in the [currently active releases](./RELEASES.md#version-matrix):
+
+| Feature | Release | `v1.2.0-multiden` | `v2.0.0` | `v2.1.0-provider-lsm` | `v2.4.0-lsm` | `v3.1.0` |
+|---------|---------|------------------:|---------:|----------------------:|-------------:|---------:|
+| [Channel initialization: new chains](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md#channel-initialization-new-chains) | | ✅ | ✅ | ✅ | ✅ | ✅ | 
+| [Validator set update](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md#validator-set-update) | | ✅ | ✅ | ✅ | ✅ | ✅ | 
+| [Completion of unbonding operations](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md#completion-of-unbonding-operations) | | ✅ | ✅ | ✅ | ✅ | ✅ | 
+| [Consumer initiated slashing](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md#consumer-initiated-slashing) | | ✅ | ✅ | ✅ | ✅ | ✅ | 
+| [Reward distribution](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md#reward-distribution) | | ✅ | ✅ | ✅ | ✅ | ✅ | 
+| [Consumer chain removal](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/methods.md#consumer-chain-removal) | | ✅ | ✅ | ✅ | ✅ | ✅ | 
+| [Key assignment](https://github.com/cosmos/interchain-security/issues/26) | | ✅ | ✅ | ✅ | ✅ | ✅ | 
+| [Jail throttling](https://github.com/cosmos/interchain-security/issues/404) | | ✅ | ✅ | ✅ | ✅ | ✅ | 
+| [Soft opt-out](https://github.com/cosmos/interchain-security/issues/851) | | ✅ | ✅ | ✅ | ✅ | ✅ | 
+| [Channel initialization: existing chains](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/overview_and_basic_concepts.md#channel-initialization-existing-chains) (aka [Standalone to consumer changeover](https://github.com/cosmos/interchain-security/issues/756))| | ❌ | ✅ | ✅ | ✅ | ✅ | 
+| [Cryptographic verification of equivocation](https://github.com/cosmos/interchain-security/issues/732) | | ❌ | ❌ | ❌ | ✅ | ❌ | 
+

README.md

@@ -9,7 +9,11 @@
 
 **interchain-security** contains a working and in-production implementation of the Replicated Security protocol (aka Interchain Security V1). Replicated security is an open sourced IBC application which allows cosmos blockchains to lease their proof-of-stake security to one another.
 
-For more details on the Replicated Security protocol, take a look at the [docs](https://cosmos.github.io/interchain-security/) or [technical specification](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/README.md).
+For more details on the **Replicated Security protocol**, take a look at the [docs](https://cosmos.github.io/interchain-security/) or [technical specification](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/README.md).
+
+For a list of **currently active releases**, see [RELEASES.md](./RELEASES.md#version-matrix).
+
+For a list of **major ICS features** available in the currently active releases, see [FEATURES.md](./FEATURES.md).
 
 ## Instructions
 
@@ -43,7 +47,7 @@ Inspect the [Makefile](./Makefile) if curious.
 
 ## Testing
 
-See [testing docs](./docs/old/testing.md).
+See [testing docs](./TESTING.md).
 
 ## Learn more
 

RELEASES.md

@@ -0,0 +1,99 @@
+# Releases
+
+- [Releases](#releases)
+  - [Semantic Versioning](#semantic-versioning)
+    - [Breaking Changes](#breaking-changes)
+  - [Release Cycle](#release-cycle)
+  - [Stable Release Policy](#stable-release-policy)
+  - [Version Matrix](#version-matrix)
+    - [Backwards Compatibility](#backwards-compatibility)
+
+## Semantic Versioning 
+
+Interchain Security (ICS) follows [semantic versioning](https://semver.org), but with the following deviations (similar to [IBC-Go](https://github.com/cosmos/ibc-go/blob/main/RELEASES.md)):
+
+- A library API breaking change will result in an increase of the MAJOR version number (X.y.z | X > 0). 
+- A state-machine breaking change will result in an increase of the MINOR version number (x.Y.z | x > 0).
+- Any other changes (including node API breaking changes) will result in an increase of the PATCH version number (x.y.Z | x > 0).
+
+### Breaking Changes
+
+A change is considered to be ***library API breaking*** if it modifies the integration of ICS on either consumer or provider chains (i.e., it changes the way ICS is used as a library). 
+Note that bumping the major version of [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) or [IBC](https://github.com/cosmos/ibc-go) will be considered as a library API breaking change.
+
+A change is considered to be ***state-machine breaking*** if it requires a coordinated upgrade and/or state migration for either consumer or provider chains in order to preserve [state compatibility](./STATE-COMPATIBILITY.md). 
+Note that when bumping the dependencies of [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) and [IBC](https://github.com/cosmos/ibc-go) we will only treat patch releases as non state-machine breaking.
+
+A change is considered to be ***node API breaking*** if it modifies the API provided by a node of either consumer or provider chains. 
+This includes events, queries, CLI interfaces. 
+
+## Release Cycle
+
+ICS follows a traditional release cycle involving release candidates (RCs) releases before finalizing a new version. 
+The stable release guarantees do not go into affect until a final release is performed.
+
+❗***It is never advisable to use a non-final release in production.***
+
+Final releases should contain little to no changes in comparison to the latest RC. 
+
+A release should not be finalized until the development team and the external community have done sufficient integration tests on the targeted release.
+
+## Stable Release Policy
+
+The beginning of a new major release series is marked by the release of a new major version. 
+A major release series is comprised of all minor and patch releases made under the same major version number. 
+The series continues to receive bug fixes (released as minor or patch releases) until it reaches end of life. 
+The date when a major release series reaches end of life is determined by one of the following methods:
+
+- If there is no known chain using a major release series, then it reached end of life. 
+  This is a temporary policy that is possible due to the relatively low number of consumer chains.
+- If the next major release is made within the first 6 months, then the end of 
+  life date of the major release series is 1 year after its initial release.
+- If the next major release is made 6 months after the initial release, then the 
+  end of life date of the major release series is 6 months after the release date 
+  of the next major release.
+
+Only the following major release series have a stable release status. 
+All missing minor release versions have been discontinued.
+
+| Release | End of Life Date |
+|---------|------------------|
+| `v1.2.x` | February 21, 2024 |
+| `v2.0.x` | June 09, 2024 |
+| `v2.1.x-provider-lsm` | June 09, 2024 |
+| `v2.4.x-lsm` | June 09, 2024 |
+| `v3.1.x` | July 10, 2024 |
+| `v3.2.x` | July 10, 2024 |
+
+**Note**: As of [Gaia v12.0.0](https://github.com/cosmos/gaia/releases/tag/v12.0.0), 
+the Cosmos Hub uses a fork of Cosmos SDK ([v0.45.16-ics-lsm](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.45.16-ics-lsm)) 
+that contains the Liquid Staking Module (LSM). 
+This means the Cosmos Hub requires a fork of ICS. 
+This fork is maintained by the development team and released using the `-lsm` prefix. 
+As soon as the Cosmos Hub uses mainline Cosmos SDK, the `-lsm` releases will reach end of life. 
+
+## Version Matrix
+
+Versions of Golang, IBC, Cosmos SDK and CometBFT used by ICS in the currently active releases:
+
+| ICS | Golang | IBC | Cosmos SDK | CometBFT | Note |
+|-----|--------|-----|------------|----------|------|
+| [v1.2.0-multiden](https://github.com/cosmos/interchain-security/releases/tag/v1.2.0-multiden) | 1.18 | v4.2.0 | v0.45.15-ics | v0.34.27 | Consumer only |
+| [v2.0.0](https://github.com/cosmos/interchain-security/releases/tag/v2.0.0) | 1.19 | v4.4.2 | v0.45.15-ics | v0.34.28 | 
+| [v2.1.0-provider-lsm](https://github.com/cosmos/interchain-security/releases/tag/v2.1.0-provider-lsm) | 1.19 | v4.4.2 | v0.45.16-ics-lsm | v0.34.28 | Provider only (Cosmos Hub specific) |
+| [v2.4.0-lsm](https://github.com/cosmos/interchain-security/releases/tag/v2.4.0-lsm) | 1.19 | v4.4.2 | v0.45.16-ics-lsm | v0.34.28 | Provider only (Cosmos Hub specific) |
+| [v3.1.0](https://github.com/cosmos/interchain-security/releases/tag/v3.1.0) | 1.20 | v7.1.0 | v0.47.3 | v0.37.2 |
+
+**Note:** For a list of major ICS features available in the currently active releases, see [FEATURES.md](./FEATURES.md).
+
+### Backwards Compatibility
+
+A MAJOR version of ICS will always be backwards compatible with the previous MAJOR version of ICS. 
+
+The following table indicates the compatibility of currently active releases:
+
+| Consumer | Provider | `v2.0.0` | `v2.1.0-provider-lsm` | `v2.4.0-lsm` | `v3.1.0` |
+|----------|----------|--------:|----------------------:|----------------------:|---------:|
+| `v1.2.0-multiden` || ✅ | ✅ | ✅ | ✅ | 
+| `v2.0.0` || ✅ | ✅ | ✅ | ✅ | 
+| `v3.1.0` || ✅ | ✅ | ✅ | ✅ |