chore: port mcms helpers from chainlink/deployment (#923)

We are porting the code in
https://github.com/smartcontractkit/chainlink/blob/develop/deployment/common/proposalutils/mcms_helpers.go
to CLDF in order to remove deps on core repo for some downstream
consumers. The functions were splitted in separate files to keep them
under semantically meaningful names. Also added unit tests and fixed
some obvious issues pointed out by copilot, but in general keeping the
logic as close as possible to what we have in core today.

1. `McmsInspectorForChain` in core repo -> moved to
`experimental/proposalutils/inspectors.go` in CLDF.
2. `BatchOperationForChain` and `TransactionForChain` moved to
`experimental/proposalutils/operations.go`in CLDF
3. `test_helpers.go` and `types.go` are moved as is from core repo to
CLDF

Followup PRs in core will attempt to replace usages with these. So we
can delete the `mcms_helpers.go` from core

## AI Summary
This pull request ports the `proposalutils` helpers from the
`chainlink/deployment` repository into the
`chainlink-deployments-framework`, making them part of the framework and
improving proposal creation, inspection, and testing across multiple
blockchain environments. The main changes include adding utility
functions for proposal operations, inspectors, and test helpers, as well
as defining relevant types and constants for MCMS (Many Chain Multisig)
and timelock configurations.

**New proposal utilities and helpers:**

* Added `experimental/proposalutils/inspectors.go` providing functions
to build MCMS inspectors for different chains, supporting optional
timelock actions and mass inspector creation.
* Added `experimental/proposalutils/operations.go` with helpers to
create transactions and batch operations for different chain families
(EVM, Solana), abstracting over chain-specific details.

**Testing support:**

* Added `experimental/proposalutils/test_helpers.go` containing test
helpers for signing and executing MCMS proposals and timelock proposals,
as well as generating single-group configs and finding call proxy
addresses for tests.

**Types and constants:**

* Added `experimental/proposalutils/types.go` defining types and
constants for MCMS roles, contract types, and configuration structures
(including gas boost config), supporting both legacy and new MCMS config
formats.

**Changelog:**

* Updated the changeset to document the addition of proposalutils
helpers to the framework.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: ecPablo

.changeset/tame-lamps-lie.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+port proposalutils helpers from engine/cld/mcms/proposalutils/ so they are part of the framework

engine/cld/mcms/proposalutils/contract_types.go

@@ -0,0 +1,19 @@
+package proposalutils
+
+import cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
+
+const (
+	BypasserManyChainMultisig        cldf.ContractType = "BypasserManyChainMultiSig"
+	CancellerManyChainMultisig       cldf.ContractType = "CancellerManyChainMultiSig"
+	ProposerManyChainMultisig        cldf.ContractType = "ProposerManyChainMultiSig"
+	ManyChainMultisig                cldf.ContractType = "ManyChainMultiSig"
+	RBACTimelock                     cldf.ContractType = "RBACTimelock"
+	CallProxy                        cldf.ContractType = "CallProxy"
+	ManyChainMultisigProgram         cldf.ContractType = "ManyChainMultiSigProgram"
+	RBACTimelockProgram              cldf.ContractType = "RBACTimelockProgram"
+	AccessControllerProgram          cldf.ContractType = "AccessControllerProgram"
+	ProposerAccessControllerAccount  cldf.ContractType = "ProposerAccessControllerAccount"
+	ExecutorAccessControllerAccount  cldf.ContractType = "ExecutorAccessControllerAccount"
+	CancellerAccessControllerAccount cldf.ContractType = "CancellerAccessControllerAccount"
+	BypasserAccessControllerAccount  cldf.ContractType = "BypasserAccessControllerAccount"
+)

engine/cld/mcms/proposalutils/inspectors.go

@@ -0,0 +1,71 @@
+package proposalutils
+
+import (
+	"fmt"
+
+	mcmschainwrappers "github.com/smartcontractkit/mcms/chainwrappers"
+	mcmssdk "github.com/smartcontractkit/mcms/sdk"
+
+	mcmstypes "github.com/smartcontractkit/mcms/types"
+
+	cldfmcmsadapters "github.com/smartcontractkit/chainlink-deployments-framework/chain/mcms/adapters"
+	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
+)
+
+type mcmsInspectorOptions struct {
+	TimelockAction mcmstypes.TimelockAction
+}
+
+// MCMSInspectorOption configures how MCMS inspectors are built.
+type MCMSInspectorOption func(*mcmsInspectorOptions)
+
+// WithTimelockAction sets the timelock action used by the inspector.
+// When omitted, the default action is TimelockActionSchedule.
+func WithTimelockAction(action mcmstypes.TimelockAction) MCMSInspectorOption {
+	return func(opts *mcmsInspectorOptions) {
+		opts.TimelockAction = action
+	}
+}
+
+// McmsInspectorForChain builds an mcmssdk.Inspector for a single chain in the given environment.
+// The chain must be present in env.BlockChains, otherwise an error is returned.
+func McmsInspectorForChain(env cldf.Environment, chain uint64, opts ...MCMSInspectorOption) (mcmssdk.Inspector, error) {
+	var options mcmsInspectorOptions
+	for _, opt := range opts {
+		opt(&options)
+	}
+
+	action := mcmstypes.TimelockActionSchedule
+	if options.TimelockAction != "" {
+		action = options.TimelockAction
+	}
+
+	chainAccessor := cldfmcmsadapters.Wrap(env.BlockChains)
+
+	return mcmschainwrappers.BuildInspector(&chainAccessor, mcmstypes.ChainSelector(chain), action,
+		mcmstypes.ChainMetadata{})
+}
+
+// McmsInspectors builds an mcmssdk.Inspector for every chain in the environment,
+// returning them keyed by uint64 chain selector. All inspectors use the default
+// TimelockActionSchedule action.
+func McmsInspectors(env cldf.Environment) (map[uint64]mcmssdk.Inspector, error) {
+	chainsMetadata := map[mcmstypes.ChainSelector]mcmstypes.ChainMetadata{}
+	for chainSelector := range env.BlockChains.All() {
+		chainsMetadata[mcmstypes.ChainSelector(chainSelector)] = mcmstypes.ChainMetadata{}
+	}
+
+	chainAccessor := cldfmcmsadapters.Wrap(env.BlockChains)
+
+	mcmsInspectors, err := mcmschainwrappers.BuildInspectors(&chainAccessor, chainsMetadata, mcmstypes.TimelockActionSchedule)
+	if err != nil {
+		return nil, fmt.Errorf("failed to build inspectors: %w", err)
+	}
+
+	inspectors := make(map[uint64]mcmssdk.Inspector, len(mcmsInspectors))
+	for chainSelector, inspector := range mcmsInspectors {
+		inspectors[uint64(chainSelector)] = inspector
+	}
+
+	return inspectors, nil
+}

engine/cld/mcms/proposalutils/inspectors_test.go

@@ -0,0 +1,160 @@
+package proposalutils
+
+import (
+	"testing"
+
+	chainsel "github.com/smartcontractkit/chain-selectors"
+	mcmstypes "github.com/smartcontractkit/mcms/types"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain"
+	cldfevm "github.com/smartcontractkit/chainlink-deployments-framework/chain/evm"
+	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
+)
+
+func TestWithTimelockAction(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		action mcmstypes.TimelockAction
+	}{
+		{
+			name:   "sets schedule action",
+			action: mcmstypes.TimelockActionSchedule,
+		},
+		{
+			name:   "sets cancel action",
+			action: mcmstypes.TimelockActionCancel,
+		},
+		{
+			name:   "sets bypass action",
+			action: mcmstypes.TimelockActionBypass,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var opts mcmsInspectorOptions
+			WithTimelockAction(tt.action)(&opts)
+			assert.Equal(t, tt.action, opts.TimelockAction)
+		})
+	}
+}
+
+func TestMcmsInspectorForChain(t *testing.T) {
+	t.Parallel()
+
+	evmSelector := chainsel.ETHEREUM_TESTNET_SEPOLIA.Selector
+
+	tests := []struct {
+		name    string
+		chains  map[uint64]chain.BlockChain
+		chain   uint64
+		opts    []MCMSInspectorOption
+		wantErr string
+	}{
+		{
+			name: "success with default action",
+			chains: map[uint64]chain.BlockChain{
+				evmSelector: cldfevm.Chain{Selector: evmSelector},
+			},
+			chain: evmSelector,
+		},
+		{
+			name: "success with custom action",
+			chains: map[uint64]chain.BlockChain{
+				evmSelector: cldfevm.Chain{Selector: evmSelector},
+			},
+			chain: evmSelector,
+			opts:  []MCMSInspectorOption{WithTimelockAction(mcmstypes.TimelockActionBypass)},
+		},
+		{
+			name:    "error when chain not in environment",
+			chains:  nil,
+			chain:   evmSelector,
+			wantErr: "missing",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			env := cldf.Environment{
+				BlockChains: chain.NewBlockChains(tt.chains),
+			}
+
+			inspector, err := McmsInspectorForChain(env, tt.chain, tt.opts...)
+
+			if tt.wantErr != "" {
+				require.ErrorContains(t, err, tt.wantErr)
+				assert.Nil(t, inspector)
+
+				return
+			}
+
+			require.NoError(t, err)
+			assert.NotNil(t, inspector)
+		})
+	}
+}
+
+func TestMcmsInspectors(t *testing.T) {
+	t.Parallel()
+
+	evmSelector1 := chainsel.ETHEREUM_TESTNET_SEPOLIA.Selector
+	evmSelector2 := chainsel.ETHEREUM_MAINNET.Selector
+
+	tests := []struct {
+		name          string
+		chains        map[uint64]chain.BlockChain
+		wantLen       int
+		wantSelectors []uint64
+	}{
+		{
+			name:          "empty blockchains returns empty map",
+			chains:        nil,
+			wantLen:       0,
+			wantSelectors: nil,
+		},
+		{
+			name: "single chain returns single inspector with uint64 key",
+			chains: map[uint64]chain.BlockChain{
+				evmSelector1: cldfevm.Chain{Selector: evmSelector1},
+			},
+			wantLen:       1,
+			wantSelectors: []uint64{evmSelector1},
+		},
+		{
+			name: "multiple chains returns inspector per chain",
+			chains: map[uint64]chain.BlockChain{
+				evmSelector1: cldfevm.Chain{Selector: evmSelector1},
+				evmSelector2: cldfevm.Chain{Selector: evmSelector2},
+			},
+			wantLen:       2,
+			wantSelectors: []uint64{evmSelector1, evmSelector2},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			env := cldf.Environment{
+				BlockChains: chain.NewBlockChains(tt.chains),
+			}
+
+			inspectors, err := McmsInspectors(env)
+			require.NoError(t, err)
+			require.Len(t, inspectors, tt.wantLen)
+
+			for _, sel := range tt.wantSelectors {
+				assert.NotNil(t, inspectors[sel], "expected inspector for selector %d", sel)
+			}
+		})
+	}
+}

engine/cld/mcms/proposalutils/mcms_role.go

@@ -0,0 +1,14 @@
+package proposalutils
+
+// MCMSRole represents a named role within the MCMS system (e.g. proposer, bypasser, canceller).
+type MCMSRole string
+
+const (
+	ProposerRole  MCMSRole = "PROPOSER"
+	BypasserRole  MCMSRole = "BYPASSER"
+	CancellerRole MCMSRole = "CANCELLER"
+)
+
+func (role MCMSRole) String() string {
+	return string(role)
+}

engine/cld/mcms/proposalutils/mcms_role_test.go

@@ -0,0 +1,30 @@
+package proposalutils
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestMCMSRole_String(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		role MCMSRole
+		want string
+	}{
+		{name: "proposer", role: ProposerRole, want: "PROPOSER"},
+		{name: "bypasser", role: BypasserRole, want: "BYPASSER"},
+		{name: "canceller", role: CancellerRole, want: "CANCELLER"},
+		{name: "custom role", role: MCMSRole("CUSTOM"), want: "CUSTOM"},
+		{name: "empty", role: MCMSRole(""), want: ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tt.want, tt.role.String())
+		})
+	}
+}

engine/cld/mcms/proposalutils/operations.go

@@ -0,0 +1,64 @@
+package proposalutils
+
+import (
+	"fmt"
+	"math/big"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/gagliardetto/solana-go"
+	chain_selectors "github.com/smartcontractkit/chain-selectors"
+	mcmsevmsdk "github.com/smartcontractkit/mcms/sdk/evm"
+	mcmssolanasdk "github.com/smartcontractkit/mcms/sdk/solana"
+	mcmstypes "github.com/smartcontractkit/mcms/types"
+)
+
+// TransactionForChain builds an mcmstypes.Transaction for the given chain selector.
+// It currently supports EVM and Solana chains; other chain families return an error.
+func TransactionForChain(
+	chain uint64, toAddress string, data []byte, value *big.Int, contractType string, tags []string,
+) (mcmstypes.Transaction, error) {
+	chainFamily, err := mcmstypes.GetChainSelectorFamily(mcmstypes.ChainSelector(chain))
+	if err != nil {
+		return mcmstypes.Transaction{}, fmt.Errorf("failed to get chain family for chain %d: %w", chain, err)
+	}
+
+	var tx mcmstypes.Transaction
+
+	switch chainFamily {
+	case chain_selectors.FamilyEVM:
+		if !common.IsHexAddress(toAddress) {
+			return mcmstypes.Transaction{}, fmt.Errorf("invalid EVM address: %s", toAddress)
+		}
+		tx = mcmsevmsdk.NewTransaction(common.HexToAddress(toAddress), data, value, contractType, tags)
+
+	case chain_selectors.FamilySolana:
+		accounts := []*solana.AccountMeta{} // FIXME: how to pass accounts to support solana?
+		var err error
+		tx, err = mcmssolanasdk.NewTransaction(toAddress, data, value, accounts, contractType, tags)
+		if err != nil {
+			return mcmstypes.Transaction{}, fmt.Errorf("failed to create solana transaction: %w", err)
+		}
+
+	default:
+		return mcmstypes.Transaction{}, fmt.Errorf("unsupported chain family %s", chainFamily)
+	}
+
+	return tx, nil
+}
+
+// BatchOperationForChain creates an mcmstypes.BatchOperation containing a single transaction
+// for the given chain selector. It delegates to TransactionForChain, so it supports EVM and
+// Solana chains.
+func BatchOperationForChain(
+	chain uint64, toAddress string, data []byte, value *big.Int, contractType string, tags []string,
+) (mcmstypes.BatchOperation, error) {
+	tx, err := TransactionForChain(chain, toAddress, data, value, contractType, tags)
+	if err != nil {
+		return mcmstypes.BatchOperation{}, fmt.Errorf("failed to create transaction for chain: %w", err)
+	}
+
+	return mcmstypes.BatchOperation{
+		ChainSelector: mcmstypes.ChainSelector(chain),
+		Transactions:  []mcmstypes.Transaction{tx},
+	}, nil
+}