add support for passing custom ethclient to Seth (including Simulated Backend)

Author: Tofel

book/src/libs/seth.md

@@ -22,6 +22,7 @@ Reliable and debug-friendly Ethereum client
 5. [Configuration](#config)
     1. [Simplified configuration](#simplified-configuration)
     2. [ClientBuilder](#clientbuilder)
+        1. [Simulated Backend](#simulated-backend)
     3. [Supported env vars](#supported-env-vars)
     4. [TOML configuration](#toml-configuration)
 6. [Automated gas price estimation](#automatic-gas-estimator)
@@ -263,6 +264,67 @@ if err != nil {
 ```
 This can be useful if you already have a config, but want to modify it slightly. It can also be useful if you read TOML config with multiple `Networks` and you want to specify which one you want to use.
 
+### Simulated Backend
+
+Last, but not least, `ClientBuilder` allows you to pass custom implementation of `simulated.Client` interface, which include Geth's [Simulated Backend](https://github.com/ethereum/go-ethereum/blob/master/ethclient/simulated/backend.go), which might be very useful for rapid testing against
+in-memory environment. When using that option bear in mind that:
+* passing RPC URL is not allowed and will result in error
+* tracing is disabled
+
+> [!NOTE]
+> Simulated Backend doesn't support tracing, because it doesn't expose the JSON-RPC `Call(result interface{}, method string, args ...interface{})` method, which we use to fetch debug information.
+
+So how do you use Seth with simulated backend?
+```go
+var startBackend := func(fundedAddresses []common.Address) (*simulated.Backend, context.CancelFunc) {
+toFund := make(map[common.Address]types.Account)
+	for _, address := range fundedAddresses {
+		toFund[address] = types.Account{
+			Balance: big.NewInt(1000000000000000000), // 1 Ether
+		}
+	}
+	backend := simulated.NewBackend(toFund)
+
+	ctx, cancelFn := context.WithCancel(context.Background())
+
+    // 100ms block time
+	ticker := time.NewTicker(100 * time.Millisecond)
+	go func() {
+		for {
+			select {
+			case <-ticker.C:
+				backend.Commit()
+			case <-ctx.Done():
+				backend.Close()
+				return
+			}
+		}
+	}()
+
+	return backend, cancelFn
+}
+
+// 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266 is the default dev account
+backend, cancelFn := startBackend(
+    []common.Address{common.HexToAddress("0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266")},
+)
+defer func() { cancelFn() }()
+
+client, err := builder.
+    WithNetworkName("simulated").
+    WithEthClient(backend.Client()).
+    WithPrivateKeys([]string{"ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"}).
+    Build()
+
+require.NoError(t, err, "failed to build client")
+_ = client
+```
+
+> [!WARNING]
+> When using `simulated.Backend` do remember that it doesn't automatically mine blocks. You need to call `backend.Commit()` manually
+> to mine a new block and have your transactions processed. The best way to do it is having a goroutine running in the background
+> that either mines at specific intervals or when it receives a message on channel.
+
 ### Supported env vars
 
 Some crucial data is stored in env vars, create `.envrc` and use `source .envrc`, or use `direnv`

seth/client.go

@@ -5,14 +5,17 @@ import (
 	"crypto/ecdsa"
 	"fmt"
 	"math/big"
+	"net/http"
 	"path/filepath"
 	"reflect"
 	"strings"
 	"time"
 
 	"github.com/avast/retry-go"
 	"github.com/ethereum/go-ethereum"
+	"github.com/ethereum/go-ethereum/ethclient"
 	"github.com/ethereum/go-ethereum/ethclient/simulated"
+	"github.com/ethereum/go-ethereum/rpc"
 
 	"github.com/ethereum/go-ethereum/accounts/abi"
 	"github.com/ethereum/go-ethereum/accounts/abi/bind"
@@ -137,23 +140,26 @@ func NewClientWithConfig(cfg *Config) (*Client, error) {
 	}
 
 	abiFinder := NewABIFinder(contractAddressToNameMap, cs)
-	if len(cfg.Network.URLs) == 0 {
-		return nil, fmt.Errorf("at least one url should be present in config in 'secret_urls = []'")
-	}
-	tr, err := NewTracer(cs, &abiFinder, cfg, contractAddressToNameMap, addrs)
-	if err != nil {
-		return nil, errors.Wrap(err, ErrCreateTracer)
+
+	var opts []ClientOpt
+
+	// even if the ethclient that was passed supports tracing, we still need the RPC URL, because we cannot get from
+	// the instance of ethclient, since it doesn't expose any such method
+	if (cfg.ethclient != nil && shouldIntialiseTracer(cfg.ethclient, cfg) && len(cfg.Network.URLs) > 0) || cfg.ethclient == nil {
+		tr, err := NewTracer(cs, &abiFinder, cfg, contractAddressToNameMap, addrs)
+		if err != nil {
+			return nil, errors.Wrap(err, ErrCreateTracer)
+		}
+		opts = append(opts, WithTracer(tr))
 	}
 
+	opts = append(opts, WithContractStore(cs), WithNonceManager(nm), WithContractMap(contractAddressToNameMap), WithABIFinder(&abiFinder))
+
 	return NewClientRaw(
 		cfg,
 		addrs,
 		pkeys,
-		WithContractStore(cs),
-		WithNonceManager(nm),
-		WithTracer(tr),
-		WithContractMap(contractAddressToNameMap),
-		WithABIFinder(&abiFinder),
+		opts...,
 	)
 }
 
@@ -177,39 +183,46 @@ func NewClientRaw(
 		return nil, errors.New(ErrReadOnlyWithPrivateKeys)
 	}
 
-	// TODO we should execute this only if we haven't passed an instance of Client
-	// or... we should externalize client creation to a separate function
-	// and by default create a new instance of Client using the URL from the config
-	// althouth that would change the API a bit
-
-	// if len(cfg.Network.URLs) == 0 {
-	// 	return nil, errors.New("no RPC URL provided")
-	// }
-
-	// if len(cfg.Network.URLs) > 1 {
-	// 	L.Warn().Msg("Multiple RPC URLs provided, only the first one will be used")
-	// }
-
-	// ctx, cancel := context.WithTimeout(context.Background(), cfg.Network.DialTimeout.Duration())
-	// defer cancel()
-	// rpcClient, err := rpc.DialOptions(ctx,
-	// 	cfg.FirstNetworkURL(),
-	// 	rpc.WithHeaders(cfg.RPCHeaders),
-	// 	rpc.WithHTTPClient(&http.Client{
-	// 		Transport: NewLoggingTransport(),
-	// 	}),
-	// )
-	// if err != nil {
-	// 	return nil, fmt.Errorf("failed to connect RPC client to '%s' due to: %w", cfg.FirstNetworkURL(), err)
-	// }
-	// client := ethclient.NewClient(rpcClient)
+	var firstUrl string
+	var client simulated.Client
+	if cfg.ethclient == nil {
+		L.Info().Msg("Creating new ethereum client")
+		if len(cfg.Network.URLs) == 0 {
+			return nil, errors.New("no RPC URL provided")
+		}
+
+		if len(cfg.Network.URLs) > 1 {
+			L.Warn().Msg("Multiple RPC URLs provided, only the first one will be used")
+		}
+
+		ctx, cancel := context.WithTimeout(context.Background(), cfg.Network.DialTimeout.Duration())
+		defer cancel()
+		rpcClient, err := rpc.DialOptions(ctx,
+			cfg.MustFirstNetworkURL(),
+			rpc.WithHeaders(cfg.RPCHeaders),
+			rpc.WithHTTPClient(&http.Client{
+				Transport: NewLoggingTransport(),
+			}),
+		)
+		if err != nil {
+			return nil, fmt.Errorf("failed to connect RPC client to '%s' due to: %w", cfg.MustFirstNetworkURL(), err)
+		}
+		client = ethclient.NewClient(rpcClient)
+		firstUrl = cfg.MustFirstNetworkURL()
+	} else {
+		L.Info().
+			Str("Type", reflect.TypeOf(cfg.ethclient).String()).
+			Msg("Using provided ethereum client")
+		client = cfg.ethclient
+	}
 
 	ctx, cancelFunc := context.WithCancel(context.Background())
 	c := &Client{
+		Client:      client,
 		Cfg:         cfg,
 		Addresses:   addrs,
 		PrivateKeys: pkeys,
-		URL:         cfg.FirstNetworkURL(),
+		URL:         firstUrl,
 		ChainID:     mustSafeInt64(cfg.Network.ChainID),
 		Context:     ctx,
 		CancelFunc:  cancelFunc,
@@ -225,7 +238,7 @@ func NewClientRaw(
 			return nil, errors.Wrap(err, "failed to get chain ID")
 		}
 		cfg.Network.ChainID = chainId.Uint64()
-		c.ChainID = int64(cfg.Network.ChainID)
+		c.ChainID = mustSafeInt64(cfg.Network.ChainID)
 	}
 
 	var err error
@@ -287,7 +300,7 @@ func NewClientRaw(
 	L.Info().
 		Str("NetworkName", cfg.Network.Name).
 		Interface("Addresses", addrs).
-		Str("RPC", cfg.FirstNetworkURL()).
+		Str("RPC", firstUrl).
 		Uint64("ChainID", cfg.Network.ChainID).
 		Int64("Ephemeral keys", *cfg.EphemeralAddrs).
 		Msg("Created new client")
@@ -324,7 +337,9 @@ func NewClientRaw(
 		}
 	}
 
-	if c.Cfg.TracingLevel != TracingLevel_None && c.Tracer == nil {
+	// we cannot use the tracer with simulated backend, because it doesn't expose a method to get rpcClient (even though it has one)
+	// and Tracer needs rpcClient to call debug_traceTransaction
+	if shouldIntialiseTracer(c.Client, cfg) && c.Cfg.TracingLevel != TracingLevel_None && c.Tracer == nil {
 		if c.ContractStore == nil {
 			cs, err := NewContractStore(filepath.Join(cfg.ConfigDir, cfg.ABIDir), filepath.Join(cfg.ConfigDir, cfg.BINDir), cfg.GethWrappersDirs)
 			if err != nil {
@@ -537,12 +552,6 @@ func WithTracer(t *Tracer) ClientOpt {
 	}
 }
 
-func WithEthClient(ethClient simulated.Client) ClientOpt {
-	return func(c *Client) {
-		c.Client = ethClient
-	}
-}
-
 /* CallOpts function options */
 
 // CallOpt is a functional option for bind.CallOpts
@@ -1401,3 +1410,11 @@ func (m *Client) mergeLogMeta(pe *DecodedTransactionLog, l types.Log) {
 	pe.TXIndex = l.TxIndex
 	pe.Removed = l.Removed
 }
+
+func shouldIntialiseTracer(client simulated.Client, cfg *Config) bool {
+	return len(cfg.Network.URLs) > 0 && supportsTracing(client)
+}
+
+func supportsTracing(client simulated.Client) bool {
+	return strings.Contains(reflect.TypeOf(client).String(), "ethclient.Client")
+}

seth/client_builder.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"time"
 
+	"github.com/ethereum/go-ethereum/ethclient/simulated"
 	"github.com/pkg/errors"
 )
 
@@ -12,6 +13,7 @@ const (
 	NoPkForNonceProtection    = "you need to provide at least one private key to enable nonce protection"
 	NoPkForEphemeralKeys      = "you need to provide at least one private key to generate and fund ephemeral addresses"
 	NoPkForGasPriceEstimation = "you need to provide at least one private key to enable gas price estimations"
+	EthClientAndUrlsSet       = "you cannot set both EthClient and RPC URLs"
 )
 
 type ClientBuilder struct {
@@ -363,6 +365,14 @@ func (c *ClientBuilder) WithNonceManager(rateLimitSec int, retries uint, timeout
 	return c
 }
 
+// WithEthClient sets the ethclient to use. It means that the URL you pass will be ignored and the client will use the provided ethclient,
+// but what it allows you is to use Geth's Simulated Backend or similar implementations for testing.
+// Default value is nil.
+func (c *ClientBuilder) WithEthClient(ethclient simulated.Client) *ClientBuilder {
+	c.config.ethclient = ethclient
+	return c
+}
+
 // WithReadOnlyMode sets the client to read-only mode. It removes all private keys from all Networks and disables nonce protection and ephemeral addresses.
 func (c *ClientBuilder) WithReadOnlyMode() *ClientBuilder {
 	c.readonly = true
@@ -423,6 +433,9 @@ func (c *ClientBuilder) validateConfig() {
 		if len(c.config.Network.PrivateKeys) == 0 && c.config.Network.GasPriceEstimationEnabled {
 			c.errors = append(c.errors, errors.New(NoPkForGasPriceEstimation))
 		}
+		if len(c.config.Network.URLs) > 0 && c.config.ethclient != nil {
+			c.errors = append(c.errors, errors.New(EthClientAndUrlsSet))
+		}
 	}
 }