fix: bind changesets and proposal operations using changeset uuids (#919)

Change how we associate proposal operations and changesets. Previously
we relied on the "operation id"s, which had recently been added to the
proposal's operation types. However, that change had to be reverted and
the latest release of mcms no longer contains the operation id
attributes.

As an alternative, we now reverse the association by assigning a unique
(uu)id to each changeset, and then add a tag to the operations that were
generated by the changeset:

```json
{
  ...
  "metadata": {
    "changesets": [{
      "id": "c00e5d67-c275-4389-aded-7d8b151cbd5b",
        "name": "my_changeset",
        "input": {
          "payload": {
            "key": "value"
          }
        }
    }]
  },
  "operations": [{
    "chainSelector": 12345678901234567890,
    "transactions": [{
      "to": "0x02",
      "data": "",
      "additionalFields": { "value": 0 },
      "contractType": "",
      "tags": [ "changeset:c00e5d67-c275-4389-aded-7d8b151cbd5b" ]
    }]
  }]
}
```

This pull-request also applies a couple of change requests from CCIP
after initial tests with the proposal hooks API:
1. return a failure in fork tests and the "mcms hooks" command when a
hook with failure policy set as "abort" returns an error
2. expose an new interface in the ProposalHookEnv (`ForkContext`) and a
corresponding implementation for EVM (`EVMForkContext`) which allows
hooks to identify that they're running inside a "forked environment" and
gives them the configuration so that they can directly access it (e.g.,
the URL of the RPC spawned by the anvil container).
  
--- 
OPT-467

Author: gustavogama-cll

.changeset/quick-cities-hide.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": patch
+---
+
+fix: use "changeset uuids" to associate proposal operations and changesets

engine/cld/changeset/hooks.go

@@ -50,6 +50,8 @@ type ProposalHookEnv struct {
 	Name        string
 	Logger      logger.Logger
 	BlockChains chain.BlockChains
+	ForkContext ForkContext
+	// TODO: read-only JD and CRE clients
 }
 
 // PreHookParams is passed to pre-hooks.

engine/cld/changeset/mcms.go

@@ -7,22 +7,32 @@ import (
 	"time"
 
 	gethcommon "github.com/ethereum/go-ethereum/common"
+	chainsel "github.com/smartcontractkit/chain-selectors"
 	"github.com/smartcontractkit/mcms"
 	mcmstypes "github.com/smartcontractkit/mcms/types"
 
 	fdeployment "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
+	cldfenv "github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/environment"
 )
 
 // ----- mcms timelock execution report types -----
 
+type MCMSReportStatus string
+
+const (
+	StatusSuccess MCMSReportStatus = "SUCCESS"
+	StatusNoOp    MCMSReportStatus = "NOOP"
+	StatusFailed  MCMSReportStatus = "FAILED"
+)
+
 type mcmsReport[IN, OUT any] struct {
-	ID        string    `json:"id"`
-	Type      string    `json:"type"`
-	Status    string    `json:"status,omitempty"`
-	Error     string    `json:"error,omitempty"`
-	Timestamp time.Time `json:"timestamp,omitzero"`
-	Input     IN        `json:"input,omitempty"`
-	Output    OUT       `json:"output,omitempty"`
+	ID        string           `json:"id"`
+	Type      string           `json:"type"`
+	Status    MCMSReportStatus `json:"status,omitempty"`
+	Error     string           `json:"error,omitempty"`
+	Timestamp time.Time        `json:"timestamp,omitzero"`
+	Input     IN               `json:"input,omitempty"`
+	Output    OUT              `json:"output,omitempty"`
 }
 
 type MCMSTimelockExecuteReportInput struct {
@@ -40,6 +50,7 @@ type MCMSTimelockExecuteReportOutput struct {
 }
 
 type MCMSReportChangeset struct {
+	ID    string `json:"id"`
 	Index int    `json:"index"`
 	Name  string `json:"name,omitzero"`
 }
@@ -48,24 +59,49 @@ type MCMSTimelockExecuteReport mcmsReport[MCMSTimelockExecuteReportInput, MCMSTi
 
 const MCMSTimelockExecuteReportType = "timelock-execution"
 
+// ----- fork context -----
+
+// ForkContext provides information about the forked state of the environment, if applicable. It is
+// exposed to hooks to allow them to adjust their behavior accordingly.
+type ForkContext interface {
+	ChainFamily() string
+}
+
+type EVMForkContext struct {
+	ChainConfig cldfenv.ChainConfig
+	Client      cldfenv.ForkedOnchainClient
+}
+
+func (*EVMForkContext) ChainFamily() string {
+	return chainsel.FamilyEVM
+}
+
 // RunProposalHooks executes all post-proposal hooks for the given proposal and reports. It returns
 // an error if any of the hooks fail.
 // Execution order is:
 //  1. Per-changeset post-proposal-hooks
 //  2. Global post-proposal-hooks
 func (r *ChangesetsRegistry) RunProposalHooks(
-	key string, e fdeployment.Environment, proposal *mcms.TimelockProposal, input any, reports []MCMSTimelockExecuteReport,
+	key string, e fdeployment.Environment, proposal *mcms.TimelockProposal, input any,
+	reports []MCMSTimelockExecuteReport, forkCtx ForkContext,
 ) error {
 	applySnapshot, err := r.getApplySnapshot(key)
 	if err != nil {
 		return err
 	}
 
+	blockChains := e.BlockChains
+	if forkCtx == nil {
+		blockChains = blockChains.ReadOnly()
+	}
+
 	params := PostProposalHookParams{
 		Env: ProposalHookEnv{
 			Name:        e.Name,
 			Logger:      e.Logger,
-			BlockChains: e.BlockChains.ReadOnly(),
+			BlockChains: blockChains,
+			ForkContext: forkCtx,
+			// TODO: JD and CRE clients
 		},
 		ChangesetKey: key,
 		Proposal:     proposal,

engine/cld/changeset/mcms_test.go

@@ -148,7 +148,7 @@ func Test_RunProposalHooks(t *testing.T) {
 			execLogs := []string{}
 			registry := tt.setup(&execLogs)
 
-			err := registry.RunProposalHooks(tt.key, hookTestEnv(t), &mcms.TimelockProposal{}, nil, nil)
+			err := registry.RunProposalHooks(tt.key, hookTestEnv(t), &mcms.TimelockProposal{}, nil, nil, nil)
 
 			if tt.wantErr == "" {
 				require.NoError(t, err)
@@ -181,7 +181,7 @@ func Test_RunProposalHooks_HookReceivesCorrectParams(t *testing.T) {
 		}},
 	}
 
-	err := r.RunProposalHooks("test-cs", hookTestEnv(t), proposal, input, reports)
+	err := r.RunProposalHooks("test-cs", hookTestEnv(t), proposal, input, reports, nil)
 	require.NoError(t, err)
 
 	expectedParams := PostProposalHookParams{

engine/cld/changeset/registry_test.go

@@ -919,7 +919,7 @@ func Test_FluentAPI_HooksExtractedByAdd(t *testing.T) {
 		require.Len(t, entry.postProposalHooks, 1, "Add should extract post-proposal-hooks via hookCarrier")
 		require.Equal(t, "proposal-hook", entry.postProposalHooks[0].Name)
 
-		err := r.RunProposalHooks("test-cs", hookTestEnv(t), nil, "input", nil)
+		err := r.RunProposalHooks("test-cs", hookTestEnv(t), nil, "input", nil, nil)
 		require.NoError(t, err)
 		require.Equal(t, []string{"proposal"}, hookExecutions)
 	})
@@ -940,7 +940,7 @@ func Test_FluentAPI_HooksExtractedByAdd(t *testing.T) {
 		require.Len(t, entry.postProposalHooks, 1)
 		require.Equal(t, "proposal-hook", entry.postProposalHooks[0].Name)
 
-		err := r.RunProposalHooks("test-cs", hookTestEnv(t), nil, "input", nil)
+		err := r.RunProposalHooks("test-cs", hookTestEnv(t), nil, "input", nil, nil)
 		require.NoError(t, err)
 		require.Equal(t, []string{"proposal"}, hookExecutions)
 	})

engine/cld/commands/mcms/cmd_execute_fork.go

@@ -30,6 +30,7 @@ import (
 
 	"github.com/smartcontractkit/chainlink-deployments-framework/chain"
 	cldf_evm "github.com/smartcontractkit/chainlink-deployments-framework/chain/evm"
+	cldfchangeset "github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/changeset"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/flags"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/mcms/layout"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/text"
@@ -166,28 +167,33 @@ func executeFork(
 	}
 	if family != chainsel.FamilyEVM {
 		lggr.Infof("Skipping fork execution: chain selector %d is not EVM. Family is %s", cfg.chainSelector, family)
-
-		return nil // don't fail, just exit cleanly
+		return nil
 	}
 
-	if len(cfg.forkedEnv.ChainConfigs[cfg.chainSelector].HTTPRPCs) == 0 {
+	chainConfig, ok := cfg.forkedEnv.ChainConfigs[cfg.chainSelector]
+	if !ok {
+		return fmt.Errorf("failed to get forked env's chain config for chain %d", cfg.chainSelector)
+	}
+	if len(chainConfig.HTTPRPCs) == 0 {
 		return fmt.Errorf("no rpcs loaded in forked environment for chain %d (fork tests require public RPCs)", cfg.chainSelector)
 	}
-
-	// get the chain URL, chain ID and MCM contract address
-	url := cfg.forkedEnv.ChainConfigs[cfg.chainSelector].HTTPRPCs[0].External
-	anvilClient := rpc.New(url, nil)
-	chainID := cfg.forkedEnv.ChainConfigs[cfg.chainSelector].ChainID
+	forkClient, ok := cfg.forkedEnv.ForkClients[cfg.chainSelector]
+	if !ok {
+		return fmt.Errorf("failed to get fork client for chain %d", cfg.chainSelector)
+	}
 
 	// zkSync VM chains (zkSync Era, Lens, Cronos zkEVM, etc.) require anvil-zksync,
 	// not standard Anvil. Derive this from the loaded chain which is set by the chain
 	// provider, so it stays in sync with new zkSync chains automatically.
 	if evmChain, ok := cfg.blockchains.EVMChains()[cfg.chainSelector]; ok && evmChain.IsZkSyncVM {
 		lggr.Infof("Skipping fork execution: chain selector %d is zkSync VM (chain ID %s), which requires anvil-zksync instead of standard anvil",
-			cfg.chainSelector, chainID)
+			cfg.chainSelector, chainConfig.ChainID)
 
 		return nil
 	}
+
+	url := chainConfig.HTTPRPCs[0].External
+	anvilClient := rpc.New(url, nil)
 	mcmAddress := cfg.proposal.ChainMetadata[types.ChainSelector(cfg.chainSelector)].MCMAddress
 	timelockAddress := common.HexToAddress(cfg.timelockProposal.TimelockAddresses[types.ChainSelector(cfg.chainSelector)])
 
@@ -203,7 +209,7 @@ func executeFork(
 			blockchain.DefaultAnvilPublicKey,
 			blockchain.DefaultAnvilPublicKey,
 			url,
-			chainID,
+			chainConfig.ChainID,
 			mcmAddress,
 		); lerr != nil {
 			return fmt.Errorf("failed to set signer: %w", lerr)
@@ -220,7 +226,7 @@ func executeFork(
 			return fmt.Errorf("failed to overwrite proposal signature: %w", lerr)
 		}
 
-		lerr = overrideForkChainDeployerKeyWithTestSigner(cfg, chainID)
+		lerr = overrideForkChainDeployerKeyWithTestSigner(cfg, chainConfig.ChainID)
 		if lerr != nil {
 			return fmt.Errorf("failed to override fork deployer key to test signer: %w", lerr)
 		}
@@ -273,10 +279,11 @@ func executeFork(
 		return nil
 	}
 
+	forkContext := &cldfchangeset.EVMForkContext{ChainConfig: chainConfig, Client: forkClient}
 	cfg.env.Name = cfg.envStr // ensure hooks load the correct env config for the fork
-	err = runHooksInternal(mcmsCfg, cfg.env, cfg.timelockProposal, reports)
+	err = runHooksInternal(mcmsCfg, cfg.env, cfg.timelockProposal, reports, forkContext)
 	if err != nil {
-		lggr.Warnw("Failed to run post-execution hooks", "err", err)
+		return fmt.Errorf("failed to run post-proposal hooks: %w", err)
 	}
 
 	return nil

engine/cld/commands/mcms/cmd_run_hooks.go

@@ -6,7 +6,6 @@ import (
 	"errors"
 	"fmt"
 	"os"
-	"slices"
 
 	"github.com/go-viper/mapstructure/v2"
 	"github.com/samber/lo"
@@ -46,21 +45,15 @@ type runHooksFlags struct {
 }
 
 type proposalMetadata struct {
-	Changesets         []changesetMetadata     `json:"changesets" mapstructure:"changesets"`
-	PostExecutionHooks []proposalHooksMetadata `json:"postExecutionHooks" mapstructure:"postExecutionHooks"`
+	Changesets []changesetMetadata `json:"changesets" mapstructure:"changesets"`
 }
 
-type proposalHooksMetadata struct {
+type changesetMetadata struct {
+	ID    string `json:"id" mapstructure:"id"`
 	Name  string `json:"name" mapstructure:"name"`
 	Input any    `json:"input" mapstructure:"input"`
 }
 
-type changesetMetadata struct {
-	Name         string   `json:"name" mapstructure:"name"`
-	OperationIDs []string `json:"operationIDs" mapstructure:"operationIDs"`
-	Input        any      `json:"input" mapstructure:"input"`
-}
-
 func newRunProposalHooksCmd(cfg Config) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:          "hooks",
@@ -120,14 +113,15 @@ func runHooks(ctx context.Context, cfg Config, hFlags runHooksFlags) error {
 		return errors.New("expected proposal to be a TimelockProposal")
 	}
 
-	return runHooksInternal(cfg, proposalCfg.Env, proposalCfg.TimelockProposal, hFlags.reports)
+	return runHooksInternal(cfg, proposalCfg.Env, proposalCfg.TimelockProposal, hFlags.reports, nil)
 }
 
 func runHooksInternal(
 	cfg Config,
 	env cldf.Environment,
 	timelockProposal *mcms.TimelockProposal,
 	reports []cldfchangeset.MCMSTimelockExecuteReport,
+	forkCtx cldfchangeset.ForkContext,
 ) error {
 	if cfg.LoadChangesets == nil {
 		return errors.New("LoadChangesets function is required for proposal hook execution")
@@ -146,17 +140,17 @@ func runHooksInternal(
 
 	for _, changeset := range metadata.Changesets {
 		changesetReports := lo.Filter(reports, func(r cldfchangeset.MCMSTimelockExecuteReport, _ int) bool {
-			return slices.Contains(changeset.OperationIDs, r.Input.OperationID.Hex())
+			return changeset.ID != "" && changeset.ID == r.Input.Changeset.ID
 		})
 
-		herr := changesetRegistry.RunProposalHooks(changeset.Name, env, timelockProposal, changeset.Input, changesetReports)
+		herr := changesetRegistry.RunProposalHooks(changeset.Name, env, timelockProposal,
+			changeset.Input, changesetReports, forkCtx)
 		if herr != nil {
-			cfg.Logger.Errorw("proposal hook failed", "changeset", changeset.Name, "error", herr)
-			err = errors.Join(err, fmt.Errorf("proposal hook for changeset %q failed: %w", changeset.Name, herr))
+			return fmt.Errorf("proposal hook for changeset %q failed: %w", changeset.Name, herr)
 		}
 	}
 
-	return err
+	return nil
 }
 
 func loadReport(path string) ([]cldfchangeset.MCMSTimelockExecuteReport, error) {