feat: add flag --wait-for-receipt to loadtest

[tclemos]

closes https://github.com/0xPolygon/devtools/issues/352

✅ Task Implementation Summary: --wait-for-receipt Flag

Background

Successfully implemented an opt-in --wait-for-receipt flag that forces each goroutine to wait for transaction receipts before proceeding, preventing orphaned transactions and
nonce gaps on unreliable RPC endpoints.

🎯 Goals Achieved

✅ Opt-in Receipt Waiting

• Added --wait-for-receipt flag (defaults to false)
• Forces transaction-sending paths to wait for receipts before proceeding
• Preserves existing fire-and-forget behavior when flag is omitted

✅ Universal Mode Support

• Applied consistently across all existing transaction modes:
  • transaction, deploy, erc20, erc721, blob, contract-call, inscription, etc.
• Integrated at main transaction loop level without code duplication
• Reuses existing nonce-tracking and worker-pool logic

✅ Configurable Retry Logic

• --receipt-retry-max (default: 30) - Maximum retry attempts
• --receipt-retry-initial-delay-ms (default: 100) - Initial delay with exponential backoff
• --receipt-retry-max=0 enables infinite retries until timeout

✅ Exponential Backoff with Jitter

• Exponential growth: baseDelay * (2^attempt)
• Jitter: Random 0-50% additional delay to prevent thundering herd
• Delay cap: 30-second maximum to prevent runaway growth
• Context timeout: 1-minute default prevents infinite loops

✅ Updated Documentation

• All flags visible in --help with clear descriptions
• Auto-generated documentation updated (polycli_loadtest.md)

🏗️ Implementation Details

Clean API Design

Created multiple convenience functions for different use cases:

• waitReceipt(ctx, client, txHash) // Simple default
• waitReceiptWithRetries(ctx, client, txHash, maxRetries, delayMs) // With retry config
• waitReceiptWithTimeout(ctx, client, txHash, timeout) // With timeout only
• internalWaitReceipt(ctx, client, txHash, retries, delay, timeout) // Full-featured

Robust Edge Case Handling

• Zero values: Use sensible defaults (0 retries = infinite, 0 delay = 100ms)
• Minimum delays: 10ms minimum prevents aggressive polling
• Delay caps: 30s maximum prevents exponential runaway
• Context integration: Respects existing timeout patterns

Integration Points

• Main integration: loadtest.go:902-905 - Applied after all transaction modes
• Account funding: Uses waitReceipt() for funding transactions
• Error handling: Existing error logging captures receipt failures

✅ Acceptance Criteria Verification

Criteria	Status	Implementation
Opt-in flag forces receipt waiting	✅	--wait-for-receipt flag implemented
Fire-and-forget preserved when omitted	✅	No performance regression, defaults to false
Works with all transaction modes	✅	Applied at main loop level, covers all modes
Exponential backoff with jitter	✅	2^n growth + random jitter, configurable params
Receipt polling with retry limits	✅	Configurable max retries or infinite until timeout
Error handling and logging	✅	Proper error messages with retry counts
Updated help documentation	✅	All flags documented with defaults

🚀 Usage Examples

Basic Receipt Waiting

polycli loadtest --wait-for-receipt --mode transaction --requests 100

Custom Retry Configuration

polycli loadtest --wait-for-receipt
--receipt-retry-max 50
--receipt-retry-initial-delay-ms 200
--mode erc20 --requests 1000

Infinite Retries Until Timeout

polycli loadtest --wait-for-receipt
--receipt-retry-max 0
--mode deploy --requests 10

🎉 Benefits

• ✅ Prevents nonce gaps on unreliable RPC endpoints
• ✅ Guarantees linear nonce usage for high-throughput scenarios
• ✅ Maintains backward compatibility with existing workflows
• ✅ Configurable for different network conditions (fast/slow, reliable/unreliable)
• ✅ Production-ready with comprehensive error handling

📋 Testing Verified

• ✅ Flag parsing and help documentation
• ✅ Default behavior preservation
• ✅ Exponential backoff with jitter mathematics
• ✅ Infinite retry logic (maxRetries=0)
• ✅ Context timeout handling
• ✅ Integration across all transaction modes

---

Status: ✅ COMPLETE - All requirements fulfilled, ready for deployment

[leovct]

lgtm