polish Seth hooks and update docs

Author: Tofel

book/src/libs/seth.md

@@ -65,7 +65,7 @@ Reliable and debug-friendly Ethereum client
 - [x] CLI to manipulate test keys
 - [x] Simple manual gas price estimation
 - [ ] Fail over client logic
-- [ ] Decode collided event hashes
+- [x] Decode collided event hashes
 - [x] Tracing support (4byte)
 - [x] Tracing support (callTracer)
 - [ ] Tracing support (prestate)
@@ -262,7 +262,53 @@ if err != nil {
     log.Fatal(err)
 }
 ```
-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.
+This can be useful if you already have a config, but want to modify it slightly. This approach will only work if you pass it the full config, since it will not apply any defaults. It can also be useful if you read TOML config with multiple `Networks` and you want to specify which one you want to use. Although for that use case it's better to make use of the following approach:
+```go
+// assuming that "readSethNetworks" knows how to read the TOML file and convert it to []*seth.Network
+/* example content of networks.toml:
+[[networks]]
+name = "Anvil"
+dial_timeout = "1m"
+transaction_timeout = "30s"
+urls_secret = ["ws://localhost:8545"]
+transfer_gas_fee = 21_000
+gas_limit = 10_000_000
+# legacy transactions
+gas_price = 1_000_000_000
+# EIP-1559 transactions
+# disabled as it makes some of our tests fail
+# eip_1559_dynamic_fees = true
+gas_fee_cap = 1_000_000_000
+gas_tip_cap = 1_000_000_000
+
+[[networks]]
+name = "Geth"
+dial_timeout = "1m"
+transaction_timeout = "30s"
+urls_secret = ["ws://localhost:8546"]
+transfer_gas_fee = 21_000
+gas_limit = 8_000_000
+# legacy transactions
+gas_price = 1_000_000_000
+# EIP-1559 transactions
+# disabled as it makes some of our tests fail
+# eip_1559_dynamic_fees = true
+gas_fee_cap = 10_000_000_000
+gas_tip_cap = 3_000_000_000
+*/
+networks, err := readSethNetworks("networks.toml")
+if err != nil {
+    log.Fatal(err)
+}
+
+client, err := NewClientBuilderWithConfig(&existingConfig).
+        UseNetworkWithName("Anvil"). // or alternatively use UseNetworkWithChainId (if you defined it for you network)
+	    Build()
+
+if err != nil {
+    log.Fatal(err)
+}
+```
 
 ### Simulated Backend
 
@@ -325,6 +371,37 @@ _ = client
 > 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.
 
+### Hooks
+Seth supports pre/post operation hooks for two functions:
+* `DeployContract()`
+* `Decode` (also `DecodeTx`)
+
+As the name suggest each will be executed before and after mentioned operation. By default, no hooks are set. Adding hooks doesn't influence retry/gas bumping logic.
+
+You can either set hooks directly on the `seth.Config` object (not recommended) or pass them to the `ClientBuilder`:
+```go
+// assuming backend is the simulated backend, to show how we can speed up contract deployments by calling `Commit()` right after deploying the contract
+hooks := seth.Hooks{
+    ContractDeployment: seth.ContractDeploymentHooks{
+        Post: func(client *seth.Client, tx *types.Transaction) error {
+            backend.Commit()
+            return nil
+        },
+    },
+}
+
+client, err := builder.
+    WithNetworkName("simulated").
+    WithHooks(hooks).
+    WithEthClient(backend.Client()).
+    WithPrivateKeys([]string{"ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"}).
+    Build()
+
+if err != nil {
+    log.Fatal(err)
+}
+```
+
 ### Supported env vars
 
 Some crucial data is stored in env vars, create `.envrc` and use `source .envrc`, or use `direnv`

seth/client.go

@@ -39,6 +39,9 @@ const (
 	// unused by Seth, but used by upstream
 	ErrNoKeyLoaded = "failed to load private key"
 
+	ErrSethConfigIsNil         = "seth config is nil"
+	ErrNetworkIsNil            = "no Network is set in the Seth config"
+	ErrNonceManagerConfigIsNil = "nonce manager config is nil"
 	ErrReadOnlyWithPrivateKeys = "read-only mode is enabled, but you tried to load private keys"
 	ErrReadOnlyEphemeralKeys   = "ephemeral mode is not supported in read-only mode"
 	ErrReadOnlyGasBumping      = "gas bumping is not supported in read-only mode"
@@ -86,9 +89,8 @@ func NewClientWithConfig(cfg *Config) (*Client, error) {
 	initDefaultLogging()
 
 	if cfg == nil {
-		return nil, errors.New("seth config cannot be nil")
+		return nil, errors.New(ErrSethConfigIsNil)
 	}
-
 	if cfgErr := cfg.Validate(); cfgErr != nil {
 		return nil, cfgErr
 	}
@@ -179,6 +181,12 @@ func NewClientRaw(
 	pkeys []*ecdsa.PrivateKey,
 	opts ...ClientOpt,
 ) (*Client, error) {
+	if cfg == nil {
+		return nil, errors.New(ErrSethConfigIsNil)
+	}
+	if cfgErr := cfg.Validate(); cfgErr != nil {
+		return nil, cfgErr
+	}
 	if cfg.ReadOnly && (len(addrs) > 0 || len(pkeys) > 0) {
 		return nil, errors.New(ErrReadOnlyWithPrivateKeys)
 	}

seth/client_builder.go

@@ -9,6 +9,7 @@ import (
 )
 
 const (
+	NoNetworkErr              = "you need to set the Network"
 	NoPkForRpcHealthCheckErr  = "you need to provide at least one private key to check the RPC health"
 	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"
@@ -94,14 +95,6 @@ func (c *ClientBuilder) UseNetworkWithName(name string) *ClientBuilder {
 		}
 	}
 
-	// if the network is not found, we will try to use the default network
-	for _, network := range c.config.Networks {
-		if network.Name == DefaultNetworkName {
-			c.config.Network = network
-			return c
-		}
-	}
-
 	c.errors = append(c.errors, fmt.Errorf("network with name '%s' not found", name))
 	return c
 }
@@ -116,14 +109,6 @@ func (c *ClientBuilder) UseNetworkWithChainId(chainId uint64) *ClientBuilder {
 		}
 	}
 
-	// if the network is not found, we will try to use the default network
-	for _, network := range c.config.Networks {
-		if network.Name == DefaultNetworkName {
-			c.config.Network = network
-			return c
-		}
-	}
-
 	c.errors = append(c.errors, fmt.Errorf("network with chainId '%d' not found", chainId))
 	return c
 }
@@ -144,6 +129,14 @@ func (c *ClientBuilder) WithPrivateKeys(pks []string) *ClientBuilder {
 	return c
 }
 
+// WithNetworks sets the networks for the config. At least one is required to build a valid config.
+// It overrides the default network.
+// In order to use one of providers networks, you need to call `UseNetworkWithName(network-name)` or `UseNetworkWithChainId(networks-chain-id)` after calling this method.
+func (c *ClientBuilder) WithNetworks(networks []*Network) *ClientBuilder {
+	c.config.Networks = networks
+	return c
+}
+
 // WithNetworkName sets the network name, useful mostly for debugging and logging.
 // Default value is "default".
 func (c *ClientBuilder) WithNetworkName(name string) *ClientBuilder {
@@ -425,22 +418,25 @@ func (c *ClientBuilder) handleReadOnlyMode() {
 }
 
 func (c *ClientBuilder) validateConfig() {
-	if c.config.Network != nil {
-		if len(c.config.Network.PrivateKeys) == 0 && c.config.CheckRpcHealthOnStart {
-			c.errors = append(c.errors, errors.New(NoPkForRpcHealthCheckErr))
-		}
-		if len(c.config.Network.PrivateKeys) == 0 && c.config.PendingNonceProtectionEnabled {
-			c.errors = append(c.errors, errors.New(NoPkForNonceProtection))
-		}
-		if len(c.config.Network.PrivateKeys) == 0 && c.config.EphemeralAddrs != nil && *c.config.EphemeralAddrs > 0 {
-			c.errors = append(c.errors, errors.New(NoPkForEphemeralKeys))
-		}
-		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))
-		}
+	if c.config.Network == nil {
+		c.errors = append(c.errors, errors.New(NoNetworkErr))
+		return
+	}
+
+	if len(c.config.Network.PrivateKeys) == 0 && c.config.CheckRpcHealthOnStart {
+		c.errors = append(c.errors, errors.New(NoPkForRpcHealthCheckErr))
+	}
+	if len(c.config.Network.PrivateKeys) == 0 && c.config.PendingNonceProtectionEnabled {
+		c.errors = append(c.errors, errors.New(NoPkForNonceProtection))
+	}
+	if len(c.config.Network.PrivateKeys) == 0 && c.config.EphemeralAddrs != nil && *c.config.EphemeralAddrs > 0 {
+		c.errors = append(c.errors, errors.New(NoPkForEphemeralKeys))
+	}
+	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))
 	}
 }