0xPolygon
diff --git a/‎CLAUDE.md‎
Lines changed: 146 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 146 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 2 additions & 0 deletions b/‎README.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎cmd/loadtest/cmd.go‎
Lines changed: 25 additions & 1 deletion b/‎cmd/loadtest/cmd.go‎
Lines changed: 25 additions & 1 deletion
diff --git a/‎cmd/loadtest/loadtestUsage.md‎
Lines changed: 18 additions & 0 deletions b/‎cmd/loadtest/loadtestUsage.md‎
Lines changed: 18 additions & 0 deletions
@@ -317,6 +317,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
 
@@ -83,6 +83,8 @@ Note: Do not modify this section! It is auto-generated by `cobra` using `make ge
 
 - [polycli parseethwallet](doc/polycli_parseethwallet.md) - Extract the private key from an eth wallet.
 
+- [polycli plot](doc/polycli_plot.md) - Plot a chart of transaction gas prices and limits.
+
 - [polycli publish](doc/polycli_publish.md) - Publish transactions to the network with high-throughput.
 
 - [polycli report](doc/polycli_report.md) - Generate a report analyzing a range of blocks from an Ethereum-compatible blockchain.
 
@@ -34,6 +34,9 @@ var cfg = &config.Config{
 // uniswapCfg holds UniswapV3-specific configuration.
 var uniswapCfg = &config.UniswapV3Config{}
 
+// gasManagerCfg holds gas manager configuration.
+var gasManagerCfg = &config.GasManagerConfig{}
+
 // LoadtestCmd represents the loadtest command.
 var LoadtestCmd = &cobra.Command{
 	Use:   "loadtest",
@@ -55,6 +58,8 @@ var LoadtestCmd = &cobra.Command{
 		return cfg.Validate()
 	},
 	RunE: func(cmd *cobra.Command, args []string) error {
+		// Attach gas manager config.
+		cfg.GasManager = gasManagerCfg
 		return loadtest.Run(cmd.Context(), cfg)
 	},
 }
@@ -69,9 +74,10 @@ var uniswapv3Cmd = &cobra.Command{
 		return uniswapCfg.Validate()
 	},
 	RunE: func(cmd *cobra.Command, args []string) error {
-		// Override mode to uniswapv3 and attach UniswapV3 config.
+		// Override mode to uniswapv3 and attach configs.
 		cfg.Modes = []string{"v3"}
 		cfg.UniswapV3 = uniswapCfg
+		cfg.GasManager = gasManagerCfg
 
 		return loadtest.Run(cmd.Context(), cfg)
 	},
@@ -115,6 +121,24 @@ func initPersistentFlags() {
 	pf.BoolVar(&cfg.LegacyTxMode, "legacy", false, "send a legacy transaction instead of an EIP1559 transaction")
 	pf.BoolVar(&cfg.FireAndForget, "fire-and-forget", false, "send transactions and load without waiting for it to be mined")
 	pf.BoolVar(&cfg.FireAndForget, "send-only", false, "alias for --fire-and-forget")
+
+	initGasManagerFlags()
+}
+
+func initGasManagerFlags() {
+	pf := LoadtestCmd.PersistentFlags()
+
+	// Oscillation wave
+	pf.StringVar(&gasManagerCfg.OscillationWave, "gas-manager-oscillation-wave", "flat", "type of oscillation wave (flat | sine | square | triangle | sawtooth)")
+	pf.Uint64Var(&gasManagerCfg.Target, "gas-manager-target", 30_000_000, "target gas limit for oscillation wave")
+	pf.Uint64Var(&gasManagerCfg.Period, "gas-manager-period", 1, "period in blocks for oscillation wave")
+	pf.Uint64Var(&gasManagerCfg.Amplitude, "gas-manager-amplitude", 0, "amplitude for oscillation wave")
+
+	// Pricing strategy
+	pf.StringVar(&gasManagerCfg.PriceStrategy, "gas-manager-price-strategy", "estimated", "gas price strategy (estimated | fixed | dynamic)")
+	pf.Uint64Var(&gasManagerCfg.FixedGasPriceWei, "gas-manager-fixed-gas-price-wei", 300000000, "fixed gas price in wei")
+	pf.StringVar(&gasManagerCfg.DynamicGasPricesWei, "gas-manager-dynamic-gas-prices-wei", "0,1000000,0,10000000,0,100000000", "comma-separated gas prices in wei for dynamic strategy")
+	pf.Float64Var(&gasManagerCfg.DynamicGasPricesVariation, "gas-manager-dynamic-gas-prices-variation", 0.3, "variation percentage for dynamic strategy")
 }
 
 func initFlags() {
 
@@ -52,6 +52,24 @@ Here is a simple example that runs 1000 requests at a max rate of 1 request per
 $ polycli loadtest --verbosity 700 --chain-id 1256 --concurrency 1 --requests 1000 --rate-limit 1 --mode t --rpc-url http://localhost:8888
 ```
 
+### Gas Manager
+
+The loadtest command includes a gas manager for controlling transaction gas limits and pricing. Use the `--gas-manager-*` flags to:
+
+- **Oscillate gas limits** with wave patterns (flat, sine, square, triangle, sawtooth)
+- **Control gas pricing** with strategies (estimated, fixed, dynamic)
+
+Example with sine wave oscillation:
+```bash
+$ polycli loadtest --rpc-url http://localhost:8545 \
+  --gas-manager-oscillation-wave sine \
+  --gas-manager-target 20000000 \
+  --gas-manager-amplitude 10000000 \
+  --gas-manager-period 100
+```
+
+See [Gas Manager README](../../loadtest/gasmanager/README.md) for detailed documentation.
+
 ### Load Test Contract
 
 The codebase has a contract that used for load testing. It's written in Solidity. The workflow for modifying this contract is.