feat(mcms): add Solana deploy changeset for MCMS with timelock [CLD-2719]

Register Solana in the MCMS deploy registry with an operations-based
sequence that deploys programs, initializes accounts/instances, and
grants timelock roles, matching the EVM deploy pattern.

Author: graham-chainlink

mcms/evm/deploy/addresses.go

@@ -3,6 +3,8 @@
 package evmdeploy
 
 import (
+	"fmt"
+
 	"github.com/ethereum/go-ethereum/common"
 	cldfdatastore "github.com/smartcontractkit/chainlink-deployments-framework/datastore"
 	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
@@ -21,9 +23,9 @@ type deployedAddresses struct {
 	CallProxy common.Address
 }
 
-func loadDeployedAddresses(ds cldfdatastore.DataStore, chainSelector uint64, qualifier string) deployedAddresses {
+func loadDeployedAddresses(ds cldfdatastore.DataStore, chainSelector uint64, qualifier string) (deployedAddresses, error) {
 	if ds == nil {
-		return deployedAddresses{}
+		return deployedAddresses{}, nil
 	}
 
 	type lookup struct {
@@ -41,45 +43,46 @@ func loadDeployedAddresses(ds cldfdatastore.DataStore, chainSelector uint64, qua
 	}
 
 	for _, l := range lookups {
-		if addr, ok := findDeployedAddress(ds.Addresses(), chainSelector, l.contractType, qualifier); ok {
+		addr, ok, err := findDeployedAddress(ds.Addresses(), chainSelector, l.contractType, qualifier)
+		if err != nil {
+			return deployedAddresses{}, err
+		}
+		if ok {
 			*l.dest = addr
 		}
 	}
 
-	return addrs
+	return addrs, nil
 }
 
 // findDeployedAddress returns a previously deployed contract address for this
-// deploy package's version. Legacy datastore entries without a version are
-// accepted as a fallback; refs with a different version are ignored so a
-// version bump can redeploy.
+// deploy package's version. Qualifier is always matched exactly, including "".
+// Returns ok=false when no ref matches; an error when multiple refs match.
 func findDeployedAddress(
 	store cldfdatastore.AddressRefStore,
 	chainSelector uint64,
 	contractType cldf.ContractType,
 	qualifier string,
-) (common.Address, bool) {
-	baseFilters := make([]cldfdatastore.FilterFunc[cldfdatastore.AddressRefKey, cldfdatastore.AddressRef], 0, 3)
-	baseFilters = append(baseFilters,
+) (common.Address, bool, error) {
+	version := semvers.V1_0_0
+	refs := store.Filter(
 		cldfdatastore.AddressRefByChainSelector(chainSelector),
 		cldfdatastore.AddressRefByType(cldfdatastore.ContractType(contractType)),
 		cldfdatastore.AddressRefByQualifier(qualifier),
+		cldfdatastore.AddressRefByVersion(&version),
 	)
-
-	version := semvers.V1_0_0
-	refs := store.Filter(append(baseFilters, cldfdatastore.AddressRefByVersion(&version))...)
-	if len(refs) > 0 {
-		return common.HexToAddress(refs[0].Address), true
+	switch len(refs) {
+	case 0:
+		return common.Address{}, false, nil
+	case 1:
+		return common.HexToAddress(refs[0].Address), true, nil
+	default:
+		return common.Address{}, false, fmt.Errorf(
+			"%w: chain selector %d contract type %s qualifier %q version %s: found %d refs",
+			cldfdatastore.ErrAddressRefQueryAmbiguous,
+			chainSelector, contractType, qualifier, version, len(refs),
+		)
 	}
-
-	refs = store.Filter(baseFilters...)
-	for _, ref := range refs {
-		if ref.Version == nil {
-			return common.HexToAddress(ref.Address), true
-		}
-	}
-
-	return common.Address{}, false
 }
 
 // addressRefWithLabel attaches an optional label to a deployed contract address ref.

mcms/evm/deploy/addresses_test.go

@@ -21,13 +21,14 @@ func TestLoadDeployedAddresses(t *testing.T) {
 	v090 := semver.MustParse("0.9.0")
 
 	bypasserV100 := common.HexToAddress("0x00000000000000000000000000000000000000b1")
-	bypasserLegacy := common.HexToAddress("0x00000000000000000000000000000000000000b2")
 	bypasserOld := common.HexToAddress("0x00000000000000000000000000000000000000b3")
 	proposerV100 := common.HexToAddress("0x00000000000000000000000000000000000000c1")
 
 	t.Run("nil datastore", func(t *testing.T) {
 		t.Parallel()
-		require.Equal(t, deployedAddresses{}, loadDeployedAddresses(nil, selector, ""))
+		addrs, err := loadDeployedAddresses(nil, selector, "")
+		require.NoError(t, err)
+		require.Equal(t, deployedAddresses{}, addrs)
 	})
 
 	t.Run("matches v1.0.0", func(t *testing.T) {
@@ -41,7 +42,8 @@ func TestLoadDeployedAddresses(t *testing.T) {
 			Version:       &v100,
 		}))
 
-		addrs := loadDeployedAddresses(ds.Seal(), selector, "")
+		addrs, err := loadDeployedAddresses(ds.Seal(), selector, "")
+		require.NoError(t, err)
 		require.Equal(t, bypasserV100, addrs.Bypasser)
 	})
 
@@ -56,63 +58,52 @@ func TestLoadDeployedAddresses(t *testing.T) {
 			Version:       v090,
 		}))
 
-		addrs := loadDeployedAddresses(ds.Seal(), selector, "")
+		addrs, err := loadDeployedAddresses(ds.Seal(), selector, "")
+		require.NoError(t, err)
 		require.Equal(t, common.Address{}, addrs.Bypasser)
 	})
 
-	t.Run("falls back to legacy nil version", func(t *testing.T) {
+	t.Run("respects qualifier", func(t *testing.T) {
 		t.Parallel()
 
-		store := fakeAddressRefStore{refs: []cldfdatastore.AddressRef{{
+		ds := cldfdatastore.NewMemoryDataStore()
+		require.NoError(t, ds.Addresses().Add(cldfdatastore.AddressRef{
 			ChainSelector: selector,
-			Address:       bypasserLegacy.Hex(),
-			Type:          cldfdatastore.ContractType(mcmscontracts.BypasserManyChainMultisig),
-		}}}
+			Address:       proposerV100.Hex(),
+			Type:          cldfdatastore.ContractType(mcmscontracts.ProposerManyChainMultisig),
+			Version:       &v100,
+			Qualifier:     "prod",
+		}))
 
-		got, ok := findDeployedAddress(store, selector, mcmscontracts.BypasserManyChainMultisig, "")
-		require.True(t, ok)
-		require.Equal(t, bypasserLegacy, got)
+		addrs, err := loadDeployedAddresses(ds.Seal(), selector, "")
+		require.NoError(t, err)
+		require.Equal(t, common.Address{}, addrs.Proposer)
+
+		addrs, err = loadDeployedAddresses(ds.Seal(), selector, "prod")
+		require.NoError(t, err)
+		require.Equal(t, proposerV100, addrs.Proposer)
 	})
 
-	t.Run("prefers v1.0.0 over legacy nil version", func(t *testing.T) {
+	t.Run("duplicate refs", func(t *testing.T) {
 		t.Parallel()
 
 		store := fakeAddressRefStore{refs: []cldfdatastore.AddressRef{
 			{
 				ChainSelector: selector,
-				Address:       bypasserLegacy.Hex(),
+				Address:       bypasserV100.Hex(),
 				Type:          cldfdatastore.ContractType(mcmscontracts.BypasserManyChainMultisig),
+				Version:       &v100,
 			},
 			{
 				ChainSelector: selector,
-				Address:       bypasserV100.Hex(),
+				Address:       bypasserOld.Hex(),
 				Type:          cldfdatastore.ContractType(mcmscontracts.BypasserManyChainMultisig),
 				Version:       &v100,
 			},
 		}}
 
-		got, ok := findDeployedAddress(store, selector, mcmscontracts.BypasserManyChainMultisig, "")
-		require.True(t, ok)
-		require.Equal(t, bypasserV100, got)
-	})
-
-	t.Run("respects qualifier", func(t *testing.T) {
-		t.Parallel()
-
-		ds := cldfdatastore.NewMemoryDataStore()
-		require.NoError(t, ds.Addresses().Add(cldfdatastore.AddressRef{
-			ChainSelector: selector,
-			Address:       proposerV100.Hex(),
-			Type:          cldfdatastore.ContractType(mcmscontracts.ProposerManyChainMultisig),
-			Version:       &v100,
-			Qualifier:     "prod",
-		}))
-
-		addrs := loadDeployedAddresses(ds.Seal(), selector, "")
-		require.Equal(t, common.Address{}, addrs.Proposer)
-
-		addrs = loadDeployedAddresses(ds.Seal(), selector, "prod")
-		require.Equal(t, proposerV100, addrs.Proposer)
+		_, err := loadDeployedAddresses(fakeDataStore{store: store}, selector, "")
+		require.ErrorIs(t, err, cldfdatastore.ErrAddressRefQueryAmbiguous)
 	})
 }
 
@@ -131,7 +122,8 @@ func TestFindDeployedAddress(t *testing.T) {
 		Version:       &v100,
 	}))
 
-	got, ok := findDeployedAddress(ds.Addresses(), selector, mcmscontracts.RBACTimelock, "")
+	got, ok, err := findDeployedAddress(ds.Addresses(), selector, mcmscontracts.RBACTimelock, "")
+	require.NoError(t, err)
 	require.True(t, ok)
 	require.Equal(t, addr, got)
 }
@@ -162,3 +154,15 @@ func (f fakeAddressRefStore) Filter(filters ...cldfdatastore.FilterFunc[cldfdata
 
 	return refs
 }
+
+type fakeDataStore struct {
+	store fakeAddressRefStore
+}
+
+func (f fakeDataStore) Addresses() cldfdatastore.AddressRefStore { return f.store }
+
+func (f fakeDataStore) ChainMetadata() cldfdatastore.ChainMetadataStore { return nil }
+
+func (f fakeDataStore) ContractMetadata() cldfdatastore.ContractMetadataStore { return nil }
+
+func (f fakeDataStore) EnvMetadata() cldfdatastore.EnvMetadataStore { return nil }

mcms/evm/deploy/sequence.go

@@ -54,11 +54,13 @@ func deployMCMSWithTimelock(
 
 	qualifier := qualifierFromConfig(in.Config.Qualifier)
 
-	existing := loadDeployedAddresses(deps.DataStore, in.ChainSelector, qualifier)
+	existing, err := loadDeployedAddresses(deps.DataStore, in.ChainSelector, qualifier)
+	if err != nil {
+		return sequenceutils.OnChainOutput{}, fmt.Errorf("load deployed addresses: %w", err)
+	}
 
 	d := &deployer{b: b, chain: chain, config: in.Config, qualifier: qualifier}
 
-	var err error
 	if existing.Bypasser, err = d.deployMCMIfNeeded(mcmscontracts.BypasserManyChainMultisig, in.Config.Bypasser, existing.Bypasser); err != nil {
 		return d.out, err
 	}

mcms/solana/deploy/addresses.go

@@ -0,0 +1,153 @@
+package soldeploy
+
+import (
+	"fmt"
+
+	solanago "github.com/gagliardetto/solana-go"
+	cldfdatastore "github.com/smartcontractkit/chainlink-deployments-framework/datastore"
+	cldf "github.com/smartcontractkit/chainlink-deployments-framework/deployment"
+	mcmscontracts "github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/contracts/mcms"
+
+	"github.com/smartcontractkit/cld-changesets/internal/semvers"
+	legacysolana "github.com/smartcontractkit/cld-changesets/legacy/pkg/family/solana"
+)
+
+// deployedAddresses holds the on-chain state of an MCMS+timelock deployment on one
+// Solana chain. Zero values mean the corresponding program or account has not yet
+// been deployed/initialized.
+type deployedAddresses struct {
+	AccessControllerProgram          solanago.PublicKey
+	ProposerAccessControllerAccount  solanago.PublicKey
+	ExecutorAccessControllerAccount  solanago.PublicKey
+	CancellerAccessControllerAccount solanago.PublicKey
+	BypasserAccessControllerAccount  solanago.PublicKey
+	McmProgram                       solanago.PublicKey
+	ProposerMCMSeed                  legacysolana.PDASeed
+	CancellerMCMSeed                 legacysolana.PDASeed
+	BypasserMCMSeed                  legacysolana.PDASeed
+	TimelockProgram                  solanago.PublicKey
+	TimelockSeed                     legacysolana.PDASeed
+}
+
+func (d deployedAddresses) hasProposerMCM() bool {
+	return d.ProposerMCMSeed != (legacysolana.PDASeed{})
+}
+func (d deployedAddresses) hasCancellerMCM() bool {
+	return d.CancellerMCMSeed != (legacysolana.PDASeed{})
+}
+func (d deployedAddresses) hasBypasserMCM() bool {
+	return d.BypasserMCMSeed != (legacysolana.PDASeed{})
+}
+func (d deployedAddresses) hasTimelock() bool { return d.TimelockSeed != (legacysolana.PDASeed{}) }
+
+// loadDeployedAddresses returns the current deployment state for the given chain
+// and qualifier by reading address refs from the datastore. A zero value in any
+// field means the corresponding program or account has not been deployed yet.
+func loadDeployedAddresses(ds cldfdatastore.DataStore, chainSelector uint64, qualifier string) (deployedAddresses, error) {
+	if ds == nil {
+		return deployedAddresses{}, nil
+	}
+
+	var addrs deployedAddresses
+
+	// findRef returns the address string for a given contract type at this
+	// deploy package's version. Qualifier is always matched exactly, including "".
+	// Returns ("", nil) when no ref matches; an error when multiple refs match.
+	findRef := func(ct cldf.ContractType) (string, error) {
+		version := semvers.V1_0_0
+		refs := ds.Addresses().Filter(
+			cldfdatastore.AddressRefByChainSelector(chainSelector),
+			cldfdatastore.AddressRefByType(cldfdatastore.ContractType(ct)),
+			cldfdatastore.AddressRefByQualifier(qualifier),
+			cldfdatastore.AddressRefByVersion(&version),
+		)
+		switch len(refs) {
+		case 0:
+			return "", nil
+		case 1:
+			return refs[0].Address, nil
+		default:
+			return "", fmt.Errorf(
+				"%w: chain selector %d contract type %s qualifier %q version %s: found %d refs",
+				cldfdatastore.ErrAddressRefQueryAmbiguous,
+				chainSelector, ct, qualifier, version, len(refs),
+			)
+		}
+	}
+
+	loadPubkey := func(ct cldf.ContractType, dest *solanago.PublicKey) error {
+		addr, err := findRef(ct)
+		if err != nil {
+			return err
+		}
+		if addr == "" {
+			return nil
+		}
+		pk, err := solanago.PublicKeyFromBase58(addr)
+		if err != nil {
+			return fmt.Errorf("parse %s address %q: %w", ct, addr, err)
+		}
+		*dest = pk
+
+		return nil
+	}
+
+	// Plain base58 addresses (program IDs and AC accounts)
+	for _, entry := range []struct {
+		ct   cldf.ContractType
+		dest *solanago.PublicKey
+	}{
+		{mcmscontracts.AccessControllerProgram, &addrs.AccessControllerProgram},
+		{mcmscontracts.ProposerAccessControllerAccount, &addrs.ProposerAccessControllerAccount},
+		{mcmscontracts.ExecutorAccessControllerAccount, &addrs.ExecutorAccessControllerAccount},
+		{mcmscontracts.CancellerAccessControllerAccount, &addrs.CancellerAccessControllerAccount},
+		{mcmscontracts.BypasserAccessControllerAccount, &addrs.BypasserAccessControllerAccount},
+		{mcmscontracts.ManyChainMultisigProgram, &addrs.McmProgram},
+		{mcmscontracts.RBACTimelockProgram, &addrs.TimelockProgram},
+	} {
+		if err := loadPubkey(entry.ct, entry.dest); err != nil {
+			return deployedAddresses{}, err
+		}
+	}
+
+	// Seed-encoded MCM instance addresses (programID:seed)
+	for ct, dst := range map[cldf.ContractType]*legacysolana.PDASeed{
+		mcmscontracts.ProposerManyChainMultisig:  &addrs.ProposerMCMSeed,
+		mcmscontracts.CancellerManyChainMultisig: &addrs.CancellerMCMSeed,
+		mcmscontracts.BypasserManyChainMultisig:  &addrs.BypasserMCMSeed,
+	} {
+		addr, err := findRef(ct)
+		if err != nil {
+			return deployedAddresses{}, err
+		}
+		if addr == "" {
+			continue
+		}
+		programID, seed, err := legacysolana.DecodeAddressWithSeed(addr)
+		if err != nil {
+			return deployedAddresses{}, fmt.Errorf("decode %s address %q: %w", ct, addr, err)
+		}
+		// The program ID embedded in instance refs is authoritative when the
+		// program-level ref is absent.
+		if addrs.McmProgram.IsZero() {
+			addrs.McmProgram = programID
+		}
+		*dst = seed
+	}
+
+	// Seed-encoded timelock instance (programID:seed)
+	if addr, err := findRef(mcmscontracts.RBACTimelock); err != nil {
+		return deployedAddresses{}, err
+	} else if addr != "" {
+		programID, seed, err := legacysolana.DecodeAddressWithSeed(addr)
+		if err != nil {
+			return deployedAddresses{}, fmt.Errorf("decode %s address %q: %w", mcmscontracts.RBACTimelock, addr, err)
+		}
+		if addrs.TimelockProgram.IsZero() {
+			addrs.TimelockProgram = programID
+		}
+		addrs.TimelockSeed = seed
+	}
+
+	return addrs, nil
+}