feat(datastore): adds ChainMetadata (#177)

This PR adds a new metadata type for storing information related to a
chain. Similar to other sections of the datastore that support custom
domain metadata, chain metadata uses the chain selector as the key and
includes a metadata field of type any.

Author: giogam

.changeset/lemon-cars-move.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": patch
+---
+
+feat(datastore): adds ChainMetadata

datastore/chain_metadata.go

@@ -0,0 +1,38 @@
+package datastore
+
+import "errors"
+
+var ErrChainMetadataNotFound = errors.New("no chain metadata record can be found for the provided key")
+var ErrChainMetadataExists = errors.New("a chain metadata record with the supplied key already exists")
+
+// ChainMetadata implements the UniqueRecord interface
+var _ UniqueRecord[ChainMetadataKey, ChainMetadata] = ChainMetadata{}
+
+// ChainMetadata is a struct that holds the metadata for a specific chain.
+// It implements the UniqueRecord interface and is used to store chain metadata in the datastore.
+// NOTE: Metadata can be of any type. To convert from any to a specific type, use the utility method As.
+type ChainMetadata struct {
+	// ChainSelector refers to the chain associated with the metadata.
+	ChainSelector uint64 `json:"chainSelector"`
+	// Metadata is the metadata associated with the chain.
+	Metadata any `json:"metadata"`
+}
+
+// Clone creates a copy of the ChainMetadata.
+func (r ChainMetadata) Clone() (ChainMetadata, error) {
+	metaClone, err := clone(r.Metadata)
+	if err != nil {
+		return ChainMetadata{}, err
+	}
+
+	return ChainMetadata{
+		ChainSelector: r.ChainSelector,
+		Metadata:      metaClone,
+	}, nil
+}
+
+// Key returns the ChainMetadataKey for the ChainMetadata.
+// It is used to uniquely identify the chain metadata in the datastore.
+func (r ChainMetadata) Key() ChainMetadataKey {
+	return NewChainMetadataKey(r.ChainSelector)
+}

datastore/chain_metadata_key.go

@@ -0,0 +1,45 @@
+package datastore
+
+import (
+	"fmt"
+	"strconv"
+)
+
+// ChainMetadataKey is an interface that represents a key for ChainMetadata records.
+// It is used to uniquely identify a record in the ChainMetadataStore.
+type ChainMetadataKey interface {
+	Comparable[ChainMetadataKey]
+	fmt.Stringer
+
+	// ChainSelector returns the chain-selector of the chain associated with the metadata.
+	ChainSelector() uint64
+}
+
+// contractMetadataKey implements the ChainMetadataKey interface.
+var _ ChainMetadataKey = chainMetadataKey{}
+
+// chainMetadataKey is a struct that implements the ChainMetadataKey interface.
+// It is used to uniquely identify a record in the ChainMetadataStore.
+type chainMetadataKey struct {
+	chainSelector uint64
+}
+
+// ChainSelector returns the chain-selector of the chain associated with the metadata.
+func (c chainMetadataKey) ChainSelector() uint64 { return c.chainSelector }
+
+// Equals returns true if the two ChainMetadataKey instances are equal, false otherwise.
+func (c chainMetadataKey) Equals(other ChainMetadataKey) bool {
+	return c.chainSelector == other.ChainSelector()
+}
+
+// String returns a string representation of the ChainMetadataKey.
+func (c chainMetadataKey) String() string {
+	return strconv.FormatUint(c.chainSelector, 10)
+}
+
+// NewChainMetadataKey creates a new ChainMetadataKey instance.
+func NewChainMetadataKey(chainSelector uint64) ChainMetadataKey {
+	return chainMetadataKey{
+		chainSelector: chainSelector,
+	}
+}

datastore/chain_metadata_key_test.go

@@ -0,0 +1,57 @@
+package datastore
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestChainMetadataKey_Equals(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		key1     ChainMetadataKey
+		key2     ChainMetadataKey
+		expected bool
+	}{
+		{
+			name:     "Equal keys",
+			key1:     NewChainMetadataKey(1),
+			key2:     NewChainMetadataKey(1),
+			expected: true,
+		},
+		{
+			name:     "Different keys",
+			key1:     NewChainMetadataKey(1),
+			key2:     NewChainMetadataKey(2),
+			expected: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			require.Equal(t, tt.expected, tt.key1.Equals(tt.key2))
+		})
+	}
+}
+
+func TestChainMetadataKey_ChainSelector(t *testing.T) {
+	t.Parallel()
+
+	chainSelector := uint64(1)
+
+	key := NewChainMetadataKey(chainSelector)
+
+	require.Equal(t, chainSelector, key.ChainSelector(), "ChainSelector should return the correct chain selector")
+}
+
+func TestChainMetadataKey_String(t *testing.T) {
+	t.Parallel()
+
+	key := NewChainMetadataKey(99)
+	expected := "99"
+	require.Equal(t, expected, key.String())
+}

datastore/chain_metadata_test.go

@@ -0,0 +1,57 @@
+package datastore
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	chain_selectors "github.com/smartcontractkit/chain-selectors"
+)
+
+func TestChainMetadata_Clone(t *testing.T) {
+	t.Parallel()
+
+	original := ChainMetadata{
+		ChainSelector: 1,
+		Metadata: testMetadata{
+			Field:         "test field",
+			ChainSelector: chain_selectors.APTOS_MAINNET.Selector,
+		},
+	}
+
+	cloned, err := original.Clone()
+	require.NoError(t, err, "Clone should not return an error")
+
+	require.Equal(t, original.ChainSelector, cloned.ChainSelector)
+
+	concrete, err := As[testMetadata](cloned.Metadata)
+	require.NoError(t, err, "As should not return an error for CustomMetadata")
+	require.Equal(t, original.Metadata, concrete)
+
+	// Modify the original and ensure the cloned remains unchanged
+	original.ChainSelector = 2
+	original.Metadata = testMetadata{
+		Field:         "updated field",
+		ChainSelector: chain_selectors.APTOS_MAINNET.Selector,
+	}
+
+	require.NotEqual(t, original.ChainSelector, cloned.ChainSelector)
+
+	concrete, err = As[testMetadata](cloned.Metadata)
+	require.NoError(t, err, "As should not return an error for CustomMetadata")
+	require.NotEqual(t, original.Metadata, concrete, "Cloned metadata should not be equal to modified original")
+}
+
+func TestChainMetadata_Key(t *testing.T) {
+	t.Parallel()
+
+	metadata := ChainMetadata{
+		ChainSelector: 1,
+		Metadata:      testMetadata{Field: "test data", ChainSelector: 0},
+	}
+
+	key := metadata.Key()
+	expectedKey := NewChainMetadataKey(1)
+
+	require.Equal(t, expectedKey, key)
+}

datastore/filters.go

@@ -87,3 +87,17 @@ func ContractMetadataByChainSelector(chainSelector uint64) FilterFunc[ContractMe
 		return filtered
 	}
 }
+
+// ChainMetadataByChainSelector returns a filter that only includes records with the provided chain selector.
+func ChainMetadataByChainSelector(chainSelector uint64) FilterFunc[ChainMetadataKey, ChainMetadata] {
+	return func(records []ChainMetadata) []ChainMetadata {
+		filtered := make([]ChainMetadata, 0, len(records)) // Pre-allocate capacity
+		for _, record := range records {
+			if record.ChainSelector == chainSelector {
+				filtered = append(filtered, record)
+			}
+		}
+
+		return filtered
+	}
+}

datastore/filters_test.go

@@ -406,3 +406,63 @@ func TestContractMetadataByChainSelector(t *testing.T) {
 		})
 	}
 }
+
+func TestChainMetadataByChainSelector(t *testing.T) {
+	t.Parallel()
+
+	var (
+		recordOne = ChainMetadata{
+			ChainSelector: 1,
+			Metadata:      testMetadata{Field: "Record1", ChainSelector: 0},
+		}
+		recordTwo = ChainMetadata{
+			ChainSelector: 2,
+			Metadata:      testMetadata{Field: "Record2", ChainSelector: 0},
+		}
+		recordThree = ChainMetadata{
+			ChainSelector: 1,
+			Metadata:      testMetadata{Field: "Record3", ChainSelector: 0},
+		}
+	)
+
+	tests := []struct {
+		name           string
+		givenState     []ChainMetadata
+		giveChain      uint64
+		expectedResult []ChainMetadata
+	}{
+		{
+			name: "success: returns records with given chain",
+			givenState: []ChainMetadata{
+				recordOne,
+				recordTwo,
+				recordThree,
+			},
+			giveChain: 1,
+			expectedResult: []ChainMetadata{
+				recordOne,
+				recordThree,
+			},
+		},
+		{
+			name: "success: returns no records with given chain",
+			givenState: []ChainMetadata{
+				recordOne,
+				recordTwo,
+				recordThree,
+			},
+			giveChain:      3,
+			expectedResult: []ChainMetadata{},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			filter := ChainMetadataByChainSelector(tt.giveChain)
+			filteredRecords := filter(tt.givenState)
+			assert.Equal(t, tt.expectedResult, filteredRecords)
+		})
+	}
+}