provider

Overview ¶

Package provider contains EVM chain providers for the Chainlink Deployments Framework.

This file implements CTFAnvilChainProvider, which provides Anvil EVM chain instances running inside Chainlink Testing Framework (CTF) Docker containers.

Anvil Integration ¶

Anvil is a local Ethereum node designed for development and testing, part of the Foundry toolkit. It provides fast, deterministic blockchain simulation with pre-funded accounts and configurable mining behavior.

Usage Patterns ¶

Basic usage for simple testing:

func TestBasicContract(t *testing.T) {
	var once sync.Once
	config := CTFAnvilChainProviderConfig{
		Once:           &once,
		ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
		T:              t, // Required when Port is not provided
	}

	provider := NewCTFAnvilChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// Deploy and test contracts...
}

Advanced usage with custom configuration:

func TestAdvancedScenario(t *testing.T) {
	var once sync.Once
	config := CTFAnvilChainProviderConfig{
		Once:                  &once,
		ConfirmFunctor:        ConfirmFuncGeth(30 * time.Second),
		NumAdditionalAccounts: 5, // Limit to 5 additional accounts + deployer
		T:                     t, // Required when Port is not provided
	}

	provider := NewCTFAnvilChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// Run complex multi-account tests...
}

Usage with custom deployer key (using TransactorFromRaw):

func TestWithCustomDeployer(t *testing.T) {
	var once sync.Once
	config := CTFAnvilChainProviderConfig{
		Once:                  &once,
		ConfirmFunctor:        ConfirmFuncGeth(2 * time.Minute),
		DeployerTransactorGen: TransactorFromRaw("your-custom-private-key-here"), // 64 chars hex, no 0x prefix
		T:                     t, // Required when Port is not provided
	}

	provider := NewCTFAnvilChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// The deployer account will use your custom key instead of Anvil's default
	// User accounts will still use Anvil's standard test accounts
}

Usage with KMS deployer key:

func TestWithKMSDeployer(t *testing.T) {
	var once sync.Once
	config := CTFAnvilChainProviderConfig{
		Once:                  &once,
		ConfirmFunctor:        ConfirmFuncGeth(2 * time.Minute),
		DeployerTransactorGen: TransactorFromKMS("your-kms-key-id"),
		T:                     t, // Required when Port is not provided
	}

	provider := NewCTFAnvilChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// The deployer account will use KMS for signing
	// User accounts will still use Anvil's standard test accounts
}

Usage with custom client options:

func TestWithCustomClientOpts(t *testing.T) {
	var once sync.Once
	config := CTFAnvilChainProviderConfig{
		Once:           &once,
		ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
		ClientOpts: []func(client *rpcclient.MultiClient){
			func(client *rpcclient.MultiClient) {
				// Custom client configuration
				client.SetTimeout(30 * time.Second)
			},
		},
		T: t, // Required when Port is not provided
	}

	provider := NewCTFAnvilChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// The MultiClient will use the custom configuration options
}

Usage with custom Docker command parameters:

func TestWithDockerCmdOverrides(t *testing.T) {
	var once sync.Once
	config := CTFAnvilChainProviderConfig{
		Once:           &once,
		ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
		DockerCmdParamsOverrides: []string{
			"--block-time", "2",          // Mine blocks every 2 seconds
			"--gas-limit", "30000000",    // Set gas limit to 30M
			"--gas-price", "1000000000",  // Set gas price to 1 gwei
		},
		T: t, // Required when Port is not provided
	}

	provider := NewCTFAnvilChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// Anvil will run with the custom parameters
}

Usage with custom Port and Image:

func TestWithCustomContainer(t *testing.T) {
	var once sync.Once
	config := CTFAnvilChainProviderConfig{
		Once:           &once,
		ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
		Port:           "8545",                    // Use specific port (T not required when Port is provided)
		Image:          "ghcr.io/foundry-rs/foundry:latest", // Custom Anvil image
	}

	provider := NewCTFAnvilChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// Anvil will run on port 8545, using the specified image
	// Chain ID is automatically derived from the chainSelector
}

Usage in production/non-test contexts with manual cleanup:

func main() {
	var once sync.Once
	config := CTFAnvilChainProviderConfig{
		Once:           &once,
		ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
		Port:           "8545", // T not required when Port is provided
	}

	provider := NewCTFAnvilChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	// Use the blockchain...

	// Important: Clean up the container when done
	defer func() {
		if err := provider.Cleanup(context.Background()); err != nil {
			log.Printf("Failed to cleanup container: %v", err)
		}
	}()
}

Chain Selectors ¶

Common chain selectors for Anvil testing:

• 13264668187771770619: Chain ID 31337 (default Anvil chain ID)

Standard Test Accounts ¶

The provider uses Anvil's standard test accounts:

• Account 0 (Deployer): 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
• Account 1: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8
• Account 2: 0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc
• ... up to 10 total pre-funded accounts

Port Management ¶

The provider supports two modes for port allocation:

• Explicit Port: When Port is specified in the config, that exact port will be used
• Automatic Port: When Port is empty, a free port is automatically allocated using freeport (requires T field to be set in the config for cleanup management)

Requirements ¶

• Docker must be installed and running
• CTF framework must be properly configured
• Sufficient system resources for container execution
• When using automatic port allocation (Port not specified), T field must be set in config

Package provider contains EVM chain providers for the Chainlink Deployments Framework.

This file implements CTFGethChainProvider, which provides Geth EVM chain instances running inside Chainlink Testing Framework (CTF) Docker container.

Geth Integration ¶

Geth is a local Ethereum node.

Usage Patterns ¶

Basic usage for simple testing:

func TestBasicContract(t *testing.T) {
	var once sync.Once
	config := CTFGethChainProviderConfig{
		Once:           &once,
		ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
		T:              t, // Required when Port is not provided
	}

	provider := NewCTFGethChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// Deploy and test contracts...
}

Advanced usage with custom configuration:

	func TestAdvancedScenario(t *testing.T) {
		var once sync.Once
 	config := CTFGethChainProviderConfig{
     Once:               &once,
     ConfirmFunctor:     ConfirmFuncGeth(30 * time.Second),
     AdditionalAccounts: true, // Create & auto-fund all extra users from the built-in pool
     T:                  t,    // Required when Port is not provided
 }

		provider := NewCTFGethChainProvider(chainSelector, config)
		blockchain, err := provider.Initialize(context.Background())
		require.NoError(t, err)

		// Run complex multi-account tests...
	}

Usage with custom deployer key (using TransactorFromRaw):

func TestWithCustomDeployer(t *testing.T) {
	var once sync.Once
	config := CTFGethChainProviderConfig{
		Once:                  &once,
		ConfirmFunctor:        ConfirmFuncGeth(2 * time.Minute),
		DeployerTransactorGen: TransactorFromRaw("your-custom-private-key-here"), // 64 chars hex, no 0x prefix
		T:                     t, // Required when Port is not provided
	}

	provider := NewCTFGethChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// The deployer account will use your custom key instead of Geth's default
	// User accounts will still use Geth's standard test accounts
}

Usage with KMS deployer key:

func TestWithKMSDeployer(t *testing.T) {
	var once sync.Once
	config := CTFGethChainProviderConfig{
		Once:                  &once,
		ConfirmFunctor:        ConfirmFuncGeth(2 * time.Minute),
		DeployerTransactorGen: TransactorFromKMS("your-kms-key-id"),
		T:                     t, // Required when Port is not provided
	}

	provider := NewCTFGethChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// The deployer account will use KMS for signing
	// User accounts will still use Geth's standard test accounts
}

Usage with custom client options:

func TestWithCustomClientOpts(t *testing.T) {
	var once sync.Once
	config := CTFGethChainProviderConfig{
		Once:           &once,
		ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
		ClientOpts: []func(client *rpcclient.MultiClient){
			func(client *rpcclient.MultiClient) {
				// Custom client configuration
				client.SetTimeout(30 * time.Second)
			},
		},
		T: t, // Required when Port is not provided
	}

	provider := NewCTFGethChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// The MultiClient will use the custom configuration options
}

Usage with custom Docker command parameters:

	func TestWithDockerCmdOverrides(t *testing.T) {
		var once sync.Once
		config := CTFGethChainProviderConfig{
			Once:           &once,
			ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
			DockerCmdParamsOverrides: []string{
         "--miner.gasprice", "1000000000",  // Set min gas price to 1 gwei
         "--miner.threads", "1",            // Use 1 mining thread
         "--cache", "1024",                 // Allocate 1GB cache
			},
			T: t, // Required when Port is not provided
		}

		provider := NewCTFGethChainProvider(chainSelector, config)
		blockchain, err := provider.Initialize(context.Background())
		require.NoError(t, err)

		// Geth will run with the custom parameters
	}

Usage with custom Port and Image:

func TestWithCustomContainer(t *testing.T) {
	var once sync.Once
	config := CTFGethChainProviderConfig{
		Once:           &once,
		ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
		Port:           "8546",                    // Use specific port (T not required when Port is provided)
		Image:          "ethereum/client-go:stable", // Custom Geth image/version if desired
	}

	provider := NewCTFGethChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	require.NoError(t, err)

	// Geth will run on port 8546, using the specified image
	// Chain ID is automatically derived from the chainSelector
}

Usage in production/non-test contexts with manual cleanup:

func main() {
	var once sync.Once
	config := CTFGethChainProviderConfig{
		Once:           &once,
		ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
		Port:           "8546", // T not required when Port is provided
	}

	provider := NewCTFGethChainProvider(chainSelector, config)
	blockchain, err := provider.Initialize(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	// Use the blockchain...

	// Important: Clean up the container when done
	defer func() {
		if err := provider.Cleanup(context.Background()); err != nil {
			log.Printf("Failed to cleanup container: %v", err)
		}
	}()
}

Chain Selectors ¶

Common chain selectors for Geth testing:

• 13264668187771770619: Chain ID 31337 (default Geth chain ID)

Standard Test Accounts ¶

This provider ships with a built-in pool of Geth-style test keys:

• Account 0 (Deployer): 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
• Account 1: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8
• Account 2: 0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc
• Account 3: 0x90f79bf6eb2c4f870365e785982e1f101e93b906
• Account 4: 0x15d34aaf54267db7d7c367839aaf71a00a2c6a65

Behavior:

• By default, only the deployer (Account 0) is created.
• If config.AdditionalAccounts == true, *all* extra users (Accounts 1..N) from the pool are created and auto-funded during Initialize().

Port Management ¶

The provider supports two modes for port allocation:

• Explicit Port: When Port is specified in the config, that exact port will be used
• Automatic Port: When Port is empty, a free port is automatically allocated using freeport (requires T field to be set in the config for cleanup management)

Requirements ¶

• Docker must be installed and running
• CTF framework must be properly configured
• Sufficient system resources for container execution
• When using automatic port allocation (Port not specified), T field must be set in config