Updated chainio and signer READMEs + some code comments

chainio/README.md

@@ -1,20 +1,30 @@
 ## ChainIO
 
-This module is used to facilitate reading/writing/subscribing to [eigenlayer core](./clients/elcontracts/) contracts and [avs registry](./clients/avsregistry/) contracts.
 
-To make it easier to understand the different structs in this package, and their hierarchical relationship, we describe each of them below:
-- geth's ethClient
-- eigensdk [ethClient](./clients/eth/client.go)
-  - wraps geth's ethClient and adds convenience methods
-- [eigenlayerContractBindings](../contracts/bindings/)
+### Interacting with a json-rpc node
+
+We have a basic [ethClient](./clients/eth/client.go) which simply wraps geth's ethClient and adds some convenience methods. The Client interface is also implemented by [instrumentedClient](./clients/eth/instrumented_client.go) which adds metrics to the ethClient to conform to the node spec's [rpc metrics](https://docs.eigenlayer.xyz/eigenlayer/avs-guides/spec/metrics/metrics-prom-spec#rpc-metrics) requirements.
+
+
+### Building Transactions
+
+In order to facilitate reading/writing/subscribing to [eigenlayer core](./clients/elcontracts/) contracts and [avs registry](./clients/avsregistry/) contracts, we use geth's abigen created bindings for low-level interactions, as well as our own high-level clients with higher utility functions:
+- [Eigenlayer Contract Bindings](./clients/elcontracts/bindings.go)
   - generated by abigen
   - low level bindings to eigenlayer core contracts, which wrap our ethClient
-- [elContractsClient](./clients/eth/client.go)
-  - wraps eigenlayerContractBindings and hides a little bit of the underlying complexity, which is not needed in 99% of cases.
-  - abigen also doesn't create an interface for the bindings it generates, whereas elContractsClient has a well defined interface which we use to generate mocks to help with testing.
 - [ELChainReader](./clients/elcontracts/reader.go) / [ELChainWriter](./clients/elcontracts/writer.go) / [ELChainSubscriber](./clients/avsregistry/subscriber.go)
-  - wraps elContractsClient and adds convenience methods
-  - hides even more complexity than elContractsClient
+  - wraps bindings and adds convenience methods
   - These structs should be the only ones used by AVS developers, apart from interacting with an ethClient directly to make direct json rpc calls such as waiting for a transaction receipt.
 
-A similar hierarchy applies for the avs registry contracts.
+There's a similar setup for the [avs registry](./clients/avsregistry/) contracts.
+
+### Signing, Sending, and Managing Transactions
+
+After building transactions, we need to sign them, send them to the network, and manage the nonce and gas price to ensure they are mined. This functionality is provided by:
+- [txmgr](./txmgr/README.md)
+  - uses a wallet to sign and submit transactions, but then manages them by resubmitting with higher gas prices until they are mined.
+- [wallet](./clients/wallet)
+  - uses a signerv2 to sign transactions, sends them to the network and can query for their receipts
+  - wallet abstraction is needed because "wallets", such as fireblocks, both sign and send transactions to the network (they don't simply return signed bytes so that we can send them ourselves)
+- [signerv2](../signerv2/README.md)
+  - signs transactions

chainio/clients/wallet/READMD.md

@@ -0,0 +1,3 @@
+# Wallet
+
+TODO

chainio/clients/wallet/wallet.go

@@ -9,7 +9,8 @@ import (
 
 type TxID = string
 
-// Wallet is an interface for signing and sending transactions to the network
+// Wallet is an interface for signing and sending transactions to the txpool.
+// For a higher-level interface that includes nonce management and gas bumping, use the TxManager interface.
 // This interface is used to abstract the process of sending transactions to the Ethereum network
 // For example, for an MPC signer, the transaction would be broadcasted via an external API endpoint
 // and the status is tracked via another external endpoint instead of being broadcasted

chainio/txmgr/README.md

@@ -1,12 +1,13 @@
 ## Transaction Manager
+
 Transaction Manager is responsible for
 * Building transactions
-* Estimating fees and adding buffer
+* Estimating fees and adding gas limit buffer
 * Signing transactions
 * Sending transactions to the network
+* Doing transaction nonce and gas price management to ensure transactions are mined
 
 
 ### Simple Transaction Manager
-Here's the flow of the simple transaction manager which is used to send smart contract 
-transactions to the network.
+Here's the flow of the simple transaction manager which is used to send smart contract transactions to the network.
 ![Simple Transaction Manager](./simple-tx-manager-flow.png)

chainio/txmgr/txmgr.go

@@ -28,12 +28,16 @@ var (
 // https://github.com/ethereum-optimism/optimism/blob/develop/op-service/txmgr/txmgr.go
 
 type TxManager interface {
-	// Send is used to send a transaction
+	// Send is used to send a transaction and 
 	// It takes an unsigned transaction and then signs it before sending
 	// It also takes care of nonce management and gas estimation
 	Send(ctx context.Context, tx *types.Transaction) (*types.Receipt, error)
 
-	// GetNoSendTxOpts This generates a noSend TransactOpts so that we can use
+	// GetNoSendTxOpts generates a TransactOpts with
+	// - NoSend=true: b/c we want to manage the sending ourselves
+	// - Signer=NoopSigner: b/c we want the wallet to manage signing
+	// - From=sender: unfortunately needed as first parameter to 
+	// This is needed when using abigen to construct transactions.
 	// this to generate the transaction without actually sending it
 	GetNoSendTxOpts() (*bind.TransactOpts, error)
 }

signer/README.md

@@ -1,4 +1,8 @@
 ## Signer
+
+> [!WARNING]
+> signer is deprecated. Please use [signerv2](../signerv2/README.md) instead.
+
 This module is used for initializing the signer used to sign smart contract transactions.
 
 There are two types of signer we support

signerv2/README.md

@@ -0,0 +1,3 @@
+# Signerv2
+
+TODO