feat!: Add support for priority validators

.changelog/unreleased/api-breaking/provider/2101-introduce-priority-validators.md

@@ -0,0 +1,2 @@
+- Allow consumer chains to specify a list of priority validators that are included in the validator set before other validators are considered
+  ([\#2101](https://github.com/cosmos/interchain-security/pull/2101))

.changelog/unreleased/features/provider/2101-introduce-priority-validators.md

@@ -0,0 +1,2 @@
+- Allow consumer chains to specify a list of priority validators that are included in the validator set before other validators are considered
+  ([\#2101](https://github.com/cosmos/interchain-security/pull/2101))

.github/workflows/nightly-e2e.yml

@@ -277,6 +277,22 @@ jobs:
           go-version: "1.22" # 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
+  partial-set-security-validators-prioritylisted-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+      - uses: actions/checkout@v4
+      - name: Checkout LFS objects
+        run: git lfs checkout
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22" # The Go version to download (if necessary) and use.
+      - name: E2E partial set security prioritylist
+        run: go run ./tests/e2e/... --tc partial-set-security-validators-prioritylisted
   partial-set-security-modification-proposal:
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -376,6 +392,7 @@ jobs:
       - partial-set-security-validators-power-cap-test
       - partial-set-security-validators-allowlisted-test
       - partial-set-security-validators-denylisted-test
+      - partial-set-security-validators-prioritylisted-test
       - partial-set-security-modification-proposal
       - active-set-changes-test
       - permissionless-basic-test

contrib/local-testnet.sh

@@ -317,7 +317,8 @@ tee ${PROV_NODE_DIR}/consumer_prop.json<<EOF
                 "allowlist": [],
                 "denylist": [],
                 "min_stake": 1000,
-                "allow_inactive_vals": true
+                "allow_inactive_vals": true,
+                "prioritylist": [],
             }
         }
     ],

docs/docs/adrs/adr-019-permissionless-ics.md

@@ -143,6 +143,7 @@ or a combination of them.
 | `ConsumerCommissionRatePrefix`          | Commission rate per chain per validator                                                                                      | validator                        | consumer chain                   | Every `MsgSetConsumerCommissionRate` message                                                             |
 | `MinimumPowerInTopNBytePrefix`          | Stores the minimum power needed to opt in for a chain                                                                        | not applicable for Opt In chains | not applicable for Opt In chains | Every epoch                                                                                              |
 | `ConsumerAddrsToPruneV2BytePrefix`      | Stores consumer addresses to be pruned (as part of `VSCMaturedPacket`s deprecation)                                          | validator or provider chain      | provider chain                   | Every `MsgAssignConsumerKey` or `MsgOptIn` and later during actual pruning                               |
+| `PrioritylistPrefix`                        | Stores the prioritylist of a chain                                                                                               | consumer chain                   | consumer chain| Every parameter update    |
 
 Everything stored under one of the above keys is associated with a `chainId` and has to be migrated to new state under a `consumerId`.
 
@@ -271,6 +272,8 @@ message PowerShapingParameters {
   uint64 min_stake = 6;
   // Corresponds to whether inactive validators are allowed to validate the consumer chain.
   bool allow_inactive_vals = 7;
+  // corresponds to a list of provider consensus addresses of validators that have priority
+  repeated string prioritylist = 8;
 }
 
 ```

docs/docs/build/modules/02-provider.md

@@ -225,6 +225,12 @@ Format: `byte(37) | len(consumerId) | []byte(consumerId) | addr -> []byte{}`, wi
 
 Format: `byte(40) | len(consumerId) | []byte(consumerId) -> uint64`
 
+#### Prioritylist
+
+`Prioritylist` is the list of provider validators that have priority to validate a given consumer chain.
+
+Format: `byte(56) | len(consumerId) | []byte(consumerId) | addr -> []byte{}`, with `addr` the validator's consensus address on the provider chain.
+
 ### Validator Set Updates
 
 #### ValidatorSetUpdateId
@@ -1089,6 +1095,7 @@ Output:
 chains:
 - allow_inactive_vals: true
   allowlist: []
+  prioritylist: []
   chain_id: pion-1
   client_id: 07-tendermint-0
   consumer_id: "0"
@@ -1554,6 +1561,7 @@ power_shaping_params:
   top_N: 100
   validator_set_cap: 0
   validators_power_cap: 0
+  prioritylist: []
 ```
 
 </details>
@@ -1679,8 +1687,9 @@ where `update-consumer-msg.json` contains:
       "validator_set_cap": 50,
       "allowlist":["cosmosvalcons1l9qq4m300z8c5ez86ak2mp8znftewkwgjlxh88"],
       "denylist":[],
-      "min_stake": 1000,
-      "allow_inactive_vals":true
+      "min_stake": "1000",
+      "allow_inactive_vals":true,
+      "prioritylist":[]
   },
   "allowlisted_reward_denoms": {
     "denoms": ["ibc/0025F8A87464A471E66B234C4F93AEC5B4DA3D42D7986451A059273426290DD5"]

docs/docs/consumer-development/onboarding.md

@@ -126,7 +126,9 @@ Example of power-shaping parameters:
     // Corresponds to the minimal amount of (provider chain) stake required to validate on the consumer chain.
     "min_stake": 0,
     // Corresponds to whether inactive validators are allowed to validate the consumer chain.
-    "allow_inactive_vals": false
+    "allow_inactive_vals": false,
+    // Corresponds to a list of provider consensus addresses of validators that have priority
+    "prioritylist": [],
 }
 ```
 

docs/docs/features/power-shaping.md

@@ -80,6 +80,10 @@ This can be useful for chains that want to have a larger validator set than the
 Consumer chains that enable this feature should strongly consider setting a minimum validator stake to ensure that only validators with some reputation/stake can validate the chain.
 By default, this parameter is set to `false`, i.e., validators outside of the provider's active set are not eligible to opt in. 
 
+### Prioritylist
+
+The consumer chain can specify a priority list of validators for participation in the validator set. Validators on the priority list are considered first when forming the consumer chain's validator set. If a priority list isn't set, the remaining slots are filled based on validator power.
+
 ## Setting Power Shaping Parameters
 
 All the power shaping parameters can be set by the consumer chain in the `MsgCreateConsumer` or `MsgUpdateConsumer` messages.