fix(mcms/transfer): change to datastore ref type (#113)

For the transfer to timelock changeset, the input type contains evm
specific type which should be avoided. This commit changes the type into
a generic datastore type.

Before
```
type Config struct {
	ContractsByChain map[uint64][]common.Address `json:"contractsByChain"`
```

After
```
type Config struct {
	// ContractsByChain lists contracts as datastore refs for every supported chain family.
	ContractsByChain map[uint64][]refkey.RefKey `json:"contractsByChain,omitempty"`
```

Author: graham-chainlink

mcms/changesets/transfer-to-timelock/changeset.go

@@ -68,7 +68,17 @@ func (Changeset) Apply(env cldf.Environment, input Input) (cldf.ChangesetOutput,
 	var agg sequenceutils.OnChainOutput
 
 	for _, chainSelector := range maputil.SortedMapKeys(input.Cfg.ContractsByChain) {
-		contracts := input.Cfg.ContractsByChain[chainSelector]
+		contracts, normErr := normalizeContractRefs(chainSelector, input.Cfg.ContractsByChain[chainSelector])
+		if normErr != nil {
+			return buildOutput(env, input.MCMS, agg, fmt.Errorf("chain selector %d: %w", chainSelector, normErr))
+		}
+
+		chainInput := ChainInput{
+			ChainSelector:       chainSelector,
+			Contracts:           contracts,
+			OnlyAcceptOwnership: input.Cfg.OnlyAcceptOwnership,
+			MCMS:                input.MCMS,
+		}
 
 		seq, seqErr := Registry.SequenceForChainSelector(chainSelector)
 		if seqErr != nil {
@@ -80,12 +90,7 @@ func (Changeset) Apply(env cldf.Environment, input Input) (cldf.ChangesetOutput,
 			env.OperationsBundle,
 			deps,
 			seq,
-			ChainInput{
-				ChainSelector:       chainSelector,
-				Contracts:           contracts,
-				OnlyAcceptOwnership: input.Cfg.OnlyAcceptOwnership,
-				MCMS:                input.MCMS,
-			},
+			chainInput,
 			agg,
 		)
 		if mergeErr != nil {
@@ -134,13 +139,20 @@ func groupByFamily(input Input) (map[string][]ChainInput, error) {
 		if len(contracts) == 0 {
 			return nil, fmt.Errorf("chain %d: no contracts provided", chainSelector)
 		}
+
+		normalized, err := normalizeContractRefs(chainSelector, contracts)
+		if err != nil {
+			return nil, fmt.Errorf("chain %d: %w", chainSelector, err)
+		}
+
 		family, err := chainselectors.GetSelectorFamily(chainSelector)
 		if err != nil {
 			return nil, fmt.Errorf("chain selector %d: %w", chainSelector, err)
 		}
+
 		byFamily[family] = append(byFamily[family], ChainInput{
 			ChainSelector:       chainSelector,
-			Contracts:           contracts,
+			Contracts:           normalized,
 			OnlyAcceptOwnership: input.Cfg.OnlyAcceptOwnership,
 			MCMS:                input.MCMS,
 		})

mcms/changesets/transfer-to-timelock/changeset_test.go

@@ -5,7 +5,6 @@ import (
 	"testing"
 	"time"
 
-	"github.com/ethereum/go-ethereum/common"
 	chainselectors "github.com/smartcontractkit/chain-selectors"
 	cldf_chain "github.com/smartcontractkit/chainlink-deployments-framework/chain"
 	"github.com/smartcontractkit/chainlink-deployments-framework/datastore"
@@ -15,6 +14,8 @@ import (
 	mcmstypes "github.com/smartcontractkit/mcms/types"
 	"github.com/stretchr/testify/require"
 
+	"github.com/smartcontractkit/cld-changesets/datastore/refkey"
+	"github.com/smartcontractkit/cld-changesets/internal/semvers"
 	transfertotimelock "github.com/smartcontractkit/cld-changesets/mcms/changesets/transfer-to-timelock"
 )
 
@@ -43,15 +44,19 @@ func testMCMSInput() *cldf.MCMSTimelockProposalInput {
 	}
 }
 
+func testContractRef(selector uint64) refkey.RefKey {
+	return refkey.New(selector, "LinkToken", &semvers.V1_0_0, "")
+}
+
 func TestChangeset_VerifyPreconditions_NoDatastore(t *testing.T) {
 	t.Parallel()
 
 	env := testEnvironment(t, nil)
 	input := transfertotimelock.Input{
 		MCMS: testMCMSInput(),
 		Cfg: transfertotimelock.Config{
-			ContractsByChain: map[uint64][]common.Address{
-				chainselectors.TEST_90000001.Selector: {common.HexToAddress("0x1")},
+			ContractsByChain: map[uint64][]refkey.RefKey{
+				chainselectors.TEST_90000001.Selector: {testContractRef(chainselectors.TEST_90000001.Selector)},
 			},
 		},
 	}
@@ -66,8 +71,8 @@ func TestChangeset_VerifyPreconditions_NoMCMSInput(t *testing.T) {
 	env := testEnvironment(t, datastore.NewMemoryDataStore().Seal())
 	input := transfertotimelock.Input{
 		Cfg: transfertotimelock.Config{
-			ContractsByChain: map[uint64][]common.Address{
-				chainselectors.TEST_90000001.Selector: {common.HexToAddress("0x1")},
+			ContractsByChain: map[uint64][]refkey.RefKey{
+				chainselectors.TEST_90000001.Selector: {testContractRef(chainselectors.TEST_90000001.Selector)},
 			},
 		},
 	}
@@ -96,7 +101,7 @@ func TestChangeset_VerifyPreconditions_EmptyContractsForChain(t *testing.T) {
 	input := transfertotimelock.Input{
 		MCMS: testMCMSInput(),
 		Cfg: transfertotimelock.Config{
-			ContractsByChain: map[uint64][]common.Address{
+			ContractsByChain: map[uint64][]refkey.RefKey{
 				selector: {},
 			},
 		},
@@ -114,8 +119,8 @@ func TestChangeset_VerifyPreconditions_UnsupportedChainFamily(t *testing.T) {
 	input := transfertotimelock.Input{
 		MCMS: testMCMSInput(),
 		Cfg: transfertotimelock.Config{
-			ContractsByChain: map[uint64][]common.Address{
-				selector: {common.HexToAddress("0x1")},
+			ContractsByChain: map[uint64][]refkey.RefKey{
+				selector: {testContractRef(selector)},
 			},
 		},
 	}
@@ -130,8 +135,8 @@ func TestChangeset_Apply_NoMCMSInput(t *testing.T) {
 	env := testEnvironment(t, datastore.NewMemoryDataStore().Seal())
 	input := transfertotimelock.Input{
 		Cfg: transfertotimelock.Config{
-			ContractsByChain: map[uint64][]common.Address{
-				chainselectors.TEST_90000001.Selector: {common.HexToAddress("0x1")},
+			ContractsByChain: map[uint64][]refkey.RefKey{
+				chainselectors.TEST_90000001.Selector: {testContractRef(chainselectors.TEST_90000001.Selector)},
 			},
 		},
 	}

mcms/changesets/transfer-to-timelock/doc.go

@@ -7,17 +7,18 @@
 // sequence (plus MCMS readers when building timelock proposals):
 //
 //	import (
-//		"github.com/ethereum/go-ethereum/common"
-//
 //		transfertotimelock "github.com/smartcontractkit/cld-changesets/mcms/changesets/transfer-to-timelock"
+//		"github.com/smartcontractkit/cld-changesets/datastore/refkey"
 //		_ "github.com/smartcontractkit/cld-changesets/mcms/evm/readers"
 //		_ "github.com/smartcontractkit/cld-changesets/mcms/evm/transfer-to-timelock"
 //	)
 //
 //	rt.Exec(runtime.ChangesetTask(transfertotimelock.Changeset{}, transfertotimelock.Input{
 //		Cfg: transfertotimelock.Config{
-//			ContractsByChain: map[uint64][]common.Address{
-//				chainSelector: {common.HexToAddress("0x...")},
+//			ContractsByChain: map[uint64][]refkey.RefKey{
+//				chainSelector: {
+//					refkey.New(chainSelector, contractType, version, qualifier),
+//				},
 //			},
 //		},
 //		MCMS: mcmsInput,

mcms/changesets/transfer-to-timelock/refs.go

@@ -0,0 +1,26 @@
+package transfertotimelock
+
+import (
+	"fmt"
+
+	"github.com/smartcontractkit/cld-changesets/datastore/refkey"
+)
+
+func normalizeContractRefs(chainSelector uint64, refs []refkey.RefKey) ([]refkey.RefKey, error) {
+	normalized := make([]refkey.RefKey, len(refs))
+	for i, ref := range refs {
+		if ref.ChainSelector != 0 && ref.ChainSelector != chainSelector {
+			return nil, fmt.Errorf(
+				"contracts[%d]: ref chain selector %d does not match chain %d",
+				i,
+				ref.ChainSelector,
+				chainSelector,
+			)
+		}
+
+		ref.ChainSelector = chainSelector
+		normalized[i] = ref
+	}
+
+	return normalized, nil
+}

mcms/changesets/transfer-to-timelock/refs_test.go

@@ -0,0 +1,39 @@
+package transfertotimelock
+
+import (
+	"testing"
+
+	chainselectors "github.com/smartcontractkit/chain-selectors"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smartcontractkit/cld-changesets/datastore/refkey"
+	"github.com/smartcontractkit/cld-changesets/internal/semvers"
+)
+
+func TestNormalizeContractRefs_fillsChainSelector(t *testing.T) {
+	t.Parallel()
+
+	selector := chainselectors.TEST_90000001.Selector
+	ref := refkey.RefKey{
+		Type:      "LinkToken",
+		Version:   &semvers.V1_0_0,
+		Qualifier: "",
+	}
+
+	got, err := normalizeContractRefs(selector, []refkey.RefKey{ref})
+	require.NoError(t, err)
+	require.Len(t, got, 1)
+	require.Equal(t, selector, got[0].ChainSelector)
+}
+
+func TestNormalizeContractRefs_rejectsMismatchedChainSelector(t *testing.T) {
+	t.Parallel()
+
+	selector := chainselectors.TEST_90000001.Selector
+	other := chainselectors.TEST_90000002.Selector
+
+	_, err := normalizeContractRefs(selector, []refkey.RefKey{
+		refkey.New(other, "LinkToken", &semvers.V1_0_0, ""),
+	})
+	require.ErrorContains(t, err, "does not match chain")
+}

mcms/changesets/transfer-to-timelock/types.go

@@ -1,17 +1,19 @@
 package transfertotimelock
 
 import (
-	"github.com/ethereum/go-ethereum/common"
 	"github.com/smartcontractkit/chainlink-deployments-framework/chain"
 	"github.com/smartcontractkit/chainlink-deployments-framework/changeset/sequenceutils"
 	cldfdatastore "github.com/smartcontractkit/chainlink-deployments-framework/datastore"
 	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 	"github.com/smartcontractkit/chainlink-deployments-framework/operations"
+
+	"github.com/smartcontractkit/cld-changesets/datastore/refkey"
 )
 
 // Config selects ownable contracts to transfer to the MCMS timelock per chain.
 type Config struct {
-	ContractsByChain map[uint64][]common.Address `json:"contractsByChain"`
+	// ContractsByChain lists contracts as datastore refs for every supported chain family.
+	ContractsByChain map[uint64][]refkey.RefKey `json:"contractsByChain,omitempty"`
 	// OnlyAcceptOwnership skips the on-chain transferOwnership step and only
 	// builds accept-ownership operations for the MCMS proposal.
 	OnlyAcceptOwnership bool `json:"onlyAcceptOwnership,omitempty"`
@@ -23,7 +25,7 @@ type Input = sequenceutils.WithMCMS[Config]
 // ChainInput is the per-chain request passed to a family sequence.
 type ChainInput struct {
 	ChainSelector       uint64                          `json:"chainSelector"`
-	Contracts           []common.Address                `json:"contracts"`
+	Contracts           []refkey.RefKey                 `json:"contracts,omitempty"`
 	OnlyAcceptOwnership bool                            `json:"onlyAcceptOwnership,omitempty"`
 	MCMS                *cldf.MCMSTimelockProposalInput `json:"mcms,omitempty"`
 }

mcms/evm/transfer-to-timelock/addresses.go

@@ -4,8 +4,31 @@ import (
 	"fmt"
 
 	"github.com/ethereum/go-ethereum/common"
+	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
+
+	"github.com/smartcontractkit/cld-changesets/datastore/refkey"
 )
 
+func resolveEVMAddress(env cldf.Environment, chainSelector uint64, ref refkey.RefKey) (common.Address, error) {
+	if ref.ChainSelector != 0 && ref.ChainSelector != chainSelector {
+		return common.Address{}, fmt.Errorf(
+			"ref chain selector %d does not match chain %d",
+			ref.ChainSelector,
+			chainSelector,
+		)
+	}
+	if ref.ChainSelector == 0 {
+		ref.ChainSelector = chainSelector
+	}
+
+	resolved, err := ref.Resolve(env)
+	if err != nil {
+		return common.Address{}, err
+	}
+
+	return parseEVMAddress(resolved.Address, "contract")
+}
+
 func parseEVMAddress(addr string, label string) (common.Address, error) {
 	if !common.IsHexAddress(addr) {
 		return common.Address{}, fmt.Errorf("invalid %s address %q", label, addr)

mcms/evm/transfer-to-timelock/changeset_test.go

@@ -20,6 +20,7 @@ import (
 	mcmstypes "github.com/smartcontractkit/mcms/types"
 	"github.com/stretchr/testify/require"
 
+	"github.com/smartcontractkit/cld-changesets/datastore/refkey"
 	"github.com/smartcontractkit/cld-changesets/internal/semvers"
 	"github.com/smartcontractkit/cld-changesets/mcms/changesets/deploy"
 	transfertotimelock "github.com/smartcontractkit/cld-changesets/mcms/changesets/transfer-to-timelock"
@@ -39,8 +40,8 @@ func TestChangeset_TransferOwnershipToTimelock(t *testing.T) {
 	err := rt.Exec(
 		runtime.ChangesetTask(transfertotimelock.Changeset{}, transfertotimelock.Input{
 			Cfg: transfertotimelock.Config{
-				ContractsByChain: map[uint64][]common.Address{
-					selector: {linkToken.Address()},
+				ContractsByChain: map[uint64][]refkey.RefKey{
+					selector: {linkTokenRef(selector)},
 				},
 			},
 			MCMS: &cldf.MCMSTimelockProposalInput{
@@ -80,8 +81,8 @@ func TestChangeset_OnlyAcceptOwnership(t *testing.T) {
 		runtime.ChangesetTask(transfertotimelock.Changeset{}, transfertotimelock.Input{
 			Cfg: transfertotimelock.Config{
 				OnlyAcceptOwnership: true,
-				ContractsByChain: map[uint64][]common.Address{
-					selector: {linkToken.Address()},
+				ContractsByChain: map[uint64][]refkey.RefKey{
+					selector: {linkTokenRef(selector)},
 				},
 			},
 			MCMS: &cldf.MCMSTimelockProposalInput{
@@ -154,6 +155,12 @@ func newTransferToTimelockTestEnv(
 	return rt, chain, timelockAddr, linkToken
 }
 
+func linkTokenRef(selector uint64) refkey.RefKey {
+	tv := cldf.NewTypeAndVersion(linkcontracts.LinkToken, semvers.V1_0_0)
+
+	return refkey.New(selector, datastore.ContractType(tv.Type.String()), &semvers.V1_0_0, "")
+}
+
 func loadLinkTokenFromDataStore(t *testing.T, chain cldfevm.Chain, ds datastore.DataStore) *link_token.LinkToken {
 	t.Helper()
 

mcms/evm/transfer-to-timelock/sequence.go

@@ -47,7 +47,12 @@ func runEVMTransferToTimelock(
 	}
 
 	var transactions []mcmstypes.Transaction
-	for _, contract := range in.Contracts {
+	for i, ref := range in.Contracts {
+		contract, err := resolveEVMAddress(env, in.ChainSelector, ref)
+		if err != nil {
+			return sequenceutils.OnChainOutput{}, fmt.Errorf("contracts[%d]: %w", i, err)
+		}
+
 		txs, err := transferContractToTimelock(b, chain, timelock, contract, in)
 		if err != nil {
 			return sequenceutils.OnChainOutput{}, fmt.Errorf("contract %s: %w", contract.Hex(), err)