feat!: Add support for priority validators

.changelog/unreleased/api-breaking/provider/xxxx-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/xxxx-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))

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>
@@ -1680,7 +1688,8 @@ where `update-consumer-msg.json` contains:
       "allowlist":["cosmosvalcons1l9qq4m300z8c5ez86ak2mp8znftewkwgjlxh88"],
       "denylist":[],
       "min_stake": "1000",
-      "allow_inactive_vals":true
+      "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.