deployment: use timelock qualifier in SetConfigMCMSV2 changeset (#21716)

* deployment: use timelock qualifier in SetConfigMCMSV2 changeset

The SetConfigMCMSV2 changeset was loading MCMS with timelock state using
MaybeLoadMCMSWithTimelockState, which does not support timelock qualifiers.
This meant that when a ProposalConfig specified a TimelockQualifierPerChain,
the qualifier was silently ignored during both validation and execution,
causing the changeset to load the wrong timelock state.

Update both Validate() and SetConfigMCMSV2() to extract the qualifier from
ProposalConfig.TimelockQualifierPerChain and pass it to the new
MaybeLoadMCMSWithTimelockStateWithQualifier function. When ProposalConfig
is nil, the qualifier defaults to an empty string, preserving backward
compatibility.

* deployment: add unit tests for timelock qualifier in SetConfigMCMSV2

Add TestSetConfigMCMSV2WithTimelockQualifier to verify that the
TimelockQualifierPerChain field in ProposalConfig is correctly extracted
and passed to MaybeLoadMCMSWithTimelockStateWithQualifier during
validation.

The test deploys two MCMS instances on the same chain with different
qualifiers (CLLCCIP and RMNMCMS), mirroring the production setup, and
validates four scenarios:
- CLLCCIP qualifier resolves to the correct MCMS deployment
- RMNMCMS qualifier resolves to the correct MCMS deployment
- Empty qualifier fails with "found more than one instance" when
  multiple MCMS deployments exist, documenting the problem this
  changeset solves
- Non-existent qualifier fails with "no addresses found"

Author: futureproof1

deployment/common/changeset/set_config_mcms.go

@@ -66,7 +66,11 @@ func (cfg MCMSConfigV2) Validate(e cldf.Environment, selectors []uint64) error {
 
 		switch family {
 		case chain_selectors.FamilyEVM:
-			state, err := commonState.MaybeLoadMCMSWithTimelockState(e, []uint64{chainSelector})
+			qualifier := ""
+			if cfg.ProposalConfig != nil {
+				qualifier = cfg.ProposalConfig.TimelockQualifierPerChain[chainSelector]
+			}
+			state, err := commonState.MaybeLoadMCMSWithTimelockStateWithQualifier(e, []uint64{chainSelector}, qualifier)
 			if err != nil {
 				return err
 			}
@@ -213,7 +217,11 @@ func SetConfigMCMSV2(e cldf.Environment, cfg MCMSConfigV2) (cldf.ChangesetOutput
 		switch family {
 		case chain_selectors.FamilyEVM:
 			chain := e.BlockChains.EVMChains()[chainSelector]
-			mcmsStatePerChain, err := commonState.MaybeLoadMCMSWithTimelockState(e, []uint64{chainSelector})
+			qualifier := ""
+			if cfg.ProposalConfig != nil {
+				qualifier = cfg.ProposalConfig.TimelockQualifierPerChain[chainSelector]
+			}
+			mcmsStatePerChain, err := commonState.MaybeLoadMCMSWithTimelockStateWithQualifier(e, []uint64{chainSelector}, qualifier)
 			if err != nil {
 				return cldf.ChangesetOutput{}, err
 			}

deployment/common/changeset/set_config_mcms_test.go

@@ -514,6 +514,99 @@ func createSolSigner(t *testing.T) (*ecdsa.PrivateKey, common.Address) {
 	return key, crypto.PubkeyToAddress(*publicKey)
 }
 
+func TestSetConfigMCMSV2WithTimelockQualifier(t *testing.T) {
+	t.Parallel()
+
+	selector := chain_selectors.TEST_90000001.Selector
+	cllccipQualifier := "CLLCCIP"
+	rmnmcmsQualifier := "RMNMCMS"
+
+	rt, err := runtime.New(t.Context(), runtime.WithEnvOpts(
+		environment.WithEVMSimulated(t, []uint64{selector}),
+		environment.WithLogger(logger.Test(t)),
+	))
+	require.NoError(t, err)
+
+	// Deploy two MCMS instances on the same chain with different qualifiers,
+	// mirroring the production setup where each chain has CLLCCIP and RMNMCMS deployments
+	cllccipConfig := proposalutils.SingleGroupTimelockConfigV2(t)
+	cllccipConfig.Qualifier = &cllccipQualifier
+
+	rmnmcmsConfig := proposalutils.SingleGroupTimelockConfigV2(t)
+	rmnmcmsConfig.Qualifier = &rmnmcmsQualifier
+
+	err = rt.Exec(
+		runtime.ChangesetTask(cldf.CreateLegacyChangeSet(commonchangeset.DeployMCMSWithTimelockV2), map[uint64]commontypes.MCMSWithTimelockConfigV2{
+			selector: cllccipConfig,
+		}),
+	)
+	require.NoError(t, err)
+
+	err = rt.Exec(
+		runtime.ChangesetTask(cldf.CreateLegacyChangeSet(commonchangeset.DeployMCMSWithTimelockV2), map[uint64]commontypes.MCMSWithTimelockConfigV2{
+			selector: rmnmcmsConfig,
+		}),
+	)
+	require.NoError(t, err)
+
+	// Load state via the CLLCCIP qualifier to build a valid proposer config
+	cllccipState, err := state.MaybeLoadMCMSWithTimelockStateWithQualifier(rt.Environment(), []uint64{selector}, cllccipQualifier)
+	require.NoError(t, err)
+	require.NotNil(t, cllccipState[selector])
+
+	cfgProposer := proposalutils.SingleGroupMCMSV2(t)
+	cfgProposer.Signers = append(cfgProposer.Signers, cllccipState[selector].Timelock.Address())
+	cfgProposer.Quorum = 2
+
+	for _, tt := range []struct {
+		name      string
+		qualifier string
+		wantErr   string
+	}{
+		{
+			name:      "CLLCCIP qualifier matches qualified deployment",
+			qualifier: "CLLCCIP",
+		},
+		{
+			name:      "RMNMCMS qualifier matches qualified deployment",
+			qualifier: "RMNMCMS",
+		},
+		{
+			name:      "no qualifier fails with duplicate MCMS instances",
+			qualifier: "",
+			wantErr:   "found more than one instance",
+		},
+		{
+			name:      "non-existent qualifier fails",
+			qualifier: "does-not-exist",
+			wantErr:   "no addresses found",
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			mcmsCfg := commonchangeset.MCMSConfigV2{
+				ProposalConfig: &proposalutils.TimelockConfig{
+					MinDelay: 0,
+					TimelockQualifierPerChain: map[uint64]string{
+						selector: tt.qualifier,
+					},
+				},
+				ConfigsPerChain: map[uint64]commonchangeset.ConfigPerRoleV2{
+					selector: {
+						Proposer: &cfgProposer,
+					},
+				},
+			}
+			err := mcmsCfg.Validate(rt.Environment(), []uint64{selector})
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				require.ErrorContains(t, err, tt.wantErr)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}
+
 func TestSetConfigMCMSV2Partial(t *testing.T) {
 	t.Parallel()