feat: gas manager for loadtest; add tx-gas-chart

CLAUDE.md

@@ -120,7 +120,14 @@ The tool supports configuration via:
 - Use zerolog for structured, performant logging throughout the project
 
 ## Development Guidelines
-- Use conventional commit messages
+
+### Commit Messages
+- Use simple, concise one-line commit messages
+- Format: `type: brief description of what was changed`
+- Keep it direct and to the point - avoid long explanations in commit message
+- Example: `fix: correct variation formula in DynamicGasPriceStrategy`
+- Example: `test: add comprehensive unit tests for GasVault`
+- Example: `docs: update README to reflect context cancellation changes`
 
 ## Development Memories
 - Use `make build` to build polycli
@@ -294,6 +301,152 @@ go func() {
 }()
 ```
 
+## Additional Patterns & Lessons Learned
+
+### Random Variation Formula
+When implementing random variation within a percentage range:
+
+```go
+// ✅ DO: Correct uniform distribution
+variationMin := 1.0 - variation  // e.g., 0.7 for ±30%
+variationMax := 1.0 + variation  // e.g., 1.3 for ±30%
+factor := variationMin + rand.Float64() * (variationMax - variationMin)
+// Result: uniformly distributed between 0.7 and 1.3
+
+// ❌ DON'T: Incorrect - produces wrong range
+factor := variationMin + rand.Float64() * variationMax
+// Result: distributed between 0.7 and 2.0 (not ±30%!)
+```
+
+### Type Conversion Safety (big.Int and int64)
+When converting between types with different ranges:
+
+```go
+// ✅ DO: Check bounds before conversion
+numBlocks := len(blocks)
+if numBlocks == 0 {
+    avgGasUsed = 0
+} else if numBlocks > math.MaxInt64 {
+    log.Warn().Msg("value exceeds int64 max")
+    avgGasUsed = 0
+} else {
+    result := new(big.Int).Div(total, big.NewInt(int64(numBlocks)))
+    if result.IsUint64() {
+        avgGasUsed = result.Uint64()
+    } else {
+        avgGasUsed = math.MaxUint64
+        log.Warn().Msg("result exceeds uint64 max")
+    }
+}
+
+// ❌ DON'T: Blindly convert without checking
+avgGasUsed = new(big.Int).Div(total, big.NewInt(int64(len(blocks)))).Uint64()
+// Can panic if len(blocks) > MaxInt64 or result > MaxUint64
+```
+
+### Blocking Operations Must Accept Context
+Any operation that can block must accept `context.Context` for cancellation:
+
+```go
+// ✅ DO: Accept context, use ticker, handle cancellation
+func (v *Vault) SpendOrWait(ctx context.Context, amount uint64) error {
+    ticker := time.NewTicker(100 * time.Millisecond)
+    defer ticker.Stop()
+
+    for {
+        if v.trySpend(amount) {
+            return nil
+        }
+        select {
+        case <-ticker.C:
+            continue
+        case <-ctx.Done():
+            return ctx.Err()
+        }
+    }
+}
+
+// ❌ DON'T: Use bare time.Sleep in infinite loop
+func (v *Vault) SpendOrWait(amount uint64) {
+    for {
+        if v.trySpend(amount) {
+            break
+        }
+        time.Sleep(100 * time.Millisecond)  // Cannot be cancelled!
+    }
+}
+```
+
+### Constructor Validation
+Validate inputs in constructors and return errors:
+
+```go
+// ✅ DO: Validate and return error
+func NewDynamicPricer(config Config) (*DynamicPricer, error) {
+    if len(config.Prices) == 0 {
+        return nil, fmt.Errorf("config.Prices cannot be empty")
+    }
+    return &DynamicPricer{config: config}, nil
+}
+
+// ❌ DON'T: Panic on invalid input or allow invalid state
+func NewDynamicPricer(config Config) *DynamicPricer {
+    // Will panic on first use if Prices is empty
+    return &DynamicPricer{config: config}
+}
+```
+
+### Documentation Must Match Implementation
+Keep documentation (especially README files) synchronized with code:
+
+**Critical to document:**
+- Function signatures including context parameters and return types
+- Error return conditions (not just success path)
+- Async/timing behavior (e.g., "vault has zero budget until first block header received")
+- Cancellation behavior
+
+**Example:**
+```markdown
+<!-- ✅ DO: Accurate signature and behavior -->
+- **`SpendOrWaitAvailableBudget(context.Context, uint64) error`**:
+  Attempts to spend gas; blocks if insufficient budget is available or until context is cancelled.
+  Returns nil on success, ctx.Err() if cancelled.
+
+<!-- ❌ DON'T: Outdated or incomplete -->
+- **`SpendOrWaitAvailableBudget(uint64)`**:
+  Attempts to spend gas; blocks if insufficient budget is available.
+```
+
+### Test Coverage Requirements
+When adding new components, always include comprehensive unit tests:
+
+**Required test categories:**
+- Basic functionality (creation, getters, setters)
+- Edge cases (zero values, nil inputs, overflow, division by zero)
+- Error conditions (invalid configs, failed operations)
+- Concurrency (multiple goroutines, race conditions)
+- Context cancellation (immediate cancel, timeout, graceful shutdown)
+- Blocking/waiting behavior (wait then succeed, wait then timeout)
+
+**Pattern for concurrent tests:**
+```go
+func TestConcurrentAccess(t *testing.T) {
+    component := NewComponent()
+    const numGoroutines = 100
+    var wg sync.WaitGroup
+
+    for i := 0; i < numGoroutines; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            // Perform concurrent operations
+        }()
+    }
+    wg.Wait()
+    // Verify final state
+}
+```
+
 ## Code Style
 
 ### Cobra Flags

README.md

@@ -93,6 +93,8 @@ Note: Do not modify this section! It is auto-generated by `cobra` using `make ge
 
 - [polycli signer](doc/polycli_signer.md) - Utilities for security signing transactions.
 
+- [polycli tx-gas-chart](doc/polycli_tx-gas-chart.md) - plot a chart of transaction gas prices and limits
+
 - [polycli ulxly](doc/polycli_ulxly.md) - Utilities for interacting with the uLxLy bridge.
 
 - [polycli version](doc/polycli_version.md) - Get the current version of this application.

cmd/loadtest/account.go

@@ -723,7 +723,7 @@ func (ap *AccountPool) returnFunds(ctx context.Context, lock bool) error {
 	if err != nil {
 		return err
 	}
-	gasPrice, _ := getSuggestedGasPrices(ctx, ap.client)
+	gasPrice, _ := getSuggestedGasPrices(ctx, ap.client, nil)
 	txFee := new(big.Int).Mul(ethTransferGas, gasPrice)
 	// triple the txFee to account for gas price fluctuations and
 	// different ways to charge transactions, like op networks
@@ -1117,7 +1117,7 @@ func (ap *AccountPool) createEOATransferTx(ctx context.Context, sender *ecdsa.Pr
 		return nil, err
 	}
 	tops.GasLimit = uint64(21000)
-	tops = configureTransactOpts(ctx, ap.client, tops)
+	tops = configureTransactOpts(ctx, ap.client, tops, nil)
 
 	var nonce uint64
 

cmd/loadtest/app.go

@@ -89,6 +89,17 @@ type (
 		OutputRawTxOnly            bool
 		CheckBalanceBeforeFunding  bool
 
+		// gas manager
+		GasManagerOscillationWave string
+		GasManagerTarget          uint64
+		GasManagerPeriod          uint64
+		GasManagerAmplitude       uint64
+
+		GasManagerPriceStrategy             string
+		GasManagerFixedGasPriceWei          uint64
+		GasManagerDynamicGasPricesWei       string
+		GasManagerDynamicGasPricesVariation float64
+
 		// Computed
 		CurrentGasPrice       *big.Int
 		CurrentGasTipCap      *big.Int
@@ -309,6 +320,18 @@ v3, uniswapv3 - perform UniswapV3 swaps`)
 	f.UintVar(&ltp.ReceiptRetryInitialDelayMs, "receipt-retry-initial-delay-ms", 100, "initial delay in milliseconds for receipt polling (uses exponential backoff with jitter)")
 	f.BoolVar(&ltp.CheckBalanceBeforeFunding, "check-balance-before-funding", false, "check account balance before funding sending accounts (saves gas when accounts are already funded)")
 
+	// gas manager flags - gas limit
+	f.Uint64Var(&ltp.GasManagerTarget, "gas-manager-target", 30_000_000, "target gas limit for the gas manager oscillation wave")
+	f.Uint64Var(&ltp.GasManagerPeriod, "gas-manager-period", 1, "period in blocks for the gas manager oscillation wave")
+	f.Uint64Var(&ltp.GasManagerAmplitude, "gas-manager-amplitude", 0, "amplitude for the gas manager oscillation wave")
+	f.StringVar(&ltp.GasManagerOscillationWave, "gas-manager-oscillation-wave", "flat", "type of oscillation wave for the gas manager (flat | sine | square | triangle | sawtooth)")
+
+	// gas manager flags - gas price
+	f.StringVar(&ltp.GasManagerPriceStrategy, "gas-manager-price-strategy", "estimated", "gas price strategy for the gas manager (estimated | fixed | dynamic)")
+	f.Uint64Var(&ltp.GasManagerFixedGasPriceWei, "gas-manager-fixed-gas-price-wei", 300000000, "fixed gas price in wei for the gas manager fixed strategy")
+	f.StringVar(&ltp.GasManagerDynamicGasPricesWei, "gas-manager-dynamic-gas-prices-wei", "0,1000000,0,10000000,0,100000000", "comma-separated list of gas prices in wei for the gas manager dynamic strategy, 0 means the tx will use the suggested gas price from the network.")
+	f.Float64Var(&ltp.GasManagerDynamicGasPricesVariation, "gas-manager-dynamic-gas-prices-variation", 0.3, "variation percentage (e.g., 0.3 for ±30%) to apply to each gas price in the dynamic strategy")
+
 	// TODO Compression
 }