Add Sui chain providers (#257)

- Add new providers for the Sui Chain interface: RPC and CTF
- Add account generator provider

Author: RodrigoAD

.changeset/all-results-brush.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+Add Sui chain providers for RPC and CTF

chain/sui/provider/account_generator.go

@@ -0,0 +1,33 @@
+package provider
+
+import (
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain/sui"
+)
+
+// AccountGenerator is an interface for generating Sui accounts.
+type AccountGenerator interface {
+	Generate() (sui.SuiSigner, error)
+}
+
+var (
+	_ AccountGenerator = (*accountGenPrivateKey)(nil)
+)
+
+// accountGenPrivateKey is an account generator that creates an account from the private key.
+type accountGenPrivateKey struct {
+	// PrivateKey is the hex formatted private key used to generate the Aptos account.
+	PrivateKey string
+}
+
+// AccountGenPrivateKey creates a new instance of accountGenPrivateKey with the provided private key.
+func AccountGenPrivateKey(privateKey string) *accountGenPrivateKey {
+	return &accountGenPrivateKey{
+		PrivateKey: privateKey,
+	}
+}
+
+// Generate generates an Sui account from the provided private key. It returns an error if the
+// private key string cannot be parsed.
+func (g *accountGenPrivateKey) Generate() (sui.SuiSigner, error) {
+	return sui.NewSignerFromHexPrivateKey(g.PrivateKey)
+}

chain/sui/provider/account_generator_test.go

@@ -0,0 +1,67 @@
+package provider
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_AccountGenPrivateKey(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name           string
+		givePrivateKey string
+		wantAddr       string
+		wantErr        string
+	}{
+		{
+			name:           "valid private key",
+			givePrivateKey: testPrivateKey,
+			wantAddr:       testAccountAddr,
+		},
+		{
+			name:           "invalid private key",
+			givePrivateKey: "invalid_private_key",
+			wantErr:        "hex private key must be exactly 64 characters",
+		},
+		{
+			name:           "empty private key",
+			givePrivateKey: "",
+			wantErr:        "hex private key must be exactly 64 characters",
+		},
+		{
+			name:           "invalid hex private key",
+			givePrivateKey: "ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ",
+			wantErr:        "encoding/hex: invalid byte",
+		},
+		{
+			name:           "wrong length private key",
+			givePrivateKey: "E4FD0E90D32CB98DC6AD64516A421E8C",
+			wantErr:        "hex private key must be exactly 64 characters",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			gen := AccountGenPrivateKey(tt.givePrivateKey)
+			account, err := gen.Generate()
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				require.ErrorContains(t, err, tt.wantErr)
+			} else {
+				require.NoError(t, err)
+				assert.NotNil(t, account)
+
+				// Verify the account generates the expected address
+				actualAddr, err := account.GetAddress()
+				require.NoError(t, err)
+
+				assert.Equal(t, tt.wantAddr, actualAddr)
+			}
+		})
+	}
+}

chain/sui/provider/const_test.go

@@ -0,0 +1,9 @@
+package provider
+
+const (
+	// testPrivateKey is a valid Sui Ed25519 private key for testing purposes (32 bytes, 64 hex chars)
+	testPrivateKey = "E4FD0E90D32CB98DC6AD64516A421E8C2731870217CDBA64203CEB158A866304"
+
+	// testAccountAddr is the expected Sui address derived from testPrivateKey
+	testAccountAddr = "0xa402ce953053607dffcdfec89406c579c8d8ddb9c90e01b7aa28f5f1538ac289"
+)

chain/sui/provider/ctf_provider.go

@@ -0,0 +1,211 @@
+package provider
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/avast/retry-go/v4"
+	sui_sdk "github.com/block-vision/sui-go-sdk/sui"
+	chain_selectors "github.com/smartcontractkit/chain-selectors"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain"
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain/sui"
+)
+
+// CTFChainProviderConfig holds the configuration to initialize the CTFChainProvider.
+type CTFChainProviderConfig struct {
+	// Required: A generator for the deployer signer account. Use AccountGenPrivateKey to
+	// create a deployer signer from a hex private key.
+	DeployerSignerGen AccountGenerator
+
+	// Required: A sync.Once instance to ensure that the CTF framework only sets up the new
+	// DefaultNetwork once
+	Once *sync.Once
+}
+
+// validate checks if the CTFChainProviderConfig is valid.
+func (c CTFChainProviderConfig) validate() error {
+	if c.DeployerSignerGen == nil {
+		return errors.New("deployer signer generator is required")
+	}
+
+	if c.Once == nil {
+		return errors.New("sync.Once instance is required")
+	}
+
+	return nil
+}
+
+var _ chain.Provider = (*CTFChainProvider)(nil)
+
+// CTFChainProvider manages a Sui chain instance running inside a Chainlink Testing Framework (CTF) Docker container.
+//
+// This provider requires Docker to be installed and operational. Spinning up a new container can be slow,
+// so it is recommended to initialize the provider only once per test suite or parent test to optimize performance.
+type CTFChainProvider struct {
+	t        *testing.T
+	selector uint64
+	config   CTFChainProviderConfig
+
+	chain *sui.Chain
+}
+
+// NewCTFChainProvider creates a new CTFChainProvider with the given selector and configuration.
+func NewCTFChainProvider(
+	t *testing.T, selector uint64, config CTFChainProviderConfig,
+) *CTFChainProvider {
+	t.Helper()
+
+	p := &CTFChainProvider{
+		t:        t,
+		selector: selector,
+		config:   config,
+	}
+
+	return p
+}
+
+// Initialize sets up the Sui chain by validating the configuration, starting a CTF container,
+// generating a deployer signer account, and constructing the chain instance.
+func (p *CTFChainProvider) Initialize(_ context.Context) (chain.BlockChain, error) {
+	if p.chain != nil {
+		return *p.chain, nil // Already initialized
+	}
+
+	if err := p.config.validate(); err != nil {
+		return nil, fmt.Errorf("failed to validate provider config: %w", err)
+	}
+
+	// Generate the deployer account
+	deployerSigner, err := p.config.DeployerSignerGen.Generate()
+	if err != nil {
+		return nil, fmt.Errorf("failed to generate deployer account: %w", err)
+	}
+
+	// Get the Sui Chain ID
+	chainID, err := chain_selectors.GetChainIDFromSelector(p.selector)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get chain ID from selector %d: %w", p.selector, err)
+	}
+
+	// Start the CTF Container
+	url, client := p.startContainer(chainID, deployerSigner)
+
+	// Construct the chain
+	p.chain = &sui.Chain{
+		ChainMetadata: sui.ChainMetadata{
+			Selector: p.selector,
+		},
+		Client: client,
+		Signer: deployerSigner,
+		URL:    url,
+		// TODO: Implement ConfirmTransaction when available
+	}
+
+	return *p.chain, nil
+}
+
+// Name returns the name of the CTFChainProvider.
+func (*CTFChainProvider) Name() string {
+	return "Sui CTF Chain Provider"
+}
+
+// ChainSelector returns the chain selector of the Sui chain managed by this provider.
+func (p *CTFChainProvider) ChainSelector() uint64 {
+	return p.selector
+}
+
+// BlockChain returns the Sui chain instance managed by this provider. You must call Initialize
+// before using this method to ensure the chain is properly set up.
+func (p *CTFChainProvider) BlockChain() chain.BlockChain {
+	return *p.chain
+}
+
+// startContainer starts a CTF container for the Sui chain with the given chain ID and deployer account.
+// It returns the URL of the Sui node and the client to interact with it.
+func (p *CTFChainProvider) startContainer(
+	chainID string, account sui.SuiSigner,
+) (string, sui_sdk.ISuiAPI) {
+	var (
+		attempts      = uint(10)
+		url           string
+		containerName string
+	)
+
+	// initialize the docker network used by CTF
+	err := framework.DefaultNetwork(p.config.Once)
+	require.NoError(p.t, err)
+
+	// Get address from signer
+	address, err := account.GetAddress()
+	require.NoError(p.t, err)
+
+	type containerResult struct {
+		url           string
+		containerName string
+	}
+
+	result, err := retry.DoWithData(func() (containerResult, error) {
+		// NOTE: Sui blockchain containers use hardcoded ports (9000/9123) and ignore the Port field
+		input := &blockchain.Input{
+			Image:     "", // filled out by defaultSui function
+			Type:      blockchain.TypeSui,
+			ChainID:   chainID,
+			PublicKey: address,
+			// Port field is ignored by Sui containers - they always use ports 9000/9123
+		}
+
+		output, rerr := blockchain.NewBlockchainNetwork(input)
+		if rerr != nil {
+			return containerResult{}, rerr
+		}
+
+		testcontainers.CleanupContainer(p.t, output.Container)
+
+		return containerResult{
+			url:           output.Nodes[0].ExternalHTTPUrl + "/v1",
+			containerName: output.ContainerName,
+		}, nil
+	},
+		retry.Context(p.t.Context()),
+		retry.Attempts(attempts),
+		retry.Delay(1*time.Second),
+		retry.DelayType(retry.FixedDelay),
+	)
+	require.NoError(p.t, err)
+
+	url = result.url
+	containerName = result.containerName
+
+	client := sui_sdk.NewSuiClient(url)
+
+	var ready bool
+	for i := range 30 {
+		time.Sleep(time.Second)
+		// TODO: Add appropriate readiness check when available
+		p.t.Logf("Sui client ready check (attempt %d)\n", i+1)
+		ready = true
+
+		break
+	}
+	require.True(p.t, ready, "Sui network not ready")
+
+	dc, err := framework.NewDockerClient()
+	require.NoError(p.t, err)
+
+	_, err = dc.ExecContainer(containerName, []string{
+		"sui", "client", "faucet",
+		"--address", address,
+	})
+	require.NoError(p.t, err)
+
+	return url, client
+}