TT-1716 Review and improve Seth documentation (#1312)

Author: lukaszcl

seth/docs/tracing_example.png book/src/libs/images/tracing_example.pngseth/docs/tracing_example.png renamed to book/src/libs/images/tracing_example.png

@@ -36,6 +36,9 @@ Reliable and debug-friendly Ethereum client
 15. [Bulk transaction tracing](#bulk-transaction-tracing)
 16. [RPC traffic logging](#rpc-traffic-logging)
 17. [Read-only mode](#read-only-mode)
+18. [ABI Finder](#abi-finder)
+19. [Contract Map](#contract-map)
+20. [Contract Store](#contract-store)
 
 ## Goals
 
@@ -80,7 +83,7 @@ You can read more about how ABI finding and contract map works [here](../../../s
 
 ## Examples
 
-Check [examples](../../../seth/examples) folder
+Check [examples](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/seth/examples) folder
 
 Lib provides a small amount of helpers for decoding handling that you can use with vanilla `go-ethereum` generated wrappers
 
@@ -231,7 +234,7 @@ client, err := NewClientBuilder().
     WithEIP1559DynamicFees(true).
     WithDynamicGasPrices(120_000_000_000, 44_000_000_000).
     WithGasPriceEstimations(true, 10, seth.Priority_Fast).
-// gas bumping: retries, max gas price, bumping strategy function
+    // gas bumping: retries, max gas price, bumping strategy function
     WithGasBumping(5, 100_000_000_000, PriorityBasedGasBumpingStrategyFn).
     Build()
 
@@ -839,3 +842,47 @@ Additionally, when the client is build anc `cfg.ReadOnly = true` is set, we will
 * RPC health check is disabled
 * pending nonce protection is disabled
 * gas bumping is disabled
+
+## ABI Finder
+
+In order to be able to decode and trace transactions and calls between smart contracts we need their ABIs. Unfortunately it might happen that two or more contracts have methods with the same signatures, which might result in incorrect tracing. To make that problem less severe we have decided to add a single point of entry for contract deployment in Seth as that way we always know what contract is deployed at which address and thus avoid incorrect tracing due to potentially ambiguous method signatures.
+
+1.  We don’t know what contract (ABI) is located at a given address. Should be the case, when the contract either wasn’t uploaded via Seth or we haven’t supplied Seth with a contract map as part of its configuration (more on that later).
+
+    a. We sequentially iterate over all known ABIs (map: `name -> ABI_name`) checking whether it has a method with a given signature. Once we get a first match we will upsert that (`address -> ABI_name`) data into the contract map and return the ABI.
+
+        The caveat here is that if the method we are searching for belongs is present in more than one ABI we might associate the address with an incorrect address (we will use the first match).
+
+    b. If no match is found we will return an error.
+
+2.  We know what ABI is located at a given address. It should be the case, when we have either uploaded the contract via Seth, provided Seth with a contract map or already traced a transaction to that address and found an ABI with matching method signature.
+
+    a. We fetch the corresponding ABIand check if it indeed contains the method we are looking for (as mentioned earlier in some cases it might not be the case).
+
+    b. If it does, we return the ABI.
+
+    c. If it doesn’t we iterate over all known ABIs, in the same way as in 1a. If we find a match we update the (`address -> ABI_name`) association in the contract map and return the ABI.
+
+        It is possible that this will happen multiple times in case we have multiple contracts with multiple identical methods, but given a sufficiently diverse set of methods that were called we should eventually arrive at a fully correct contract map.
+
+    d. If no match is found we will return an error.
+
+### Example
+
+![tracing_example](./images/tracing_example.png)
+
+## Contract Map
+
+We support in-memory contract map and a TOML file contract map that keeps the association of (`address -> ABI_name`). The latter map is only used for non-simulated networks. Every time we deploy a contract we save (`address -> ABI_name`) entry in the in-memory map.If the network is not a simulated one we also save it in a file. That file can later be pointed to in Seth configuration and we will load the contract map from it (**currently without validating whether we have all the ABIs mentioned in the file**).
+
+When saving contract deployment information we will either generate filename for you (if you didn’t configure Seth to use a particular file) using the pattern of `deployed_contracts_${network_name}_${timestamp}.toml` or use the filename provided in Seth TOML configuration file.
+
+It has to be noted that the file contract map is currently updated only, when new contracts are deployed. There’s no mechanism for updating it if we found the mapping invalid (which might be the case if you manually created the entry in the file).
+
+## Contract Store
+
+Seth can be used with the contract store, but it would have very limited usage as transaction decoding and tracing cannot work with ABIs. Thus, when you initialise Seth with contract store it is necessary that it can load at least one ABI.
+
+Another use of Contract Store is simplified contract deployment. For that we also need the contract's bytecode. The contract store can be used to store the bytecode of the contract and then deploy it using the `DeployContractFromContractStore(auth *bind.TransactOpts, name string, backend bind.ContractBackend, params ...interface{})` method. When Seth is intialisied with the contract store and no bytecode files (`*.bin`) are provided, it will log a warning, but initialise successfully nonetheless.
+
+If bytecode file wasn't provided you need to use `DeployContract(auth *bind.TransactOpts, name string, abi abi.ABI, bytecode []byte, backend bind.ContractBackend, params ...interface{})` method, which expects you to provide contract name (best if equal to the name of the ABI file), bytecode and the ABI.

book/src/libs/seth.md

@@ -155,6 +155,11 @@ func NewClientWithConfig(cfg *Config) (*Client, error) {
 	)
 }
 
+// ValidateConfig checks and validates the provided Config struct.
+// It ensures essential fields have valid values or default to appropriate values
+// when necessary. This function performs validation on gas price estimation,
+// gas limit, tracing level, trace outputs, network dial timeout, and pending nonce protection timeout.
+// If any configuration is invalid, it returns an error.
 func ValidateConfig(cfg *Config) error {
 	if cfg.Network.GasPriceEstimationEnabled {
 		if cfg.Network.GasPriceEstimationBlocks == 0 {
@@ -454,6 +459,10 @@ func (m *Client) checkRPCHealth() error {
 	return nil
 }
 
+// TransferETHFromKey initiates a transfer of Ether from a specified key to a recipient address.
+// It validates the private key index, estimates gas limit if not provided, and sends the transaction.
+// The function signs and sends an Ethereum transaction using the specified fromKeyNum and recipient address,
+// with the specified amount and gas price.
 func (m *Client) TransferETHFromKey(ctx context.Context, fromKeyNum int, to string, value *big.Int, gasPrice *big.Int) error {
 	if err := m.validatePrivateKeysKeyNum(fromKeyNum); err != nil {
 		return err

seth/client.go

@@ -337,6 +337,7 @@ func (m *Client) handleDisabledTracing(l zerolog.Logger, decoded DecodedTransact
 	}
 }
 
+// MergeEventData merges new event data into the existing EventData map in the DecodedTransactionLog.
 func (d *DecodedCommonLog) MergeEventData(newEventData map[string]interface{}) {
 	if d.EventData == nil {
 		d.EventData = make(map[string]interface{})
@@ -541,6 +542,8 @@ func (m *Client) CallMsgFromTx(tx *types.Transaction) (ethereum.CallMsg, error)
 	}, nil
 }
 
+// DownloadContractAndGetPragma retrieves the bytecode of a contract at a specified address and block,
+// then decodes it to extract the pragma version. Returns the pragma version or an error if retrieval or decoding fails.
 func (m *Client) DownloadContractAndGetPragma(address common.Address, block *big.Int) (Pragma, error) {
 	bytecode, err := m.Client.CodeAt(context.Background(), address, block)
 	if err != nil {

seth/decode.go

@@ -19,7 +19,8 @@ func NewGasEstimator(c *Client) *GasEstimator {
 	return &GasEstimator{Client: c}
 }
 
-// Stats prints gas stats
+// Stats calculates gas price and tip cap suggestions based on historical fee data over a specified number of blocks.
+// It computes quantiles for base fees and tip caps and provides suggested gas price and tip cap values.
 func (m *GasEstimator) Stats(fromNumber uint64, priorityPerc float64) (GasSuggestions, error) {
 	bn, err := m.Client.Client.BlockNumber(context.Background())
 	if err != nil {