feat: add a new provider for zkSync EVM CTF (#166)

This adds a new provider for zkSync EVM CTF, which allows users to
interact with the zkSync CTF environment. This sets up an evm.Chain with
the zkSync specific fields populated.

Author: jkongie

.changeset/shaky-plums-say.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+Adds a zkSync CTF provider under the EVM Chain

chain/aptos/provider/ctf_provider.go

@@ -135,7 +135,7 @@ func (p *CTFChainProvider) ChainSelector() uint64 {
 // BlockChain returns the Aptos 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
+	return *p.chain
 }
 
 // startContainer starts a CTF container for the Aptos chain with the given chain ID and deployer account.

chain/aptos/provider/ctf_provider_test.go

@@ -153,5 +153,5 @@ func Test_CTFChainProvider_BlockChain(t *testing.T) {
 		chain: chain,
 	}
 
-	assert.Equal(t, chain, p.BlockChain())
+	assert.Equal(t, *chain, p.BlockChain())
 }

chain/aptos/provider/rpc_provider.go

@@ -129,5 +129,5 @@ func (p *RPCChainProvider) ChainSelector() uint64 {
 // BlockChain returns the Aptos chain instance managed by this provider. You must call Initialize
 // before using this method to ensure the chain is properly set up.
 func (p *RPCChainProvider) BlockChain() chain.BlockChain {
-	return p.chain
+	return *p.chain
 }

chain/aptos/provider/rpc_provider_test.go

@@ -151,5 +151,5 @@ func Test_RPCChainProvider_BlockChain(t *testing.T) {
 		chain: chain,
 	}
 
-	assert.Equal(t, chain, p.BlockChain())
+	assert.Equal(t, *chain, p.BlockChain())
 }

chain/evm/evm_chain.go

@@ -14,11 +14,11 @@ import (
 )
 
 // OnchainClient is an EVM chain client.
-// For EVM specifically we can use existing geth interface
-// to abstract chain clients.
+// For EVM specifically we can use existing geth interface to abstract chain clients.
 type OnchainClient interface {
 	bind.ContractBackend
 	bind.DeployBackend
+
 	BalanceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (*big.Int, error)
 	NonceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (uint64, error)
 }

chain/evm/provider/zksync_ctf_provider.go

@@ -0,0 +1,205 @@
+package provider
+
+import (
+	"context"
+	"errors"
+	"math/big"
+	"strconv"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/ethereum/go-ethereum/accounts/abi/bind"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/ethereum/go-ethereum/ethclient"
+	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/smartcontractkit/freeport"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/zksync-sdk/zksync2-go/accounts"
+	"github.com/zksync-sdk/zksync2-go/clients"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain"
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain/evm"
+)
+
+// ZkCTFChainProviderConfig holds the configuration to initialize the ZkSyncCTFChainProvider.
+type ZkSyncCTFChainProviderConfig struct {
+	// 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 config fields are valid.
+func (c ZkSyncCTFChainProviderConfig) validate() error {
+	if c.Once == nil {
+		return errors.New("sync.Once instance is required")
+	}
+
+	return nil
+}
+
+var _ chain.Provider = (*ZkSyncCTFChainProvider)(nil)
+
+// ZkSyncCTFChainProvider manages an ZkSync EVM chain instance running inside a (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 ZkSyncCTFChainProvider struct {
+	t        *testing.T
+	selector uint64
+	config   ZkSyncCTFChainProviderConfig
+
+	chain *evm.Chain
+}
+
+// NewZkCTFChainProvider creates a new ZkSyncCTFChainProvider with the given selector and
+// configuration.
+func NewZkSyncCTFChainProvider(
+	t *testing.T, selector uint64, config ZkSyncCTFChainProviderConfig,
+) *ZkSyncCTFChainProvider {
+	t.Helper()
+
+	p := &ZkSyncCTFChainProvider{
+		t:        t,
+		selector: selector,
+		config:   config,
+	}
+
+	return p
+}
+
+// Initialize sets up the ZkSync EVM chain instance managed by this provider. It starts a CTF
+// container, initializes the Ethereum client, and sets up the chain instance with the necessary
+// transactors and deployer key gathered from the CTF's default zkSync accounts. The first
+// account is used as the deployer key, and the rest are used as users for the chain.
+func (p *ZkSyncCTFChainProvider) Initialize(ctx context.Context) (chain.BlockChain, error) {
+	if p.chain != nil {
+		return *p.chain, nil // Already initialized
+	}
+
+	err := p.config.validate()
+	require.NoError(p.t, err, "failed to validate provider config")
+
+	// Get the Chain ID
+	chainID, err := chain_selectors.GetChainIDFromSelector(p.selector)
+	require.NoError(p.t, err, "failed to get chain ID from selector")
+
+	// Start the Zksync CTF container
+	httpURL := p.startContainer(chainID)
+
+	// Setup the Ethereum client
+	client, err := ethclient.Dial(httpURL)
+	require.NoError(p.t, err)
+
+	// Fetch the suggested gas price for the chain to set on the transactors.
+	// Anvil zkSync does not support eth_maxPriorityFeePerGas so we set gasPrice to force using
+	// createLegacyTx
+	gasPrice, err := client.SuggestGasPrice(ctx)
+	require.NoError(p.t, err)
+
+	// Build transactors from the default accounts provided by the CTF
+	transactors := p.getTransactors(chainID, gasPrice)
+
+	// Initialize the zksync client and wallet
+	clientZk := clients.NewClient(client.Client())
+	deployerZk, err := accounts.NewWallet(
+		common.Hex2Bytes(blockchain.AnvilZKSyncRichAccountPks[0]), clientZk, nil,
+	)
+	require.NoError(p.t, err, "failed to create deployer wallet for ZkSync")
+
+	// Construct the chain
+	p.chain = &evm.Chain{
+		Selector:    p.selector,
+		Client:      client,
+		DeployerKey: transactors[0],  // The first transactor is the deployer
+		Users:       transactors[1:], // The rest are users
+		Confirm: func(tx *types.Transaction) (uint64, error) {
+			ctxWithTimeout, cancel := context.WithTimeout(ctx, 2*time.Minute)
+			defer cancel()
+
+			receipt, err := bind.WaitMined(ctxWithTimeout, client, tx)
+			if err != nil {
+				return 0, err
+			}
+
+			return receipt.Status, nil
+		},
+		IsZkSyncVM:          true,
+		ClientZkSyncVM:      clientZk,
+		DeployerKeyZkSyncVM: deployerZk,
+	}
+
+	return *p.chain, nil
+}
+
+// Name returns the name of the ZkSyncCTFChainProvider.
+func (*ZkSyncCTFChainProvider) Name() string {
+	return "ZkSync EVM CTF Chain Provider"
+}
+
+// ChainSelector returns the chain selector of the ZkSync EVM chain managed by this provider.
+func (p *ZkSyncCTFChainProvider) ChainSelector() uint64 {
+	return p.selector
+}
+
+// BlockChain returns the ZkSync EVM chain instance managed by this provider. You must call Initialize
+// before using this method to ensure the chain is properly set up.
+func (p *ZkSyncCTFChainProvider) BlockChain() chain.BlockChain {
+	return *p.chain
+}
+
+// startContainer starts a CTF container for the ZkSync EVM returning the HTTP URL of the node.
+func (p *ZkSyncCTFChainProvider) startContainer(
+	chainID string,
+) string {
+	// initialize the docker network used by CTF
+	err := framework.DefaultNetwork(p.config.Once)
+	require.NoError(p.t, err)
+
+	// Initialize a port for the container
+	port := freeport.GetOne(p.t)
+
+	// Create the CTF container for ZkSync
+	output, err := blockchain.NewBlockchainNetwork(&blockchain.Input{
+		Type:    "anvil-zksync",
+		ChainID: chainID,
+		Port:    strconv.Itoa(port),
+	})
+	require.NoError(p.t, err)
+	testcontainers.CleanupContainer(p.t, output.Container)
+
+	return output.Nodes[0].ExternalHTTPUrl
+}
+
+// getTransactors generates transactors from the default list of accounts provided by the CTF.
+func (p *ZkSyncCTFChainProvider) getTransactors(
+	chainID string, gasPrice *big.Int,
+) []*bind.TransactOpts {
+	require.Greater(p.t, len(blockchain.AnvilZKSyncRichAccountPks), 1)
+
+	cid, ok := new(big.Int).SetString(chainID, 10)
+	if !ok {
+		require.FailNowf(p.t, "failed to parse chain ID into big.Int: %s", chainID)
+	}
+
+	transactors := make([]*bind.TransactOpts, 0)
+	for _, pk := range blockchain.AnvilZKSyncRichAccountPks {
+		privateKey, err := crypto.HexToECDSA(pk)
+		require.NoError(p.t, err)
+
+		transactor, err := bind.NewKeyedTransactorWithChainID(privateKey, cid)
+		transactor.GasPrice = gasPrice
+		require.NoError(p.t, err)
+
+		transactors = append(transactors, transactor)
+	}
+
+	return transactors
+}

chain/evm/provider/zksync_ctf_provider_test.go

@@ -0,0 +1,126 @@
+package provider
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	chain_selectors "github.com/smartcontractkit/chain-selectors"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain/evm"
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain/internal/testutils"
+)
+
+func Test_ZkSyncCTFChainProviderConfig_validate(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		config  ZkSyncCTFChainProviderConfig
+		wantErr string
+	}{
+		{
+			name: "valid config",
+			config: ZkSyncCTFChainProviderConfig{
+				Once: testutils.DefaultNetworkOnce,
+			},
+			wantErr: "",
+		},
+		{
+			name: "missing sync.Once instance",
+			config: ZkSyncCTFChainProviderConfig{
+				Once: nil,
+			},
+			wantErr: "sync.Once instance is required",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := tt.config.validate()
+			if tt.wantErr != "" {
+				require.ErrorContains(t, err, tt.wantErr)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}
+
+func Test_CTFChainProvider_Initialize(t *testing.T) {
+	t.Parallel()
+
+	var chainSelector = chain_selectors.TEST_1000.Selector
+
+	tests := []struct {
+		name         string
+		giveSelector uint64
+		giveConfig   ZkSyncCTFChainProviderConfig
+		wantErr      string
+	}{
+		{
+			name:         "valid initialization",
+			giveSelector: chainSelector,
+			giveConfig: ZkSyncCTFChainProviderConfig{
+				Once: testutils.DefaultNetworkOnce,
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			p := NewZkSyncCTFChainProvider(t, tt.giveSelector, tt.giveConfig)
+
+			got, err := p.Initialize(t.Context())
+			if tt.wantErr != "" {
+				require.ErrorContains(t, err, tt.wantErr)
+			} else {
+				require.NoError(t, err)
+				assert.NotNil(t, p.chain)
+
+				// Check that the chain is of type *aptos.Chain and has the expected fields
+				gotChain, ok := got.(evm.Chain)
+				require.True(t, ok, "expected got to be of type aptos.Chain")
+				assert.Equal(t, tt.giveSelector, gotChain.Selector)
+				assert.NotEmpty(t, gotChain.Client)
+				assert.NotEmpty(t, gotChain.DeployerKey)
+				assert.NotEmpty(t, gotChain.Users)
+				assert.NotNil(t, gotChain.Confirm)
+				assert.True(t, gotChain.IsZkSyncVM)
+				assert.NotNil(t, gotChain.ClientZkSyncVM)
+				assert.NotNil(t, gotChain.DeployerKeyZkSyncVM)
+			}
+		})
+	}
+}
+
+func Test_ZkSyncCTFChainProvider_Name(t *testing.T) {
+	t.Parallel()
+
+	p := &ZkSyncCTFChainProvider{}
+	assert.Equal(t, "ZkSync EVM CTF Chain Provider", p.Name())
+}
+
+func Test_ZkSyncCTFChainProvider_ChainSelector(t *testing.T) {
+	t.Parallel()
+
+	p := &ZkSyncCTFChainProvider{selector: chain_selectors.TEST_1000.Selector}
+	assert.Equal(t, chain_selectors.TEST_1000.Selector, p.ChainSelector())
+}
+
+func Test_ZkSyncCTFChainProvider_BlockChain(t *testing.T) {
+	t.Parallel()
+
+	chain := &evm.Chain{}
+
+	p := &ZkSyncCTFChainProvider{
+		chain: chain,
+	}
+
+	assert.Equal(t, *chain, p.BlockChain())
+}

chain/solana/provider/ctf_provider.go

@@ -185,7 +185,7 @@ func (p *CTFChainProvider) ChainSelector() uint64 {
 // BlockChain returns the Solana 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
+	return *p.chain
 }
 
 // startContainer starts a CTF container for the Solana chain.

chain/solana/provider/ctf_provider_test.go

@@ -203,5 +203,5 @@ func Test_CTFChainProvider_BlockChain(t *testing.T) {
 		chain: chain,
 	}
 
-	assert.Equal(t, chain, p.BlockChain())
+	assert.Equal(t, *chain, p.BlockChain())
 }