more error message fixes

Author: Tofel

seth/abi_finder.go

@@ -1,7 +1,6 @@
 package seth
 
 import (
-	"errors"
 	"fmt"
 	"strings"
 
@@ -47,11 +46,21 @@ func (a *ABIFinder) FindABIByMethod(address string, signature []byte) (ABIFinder
 		contractName := a.ContractMap.GetContractName(address)
 		abiInstanceCandidate, ok := a.ContractStore.ABIs[contractName+".abi"]
 		if !ok {
-			err := errors.New(ErrNoAbiFound)
+			err := fmt.Errorf("no ABI found for contract '%s' at address %s, even though it's registered in the contract map. "+
+				"This happens when:\n"+
+				"  1. Contract address is in the contract map but ABI file is missing from abi_dir\n"+
+				"  2. ABI files were moved or deleted after contract deployment\n"+
+				"  3. Contract map is corrupted or out of sync\n"+
+				"Troubleshooting:\n"+
+				"  1. Verify ABI file '%s.abi' exists in the configured abi_dir\n"+
+				"  2. Check if save_deployed_contracts_map = true in config\n"+
+				"  3. Re-deploy the contract or manually add ABI with ContractStore.AddABI()\n"+
+				"  4. For external contracts, obtain and add the ABI manually",
+				contractName, address, contractName)
 			L.Err(err).
 				Str("Contract", contractName).
 				Str("Address", address).
-				Msg("ABI not found, even though contract is known. This should not happen. Contract map might be corrupted")
+				Msg("ABI not found for known contract")
 			return ABIFinderResult{}, err
 		}
 
@@ -150,14 +159,17 @@ func (a *ABIFinder) FindABIByMethod(address string, signature []byte) (ABIFinder
 
 		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",
+			"Possible causes:\n"+
+			"  1. Contract ABI not loaded (check abi_dir and contract_map_file)\n"+
+			"  2. Method signature doesn't match any function in loaded ABIs\n"+
+			"  3. Contract address not registered in contract map\n"+
+			"  4. Wrong contract address (check deployment logs)\n"+
+			"Troubleshooting:\n"+
+			"  1. Verify contract was deployed with DeployContract() or loaded with LoadContract()\n"+
+			"  2. Check the method signature is correct (case-sensitive, including parameter types)\n"+
+			"  3. Ensure ABI file exists in the directory specified by 'abi_dir'\n"+
+			"  4. Review contract_map_file for address-to-name mappings\n"+
+			"  5. Use ContractStore.AddABI() to manually add the ABI",
 			stringSignature, address, abiCount, abiSample)
 	}
 

seth/block_stats.go

@@ -48,7 +48,14 @@ func (cs *BlockStats) Stats(startBlock *big.Int, endBlock *big.Int) error {
 	if endBlock == nil || startBlock.Sign() < 0 {
 		header, err := cs.Client.Client.HeaderByNumber(context.Background(), nil)
 		if err != nil {
-			return fmt.Errorf("failed to get the latest block header: %v", err)
+			return fmt.Errorf("failed to get the latest block header for block stats: %w\n"+
+				"This indicates RPC connectivity issues.\n"+
+				"Troubleshooting:\n"+
+				"  1. Verify RPC endpoint is accessible\n"+
+				"  2. Check network connectivity\n"+
+				"  3. Ensure the node is synced\n"+
+				"  4. Try increasing dial_timeout in config",
+				err)
 		}
 		latestBlockNumber = header.Number
 	}
@@ -62,8 +69,12 @@ 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 (%d) is greater than end block (%d). "+
-			"Ensure start block comes before end block in the range",
+		return fmt.Errorf("invalid block range for statistics: start block %d > end block %d.\n"+
+			"This is a bug in Seth's block stats calculation logic.\n"+
+			"Please open a GitHub issue at https://github.com/smartcontractkit/chainlink-testing-framework/issues with:\n"+
+			"  1. Your configuration file\n"+
+			"  2. The operation you were performing\n"+
+			"  3. Network name and chain ID",
 			startBlock.Int64(), endBlock.Int64())
 	}
 	L.Info().
@@ -109,7 +120,12 @@ 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 to analyze. Cannot calculate block durations without block data")
+		return fmt.Errorf("no block data available for duration analysis. " +
+			"This happens when:\n" +
+			"  1. No blocks were provided for analysis\n" +
+			"  2. All block fetch attempts failed\n" +
+			"  3. Block range is invalid\n" +
+			"Check RPC connectivity and ensure blocks exist in the specified range")
 	}
 	var (
 		durations          []time.Duration

seth/contract_store.go

@@ -149,13 +149,16 @@ func (c *ContractStore) loadABIs(abiPath string) error {
 			}
 		}
 		if !foundABI {
-			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)
+			absPath, _ := filepath.Abs(abiPath)
+			return fmt.Errorf("no ABI files (*.abi) found in directory '%s'.\n"+
+				"ABI files are JSON files describing contract interfaces.\n"+
+				"Solutions:\n"+
+				"  1. Verify the path is correct: %s\n"+
+				"  2. Ensure .abi files exist in this directory\n"+
+				"  3. Check directory permissions (must be readable)\n"+
+				"  4. If deploying contracts without ABIs, remove 'abi_dir' from config\n"+
+				"  5. Generate ABIs from Solidity: solc --abi YourContract.sol -o abi_dir/",
+				abiPath, absPath)
 		}
 	}
 
@@ -183,14 +186,16 @@ func (c *ContractStore) loadBINs(binPath string) error {
 			}
 		}
 		if !foundBIN {
-			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)
+			absPath, _ := filepath.Abs(binPath)
+			return fmt.Errorf("no BIN files (*.bin) found in directory '%s'.\n"+
+				"BIN files contain compiled contract bytecode needed for deployment.\n"+
+				"Solutions:\n"+
+				"  1. Verify the path is correct: %s\n"+
+				"  2. Ensure .bin files exist (should contain hex-encoded bytecode)\n"+
+				"  3. Check directory permissions (must be readable)\n"+
+				"  4. If deploying contracts without BIN files, remove 'bin_dir' from config\n"+
+				"  5. Generate BINs from Solidity: solc --bin YourContract.sol -o bin_dir/",
+				binPath, absPath)
 		}
 	}
 
@@ -231,7 +236,15 @@ func (c *ContractStore) loadGethWrappers(gethWrappersPaths []string) error {
 	}
 
 	if len(gethWrappersPaths) > 0 && !foundWrappers {
-		return fmt.Errorf("no geth wrappers found in '%v'. Fix the path or comment out 'geth_wrappers_dirs' setting", gethWrappersPaths)
+		return fmt.Errorf("no geth wrapper files found in directories: %v\n"+
+			"Geth wrappers are Go files generated by abigen containing contract ABIs.\n"+
+			"Solutions:\n"+
+			"  1. Verify all paths exist and are readable\n"+
+			"  2. Generate wrappers using abigen:\n"+
+			"     abigen --abi contract.abi --bin contract.bin --pkg wrappers --out contract_wrapper.go\n"+
+			"  3. Ensure wrapper files contain ABI metadata (check for 'ABI' variable)\n"+
+			"  4. If not using geth wrappers, remove 'geth_wrappers_dirs' from config",
+			gethWrappersPaths)
 	}
 
 	return nil

seth/decode.go

@@ -415,7 +415,13 @@ func (m *Client) decodeTransaction(l zerolog.Logger, tx *types.Transaction, rece
 
 	sig := txData[:4]
 	if m.ABIFinder == nil {
-		l.Err(errors.New("ABIFInder is nil")).Msg("ABIFinder is required for transaction decoding")
+		err := fmt.Errorf("ABIFinder is not initialized, cannot decode transaction. " +
+			"This is an internal error - ABIFinder should be set during client initialization.\n" +
+			"If you see this error:\n" +
+			"  1. Ensure you're using NewClient() or NewClientWithConfig() to create the client\n" +
+			"  2. Don't manually modify client.ABIFinder\n" +
+			"  3. If the issue persists, please open a GitHub issue at https://github.com/smartcontractkit/chainlink-testing-framework/issues")
+		l.Err(err).Msg("ABIFinder is required for transaction decoding")
 		return defaultTxn, nil
 	}
 
@@ -499,7 +505,13 @@ func (m *Client) DecodeCustomABIErr(txErr error) (string, error) {
 	//nolint
 	cerr, ok := txErr.(rpc.DataError)
 	if !ok {
-		return "", errors.New(ErrRPCJSONCastError)
+		return "", fmt.Errorf("failed to extract revert reason from RPC error response. " +
+			"The RPC response format is not recognized.\n" +
+			"This could mean:\n" +
+			"  1. Your RPC node uses a non-standard error format\n" +
+			"  2. The transaction didn't revert (unexpected state)\n" +
+			"  3. RPC node is experiencing issues\n" +
+			"The transaction trace may still contain useful information")
 	}
 	if m.ContractStore == nil {
 		L.Warn().Msg(WarnNoContractStore)
@@ -605,7 +617,13 @@ func (m *Client) callAndGetRevertReason(tx *types.Transaction, rc *types.Receipt
 		return err
 	}
 	if decodedABIErrString != "" {
-		return errors.New(decodedABIErrString)
+		return fmt.Errorf("failed to decode ABI from contract code: %s\n"+
+			"This happens when:\n"+
+			"  1. Contract bytecode doesn't contain valid ABI metadata\n"+
+			"  2. Contract wasn't compiled with metadata (--metadata-hash none)\n"+
+			"  3. Contract code at the address is not a valid contract\n"+
+			"For third-party contracts, manually load the ABI instead of relying on auto-detection",
+			decodedABIErrString)
 	}
 
 	if plainStringErr != nil {
@@ -637,7 +655,13 @@ func (m *Client) callAndGetRevertReason(tx *types.Transaction, rc *types.Receipt
 func decodeTxInputs(l zerolog.Logger, txData []byte, method *abi.Method) (map[string]interface{}, error) {
 	l.Trace().Msg("Parsing tx inputs")
 	if (len(txData)) < 4 {
-		return nil, errors.New(ErrTooShortTxData)
+		return nil, fmt.Errorf("transaction data is too short to contain a valid function call. "+
+			"Expected at least 4 bytes for function selector, got %d bytes.\n"+
+			"This might indicate:\n"+
+			"  1. Plain ETH transfer (no function call)\n"+
+			"  2. Invalid/corrupted transaction data\n"+
+			"  3. Contract deployment (not a function call)",
+			len(txData))
 	}
 
 	inputMap := make(map[string]interface{})

seth/gas_adjuster.go

@@ -2,7 +2,6 @@ package seth
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"math"
 	"math/big"
@@ -44,7 +43,9 @@ var (
 // according to selected strategy.
 func (m *Client) CalculateNetworkCongestionMetric(blocksNumber uint64, strategy string) (float64, error) {
 	if m.HeaderCache == nil {
-		return 0, fmt.Errorf("header cache is nil")
+		return 0, fmt.Errorf("header cache is not initialized. " +
+			"This is an internal error that shouldn't happen. " +
+			"If you see this, please open a GitHub issue at https://github.com/smartcontractkit/chainlink-testing-framework/issues with your configuration details")
 	}
 	var getHeaderData = func(bn *big.Int) (*types.Header, error) {
 		if bn == nil {
@@ -128,7 +129,18 @@ func (m *Client) CalculateNetworkCongestionMetric(blocksNumber uint64, strategy
 
 	minBlockCount := int(float64(blocksNumber) * 0.8)
 	if len(headers) < minBlockCount {
-		return 0, fmt.Errorf("%s. Wanted at least %d, got %d", BlockFetchingErr, minBlockCount, len(headers))
+		return 0, fmt.Errorf("failed to fetch sufficient block headers for gas estimation. "+
+			"Needed at least %d blocks, but only got %d (%.1f%% success rate).\n"+
+			"This usually indicates:\n"+
+			"  1. RPC node is experiencing high latency or load\n"+
+			"  2. Network connectivity issues\n"+
+			"  3. RPC rate limiting\n"+
+			"Solutions:\n"+
+			"  1. Retry the transaction (temporary RPC issue)\n"+
+			"  2. Use a different RPC endpoint\n"+
+			"  3. Disable gas estimation: set gas_price_estimation_enabled = false\n"+
+			"  4. Reduce gas_price_estimation_blocks to fetch fewer blocks",
+			minBlockCount, len(headers), float64(len(headers))/float64(blocksNumber)*100)
 	}
 
 	switch strategy {
@@ -137,7 +149,10 @@ func (m *Client) CalculateNetworkCongestionMetric(blocksNumber uint64, strategy
 	case CongestionStrategy_NewestFirst:
 		return calculateNewestFirstNetworkCongestionMetric(headers), nil
 	default:
-		return 0, fmt.Errorf("unknown congestion strategy: %s", strategy)
+		return 0, fmt.Errorf("unknown network congestion strategy '%s'. "+
+			"Valid strategies are: 'simple' (equal weight) or 'newest_first' (recent blocks weighted more).\n"+
+			"This is likely a configuration error. Check your gas estimation settings",
+			strategy)
 	}
 }
 
@@ -202,7 +217,12 @@ func (m *Client) GetSuggestedEIP1559Fees(ctx context.Context, priority string) (
 	}
 	// defensive programming
 	if baseFee == nil || currentGasTip == nil {
-		err = errors.New(ZeroGasSuggestedErr)
+		err = fmt.Errorf("RPC node returned nil gas price or zero gas tip. " +
+			"This indicates the node's gas estimation is not working properly.\n" +
+			"Solutions:\n" +
+			"  1. Use a different RPC endpoint\n" +
+			"  2. Disable gas estimation: set gas_price_estimation_enabled = false in config\n" +
+			"  3. Set explicit gas values: gas_price, gas_fee_cap, and gas_tip_cap (in your config (seth.toml or ClientBuilder)")
 		return
 	}
 
@@ -606,7 +626,10 @@ func getAdjustmentFactor(priority string) (float64, error) {
 	case Priority_Slow:
 		return 0.8, nil
 	default:
-		return 0, fmt.Errorf("unsupported priority: %s", priority)
+		return 0, fmt.Errorf("unsupported transaction priority '%s'. "+
+			"Valid priorities: 'fast', 'standard', 'slow', 'auto'. "+
+			"Set 'gas_price_estimation_tx_priority' in your config (seth.toml or ClientBuilder)",
+			priority)
 	}
 }
 
@@ -621,7 +644,10 @@ func getCongestionFactor(congestionClassification string) (float64, error) {
 	case Congestion_VeryHigh:
 		return 1.40, nil
 	default:
-		return 0, fmt.Errorf("unsupported congestion classification: %s", congestionClassification)
+		return 0, fmt.Errorf("unsupported congestion classification '%s'. "+
+			"Valid classifications: 'low', 'medium', 'high', 'extreme'. "+
+			"This is likely an internal error. Please open a GitHub issue at https://github.com/smartcontractkit/chainlink-testing-framework/issues",
+			congestionClassification)
 	}
 }
 
@@ -652,7 +678,10 @@ func (m *Client) HistoricalFeeData(ctx context.Context, priority string) (baseFe
 	case Priority_Slow:
 		percentileTip = 25
 	default:
-		err = fmt.Errorf("unknown priority: %s", priority)
+		err = fmt.Errorf("unsupported transaction priority '%s'. "+
+			"Valid priorities: 'fast', 'standard', 'slow'. "+
+			"Set 'gas_price_estimation_tx_priority' in your config (seth.toml or ClientBuilder)",
+			priority)
 		L.Debug().
 			Str("Priority", priority).
 			Msgf("Unknown priority: %s", err.Error())
@@ -682,7 +711,10 @@ func (m *Client) HistoricalFeeData(ctx context.Context, priority string) (baseFe
 	case Priority_Slow:
 		baseFee = stats.BaseFeePerc.Perc25
 	default:
-		err = fmt.Errorf("unsupported priority: %s", priority)
+		err = fmt.Errorf("unsupported transaction priority '%s'. "+
+			"Valid priorities: 'fast', 'standard', 'slow'. "+
+			"Set 'gas_price_estimation_tx_priority' in your config (seth.toml or ClientBuilder)",
+			priority)
 		L.Debug().
 			Str("Priority", priority).
 			Msgf("Unsupported priority: %s", err.Error())

seth/keyfile.go

@@ -3,7 +3,7 @@ package seth
 import (
 	"context"
 	"crypto/ecdsa"
-	"errors"
+	"fmt"
 	"math/big"
 
 	"github.com/ethereum/go-ethereum/common"
@@ -22,7 +22,11 @@ func NewAddress() (string, string, error) {
 	publicKey := privateKey.Public()
 	publicKeyECDSA, ok := publicKey.(*ecdsa.PublicKey)
 	if !ok {
-		return "", "", errors.New("error casting public key to ECDSA")
+		return "", "", fmt.Errorf("failed to cast generated public key to ECDSA type.\n"+
+			"This is an internal error in the crypto.GenerateKey() function.\n"+
+			"Expected type: *ecdsa.PublicKey, got: %T\n"+
+			"Please report this issue: https://github.com/smartcontractkit/chainlink-testing-framework/issues",
+			publicKey)
 	}
 	address := crypto.PubkeyToAddress(*publicKeyECDSA).Hex()
 	L.Info().
@@ -49,7 +53,13 @@ func ReturnFunds(c *Client, toAddr string) error {
 	}
 
 	if len(c.Addresses) == 1 {
-		return errors.New("No addresses to return funds from. Have you passed correct key file?")
+		return fmt.Errorf("no ephemeral addresses found to return funds from.\n"+
+			"Current addresses count: %d (only root key present)\n"+
+			"This indicates either:\n"+
+			"  1. Key file doesn't contain ephemeral addresses\n"+
+			"  2. Wrong key file was loaded\n"+
+			"  3. Ephemeral keys were never created (set 'ephemeral_addresses_number' > 0 in config)",
+			len(c.Addresses))
 	}
 
 	eg, egCtx := errgroup.WithContext(ctx)