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
+  ([\#xxxx](https://github.com/cosmos/interchain-security/pull/xxxx))

.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
+  ([\#xxxx](https://github.com/cosmos/interchain-security/pull/xxxx))

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.

proto/interchain_security/ccv/provider/v1/provider.proto

@@ -55,7 +55,7 @@ message ConsumerAdditionProposal {
   bytes binary_hash = 6;
   // spawn time is the time on the provider chain at which the consumer chain
   // genesis is finalized and all validators will be responsible for starting
-  // their consumer chain validator node.
+  // their consumer chain validator nodeConsumerAd.
   google.protobuf.Timestamp spawn_time = 7
       [ (gogoproto.stdtime) = true, (gogoproto.nullable) = false ];
 
@@ -489,6 +489,11 @@ 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 should have PRIORITY to validate on the consumer chain,
+  // meaning as long as they are eligible/opted in to validate on the consumer chain, the validator set will be
+  // filled with these validators first, and other validators will be added to the validator set only if there are
+  // not enough eligible priority validators.
+  repeated string prioritylist = 8;
 }
 
 // ConsumerIds contains consumer ids of chains

proto/interchain_security/ccv/provider/v1/query.proto

@@ -196,6 +196,11 @@ message Chain {
   string consumer_id = 13;
   // the reward denoms allowlisted by this consumer chain
   AllowlistedRewardDenoms allowlisted_reward_denoms = 14;
+  // Corresponds to a list of provider consensus addresses of validators that should have PRIORITY to validate on the consumer chain,
+  // meaning as long as they are eligible/opted in to validate on the consumer chain, the validator set will be
+  // filled with these validators first, and other validators will be added to the validator set only if there are
+  // not enough eligible priority validators.
+  repeated string prioritylist = 15;
 }
 
 message QueryValidatorConsumerAddrRequest {

tests/e2e/actions.go

@@ -289,6 +289,7 @@ type PowerShapingParameters struct {
 	Denylist           []string
 	MinStake           uint64
 	AllowInactiveVals  bool
+	Prioritylist       []string
 }
 
 func (tr Chain) updateConsumerChain(action UpdateConsumerChainAction, verbose bool) {
@@ -320,6 +321,7 @@ func (tr Chain) updateConsumerChain(action UpdateConsumerChainAction, verbose bo
 		Denylist:           action.PowerShapingParams.Denylist,
 		MinStake:           action.PowerShapingParams.MinStake,
 		AllowInactiveVals:  action.PowerShapingParams.AllowInactiveVals,
+		Prioritylist:       action.PowerShapingParams.Prioritylist,
 	}
 
 	consumerId := tr.testConfig.chainConfigs[action.ConsumerChain].ConsumerId
@@ -376,6 +378,7 @@ func (tr Chain) createConsumerChain(action CreateConsumerChainAction, verbose bo
 		Denylist:           action.PowerShapingParams.Denylist,
 		MinStake:           action.PowerShapingParams.MinStake,
 		AllowInactiveVals:  action.PowerShapingParams.AllowInactiveVals,
+		Prioritylist:       action.PowerShapingParams.Prioritylist,
 	}
 
 	metadata := types.ConsumerMetadata{
@@ -463,6 +466,7 @@ type SubmitConsumerAdditionProposalAction struct {
 	Denylist            []string
 	MinStake            uint64
 	AllowInactiveVals   bool
+	Prioritylist        []string
 }
 
 func (tr Chain) UpdateConsumer(providerChain ChainID, validator ValidatorID, update types.MsgUpdateConsumer, verbose bool) {
@@ -657,6 +661,7 @@ func (tr Chain) submitConsumerAdditionProposal(
 		Denylist:           action.Denylist,
 		MinStake:           action.MinStake,
 		AllowInactiveVals:  action.AllowInactiveVals,
+		Prioritylist:       action.Prioritylist,
 	}
 	update.PowerShapingParameters = &powerShapingParameters
 	tr.UpdateConsumer(action.Chain, action.From, *update, verbose)
@@ -757,6 +762,7 @@ func (tr Chain) submitConsumerAdditionLegacyProposal(
 		Denylist:                          action.Denylist,
 		MinStake:                          action.MinStake,
 		AllowInactiveVals:                 action.AllowInactiveVals,
+		Prioritylist:                      action.Prioritylist,
 	}
 
 	bz, err := json.Marshal(prop)
@@ -937,6 +943,7 @@ type SubmitConsumerModificationProposalAction struct {
 	AllowInactiveVals  bool
 	MinStake           uint64
 	NewOwner           string
+	Prioritylist       []string
 }
 
 func (tr Chain) submitConsumerModificationProposal(
@@ -962,6 +969,7 @@ func (tr Chain) submitConsumerModificationProposal(
 			ValidatorSetCap:    action.ValidatorSetCap,
 			Allowlist:          action.Allowlist,
 			Denylist:           action.Denylist,
+			Prioritylist:       action.Prioritylist,
 		},
 	}
 
@@ -1019,6 +1027,7 @@ func (tr Chain) submitConsumerModificationLegacyProposal(
 		ValidatorSetCap:    action.ValidatorSetCap,
 		Allowlist:          action.Allowlist,
 		Denylist:           action.Denylist,
+		Prioritylist:       action.Prioritylist,
 	}
 
 	bz, err := json.Marshal(prop)

tests/e2e/steps_permissionless_ics.go

@@ -142,9 +142,10 @@ func stepsPermissionlessICS() []Step {
 						SpawnTime:     0,
 					},
 					PowerShapingParams: &PowerShapingParameters{
-						TopN:      0,
-						Allowlist: []string{getDefaultValidators()[ValidatorID("carol")].ValconsAddress},
-						Denylist:  []string{getDefaultValidators()[ValidatorID("bob")].ValconsAddress},
+						TopN:         0,
+						Allowlist:    []string{getDefaultValidators()[ValidatorID("carol")].ValconsAddress},
+						Denylist:     []string{getDefaultValidators()[ValidatorID("bob")].ValconsAddress},
+						Prioritylist: []string{getDefaultValidators()[ValidatorID("carol")].ValconsAddress},
 					},
 				},
 				State: State{},

testutil/keeper/unit_test_helpers.go

@@ -309,6 +309,7 @@ func GetTestPowerShapingParameters() providertypes.PowerShapingParameters {
 		Denylist:           nil,
 		MinStake:           0,
 		AllowInactiveVals:  false,
+		Prioritylist:       nil,
 	}
 }
 

x/ccv/provider/client/cli/tx.go

@@ -254,7 +254,8 @@ where create_consumer.json has the following structure:
     "allowlist": [],
     "denylist": [],
     "min_stake": "0",
-    "allow_inactive_vals": false
+    "allow_inactive_vals": false,
+	"prioritylist": []
   },
   "allowlisted_reward_denoms": {
     "denoms": ["ibc/...", "ibc/..."]
@@ -352,7 +353,8 @@ where update_consumer.json has the following structure:
     "allowlist": [],
     "denylist": [],
     "min_stake": "0",
-    "allow_inactive_vals": false
+    "allow_inactive_vals": false,
+	"prioritylist": []
    },
   "allowlisted_reward_denoms": {
     "denoms": ["ibc/...", "ibc/..."]

x/ccv/provider/client/legacy_proposals.go

@@ -43,6 +43,7 @@ type ConsumerAdditionProposalJSON struct {
 	Denylist           []string `json:"denylist"`
 	MinStake           uint64   `json:"min_stake"`
 	AllowInactiveVals  bool     `json:"allow_inactive_vals"`
+	Prioritylist       []string `json:"prioritylist"`
 }
 
 type ConsumerAdditionProposalReq struct {
@@ -176,6 +177,7 @@ type ConsumerModificationProposalJSON struct {
 	Denylist           []string `json:"denylist"`
 	MinStake           uint64   `json:"min_stake"`
 	AllowInactiveVals  bool     `json:"allow_inactive_vals"`
+	Prioritylist       []string `json:"prioritylist"`
 
 	Deposit string `json:"deposit"`
 }

x/ccv/provider/keeper/consumer_lifecycle.go

@@ -486,6 +486,7 @@ func (k Keeper) DeleteConsumerChain(ctx sdk.Context, consumerId string) (err err
 	k.DeleteDenylist(ctx, consumerId)
 	k.DeleteAllOptedIn(ctx, consumerId)
 	k.DeleteConsumerValSet(ctx, consumerId)
+	k.DeletePrioritylist(ctx, consumerId)
 
 	k.DeleteConsumerRemovalTime(ctx, consumerId)
 

x/ccv/provider/keeper/consumer_lifecycle_test.go

@@ -222,34 +222,39 @@ func TestBeginBlockLaunchConsumers(t *testing.T) {
 			ValidatorSetCap:    0,
 			Allowlist:          []string{},
 			Denylist:           []string{},
+			Prioritylist:       []string{},
 		},
 		{
 			Top_N:              50,
 			ValidatorsPowerCap: 0,
 			ValidatorSetCap:    0,
 			Allowlist:          []string{},
 			Denylist:           []string{},
+			Prioritylist:       []string{},
 		},
 		{
 			Top_N:              50,
 			ValidatorsPowerCap: 0,
 			ValidatorSetCap:    0,
 			Allowlist:          []string{},
 			Denylist:           []string{},
+			Prioritylist:       []string{},
 		},
 		{
 			Top_N:              0,
 			ValidatorsPowerCap: 0,
 			ValidatorSetCap:    0,
 			Allowlist:          []string{},
 			Denylist:           []string{},
+			Prioritylist:       []string{},
 		},
 		{
 			Top_N:              0,
 			ValidatorsPowerCap: 0,
 			ValidatorSetCap:    0,
 			Allowlist:          []string{},
 			Denylist:           []string{},
+			Prioritylist:       []string{},
 		},
 	}
 

x/ccv/provider/keeper/grpc_query.go

@@ -114,6 +114,12 @@ func (k Keeper) GetConsumerChain(ctx sdk.Context, consumerId string) (types.Chai
 		strDenylist[i] = addr.String()
 	}
 
+	prioritylist := k.GetPriorityList(ctx, consumerId)
+	strPrioritylist := make([]string, len(prioritylist))
+	for i, addr := range prioritylist {
+		strPrioritylist[i] = addr.String()
+	}
+
 	metadata, err := k.GetConsumerMetadata(ctx, consumerId)
 	if err != nil {
 		return types.Chain{}, fmt.Errorf("cannot find metadata (%s): %s", consumerId, err.Error())
@@ -139,6 +145,7 @@ func (k Keeper) GetConsumerChain(ctx sdk.Context, consumerId string) (types.Chai
 		MinStake:                powerShapingParameters.MinStake,
 		ConsumerId:              consumerId,
 		AllowlistedRewardDenoms: &types.AllowlistedRewardDenoms{Denoms: allowlistedRewardDenoms},
+		Prioritylist:            strPrioritylist, //strPrioritylist, Should I retrieve from somewhere => where do I retrieve it from? Basically where does priority list come from and where is it stored
 	}, nil
 }
 

x/ccv/provider/keeper/grpc_query_test.go

@@ -447,7 +447,12 @@ func TestGetConsumerChain(t *testing.T) {
 		{types.NewProviderConsAddress([]byte("providerAddr6"))},
 		{},
 	}
-
+	prioritylists := [][]types.ProviderConsAddress{
+		{},
+		{types.NewProviderConsAddress([]byte("providerAddr1")), types.NewProviderConsAddress([]byte("providerAddr2"))},
+		{types.NewProviderConsAddress([]byte("providerAddr3"))},
+		{},
+	}
 	allowInactiveVals := []bool{true, false, true, false}
 
 	minStakes := []math.Int{
@@ -486,6 +491,9 @@ func TestGetConsumerChain(t *testing.T) {
 		for _, addr := range denylists[i] {
 			pk.SetDenylist(ctx, consumerID, addr)
 		}
+		for _, addr := range prioritylists[i] {
+			pk.SetPrioritylist(ctx, consumerID, addr)
+		}
 		strAllowlist := make([]string, len(allowlists[i]))
 		for j, addr := range allowlists[i] {
 			strAllowlist[j] = addr.String()
@@ -496,6 +504,11 @@ func TestGetConsumerChain(t *testing.T) {
 			strDenylist[j] = addr.String()
 		}
 
+		strPrioritylist := make([]string, len(prioritylists[i]))
+		for j, addr := range allowlists[i] {
+			strPrioritylist[j] = addr.String()
+		}
+
 		metadataLists = append(metadataLists, types.ConsumerMetadata{Name: chainIDs[i]})
 		pk.SetConsumerMetadata(ctx, consumerID, metadataLists[i])
 
@@ -520,6 +533,7 @@ func TestGetConsumerChain(t *testing.T) {
 				MinStake:                minStakes[i].Uint64(),
 				ConsumerId:              consumerIDs[i],
 				AllowlistedRewardDenoms: allowlistedRewardDenoms[i],
+				Prioritylist:            strPrioritylist,
 			})
 	}
 
@@ -666,6 +680,7 @@ func TestQueryConsumerChains(t *testing.T) {
 			Metadata:                metadata,
 			ConsumerId:              consumerId,
 			AllowlistedRewardDenoms: &types.AllowlistedRewardDenoms{Denoms: []string{}},
+			Prioritylist:            []string{},
 		}
 		consumerIds[i] = consumerId
 		consumers[i] = &c