feat: add contracts verification modular command (#826)

https://smartcontract-it.atlassian.net/browse/CLD-597

Extracted CCIP domain verification code and updated it to be modular
command and domain agnostic.

Teams will need to have source code imported into domain and have input
configuration like current CCIP one.

Supports catalog and local files. ( with -local flag, otherwise by
default use domain configuration env settings )

Each domain need`ContractInputsProvider` that returns
`SolidityContractMetadata` (Standard JSON sources, bytecode, compiler
version) for each supported `(contractType, version)` First data is
loaded with proper filtering. Then going through contracts in specified
env code use proper solidty metadata to verify contract.

Domain config contains block explorer API keys and optionally catalog
GRPC for CI; use `-n` for network filtering, `-a` for address filtering,
and `--local` to skip catalog.

A potential GitHub Action job could take `domain`, `environment`,
optional `networks` (chain selectors) and `address` filters to verify
these by CI.

Author: ajaskolski

.changeset/khaki-bats-occur.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+feat: extract from cld ccip and make domain agnostic verification cmd for contracts

engine/cld/commands/commands.go

@@ -31,12 +31,14 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/addressbook"
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/contract"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/datastore"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/mcms"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/state"
 	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/domain"
 	proposalanalyzer "github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/mcms/proposalanalysis/analyzer"
 	proposalrenderer "github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/mcms/proposalanalysis/renderer"
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/verification/evm"
 	"github.com/smartcontractkit/chainlink-deployments-framework/experimental/analyzer"
 	"github.com/smartcontractkit/chainlink-deployments-framework/pkg/logger"
 )
@@ -108,3 +110,19 @@ func (c *Commands) MCMS(dom domain.Domain, cfg MCMSConfig) (*cobra.Command, erro
 		ProposalRenderers:       cfg.ProposalRenderers,
 	})
 }
+
+// ContractConfig holds configuration for contract verification commands.
+type ContractConfig struct {
+	// ContractInputsProvider supplies contract metadata for verification.
+	// Required for verify-env. Domain-specific ContractInputsProvider.
+	ContractInputsProvider evm.ContractInputsProvider
+}
+
+// Contract creates the contract command group for verification.
+func (c *Commands) Contract(dom domain.Domain, cfg ContractConfig) (*cobra.Command, error) {
+	return contract.NewCommand(contract.Config{
+		Logger:                 c.lggr,
+		Domain:                 dom,
+		ContractInputsProvider: cfg.ContractInputsProvider,
+	})
+}

engine/cld/commands/contract/command.go

@@ -0,0 +1,91 @@
+package contract
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/commands/text"
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/domain"
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/verification/evm"
+	"github.com/smartcontractkit/chainlink-deployments-framework/pkg/logger"
+)
+
+var (
+	contractShort = "Contract verification commands"
+
+	contractLong = text.LongDesc(`
+		Commands for verifying deployed contracts on block explorers.
+
+		Verify contracts in an environment using the datastore or catalog to discover
+		contracts. Requires a domain-specific ContractInputsProvider to supply
+		contract metadata (Standard JSON, bytecode) for verification.
+
+		Currently supports only EVM-based chains, but can be extended to other chain types in the future.
+	`)
+)
+
+// Config holds the configuration for contract commands.
+type Config struct {
+	Logger                 logger.Logger
+	Domain                 domain.Domain
+	ContractInputsProvider evm.ContractInputsProvider
+	// VerifierHTTPClient is optional; when set, verifiers use it for API calls (e.g. in tests).
+	VerifierHTTPClient *http.Client
+
+	Deps Deps
+}
+
+// Validate checks that all required configuration fields are set.
+func (c Config) Validate() error {
+	var missing []string
+	if c.Logger == nil {
+		missing = append(missing, "Logger")
+	}
+	if c.Domain.RootPath() == "" {
+		missing = append(missing, "Domain")
+	}
+	if c.ContractInputsProvider == nil {
+		missing = append(missing, "ContractInputsProvider")
+	}
+	if len(missing) > 0 {
+		return errors.New("contract.Config: missing required fields: " + strings.Join(missing, ", "))
+	}
+
+	return nil
+}
+
+func (c *Config) deps() {
+	c.Deps.applyDefaults()
+}
+
+// NewCommand creates the contract command with verify-env subcommand.
+func NewCommand(cfg Config) (*cobra.Command, error) {
+	if err := cfg.Validate(); err != nil {
+		return nil, err
+	}
+	cfg.deps()
+
+	cmd := &cobra.Command{
+		Use:   "contract",
+		Short: contractShort,
+		Long:  contractLong,
+	}
+	cmd.AddCommand(NewVerifyEnvCmd(cfg))
+
+	return cmd, nil
+}
+
+// NewVerifyEnvCmd creates the verify-env subcommand. Exported for domains that want
+// to add it as a top-level command (e.g. verify-evm) while using the same implementation.
+func NewVerifyEnvCmd(cfg Config) *cobra.Command {
+	return newVerifyEnvCmdWithUse(cfg, "verify-env")
+}
+
+// NewVerifyEnvCmdWithUse creates the verify command with a custom Use string.
+// Use this when adding as a top-level command with a custom name (e.g. "verify-evm").
+func NewVerifyEnvCmdWithUse(cfg Config, use string) *cobra.Command {
+	return newVerifyEnvCmdWithUse(cfg, use)
+}

engine/cld/commands/contract/command_test.go

@@ -0,0 +1,120 @@
+package contract
+
+import (
+	"testing"
+
+	"github.com/Masterminds/semver/v3"
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/datastore"
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/domain"
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/verification/evm"
+	"github.com/smartcontractkit/chainlink-deployments-framework/pkg/logger"
+)
+
+// mockContractInputsProvider is a no-op provider for testing.
+type mockContractInputsProvider struct {
+	getInputsErr error
+}
+
+func (m *mockContractInputsProvider) GetInputs(_ datastore.ContractType, _ *semver.Version) (evm.SolidityContractMetadata, error) {
+	if m != nil && m.getInputsErr != nil {
+		return evm.SolidityContractMetadata{}, m.getInputsErr
+	}
+
+	return evm.SolidityContractMetadata{}, nil
+}
+
+func newTestContractCommand(t *testing.T) *cobra.Command {
+	t.Helper()
+
+	cmd, err := NewCommand(Config{
+		Logger:                 logger.Nop(),
+		Domain:                 domain.NewDomain(t.TempDir(), "testdomain"),
+		ContractInputsProvider: &mockContractInputsProvider{},
+	})
+	require.NoError(t, err)
+
+	return cmd
+}
+
+func TestNewCommand_Structure(t *testing.T) {
+	t.Parallel()
+
+	cmd := newTestContractCommand(t)
+
+	require.Equal(t, "contract", cmd.Use)
+	require.Equal(t, contractShort, cmd.Short)
+	require.NotEmpty(t, cmd.Long)
+
+	subs := cmd.Commands()
+	require.Len(t, subs, 1)
+	require.Equal(t, "verify-env", subs[0].Use)
+}
+
+func TestNewVerifyEnvCmdWithUse_CustomUse(t *testing.T) {
+	t.Parallel()
+
+	cmd := NewVerifyEnvCmdWithUse(Config{
+		Logger:                 logger.Nop(),
+		Domain:                 domain.NewDomain(t.TempDir(), "testdomain"),
+		ContractInputsProvider: &mockContractInputsProvider{},
+	}, "verify-evm")
+
+	require.NotNil(t, cmd)
+	require.Equal(t, "verify-evm", cmd.Use)
+}
+
+func TestVerifyEnv_MissingEnvironmentFlagFails(t *testing.T) {
+	t.Parallel()
+
+	cmd := newTestContractCommand(t)
+	cmd.SetArgs([]string{"verify-env"})
+
+	err := cmd.Execute()
+
+	require.Error(t, err)
+	require.Equal(t, `required flag(s) "environment" not set`, err.Error())
+}
+
+func TestConfig_Validate(t *testing.T) {
+	t.Parallel()
+
+	tempDir := t.TempDir()
+
+	t.Run("missing all required fields", func(t *testing.T) {
+		t.Parallel()
+
+		cfg := Config{}
+		err := cfg.Validate()
+
+		require.Error(t, err)
+		require.Equal(t, "contract.Config: missing required fields: Logger, Domain, ContractInputsProvider", err.Error())
+	})
+
+	t.Run("missing ContractInputsProvider", func(t *testing.T) {
+		t.Parallel()
+
+		cfg := Config{
+			Logger: logger.Nop(),
+			Domain: domain.NewDomain(tempDir, "test"),
+		}
+		err := cfg.Validate()
+
+		require.EqualError(t, err, "contract.Config: missing required fields: ContractInputsProvider")
+	})
+
+	t.Run("valid config", func(t *testing.T) {
+		t.Parallel()
+
+		cfg := Config{
+			Logger:                 logger.Nop(),
+			Domain:                 domain.NewDomain(tempDir, "test"),
+			ContractInputsProvider: &mockContractInputsProvider{},
+		}
+		err := cfg.Validate()
+
+		require.NoError(t, err)
+	})
+}

engine/cld/commands/contract/deps.go

@@ -0,0 +1,83 @@
+package contract
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/datastore"
+	cldcatalog "github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/catalog"
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/config"
+	cfgdomain "github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/config/domain"
+	cfgnet "github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/config/network"
+	"github.com/smartcontractkit/chainlink-deployments-framework/engine/cld/domain"
+	"github.com/smartcontractkit/chainlink-deployments-framework/pkg/logger"
+)
+
+// NetworkLoaderFunc loads network configuration for an environment.
+type NetworkLoaderFunc func(env string, dom domain.Domain) (*cfgnet.Config, error)
+
+// DataStoreLoadOptions configures how the datastore is loaded.
+type DataStoreLoadOptions struct {
+	// FromLocal, when true, always use local files (envdir.DataStore) and ignore domain config.
+	// Use for local runs when you want to verify against local datastore only.
+	FromLocal bool
+}
+
+// DataStoreLoaderFunc returns a datastore for the given env directory.
+// When opts.FromLocal is false and domain uses catalog datastore, loads from the remote catalog (CI-friendly).
+type DataStoreLoaderFunc func(ctx context.Context, envdir domain.EnvDir, lggr logger.Logger, opts DataStoreLoadOptions) (datastore.DataStore, error)
+
+// Deps holds injectable dependencies.
+type Deps struct {
+	NetworkLoader   NetworkLoaderFunc
+	DataStoreLoader DataStoreLoaderFunc
+}
+
+func (d *Deps) applyDefaults() {
+	if d.NetworkLoader == nil {
+		d.NetworkLoader = defaultNetworkLoader
+	}
+	if d.DataStoreLoader == nil {
+		d.DataStoreLoader = defaultDataStoreLoader
+	}
+}
+
+func defaultNetworkLoader(env string, dom domain.Domain) (*cfgnet.Config, error) {
+	return config.LoadNetworks(env, dom, logger.Nop())
+}
+
+func defaultDataStoreLoader(ctx context.Context, envdir domain.EnvDir, lggr logger.Logger, opts DataStoreLoadOptions) (datastore.DataStore, error) {
+	dom := domain.NewDomain(envdir.RootPath(), envdir.DomainKey())
+	envKey := envdir.Key()
+
+	cfg, err := config.Load(dom, envKey, lggr)
+	if err != nil {
+		if opts.FromLocal {
+			lggr.Infow("Loading datastore from local files")
+			return envdir.DataStore()
+		}
+
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	if opts.FromLocal || cfg.DatastoreType == cfgdomain.DatastoreTypeFile {
+		lggr.Infow("Loading datastore from local files")
+		return envdir.DataStore()
+	}
+
+	if cfg.Env.Catalog.GRPC == "" {
+		return nil, fmt.Errorf("catalog GRPC endpoint is required when datastore is set to %q", cfg.DatastoreType)
+	}
+	lggr.Infow("Loading datastore from catalog", "url", cfg.Env.Catalog.GRPC)
+	catalogStore, err := cldcatalog.LoadCatalog(ctx, envKey, cfg, dom)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load catalog: %w", err)
+	}
+	ds, err := datastore.LoadDataStoreFromCatalog(ctx, catalogStore)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load data from catalog: %w", err)
+	}
+	lggr.Infow("Loaded datastore from catalog")
+
+	return ds, nil
+}