feat: add a simulated chain provider for EVM testing (#184)

This adds a geth backed simulated chain provider for testing purposes.
It provides an option to allow for the automated mining of blocks, which
is useful for testing scenarios that require block confirmations.

Author: jkongie

.changeset/full-pans-go.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+Adds a Simulated EVM Chain Provider using the go-ethereum `simulated` package as the backend.

.mockery.yml

@@ -11,4 +11,9 @@ require-template-schema-exists: true
 template: testify
 template-schema: '{{.Template}}.schema.json'
 packages:
-  #github.com/smartcontractkit/chainlink-deployments-framework/...
+  github.com/smartcontractkit/chainlink-deployments-framework/chain/evm/provider:
+    config:
+      all: false
+    interfaces:
+      ContractCaller:
+

chain/evm/provider/helpers.go

@@ -0,0 +1,86 @@
+package provider
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"math/big"
+	"strings"
+
+	"github.com/ethereum/go-ethereum"
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+)
+
+// ContractCaller is an interface that defines the CallContract method. This is copied from the
+// go-ethereum package method to limit the scope of dependencies provided to the functions.
+type ContractCaller interface {
+	CallContract(ctx context.Context, call ethereum.CallMsg, blockNumber *big.Int) ([]byte, error)
+}
+
+// getErrorReasonFromTx retrieves the error reason from a transaction by simulating the call
+// using the CallContract method. If the transaction reverts, it attempts to extract the
+// error reason from the returned error.
+func getErrorReasonFromTx(
+	ctx context.Context,
+	caller ContractCaller,
+	from common.Address,
+	tx *types.Transaction,
+	receipt *types.Receipt,
+) (string, error) {
+	call := ethereum.CallMsg{
+		From:     from,
+		To:       tx.To(),
+		Data:     tx.Data(),
+		Value:    tx.Value(),
+		Gas:      tx.Gas(),
+		GasPrice: tx.GasPrice(),
+	}
+
+	if _, err := caller.CallContract(ctx, call, receipt.BlockNumber); err != nil {
+		reason, perr := getJSONErrorData(err)
+
+		// If the reason exists and we had no issues parsing it, we return it
+		if perr == nil {
+			return reason, nil
+		}
+
+		// If we get no information from parsing the error, we return the original error from
+		// CallContract
+		if reason == "" {
+			return err.Error(), nil
+		}
+	}
+
+	return "", fmt.Errorf("tx %s reverted with no reason", tx.Hash().Hex())
+}
+
+// getJSONErrorData extracts the error data from a JSON Error.
+func getJSONErrorData(err error) (string, error) {
+	if err == nil {
+		return "", errors.New("cannot parse nil error")
+	}
+
+	// Define a custom interface that matches the structure of the JSON error because it is a
+	// private type in go-ethereum.
+	//
+	// https://github.com/ethereum/go-ethereum/blob/0983cd789ee1905aedaed96f72793e5af8466f34/rpc/json.go#L140
+	type jsonError interface {
+		Error() string
+		ErrorCode() int
+		ErrorData() any
+	}
+
+	var jerr jsonError
+	ok := errors.As(err, &jerr)
+	if !ok {
+		return "", fmt.Errorf("error must be of type jsonError: %w", err)
+	}
+
+	data := fmt.Sprintf("%s", jerr.ErrorData())
+	if data == "" && strings.Contains(jerr.Error(), "missing trie node") {
+		return "", errors.New("missing trie node, likely due to not using an archive node")
+	}
+
+	return data, nil
+}

chain/evm/provider/helpers_test.go

@@ -0,0 +1,182 @@
+package provider
+
+import (
+	"errors"
+	"fmt"
+	"math/big"
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+)
+
+func Test_getErrorReasonFromTx(t *testing.T) {
+	t.Parallel()
+
+	var (
+		tx = types.NewTransaction(
+			1,                               // nonce
+			common.HexToAddress("0xabc123"), // to address
+			big.NewInt(1000000000000000000), // value: 1 ETH
+			21000,                           // gas limit
+			big.NewInt(20000000000),         // gas price: 20 Gwei
+			[]byte{0xde, 0xad, 0xbe, 0xef},  // data
+		)
+	)
+
+	tests := []struct {
+		name        string
+		beforeFunc  func(caller *MockContractCaller)
+		giveTx      *types.Transaction
+		giveReceipt *types.Receipt
+		wantReason  string
+		wantErr     string
+	}{
+		{
+			name: "no transaction error",
+			beforeFunc: func(caller *MockContractCaller) {
+				caller.EXPECT().CallContract(
+					mock.Anything,
+					mock.AnythingOfType("ethereum.CallMsg"),
+					mock.AnythingOfType("*big.Int"),
+				).Return([]byte{}, nil)
+			},
+			giveTx:      tx,
+			giveReceipt: &types.Receipt{},
+			wantErr:     "reverted with no reason",
+		},
+		{
+			name: "transaction error with reason",
+			beforeFunc: func(caller *MockContractCaller) {
+				caller.EXPECT().CallContract(
+					mock.Anything,
+					mock.AnythingOfType("ethereum.CallMsg"),
+					mock.AnythingOfType("*big.Int"),
+				).Return(nil, &jsonError{
+					Code:    100,
+					Message: "test error message",
+					Data:    []byte("test error data"),
+				})
+			},
+			giveTx:      tx,
+			giveReceipt: &types.Receipt{},
+			wantReason:  "test error data",
+		},
+		{
+			name: "transaction error with no reason (non json error)",
+			beforeFunc: func(caller *MockContractCaller) {
+				caller.EXPECT().CallContract(
+					mock.Anything,
+					mock.AnythingOfType("ethereum.CallMsg"),
+					mock.AnythingOfType("*big.Int"),
+				).Return(nil, errors.New("error message"))
+			},
+			giveTx:      tx,
+			giveReceipt: &types.Receipt{},
+			wantReason:  "error message",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			caller := NewMockContractCaller(t)
+			if tt.beforeFunc != nil {
+				tt.beforeFunc(caller)
+			}
+
+			got, err := getErrorReasonFromTx(
+				t.Context(), caller, common.HexToAddress("0x123"), tt.giveTx, tt.giveReceipt,
+			)
+
+			if tt.wantErr != "" {
+				require.ErrorContains(t, err, tt.wantErr)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tt.wantReason, got)
+			}
+		})
+	}
+}
+
+func Test_parseError(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		give    error
+		want    string
+		wantErr string
+	}{
+		{
+			name: "valid error",
+			give: &jsonError{
+				Code:    100,
+				Message: "execution reverted",
+				Data:    "0x12345678",
+			},
+			want: "0x12345678",
+		},
+		{
+			name:    "nil error",
+			give:    nil,
+			wantErr: "cannot parse nil error",
+		},
+		{
+			name:    "invalid error type",
+			give:    errors.New("invalid"),
+			wantErr: "error must be of type jsonError",
+		},
+		{
+			name: "trie error",
+			give: &jsonError{
+				Code:    -32000,
+				Message: "missing trie node",
+				Data:    []byte{},
+			},
+			wantErr: "missing trie node",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := getJSONErrorData(tt.give)
+
+			if tt.wantErr != "" {
+				require.ErrorContains(t, err, tt.wantErr)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tt.want, got)
+			}
+		})
+	}
+}
+
+// Dummy implementation of jsonError to satisfy the interface
+type jsonError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Data    any    `json:"data,omitempty"`
+}
+
+func (err *jsonError) Error() string {
+	if err.Message == "" {
+		return fmt.Sprintf("json-rpc error %d", err.Code)
+	}
+
+	return err.Message
+}
+
+func (err *jsonError) ErrorCode() int {
+	return err.Code
+}
+
+func (err *jsonError) ErrorData() interface{} {
+	return err.Data
+}