[TT-2008] allow to pass pre/post contract deployment hooks (#1661)

Author: Tofel

.github/workflows/seth-test.yml

@@ -12,41 +12,61 @@ jobs:
           - regex: TestSmoke
             network-type: Geth
             url: "ws://localhost:8546"
+            extra_flags: "-race"
           - regex: TestSmoke
             network-type: Anvil
             url: "http://localhost:8545"
+            extra_flags: "-race"
           - regex: TestAPI
             network-type: Geth
             url: "ws://localhost:8546"
+            extra_flags: "-race"
           - regex: TestAPI
             network-type: Anvil
             url: "http://localhost:8545"
+            extra_flags: "-race"
           - regex: TestTrace
             network-type: Geth
             url: "ws://localhost:8546"
+            extra_flags: "-race"
           - regex: TestTrace
             network-type: Anvil
             url: "http://localhost:8545"
+            extra_flags: "-race"
           - regex: TestCLI
             network-type: Geth
             url: "ws://localhost:8546"
+            extra_flags: "-race"
           - regex: TestCLI
             network-type: Anvil
             url: "http://localhost:8545"
+            extra_flags: "-race"
             # TODO: wasn't stable before, fix if possible
 #          - regex: TestGasBumping
 #            network-type: Geth
 #            url: "ws://localhost:8546"
 #          - regex: TestGasBumping
 #            network-type: Anvil
 #            url: "http://localhost:8545"
-          - regex: "'TestContractMap|TestGasEstimator|TestRPCHealthCheck|TestUtil|TestContract|TestConfig'"
+            # Some test config tests use Simualted Backend, which is not has data races...
+          - regex: "'TestConfig'"
             network-type: Geth
             url: "ws://localhost:8546"
+            extra_flags: "''"
             # TODO: still expects Geth WS URL for some reason
-#          - regex: "'TestContractMap|TestGasEstimator|TestRPCHealthCheck|TestUtil|TestContract|TestConfig'"
-#            network-type: Anvil
-#            url: "http://localhost:8545"
+          - regex: "'TestConfig'"
+            network-type: Anvil
+            url: "http://localhost:8545"
+            extra_flags: "''"
+          - regex: "'TestContractMap|TestGasEstimator|TestRPCHealthCheck|TestUtil|TestContract'"
+            network-type: Geth
+            url: "ws://localhost:8546"
+            extra_flags: "-race"
+            # TODO: still expects Geth WS URL for some reason
+          - regex: "'TestContractMap|TestGasEstimator|TestRPCHealthCheck|TestUtil|TestContract'"
+            network-type: Anvil
+            url: "http://localhost:8545"
+            extra_flags: "-race"
     defaults:
       run:
         working-directory: seth
@@ -86,4 +106,4 @@ jobs:
           just-version: '1.39.0'
       - name: Run tests
         run: |
-          devbox run -- just seth-test ${{ matrix.test.network-type }} ${{ matrix.test.url }} ${{ matrix.test.regex }}
+          devbox run -- just seth-test ${{ matrix.test.network-type }} ${{ matrix.test.url }} ${{ matrix.test.regex }} ${{ matrix.test.extra_flags}}

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`

framework/clclient/client.go

@@ -1241,6 +1241,8 @@ func (c *ChainlinkClient) GetForwarders() (*Forwarders, *http.Response, error) {
 	return response, resp.RawResponse, err
 }
 
+// NewETHKey generates a new Ethereum key pair and encrypts the private key using the provided password.
+// It returns the encrypted key in JSON format and the corresponding Ethereum address, or an error if the process fails.
 func NewETHKey(password string) ([]byte, common.Address, error) {
 	privateKey, err := ecdsa.GenerateKey(crypto.S256(), rand.Reader)
 	var address common.Address

framework/config.go

@@ -238,6 +238,8 @@ func (d *JSONStrDuration) UnmarshalJSON(b []byte) error {
 	}
 }
 
+// MustParseDuration parses a duration string in Go's format and returns the corresponding time.Duration.
+// It panics if the string cannot be parsed, ensuring that the caller receives a valid duration.
 func MustParseDuration(s string) time.Duration {
 	d, err := time.ParseDuration(s)
 	if err != nil {

havoc/chaos.go

@@ -53,6 +53,9 @@ type ChaosOpts struct {
 	Remove      bool
 }
 
+// NewChaos creates a new Chaos instance based on the provided options.
+// It requires a client, a chaos object, and a logger to function properly.
+// This function is essential for initializing chaos experiments in a Kubernetes environment.
 func NewChaos(opts ChaosOpts) (*Chaos, error) {
 	if opts.Client == nil {
 		return nil, errors.New("client is required")
@@ -161,6 +164,8 @@ func (c *Chaos) Resume(ctx context.Context) error {
 	return nil
 }
 
+// Delete stops the chaos operation, updates its status, and removes the chaos object if specified.
+// It notifies listeners of the operation's completion and handles any errors encountered during the process.
 func (c *Chaos) Delete(ctx context.Context) error {
 	defer func() {
 		// Cancel the monitoring goroutine

havoc/range_grafana_annotator.go

@@ -150,4 +150,6 @@ func (l RangeGrafanaAnnotator) OnChaosEnded(chaos Chaos) {
 	l.chaosMap[chaos.GetChaosName()] = res.ID
 }
 
+// OnChaosStatusUnknown handles the event when the status of a chaos experiment is unknown.
+// It allows listeners to respond appropriately to this specific status change in the chaos lifecycle.
 func (l RangeGrafanaAnnotator) OnChaosStatusUnknown(chaos Chaos) {}

havoc/single_line_grafana_annotator.go

@@ -134,4 +134,6 @@ func (l SingleLineGrafanaAnnotator) OnChaosEnded(chaos Chaos) {
 	l.logger.Debug().Any("GrafanaResponse", resp.String()).Msg("Annotated chaos experiment end")
 }
 
+// OnChaosStatusUnknown handles the event when the status of a chaos experiment is unknown.
+// It allows listeners to respond appropriately to this specific status change in the chaos lifecycle.
 func (l SingleLineGrafanaAnnotator) OnChaosStatusUnknown(chaos Chaos) {}

havoc/template.go

@@ -45,6 +45,9 @@ type PodPartitionCfg struct {
 	ExperimentCreateDelay time.Duration
 }
 
+// RunPodPartition initiates a network partition chaos experiment on specified pods.
+// It configures the experiment based on the provided PodPartitionCfg and executes it.
+// This function is useful for testing the resilience of applications under network partition scenarios.
 func (cr *NamespaceScopedChaosRunner) RunPodPartition(ctx context.Context, cfg PodPartitionCfg) (*Chaos, error) {
 	experiment, err := NewChaos(ChaosOpts{
 		Object: &v1alpha1.NetworkChaos{
@@ -115,6 +118,9 @@ type PodDelayCfg struct {
 	ExperimentCreateDelay time.Duration
 }
 
+// RunPodDelay initiates a network delay chaos experiment on specified pods.
+// It configures the delay parameters and applies them to the targeted namespace.
+// This function is useful for testing the resilience of applications under network latency conditions.
 func (cr *NamespaceScopedChaosRunner) RunPodDelay(ctx context.Context, cfg PodDelayCfg) (*Chaos, error) {
 	experiment, err := NewChaos(ChaosOpts{
 		Object: &v1alpha1.NetworkChaos{
@@ -174,6 +180,9 @@ type PodFailCfg struct {
 	ExperimentCreateDelay time.Duration
 }
 
+// RunPodFail initiates a pod failure experiment based on the provided configuration.
+// It creates a Chaos object that simulates pod failures for a specified duration,
+// allowing users to test the resilience of their applications under failure conditions.
 func (cr *NamespaceScopedChaosRunner) RunPodFail(ctx context.Context, cfg PodFailCfg) (*Chaos, error) {
 	experiment, err := NewChaos(ChaosOpts{
 		Description: cfg.Description,
@@ -233,6 +242,9 @@ type NodeCPUStressConfig struct {
 	ExperimentCreateDelay   time.Duration
 }
 
+// RunPodStressCPU initiates a CPU stress test on specified pods within a namespace.
+// It creates a scheduled chaos experiment that applies CPU load based on the provided configuration.
+// This function is useful for testing the resilience of applications under CPU stress conditions.
 func (cr *NamespaceScopedChaosRunner) RunPodStressCPU(ctx context.Context, cfg NodeCPUStressConfig) (*Chaos, error) {
 	experiment, err := NewChaos(ChaosOpts{
 		Description: cfg.Description,

justfile

@@ -120,9 +120,9 @@ seth-Geth:
     geth --graphql --http --http.api admin,debug,web3,eth,txpool,personal,miner,net --http.corsdomain "*" --ws --ws.api admin,debug,web3,eth,txpool,personal,miner,net --ws.origins "*" --mine --miner.etherbase 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --unlock f39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --allow-insecure-unlock --datadir ./geth_data --password geth_data/password.txt --nodiscover --vmdebug --networkid 1337 > /dev/null 2>&1 &
 
 # Seth: run Seth tests, example: just seth-test Anvil http://localhost:8545 "TestAPI"
-seth-test network url test_regex:
+seth-test network url test_regex extra_flags:
     @just seth-{{network}}
-    cd seth && SETH_URL={{url}} SETH_NETWORK={{network}} SETH_ROOT_PRIVATE_KEY=ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 go test -v -race `go list ./... | grep -v examples` -run "{{test_regex}}" || pkill -f {{network}}
+    cd seth && SETH_URL={{url}} SETH_NETWORK={{network}} SETH_ROOT_PRIVATE_KEY=ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 go test -v "{{extra_flags}}" `go list ./... | grep -v examples` -run "{{test_regex}}" || pkill -f {{network}}
 
 # Run pre-commit hooks, build, lint, tidy, check typos
 pre-commit:

seth/.changeset/v1.51.2.md

@@ -0,0 +1 @@
+- Added optional pre/post contract deployment hooks and pre/post transaction decoding hooks

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)
 	}
@@ -1015,6 +1023,14 @@ func (m *Client) DeployContract(auth *bind.TransactOpts, name string, abi abi.AB
 		}
 	}
 
+	if m.Cfg.Hooks != nil && m.Cfg.Hooks.ContractDeployment.Pre != nil {
+		if err := m.Cfg.Hooks.ContractDeployment.Pre(auth, name, abi, bytecode, params...); err != nil {
+			return DeploymentData{}, errors.Wrap(err, "pre-hook failed")
+		}
+	} else {
+		L.Trace().Msg("No pre-contract deployment hook defined. Skipping")
+	}
+
 	address, tx, contract, err := bind.DeployContract(auth, abi, bytecode, m.Client, params...)
 	if err != nil {
 		return DeploymentData{}, wrapErrInMessageWithASuggestion(err)
@@ -1031,7 +1047,14 @@ func (m *Client) DeployContract(auth *bind.TransactOpts, name string, abi abi.AB
 		m.ContractStore.AddABI(name, abi)
 	}
 
-	// retry is needed both for gas bumping and for waiting for deployment to finish (sometimes there's no code at address the first time we check)
+	if m.Cfg.Hooks != nil && m.Cfg.Hooks.ContractDeployment.Post != nil {
+		if err := m.Cfg.Hooks.ContractDeployment.Post(m, tx); err != nil {
+			return DeploymentData{}, errors.Wrap(err, "post-hook failed")
+		}
+	} else {
+		L.Trace().Msg("No post-contract deployment hook defined. Skipping")
+	}
+
 	if err := retry.Do(
 		func() error {
 			ctx, cancel := context.WithTimeout(context.Background(), m.Cfg.Network.TxnTimeout.Duration())