refactor(modular-cmds): introduce mcms cmds (#727)

## MCMS Commands Migration

### Migrated to Modular Commands (`engine/cld/commands/mcms/`)

The following commands have been fully migrated to the new modular
architecture:

| Command | Description |
|---------|-------------|
| `analyze-proposal` | Analyzes MCMS proposals |
| `convert-upf` | Converts proposals to Universal Proposal Format |
| `execute-fork` | Executes proposals on forked environments (Anvil) |
| `error-decode-evm` | Decodes EVM transaction errors |

These commands are delegated from the legacy `mcmsv2` for backward
compatibility.

All deprecated code is removed. 
Code is now split into several files for better readibility.


https://smartcontract-it.atlassian.net/browse/CLD-1159

Author: ajaskolski

engine/cld/commands/commands.go

@@ -32,8 +32,10 @@ import (
 
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/addressbook"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/datastore"
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/mcms"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/state"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/domain"
+	"github.com/smartcontractkit/chainlink-deployments-framework/experimental/analyzer"
 	"github.com/smartcontractkit/chainlink-deployments-framework/pkg/logger"
 )
 
@@ -80,3 +82,19 @@ func (c *Commands) AddressBook(dom domain.Domain) (*cobra.Command, error) {
 		Domain: dom,
 	})
 }
+
+// MCMSConfig holds configuration for MCMS commands.
+type MCMSConfig struct {
+	// ProposalContextProvider creates proposal context for analysis.
+	// This is domain-specific and must be provided by the user.
+	ProposalContextProvider analyzer.ProposalContextProvider
+}
+
+// MCMS creates the mcms command group for proposal analysis and conversion.
+func (c *Commands) MCMS(dom domain.Domain, cfg MCMSConfig) (*cobra.Command, error) {
+	return mcms.NewCommand(mcms.Config{
+		Logger:                  c.lggr,
+		Domain:                  dom,
+		ProposalContextProvider: cfg.ProposalContextProvider,
+	})
+}

engine/cld/commands/flags/flags.go

@@ -18,6 +18,10 @@ func MustString(s string, _ error) string { return s }
 // Safe to use with registered flags where GetBool cannot fail.
 func MustBool(b bool, _ error) bool { return b }
 
+// MustUint64 returns the uint64 value, ignoring the error.
+// Safe to use with registered flags where GetUint64 cannot fail.
+func MustUint64(u uint64, _ error) uint64 { return u }
+
 // Environment adds the required --environment/-e flag to a command.
 // Retrieve the value with cmd.Flags().GetString("environment").
 //
@@ -68,3 +72,48 @@ func Output(cmd *cobra.Command, defaultValue string) {
 		return pflag.NormalizedName(name)
 	})
 }
+
+// --- MCMS shared flags ---
+
+// Proposal adds the required --proposal/-p flag for specifying proposal file path.
+// Retrieve the value with cmd.Flags().GetString("proposal").
+//
+// Usage:
+//
+//	flags.Proposal(cmd)
+//	// later in RunE:
+//	proposalPath, _ := cmd.Flags().GetString("proposal")
+func Proposal(cmd *cobra.Command) {
+	cmd.Flags().StringP("proposal", "p", "", "Absolute file path containing the proposal (required)")
+	_ = cmd.MarkFlagRequired("proposal")
+}
+
+// ProposalKind adds the --proposalKind/-k flag for specifying proposal type.
+// The defaultKind parameter should be a valid proposal kind string (e.g., "timelock").
+// Retrieve the value with cmd.Flags().GetString("proposalKind").
+//
+// Usage:
+//
+//	flags.ProposalKind(cmd, "timelock")
+//	// later in RunE:
+//	kind, _ := cmd.Flags().GetString("proposalKind")
+func ProposalKind(cmd *cobra.Command, defaultKind string) {
+	cmd.Flags().StringP("proposalKind", "k", defaultKind, "The type of proposal being ingested")
+}
+
+// ChainSelector adds the --selector/-s flag for specifying chain selector.
+// If required is true, the flag is marked as required.
+// Retrieve the value with cmd.Flags().GetUint64("selector").
+//
+// Usage:
+//
+//	flags.ChainSelector(cmd, false) // optional
+//	flags.ChainSelector(cmd, true)  // required
+//	// later in RunE:
+//	selector, _ := cmd.Flags().GetUint64("selector")
+func ChainSelector(cmd *cobra.Command, required bool) {
+	cmd.Flags().Uint64P("selector", "s", 0, "Chain selector")
+	if required {
+		_ = cmd.MarkFlagRequired("selector")
+	}
+}

engine/cld/commands/mcms/chain_helpers.go

@@ -0,0 +1,221 @@
+package mcms
+
+import (
+	"context"
+	"fmt"
+
+	chainsel "github.com/smartcontractkit/chain-selectors"
+	"github.com/smartcontractkit/mcms"
+	"github.com/smartcontractkit/mcms/sdk"
+	"github.com/smartcontractkit/mcms/sdk/aptos"
+	"github.com/smartcontractkit/mcms/sdk/evm"
+	"github.com/smartcontractkit/mcms/sdk/solana"
+	"github.com/smartcontractkit/mcms/sdk/sui"
+	"github.com/smartcontractkit/mcms/sdk/ton"
+	"github.com/smartcontractkit/mcms/types"
+	"github.com/xssnick/tonutils-go/tlb"
+
+	suibindings "github.com/smartcontractkit/chainlink-sui/bindings"
+)
+
+// getInspectorFromChainSelector returns an inspector for the given chain selector.
+func getInspectorFromChainSelector(cfg *forkConfig) (sdk.Inspector, error) {
+	fam, err := types.GetChainSelectorFamily(types.ChainSelector(cfg.chainSelector))
+	if err != nil {
+		return nil, fmt.Errorf("error getting chain family: %w", err)
+	}
+
+	var inspector sdk.Inspector
+	switch fam {
+	case chainsel.FamilyEVM:
+		evmChain := cfg.blockchains.EVMChains()[cfg.chainSelector]
+		inspector = evm.NewInspector(evmChain.Client)
+	case chainsel.FamilySolana:
+		solanaChain := cfg.blockchains.SolanaChains()[cfg.chainSelector]
+		inspector = solana.NewInspector(solanaChain.Client)
+	case chainsel.FamilyAptos:
+		role, err := aptosRoleFromProposal(cfg.timelockProposal)
+		if err != nil {
+			return nil, fmt.Errorf("error getting aptos role from proposal: %w", err)
+		}
+		aptosChain := cfg.blockchains.AptosChains()[cfg.chainSelector]
+		inspector = aptos.NewInspector(aptosChain.Client, *role)
+	case chainsel.FamilySui:
+		metadata, err := suiMetadataFromProposal(types.ChainSelector(cfg.chainSelector), cfg.timelockProposal)
+		if err != nil {
+			return nil, fmt.Errorf("error getting sui metadata from proposal: %w", err)
+		}
+		suiChain := cfg.blockchains.SuiChains()[cfg.chainSelector]
+		inspector, err = sui.NewInspector(suiChain.Client, suiChain.Signer, metadata.McmsPackageID, metadata.Role)
+		if err != nil {
+			return nil, fmt.Errorf("error creating sui inspector: %w", err)
+		}
+	case chainsel.FamilyTon:
+		tonChain := cfg.blockchains.TonChains()[cfg.chainSelector]
+		inspector = ton.NewInspector(tonChain.Client)
+	default:
+		return nil, fmt.Errorf("unsupported chain family %s", fam)
+	}
+
+	return inspector, nil
+}
+
+// createExecutable creates an MCMS executable for the proposal.
+func createExecutable(cfg *forkConfig) (*mcms.Executable, error) {
+	executors := make(map[types.ChainSelector]sdk.Executor, len(cfg.proposal.ChainMetadata))
+	for chainSelector := range cfg.proposal.ChainMetadata {
+		if cfg.chainSelector == 0 || cfg.chainSelector == uint64(chainSelector) {
+			executor, err := getExecutorWithChainOverride(cfg, chainSelector)
+			if err != nil {
+				return &mcms.Executable{}, fmt.Errorf("unable to get executor with chain override: %w", err)
+			}
+			executors[chainSelector] = executor
+		}
+	}
+
+	return mcms.NewExecutable(&cfg.proposal, executors)
+}
+
+// createTimelockExecutable creates a timelock executable for the proposal.
+func createTimelockExecutable(ctx context.Context, cfg *forkConfig) (*mcms.TimelockExecutable, error) {
+	executors := make(map[types.ChainSelector]sdk.TimelockExecutor, len(cfg.timelockProposal.ChainMetadata))
+	for chainSelector := range cfg.timelockProposal.ChainMetadata {
+		if cfg.chainSelector != 0 && cfg.chainSelector != uint64(chainSelector) {
+			continue
+		}
+		executor, err := getTimelockExecutorWithChainOverride(cfg, chainSelector)
+		if err != nil {
+			return &mcms.TimelockExecutable{}, err
+		}
+		executors[chainSelector] = executor
+	}
+
+	return mcms.NewTimelockExecutable(ctx, cfg.timelockProposal, executors)
+}
+
+// getExecutorWithChainOverride returns an executor for the given chain selector.
+func getExecutorWithChainOverride(cfg *forkConfig, chainSelector types.ChainSelector) (sdk.Executor, error) {
+	family, err := types.GetChainSelectorFamily(chainSelector)
+	if err != nil {
+		return nil, fmt.Errorf("error getting chain family: %w", err)
+	}
+
+	encoders, err := cfg.proposal.GetEncoders()
+	if err != nil {
+		return nil, fmt.Errorf("error getting encoders: %w", err)
+	}
+	encoder, ok := encoders[chainSelector]
+	if !ok {
+		return nil, fmt.Errorf("unable to get encoder from proposal for chain selector %v", chainSelector)
+	}
+
+	switch family {
+	case chainsel.FamilyEVM:
+		evmEncoder, ok := encoder.(*evm.Encoder)
+		if !ok {
+			return nil, fmt.Errorf("invalid encoder type: %T", encoder)
+		}
+		c := cfg.blockchains.EVMChains()[uint64(chainSelector)]
+
+		return evm.NewExecutor(evmEncoder, c.Client, c.DeployerKey), nil
+
+	case chainsel.FamilySolana:
+		solanaEncoder, ok := encoder.(*solana.Encoder)
+		if !ok {
+			return nil, fmt.Errorf("invalid encoder type: %T", encoder)
+		}
+		c := cfg.blockchains.SolanaChains()[uint64(chainSelector)]
+
+		return solana.NewExecutor(solanaEncoder, c.Client, *c.DeployerKey), nil
+
+	case chainsel.FamilyAptos:
+		aptosEncoder, ok := encoder.(*aptos.Encoder)
+		if !ok {
+			return nil, fmt.Errorf("error getting encoder for chain %d", cfg.chainSelector)
+		}
+		role, err := aptosRoleFromProposal(cfg.timelockProposal)
+		if err != nil {
+			return nil, fmt.Errorf("error getting aptos role from proposal: %w", err)
+		}
+		c := cfg.blockchains.AptosChains()[uint64(chainSelector)]
+
+		return aptos.NewExecutor(c.Client, c.DeployerSigner, aptosEncoder, *role), nil
+
+	case chainsel.FamilySui:
+		suiEncoder, ok := encoder.(*sui.Encoder)
+		if !ok {
+			return nil, fmt.Errorf("error getting encoder for chain %d", cfg.chainSelector)
+		}
+		metadata, err := suiMetadataFromProposal(chainSelector, cfg.timelockProposal)
+		if err != nil {
+			return nil, fmt.Errorf("error getting sui metadata from proposal: %w", err)
+		}
+		c := cfg.blockchains.SuiChains()[uint64(chainSelector)]
+		entrypointEncoder := suibindings.NewCCIPEntrypointArgEncoder(metadata.RegistryObj, metadata.DeployerStateObj)
+
+		return sui.NewExecutor(c.Client, c.Signer, suiEncoder, entrypointEncoder, metadata.McmsPackageID, metadata.Role, cfg.timelockProposal.ChainMetadata[chainSelector].MCMAddress, metadata.AccountObj, metadata.RegistryObj, metadata.TimelockObj)
+
+	case chainsel.FamilyTon:
+		tonEncoder, ok := encoder.(*ton.Encoder)
+		if !ok {
+			return nil, fmt.Errorf("invalid encoder type for TON chain %d: expected *ton.Encoder, got %T", chainSelector, encoder)
+		}
+		c := cfg.blockchains.TonChains()[uint64(chainSelector)]
+		opts := ton.ExecutorOpts{
+			Encoder: tonEncoder,
+			Client:  c.Client,
+			Wallet:  c.Wallet,
+			Amount:  tlb.MustFromTON(defaultTONExecutorAmount),
+		}
+
+		return ton.NewExecutor(opts)
+
+	default:
+		return nil, fmt.Errorf("unsupported chain family %s", family)
+	}
+}
+
+// getTimelockExecutorWithChainOverride returns a timelock executor for the given chain selector.
+func getTimelockExecutorWithChainOverride(cfg *forkConfig, chainSelector types.ChainSelector) (sdk.TimelockExecutor, error) {
+	family, err := types.GetChainSelectorFamily(chainSelector)
+	if err != nil {
+		return nil, fmt.Errorf("error getting chain family: %w", err)
+	}
+
+	var executor sdk.TimelockExecutor
+	switch family {
+	case chainsel.FamilyEVM:
+		c := cfg.blockchains.EVMChains()[uint64(chainSelector)]
+		executor = evm.NewTimelockExecutor(c.Client, c.DeployerKey)
+	case chainsel.FamilySolana:
+		c := cfg.blockchains.SolanaChains()[uint64(chainSelector)]
+		executor = solana.NewTimelockExecutor(c.Client, *c.DeployerKey)
+	case chainsel.FamilyAptos:
+		c := cfg.blockchains.AptosChains()[uint64(chainSelector)]
+		executor = aptos.NewTimelockExecutor(c.Client, c.DeployerSigner)
+	case chainsel.FamilySui:
+		c := cfg.blockchains.SuiChains()[uint64(chainSelector)]
+		metadata, err := suiMetadataFromProposal(chainSelector, cfg.timelockProposal)
+		if err != nil {
+			return nil, fmt.Errorf("error getting sui metadata from proposal: %w", err)
+		}
+		entrypointEncoder := suibindings.NewCCIPEntrypointArgEncoder(metadata.RegistryObj, metadata.DeployerStateObj)
+		executor, err = sui.NewTimelockExecutor(c.Client, c.Signer, entrypointEncoder, metadata.McmsPackageID, metadata.RegistryObj, metadata.AccountObj)
+		if err != nil {
+			return nil, fmt.Errorf("error creating sui timelock executor: %w", err)
+		}
+	case chainsel.FamilyTon:
+		c := cfg.blockchains.TonChains()[uint64(chainSelector)]
+		opts := ton.TimelockExecutorOpts{
+			Client: c.Client,
+			Wallet: c.Wallet,
+			Amount: tlb.MustFromTON(defaultTONExecutorAmount),
+		}
+
+		return ton.NewTimelockExecutor(opts)
+	default:
+		return nil, fmt.Errorf("unsupported chain family %s", family)
+	}
+
+	return executor, nil
+}

engine/cld/commands/mcms/chain_helpers_aptos.go

@@ -0,0 +1,33 @@
+package mcms
+
+import (
+	"errors"
+
+	"github.com/smartcontractkit/mcms"
+	"github.com/smartcontractkit/mcms/sdk/aptos"
+	"github.com/smartcontractkit/mcms/types"
+)
+
+// aptosRoleFromProposal extracts the Aptos role from a timelock proposal.
+func aptosRoleFromProposal(proposal *mcms.TimelockProposal) (*aptos.TimelockRole, error) {
+	if proposal == nil {
+		return nil, errors.New("aptos timelock proposal is needed")
+	}
+
+	switch proposal.Action {
+	case types.TimelockActionBypass:
+		role := aptos.TimelockRoleBypasser
+
+		return &role, nil
+	case types.TimelockActionSchedule:
+		role := aptos.TimelockRoleProposer
+
+		return &role, nil
+	case types.TimelockActionCancel:
+		role := aptos.TimelockRoleCanceller
+
+		return &role, nil
+	default:
+		return nil, errors.New("unknown timelock action")
+	}
+}

engine/cld/commands/mcms/chain_helpers_sui.go

@@ -0,0 +1,30 @@
+package mcms
+
+import (
+	"encoding/json"
+	"errors"
+
+	"github.com/smartcontractkit/mcms"
+	"github.com/smartcontractkit/mcms/sdk/sui"
+	"github.com/smartcontractkit/mcms/types"
+)
+
+// suiMetadataFromProposal extracts Sui metadata from a timelock proposal.
+func suiMetadataFromProposal(selector types.ChainSelector, proposal *mcms.TimelockProposal) (sui.AdditionalFieldsMetadata, error) {
+	if proposal == nil {
+		return sui.AdditionalFieldsMetadata{}, errors.New("sui timelock proposal is needed")
+	}
+
+	var metadata sui.AdditionalFieldsMetadata
+	err := json.Unmarshal([]byte(proposal.ChainMetadata[selector].AdditionalFields), &metadata)
+	if err != nil {
+		return sui.AdditionalFieldsMetadata{}, err
+	}
+
+	err = metadata.Validate()
+	if err != nil {
+		return sui.AdditionalFieldsMetadata{}, err
+	}
+
+	return metadata, nil
+}

engine/cld/commands/mcms/chain_helpers_ton.go

@@ -0,0 +1,4 @@
+package mcms
+
+// defaultTONExecutorAmount is the default amount of TON for MCMS/Timelock executor transactions.
+const defaultTONExecutorAmount = "0.1"