feat: add timelock converter and inspector helpers

.changeset/stupid-worlds-marry.md

@@ -0,0 +1,5 @@
+---
+"@smartcontractkit/mcms": minor
+---
+
+add timelock converter and inspector helpers

.mockery.yaml

@@ -32,6 +32,7 @@ packages:
         config:
           dir: "./sdk/ton/mocks"
           filename: "api.go"
+  github.com/smartcontractkit/mcms/chainwrappers:
   github.com/smartcontractkit/mcms/sdk:
   github.com/smartcontractkit/mcms/sdk/evm:
   github.com/smartcontractkit/mcms/sdk/evm/bindings:

.tool-versions

@@ -1,4 +1,4 @@
-golang 1.24.4
+golang 1.25.3
 golangci-lint 2.1.6
 mockery 2.53.5
 nodejs 20.16.0

chainwrappers/chainaccessor.go

@@ -0,0 +1,18 @@
+package chainwrappers
+
+import (
+	aptoslib "github.com/aptos-labs/aptos-go-sdk"
+	"github.com/block-vision/sui-go-sdk/sui"
+	solrpc "github.com/gagliardetto/solana-go/rpc"
+
+	evmsdk "github.com/smartcontractkit/mcms/sdk/evm"
+	suisuisdk "github.com/smartcontractkit/mcms/sdk/sui"
+)
+
+type ChainAccessor interface {
+	Selectors() []uint64
+	EVMClient(selector uint64) (evmsdk.ContractDeployBackend, bool)
+	SolanaClient(selector uint64) (*solrpc.Client, bool)
+	AptosClient(selector uint64) (aptoslib.AptosRpcClient, bool)
+	SuiClient(selector uint64) (sui.ISuiAPI, suisuisdk.SuiSigner, bool)
+}

chainwrappers/converters.go

@@ -0,0 +1,40 @@
+package chainwrappers
+
+import (
+	"fmt"
+
+	chainsel "github.com/smartcontractkit/chain-selectors"
+
+	"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/types"
+)
+
+// BuildConverters constructs a map of chain selectors to their respective timelock converters based on the provided timelock proposal.
+func BuildConverters(chainMetadata map[types.ChainSelector]types.ChainMetadata) (map[types.ChainSelector]sdk.TimelockConverter, error) {
+	converters := make(map[types.ChainSelector]sdk.TimelockConverter)
+	for chainMeta := range chainMetadata {
+		fam, err := types.GetChainSelectorFamily(chainMeta)
+		if err != nil {
+			return nil, fmt.Errorf("error getting chain family: %w", err)
+		}
+
+		var converter sdk.TimelockConverter
+		switch fam {
+		case chainsel.FamilyEVM:
+			converter = evm.NewTimelockConverter()
+		case chainsel.FamilySolana:
+			converter = solana.NewTimelockConverter()
+		case chainsel.FamilyAptos:
+			converter = aptos.NewTimelockConverter()
+		default:
+			return nil, fmt.Errorf("unsupported chain family %s", fam)
+		}
+
+		converters[chainMeta] = converter
+	}
+
+	return converters, nil
+}

chainwrappers/converters_test.go

@@ -0,0 +1,75 @@
+package chainwrappers
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/smartcontractkit/mcms/internal/testutils/chaintest"
+	"github.com/smartcontractkit/mcms/sdk/aptos"
+	"github.com/smartcontractkit/mcms/sdk/evm"
+	"github.com/smartcontractkit/mcms/sdk/solana"
+	"github.com/smartcontractkit/mcms/types"
+)
+
+func TestBuildConverters(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		metadata    map[types.ChainSelector]types.ChainMetadata
+		expectTypes map[types.ChainSelector]any
+		expectErr   string
+	}{
+		{
+			name: "supported families",
+			metadata: map[types.ChainSelector]types.ChainMetadata{
+				chaintest.Chain2Selector: {},
+				chaintest.Chain4Selector: {},
+				chaintest.Chain5Selector: {},
+			},
+			expectTypes: map[types.ChainSelector]any{
+				chaintest.Chain2Selector: (*evm.TimelockConverter)(nil),
+				chaintest.Chain4Selector: (*solana.TimelockConverter)(nil),
+				chaintest.Chain5Selector: (*aptos.TimelockConverter)(nil),
+			},
+		},
+		{
+			name: "unsupported family",
+			metadata: map[types.ChainSelector]types.ChainMetadata{
+				chaintest.Chain6Selector: {},
+			},
+			expectErr: "unsupported chain family",
+		},
+		{
+			name: "invalid selector",
+			metadata: map[types.ChainSelector]types.ChainMetadata{
+				chaintest.ChainInvalidSelector: {},
+			},
+			expectErr: "error getting chain family",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			converters, err := BuildConverters(tc.metadata)
+
+			if tc.expectErr != "" {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tc.expectErr)
+
+				return
+			}
+
+			require.NoError(t, err)
+			require.Len(t, converters, len(tc.expectTypes))
+			for selector, expectedType := range tc.expectTypes {
+				converter, ok := converters[selector]
+				require.True(t, ok)
+				require.IsType(t, expectedType, converter)
+			}
+		})
+	}
+}

chainwrappers/inspectors.go

@@ -0,0 +1,90 @@
+package chainwrappers
+
+import (
+	"fmt"
+
+	chainsel "github.com/smartcontractkit/chain-selectors"
+
+	"github.com/smartcontractkit/mcms/sdk"
+	"github.com/smartcontractkit/mcms/sdk/aptos"
+	"github.com/smartcontractkit/mcms/sdk/evm"
+	"github.com/smartcontractkit/mcms/sdk/solana"
+	sdkSui "github.com/smartcontractkit/mcms/sdk/sui"
+	"github.com/smartcontractkit/mcms/types"
+)
+
+// BuildInspectors gets a map of inspectors for the given chain metadata and chain clients
+func BuildInspectors(
+	chains ChainAccessor,
+	chainMetadata map[types.ChainSelector]types.ChainMetadata,
+	action types.TimelockAction) (map[types.ChainSelector]sdk.Inspector, error) {
+	inspectors := map[types.ChainSelector]sdk.Inspector{}
+	for chainSelector, metadata := range chainMetadata {
+		inspector, err := BuildInspector(chains, chainSelector, action, metadata)
+		if err != nil {
+			return nil, err
+		}
+		inspectors[chainSelector] = inspector
+	}
+
+	return inspectors, nil
+}
+
+// BuildInspector constructs a chain-family-specific Inspector from ChainAccessor plus metadata.
+func BuildInspector(
+	chains ChainAccessor,
+	selector types.ChainSelector,
+	action types.TimelockAction,
+	metadata types.ChainMetadata,
+) (sdk.Inspector, error) {
+	if chains == nil {
+		return nil, fmt.Errorf("chain access is required")
+	}
+
+	family, err := types.GetChainSelectorFamily(selector)
+	if err != nil {
+		return nil, fmt.Errorf("error getting chain family: %w", err)
+	}
+
+	rawSelector := uint64(selector)
+	switch family {
+	case chainsel.FamilyEVM:
+		client, ok := chains.EVMClient(rawSelector)
+		if !ok {
+			return nil, fmt.Errorf("missing EVM chain client for selector %d", rawSelector)
+		}
+
+		return evm.NewInspector(client), nil
+	case chainsel.FamilySolana:
+		client, ok := chains.SolanaClient(rawSelector)
+		if !ok {
+			return nil, fmt.Errorf("missing Solana chain client for selector %d", rawSelector)
+		}
+
+		return solana.NewInspector(client), nil
+	case chainsel.FamilyAptos:
+		client, ok := chains.AptosClient(rawSelector)
+		if !ok {
+			return nil, fmt.Errorf("missing Aptos chain client for selector %d", rawSelector)
+		}
+		role, err := aptos.AptosRoleFromAction(action)
+		if err != nil {
+			return nil, fmt.Errorf("error determining aptos role: %w", err)
+		}
+
+		return aptos.NewInspector(client, role), nil
+	case chainsel.FamilySui:
+		client, signer, ok := chains.SuiClient(rawSelector)
+		if !ok {
+			return nil, fmt.Errorf("missing Sui chain client for selector %d", rawSelector)
+		}
+		suiMetadata, err := sdkSui.SuiMetadata(metadata)
+		if err != nil {
+			return nil, fmt.Errorf("error parsing sui metadata: %w", err)
+		}
+
+		return sdkSui.NewInspector(client, signer, suiMetadata.McmsPackageID, suiMetadata.Role)
+	default:
+		return nil, fmt.Errorf("unsupported chain family %s", family)
+	}
+}

chainwrappers/inspectors_test.go

@@ -0,0 +1,78 @@
+package chainwrappers
+
+import (
+	"testing"
+
+	chainsel "github.com/smartcontractkit/chain-selectors"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smartcontractkit/mcms/chainwrappers/mocks"
+
+	mcmsTypes "github.com/smartcontractkit/mcms/types"
+)
+
+func TestMCMInspectorBuilder_BuildInspectors(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name                    string
+		chainMetadata           map[mcmsTypes.ChainSelector]mcmsTypes.ChainMetadata
+		chainAccess             *mocks.ChainAccessor
+		setup                   func(access *mocks.ChainAccessor)
+		expectErr               bool
+		errContains             string
+		expectedInspectorsCount int
+	}{
+		{
+			name:          "empty input",
+			chainMetadata: map[mcmsTypes.ChainSelector]mcmsTypes.ChainMetadata{},
+			chainAccess:   mocks.NewChainAccessor(t),
+			expectErr:     false,
+		},
+		{
+			name: "missing chain client",
+			chainMetadata: map[mcmsTypes.ChainSelector]mcmsTypes.ChainMetadata{
+				1: {MCMAddress: "0xabc", StartingOpCount: 0},
+			},
+			chainAccess: mocks.NewChainAccessor(t),
+			expectErr:   true,
+			errContains: "error getting chain family: chain family not found for selector 1",
+		},
+		{
+			name: "valid input",
+			chainMetadata: map[mcmsTypes.ChainSelector]mcmsTypes.ChainMetadata{
+				mcmsTypes.ChainSelector(chainsel.ETHEREUM_TESTNET_SEPOLIA.Selector): {MCMAddress: "0xabc", StartingOpCount: 0},
+				mcmsTypes.ChainSelector(chainsel.SOLANA_DEVNET.Selector):            {MCMAddress: "0xabc", StartingOpCount: 0},
+			},
+			chainAccess: mocks.NewChainAccessor(t),
+			expectErr:   false,
+			setup: func(access *mocks.ChainAccessor) {
+				access.EXPECT().EVMClient(mock.Anything).Return(nil, true)
+				access.EXPECT().SolanaClient(mock.Anything).Return(nil, true)
+			},
+			expectedInspectorsCount: 2,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			if tc.chainAccess == nil {
+				tc.chainAccess = mocks.NewChainAccessor(t)
+			}
+			if tc.expectedInspectorsCount > 0 {
+				tc.setup(tc.chainAccess)
+			}
+
+			inspectors, err := BuildInspectors(tc.chainAccess, tc.chainMetadata, mcmsTypes.TimelockActionSchedule)
+			if tc.expectErr {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tc.errContains)
+			} else {
+				require.NoError(t, err)
+				require.Len(t, inspectors, tc.expectedInspectorsCount)
+			}
+		})
+	}
+}