improve error messages

Author: Tofel

seth/abi_finder.go

@@ -1,6 +1,7 @@
 package seth
 
 import (
+	"fmt"
 	"strings"
 
 	"github.com/ethereum/go-ethereum/accounts/abi"
@@ -127,7 +128,37 @@ func (a *ABIFinder) FindABIByMethod(address string, signature []byte) (ABIFinder
 	}
 
 	if result.Method == nil {
-		return ABIFinderResult{}, errors.New(ErrNoABIMethod)
+		abiCount := len(a.ContractStore.ABIs)
+		abiSample := ""
+		if abiCount > 0 {
+			// Show first few ABIs as examples (max 5)
+			sampleSize := min(abiCount, 5)
+			samples := make([]string, 0, sampleSize)
+			count := 0
+			for abiName := range a.ContractStore.ABIs {
+				if count >= sampleSize {
+					break
+				}
+				samples = append(samples, strings.TrimSuffix(abiName, ".abi"))
+				count++
+			}
+			abiSample = fmt.Sprintf("\nExample ABIs loaded: %s", strings.Join(samples, ", "))
+			if abiCount > sampleSize {
+				abiSample += fmt.Sprintf(" (and %d more)", abiCount-sampleSize)
+			}
+		}
+
+		return ABIFinderResult{}, fmt.Errorf("no ABI found with method signature %s for contract at address %s.\n"+
+			"Checked %d ABIs but none matched.%s\n"+
+			"This usually means:\n"+
+			"  1. The contract ABI wasn't loaded into Seth's contract store\n"+
+			"  2. The method signature doesn't match any known ABI\n"+
+			"  3. You're calling a non-existent contract address\n"+
+			"Solutions:\n"+
+			"  1. Add the contract's ABI to the directory specified by 'abi_dir'\n"+
+			"  2. Use ContractStore.AddABI() to add it programmatically\n"+
+			"  3. Deploy the contract via Seth so it's automatically registered",
+			stringSignature, address, abiCount, abiSample)
 	}
 
 	return result, nil

seth/block_stats.go

@@ -62,7 +62,9 @@ func (cs *BlockStats) Stats(startBlock *big.Int, endBlock *big.Int) error {
 		endBlock = latestBlockNumber
 	}
 	if endBlock != nil && startBlock.Int64() > endBlock.Int64() {
-		return fmt.Errorf("start block is less than the end block")
+		return fmt.Errorf("start block (%d) is greater than end block (%d). "+
+			"Ensure start block comes before end block in the range",
+			startBlock.Int64(), endBlock.Int64())
 	}
 	L.Info().
 		Int64("EndBlock", endBlock.Int64()).
@@ -107,7 +109,7 @@ func (cs *BlockStats) Stats(startBlock *big.Int, endBlock *big.Int) error {
 // CalculateBlockDurations calculates and logs the duration, TPS, gas used, and gas limit between each consecutive block
 func (cs *BlockStats) CalculateBlockDurations(blocks []*types.Block) error {
 	if len(blocks) == 0 {
-		return fmt.Errorf("no blocks no analyze")
+		return fmt.Errorf("no blocks to analyze. Cannot calculate block durations without block data")
 	}
 	var (
 		durations          []time.Duration

seth/client.go

@@ -13,7 +13,6 @@ import (
 	"github.com/ethereum/go-ethereum/crypto"
 	"github.com/ethereum/go-ethereum/ethclient/simulated"
 	"github.com/pelletier/go-toml/v2"
-	"github.com/pkg/errors"
 )
 
 const (
@@ -131,16 +130,30 @@ func DefaultClient(rpcUrl string, privateKeys []string) (*Client, error) {
 func ReadConfig() (*Config, error) {
 	cfgPath := os.Getenv(CONFIG_FILE_ENV_VAR)
 	if cfgPath == "" {
-		return nil, errors.New(ErrEmptyConfigPath)
+		return nil, fmt.Errorf("SETH_CONFIG_PATH environment variable is not set. "+
+			"Set it to the absolute path of your seth.toml configuration file.\n"+
+			"Example: export SETH_CONFIG_PATH=/path/to/your/seth.toml")
 	}
 	var cfg *Config
 	d, err := os.ReadFile(cfgPath)
 	if err != nil {
-		return nil, errors.Wrap(err, ErrReadSethConfig)
+		return nil, fmt.Errorf("failed to read Seth config file at '%s': %w\n"+
+			"Ensure:\n"+
+			"  1. The file exists at the specified path\n"+
+			"  2. You have read permissions for the file\n"+
+			"  3. The path is correct (set via SETH_CONFIG_PATH or parameter)",
+			cfgPath, err)
 	}
 	err = toml.Unmarshal(d, &cfg)
 	if err != nil {
-		return nil, errors.Wrap(err, ErrUnmarshalSethConfig)
+		return nil, fmt.Errorf("failed to parse Seth TOML config from '%s': %w\n"+
+			"Ensure the file contains valid TOML syntax. "+
+			"Common issues:\n"+
+			"  1. Missing quotes around string values\n"+
+			"  2. Invalid array or table syntax\n"+
+			"  3. Duplicate keys\n"+
+			"See example config: https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/seth/seth.toml",
+			cfgPath, err)
 	}
 	absPath, err := filepath.Abs(cfgPath)
 	if err != nil {
@@ -162,7 +175,15 @@ func ReadConfig() (*Config, error) {
 		url := os.Getenv(URL_ENV_VAR)
 
 		if url == "" {
-			return nil, fmt.Errorf("network not selected, set %s=... or %s=..., check TOML config for available networks", NETWORK_ENV_VAR, URL_ENV_VAR)
+			availableNetworks := make([]string, 0, len(cfg.Networks))
+			for _, n := range cfg.Networks {
+				availableNetworks = append(availableNetworks, n.Name)
+			}
+			return nil, fmt.Errorf("network not selected. Set either:\n"+
+				"  - SETH_NETWORK to one of: %s\n"+
+				"  - SETH_URL to a custom RPC endpoint\n"+
+				"Check your TOML config at %s for network details",
+				strings.Join(availableNetworks, ", "), cfgPath)
 		}
 
 		//look for default network
@@ -182,13 +203,21 @@ func ReadConfig() (*Config, error) {
 		}
 
 		if cfg.Network == nil {
-			return nil, fmt.Errorf("default network not defined in the TOML file")
+			return nil, fmt.Errorf("default network not defined in the TOML file at %s. "+
+				"Add a network with name='%s' or specify a network using SETH_NETWORK environment variable",
+				cfgPath, DefaultNetworkName)
 		}
 	}
 
 	rootPrivateKey := os.Getenv(ROOT_PRIVATE_KEY_ENV_VAR)
 	if rootPrivateKey == "" {
-		return nil, errors.Errorf(ErrEmptyRootPrivateKey, ROOT_PRIVATE_KEY_ENV_VAR)
+		return nil, fmt.Errorf("no root private key was set. "+
+			"You can provide the root private key via:\n"+
+			"  1. %s environment variable (without 0x prefix)\n"+
+			"  2. 'root_private_key' field in seth.toml\n"+
+			"  3. WithPrivateKeys() when using ClientBuilder\n"+
+			"WARNING: Never commit private keys to source control. Use environment variables or secure secret management",
+			ROOT_PRIVATE_KEY_ENV_VAR)
 	}
 	cfg.Network.PrivateKeys = append(cfg.Network.PrivateKeys, rootPrivateKey)
 	if cfg.Network.DialTimeout == nil {
@@ -205,7 +234,13 @@ func ReadConfig() (*Config, error) {
 // If any configuration is invalid, it returns an error.
 func (c *Config) Validate() error {
 	if c.Network == nil {
-		return errors.New(ErrNetworkIsNil)
+		return fmt.Errorf("network configuration is nil. "+
+			"This usually means the network wasn't selected or configured properly.\n"+
+			"Solutions:\n"+
+			"  1. Set SETH_NETWORK environment variable to match a network name in seth.toml (e.g., SETH_NETWORK=sepolia)\n"+
+			"  2. Ensure your seth.toml has a [[networks]] section with 'name' field matching SETH_NETWORK\n"+
+			"  3. Use ClientBuilder with WithNetwork() to configure the network programmatically\n"+
+			"See documentation for configuration examples")
 	}
 
 	if c.Network.GasPriceEstimationEnabled {
@@ -225,12 +260,20 @@ func (c *Config) Validate() error {
 		case Priority_Slow:
 		case Priority_Auto:
 		default:
-			return errors.New("when automating gas estimation is enabled priority must be auto, fast, standard or slow. fix it or disable gas estimation")
+			return fmt.Errorf("invalid gas estimation priority '%s'. "+
+				"Must be one of: 'auto', 'fast', 'standard' or 'slow'. "+
+				"Set 'gas_price_estimation_tx_priority' in your seth.toml config. "+
+				"To disable gas estimation, set 'gas_price_estimation_enabled = false'",
+				c.Network.GasPriceEstimationTxPriority)
 		}
 
 		if c.GasBump != nil && c.GasBump.Retries > 0 &&
 			c.Network.GasPriceEstimationTxPriority == Priority_Auto {
-			return errors.New("gas bumping is not compatible with auto priority gas estimation")
+			return fmt.Errorf("configuration conflict: gas bumping (retries=%d) is not compatible with auto priority gas estimation. "+
+				"Either:\n"+
+				"  1. Set gas_price_estimation_tx_priority to 'fast', 'standard', or 'slow'\n"+
+				"  2. Set gas_bump.retries = 0 to disable gas bumping",
+				c.GasBump.Retries)
 		}
 	}
 
@@ -254,7 +297,10 @@ func (c *Config) Validate() error {
 	case TracingLevel_Reverted:
 	case TracingLevel_All:
 	default:
-		return errors.New("tracing level must be one of: NONE, REVERTED, ALL")
+		return fmt.Errorf("invalid tracing level '%s'. Must be one of: 'NONE', 'REVERTED', 'ALL'. "+
+			"Set 'tracing_level' in your seth.toml config.\n"+
+			"Recommended: 'REVERTED' for debugging failed transactions, 'NONE' to disable tracing completely",
+			c.TracingLevel)
 	}
 
 	for _, output := range c.TraceOutputs {
@@ -263,7 +309,10 @@ func (c *Config) Validate() error {
 		case TraceOutput_JSON:
 		case TraceOutput_DOT:
 		default:
-			return errors.New("trace output must be one of: console, json, dot")
+			return fmt.Errorf("invalid trace output '%s'. Must be one of: 'console', 'json', 'dot'. "+
+				"Set 'trace_outputs' in your seth.toml config. "+
+				"You can specify multiple outputs as an array",
+				output)
 		}
 	}
 
@@ -276,11 +325,18 @@ func (c *Config) Validate() error {
 	}
 
 	if c.ethclient == nil && len(c.Network.URLs) == 0 {
-		return errors.New("at least one url should be present in config in 'secret_urls = []'")
+		return fmt.Errorf("no RPC URLs configured. "+
+			"You can provide RPC URLs via:\n"+
+			"  1. 'urls_secret' field in seth.toml: urls_secret = [\"http://your-rpc-url\"]\n"+
+			"  2. WithRPCURLs() when using ClientBuilder\n"+
+			"  3. WithEthClient() to provide a pre-configured ethclient instance")
 	}
 
 	if c.ethclient != nil && len(c.Network.URLs) > 0 {
-		return errors.New(EthClientAndUrlsSet)
+		return fmt.Errorf("configuration conflict: both ethclient instance and RPC URLs are set. "+
+			"You cannot set both. Either:\n"+
+			"  1. Use the provided ethclient (remove 'urls_secret' from config)\n"+
+			"  2. Use RPC URLs from config (don't provide ethclient)")
 	}
 
 	return nil

seth/config.go

@@ -13,7 +13,6 @@ import (
 
 	"github.com/ethereum/go-ethereum/accounts/abi"
 	"github.com/ethereum/go-ethereum/common"
-	"github.com/pkg/errors"
 )
 
 const (
@@ -111,7 +110,12 @@ func NewContractStore(abiPath, binPath string, gethWrappersPaths []string) (*Con
 
 	err = cs.loadGethWrappers(gethWrappersPaths)
 	if err != nil {
-		return nil, errors.Wrapf(err, "failed to load geth wrappers from %v", gethWrappersPaths)
+		return nil, fmt.Errorf("failed to load geth wrappers from %v: %w\n"+
+			"Ensure:\n"+
+			"  1. The paths point to valid Go files with geth-generated contract wrappers\n"+
+			"  2. Files contain properly formatted ABI JSON in comments\n"+
+			"  3. The wrapper files were generated with abigen tool",
+			gethWrappersPaths, err)
 	}
 
 	return cs, nil
@@ -129,18 +133,29 @@ func (c *ContractStore) loadABIs(abiPath string) error {
 				L.Debug().Str("File", f.Name()).Msg("ABI file loaded")
 				ff, err := os.Open(filepath.Join(abiPath, f.Name()))
 				if err != nil {
-					return errors.Wrap(err, ErrOpenABIFile)
+					return fmt.Errorf("failed to open ABI file '%s': %w\n"+
+						"Ensure the file exists and has proper read permissions",
+						filepath.Join(abiPath, f.Name()), err)
 				}
 				a, err := abi.JSON(ff)
 				if err != nil {
-					return errors.Wrap(err, ErrParseABI)
+					return fmt.Errorf("failed to parse ABI file '%s': %w\n"+
+						"Ensure the file contains valid JSON ABI format. "+
+						"ABI files should be generated from contract compilation (e.g., solc, hardhat, foundry)",
+						f.Name(), err)
 				}
 				c.ABIs[f.Name()] = a
 				foundABI = true
 			}
 		}
 		if !foundABI {
-			return fmt.Errorf("no ABI files found in '%s'. Fix the path or comment out 'abi_dir' setting", abiPath)
+			return fmt.Errorf("no ABI files found in '%s'. "+
+				"Ensure:\n"+
+				"  1. The directory exists and is readable\n"+
+				"  2. Files have .abi extension\n"+
+				"  3. Path is correct (should be relative to config file or absolute)\n"+
+				"Or comment out 'abi_dir' in config if not using ABI files",
+				abiPath)
 		}
 	}
 
@@ -159,14 +174,23 @@ func (c *ContractStore) loadBINs(binPath string) error {
 				L.Debug().Str("File", f.Name()).Msg("BIN file loaded")
 				bin, err := os.ReadFile(filepath.Join(binPath, f.Name()))
 				if err != nil {
-					return errors.Wrap(err, ErrOpenBINFile)
+					return fmt.Errorf("failed to open BIN file '%s': %w\n"+
+						"Ensure the file exists and has proper read permissions",
+						filepath.Join(binPath, f.Name()), err)
 				}
 				c.BINs[f.Name()] = common.FromHex(string(bin))
 				foundBIN = true
 			}
 		}
 		if !foundBIN {
-			return fmt.Errorf("no BIN files found in '%s'. Fix the path or comment out 'bin_dir' setting", binPath)
+			return fmt.Errorf("no BIN files (bytecode) found in '%s'. "+
+				"BIN files are needed for contract deployment. "+
+				"Ensure:\n"+
+				"  1. Files have .bin extension\n"+
+				"  2. They contain compiled contract bytecode (hex-encoded)\n"+
+				"  3. Path is correct (should be relative to config file or absolute)\n"+
+				"Or comment out 'bin_dir' in config if deploying contracts via other means",
+				binPath)
 		}
 	}
 
@@ -253,12 +277,18 @@ TOP_LOOP:
 	// this cleans up all escape and similar characters that might interfere with the JSON unmarshalling
 	var rawAbi interface{}
 	if err := json.Unmarshal([]byte(abiContent), &rawAbi); err != nil {
-		return "", nil, errors.Wrap(err, "failed to unmarshal ABI content")
+		return "", nil, fmt.Errorf("failed to unmarshal ABI content from '%s': %w\n"+
+			"The ABI JSON in the wrapper file is malformed. "+
+			"Ensure the file was generated correctly with abigen",
+			filePath, err)
 	}
 
 	parsedAbi, err := abi.JSON(strings.NewReader(fmt.Sprint(rawAbi)))
 	if err != nil {
-		return "", nil, errors.Wrap(err, "failed to parse ABI content")
+		return "", nil, fmt.Errorf("failed to parse ABI content from '%s': %w\n"+
+			"The ABI structure is invalid. "+
+			"Regenerate the wrapper file with abigen",
+			filePath, err)
 	}
 
 	return contractName, &parsedAbi, nil