Merge branch 'main' into marius/bump-comet

.changelog/unreleased/features/provider/1867-add-query-for-latest-consumer-validator-set.md

@@ -0,0 +1,2 @@
+- Introduces the `consumer-validators` query to retrieve the latest set consumer-validator set for a consumer chain.
+  ([\#1863](https://github.com/cosmos/interchain-security/pull/1867))

.coderabbit.yml

@@ -23,7 +23,7 @@ reviews:
               "Assess the unit test code assessing sufficient code coverage for the changes associated in the pull request"
         - path: "**/*.md"
           instructions: |
-              "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness"
+              "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness. Please DO NOT report any missing or superfluous newlines, in particular at the end or beginning of files."
         - path: ".changelog/*"
           instructions: |
               "Assess the changes in the changelog for correctness and completeness, particularly flagging missing changes"

.github/workflows/nightly-e2e.yml

@@ -181,6 +181,102 @@ jobs:
           go-version: "1.21" # The Go version to download (if necessary) and use.
       - name: E2E consumer-double-downtime tests
         run: go run ./tests/e2e/... --tc consumer-double-downtime
+  partial-set-security-opt-in-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.21"
+      - uses: actions/checkout@v4
+      - name: Checkout LFS objects
+        run: git lfs checkout
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.21" # The Go version to download (if necessary) and use.
+      - name: E2E partial set security opt-in chain
+        run: go run ./tests/e2e/... --tc partial-set-security-opt-in
+  partial-set-security-top-n-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.21"
+      - uses: actions/checkout@v4
+      - name: Checkout LFS objects
+        run: git lfs checkout
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.21" # The Go version to download (if necessary) and use.
+      - name: E2E partial set security Top N chain
+        run: go run ./tests/e2e/... --tc partial-set-security-top-n
+  partial-set-security-validator-set-cap-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.21"
+      - uses: actions/checkout@v4
+      - name: Checkout LFS objects
+        run: git lfs checkout
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.21" # The Go version to download (if necessary) and use.
+      - name: E2E partial set security validator-set cap
+        run: go run ./tests/e2e/... --tc partial-set-security-validator-set-cap
+  partial-set-security-validators-power-cap-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.21"
+      - uses: actions/checkout@v4
+      - name: Checkout LFS objects
+        run: git lfs checkout
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.21" # The Go version to download (if necessary) and use.
+      - name: E2E partial set security validators-power cap
+        run: go run ./tests/e2e/... --tc partial-set-security-validators-power-cap
+  partial-set-security-validators-allowlisted-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.21"
+      - uses: actions/checkout@v4
+      - name: Checkout LFS objects
+        run: git lfs checkout
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.21" # The Go version to download (if necessary) and use.
+      - name: E2E partial set security allowlist
+        run: go run ./tests/e2e/... --tc partial-set-security-validators-allowlisted
+  partial-set-security-validators-denylisted-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.21"
+      - uses: actions/checkout@v4
+      - name: Checkout LFS objects
+        run: git lfs checkout
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.21" # The Go version to download (if necessary) and use.
+      - name: E2E partial set security denylist
+        run: go run ./tests/e2e/... --tc partial-set-security-validators-denylisted
 
   nightly-test-fail:
     needs:
@@ -193,6 +289,12 @@ jobs:
       - consumer-misbehaviour-test
       - consumer-double-sign-test
       - consumer-double-downtime-test
+      - partial-set-security-opt-in-test
+      - partial-set-security-top-n-test
+      - partial-set-security-validator-set-cap-test
+      - partial-set-security-validators-power-cap-test
+      - partial-set-security-validators-allowlisted-test
+      - partial-set-security-validators-denylisted-test
     if: ${{ failure() }}
     runs-on: ubuntu-latest
     steps:

Makefile

@@ -4,7 +4,8 @@ BRANCH := $(shell git rev-parse --abbrev-ref HEAD)
 COMMIT := $(shell git log -1 --format='%H')
 # Fetch tags and get the latest ICS version by filtering tags by vX.Y.Z and vX.Y.Z-lsm
 # using lazy set to only execute commands when variable is used
-LATEST_RELEASE ?= $(shell git fetch; git tag -l --sort -v:refname 'v*.?' 'v*.?'-lsm 'v*.??' 'v*.??'-lsm | head -n 1)
+# Note: v.5.0.0 is currently excluded from the list as it's a pre-release and will be added back once it's out of pre-release status
+LATEST_RELEASE ?= $(shell git fetch; git tag -l --sort -v:refname 'v*.?' 'v*.?'-lsm 'v*.??' 'v*.??'-lsm --no-contains v5.0.0 | head -n 1)
 
 # don't override user values
 ifeq (,$(VERSION))

docs/docs/consumer-development/app-integration.md

@@ -28,5 +28,6 @@ This allows the consumer chain to leverage those modules while also using the `x
 With these modules enabled, the consumer chain can mint its own governance tokens, which can then be delegated to prominent community members which are referred to as "representatives" (as opposed to "validators" in standalone chains). The token may have different use cases besides just voting on governance proposals.
 
 ## Standalone chain to consumer chain changeover
-This feature is being actively worked on. Information will be provided at a later time.
+
+See the [standalone chain to consumer chain changeover guide](./changeover-procedure.md) for more information on how to transition your standalone chain to a consumer chain.
 

docs/docs/consumer-development/changeover-procedure.md

@@ -150,7 +150,7 @@ Additionally, reach out to the community via the [forum](https://forum.cosmos.ne
 - [ ] determine consumer chain parameters to be put in the proposal
 - [ ] take note to include a link to your onboarding repository
 
-Example of a consumer chain addition proposal.
+Example of a consumer chain addition proposal (compare with the [ConsumerAdditionProposal](./onboarding.md#3-submit-a-governance-proposal) in the ICS Provider Proposals section for chains that *launch* as consumers):
 
 ```js
 // ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain or add a standalone chain.
@@ -167,7 +167,6 @@ Example of a consumer chain addition proposal.
     // Must be unique from all other consumer chain ids of the executing provider chain.
     "chain_id": "standalone-1",
     // Initial height of new consumer chain.
-    // For a completely new chain, this will be {0,1}.
     "initial_height" : {
         // must correspond to current revision number of standalone chain
         // e.g. standalone-1 => "revision_number": 1

docs/docs/consumer-development/onboarding.md

@@ -41,12 +41,15 @@ Additionally, reach out to the community via the [forum](https://forum.cosmos.ne
 - [ ] determine consumer chain parameters to be put in the proposal
 - [ ] take note to include a link to your onboarding repository
 - [ ] describe the purpose and benefits of running your chain
+- [ ] determine whether your chain should be an Opt-In chain or a Top N chain (see [Partial Set Security](../features/partial-set-security.md))
+- [ ] if desired, decide on power-shaping parameters (see [Power Shaping](../features/power-shaping.md))
 
 Example of a consumer chain addition proposal.
 
 ```js
 // ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain.
-// If it passes, then all validators on the provider chain are expected to validate the consumer chain at spawn time.
+// If it passes, if the top_N parameter is not equal to 0, the top N% of validators by voting power on the provider chain are expected to validate the consumer chain at spawn time.
+// Otherwise, only validators that opted in during the proposal period are expected to validate the consumer chain at spawn time.
 // It is recommended that spawn time occurs after the proposal end time.
 {
     // Title of the proposal
@@ -69,7 +72,7 @@ Example of a consumer chain addition proposal.
     // Hash of the consumer chain binary that should be run by validators on chain initialization.
     // It is used for off-chain confirmation of binary validity by validators and other parties.
     "binary_hash": "376cdbd3a222a3d5c730c9637454cd4dd925e2f9e2e0d0f3702fc922928583f1",
-    // Time on the provider chain at which the consumer chain genesis is finalized and all validators
+    // Time on the provider chain at which the consumer chain genesis is finalized and validators
     // will be responsible for starting their consumer chain validator node.
     "spawn_time": "2023-02-28T20:40:00.000000Z",
     // Unbonding period for the consumer chain.
@@ -97,13 +100,34 @@ Example of a consumer chain addition proposal.
 	// Note that transfer_channel_id is the ID of the channel end on the consumer chain.
     // it is most relevant for chains performing a standalone to consumer changeover
     // in order to maintain the existing ibc transfer channel
-    "distribution_transmission_channel": "channel-123"
+    "distribution_transmission_channel": "channel-123",
+    // Corresponds to the percentage of validators that have to validate the chain under the Top N case.
+    // For example, 53 corresponds to a Top 53% chain, meaning that the top 53% provider validators by voting power
+    // have to validate the proposed consumer chain. top_N can either be 0 or any value in [50, 100].
+    // A chain can join with top_N == 0 as an Opt In chain, or with top_N ∈ [50, 100] as a Top N chain.
+    "top_N": 95,
+    // Corresponds to the maximum power (percentage-wise) a validator can have on the consumer chain. For instance, if
+    // `validators_power_cap` is set to 32, it means that no validator can have more than 32% of the voting power on the
+    // consumer chain. Note that this might not be feasible. For example, think of a consumer chain with only
+    // 5 validators and with `validators_power_cap` set to 10%. In such a scenario, at least one validator would need
+    // to have more than 20% of the total voting power. Therefore, `validators_power_cap` operates on a best-effort basis.
+    "validators_power_cap": 0,
+    // Corresponds to the maximum number of validators that can validate a consumer chain.
+    // Only applicable to Opt In chains. Setting `validator_set_cap` on a Top N chain is a no-op.
+    "validator_set_cap": 0,
+    // Corresponds to a list of provider consensus addresses of validators that are the ONLY ones that can validate
+    // the consumer chain.
+    "allowlist": [],
+    // Corresponds to a list of provider consensus addresses of validators that CANNOT validate the consumer chain.
+    "denylist": []
 }
 ```
 
 ## 4. Launch
 
-The consumer chain starts after at least 66.67% of all provider's voting power comes online. The consumer chain is considered interchain secured once the appropriate CCV channels are established and the first validator set update is propagated from the provider to the consumer
+The consumer chain starts after at least 66.67% of its voting power comes online.
+Note that this means 66.67% of the voting power in the *consumer* validator set, which will be comprised of all validators that either opted in to the chain or are part of the top N% of the provider chain (and are thus automatically opted in).
+The consumer chain is considered interchain secured once the appropriate CCV channels are established and the first validator set update is propagated from the provider to the consumer
 
 - [ ] provide a repo with onboarding instructions for validators (it should already be listed in the proposal)
 - [ ] genesis.json with ccv data populated (MUST contain the initial validator set)

docs/docs/features/key-assignment.md

@@ -81,6 +81,11 @@ To change your key, simply repeat all of the steps listed above. Take note that
 
 To remove a key, simply switch it back to the consensus key you have assigned on the provider chain by following steps in the `Adding a key` section and using your provider consensus key.
 
+:::warning
+Validators are strongly recommended to assign a separate key for each consumer chain
+and **not** reuse the provider key across consumer chains for security reasons.
+:::
+
 ## Querying proposed consumer chains
 
 To query the consumer addition proposals that are in the voting period, you can use the following command on the provider:

docs/docs/features/partial-set-security.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 5
+---
+
+# Partial Set Security
+
+Partial Set Security (PSS) allows consumer chains to leverage only a subset of validators from the provider chain, which offers more flexibility than the traditional Replicated Security model. By introducing the top_N parameter, each consumer chain can choose the extent of security needed:
+
+    * Top N: Requires the top N% validators from the provider chain to secure the consumer chain. This guarantees that the validators with the most power on the provider will validate the consumer chain, while others can voluntarily opt in.
+
+    * Opt-In: If the `top_N` parameter is set to zero, no validator is mandated to secure the consumer chain. Instead, any validator from the provider chain can opt in using a dedicated transaction.
+
+An advantage of a Top N chain is that the consumer chain is guaranteed to receive at least a certain fraction of the market cap of the provider chain in security. In turn, this chain needs to be approved by governance, since validators will be forced to run the chain. Thus, Top N chains should typically expect to need to provide a strong case for why they should be added to the provider chain, and they should make sure they offer enough rewards to incentivize validators and delegators to vote for their proposal.
+
+Opt-In chains, on the other hand, are more flexible. While for technical reasons, they are also currently added via governance proposals, since validators are never forced to validate these chains and simply opt in if they want to, they should typically expect to get their proposals approved much more easily compared to Top N chains, since validators that do not want to validate the chain can simply choose not to opt in.
+However, opt in chains do not get a fixed amount of security as a relation of the market cap of the provider as top N chains do, so opt in chains might want to keep an eye on how many validators have opted in to validate their chain and adjust their reward emissions accordingly to incentivize validators.
+
+:::tip
+Partial Set Security is handled only by the provider chain - the consumer chains are simply sent validator sets, and they are not aware that this represents only a subset of the provider chain's validator set.
+:::
+
+:::caution
+Both Opt In and Top N chains currently require a governance proposal to be added to the provider chain.
+
+For Top N chains, this is also the long term vision for how they are launched.
+
+For Opt In chains, this is a temporary measure to prevent issues around chain ID squatting, i.e. someone could spuriously register many desirable chain IDs of upcoming consumer chain and simply deny legitimate consumer chains from using them. Eventually, the plan is to allow launching Opt In chains permissionlessly without going through governance, with quality control being handled by the market of validators deciding which chains they would like to validate on.
+:::