@deserialize/multi-vm-wallet 1.4.2 → 1.5.0

package/utils/rate-limiter.ts

@@ -0,0 +1,179 @@
+/**
+ * Rate Limiter for RPC calls
+ *
+ * Prevents overwhelming RPC endpoints with too many concurrent requests.
+ * Useful for wallet discovery, batch operations, and API calls.
+ */
+
+export interface RateLimiterOptions {
+    /** Maximum concurrent operations */
+    maxConcurrent?: number;
+    /** Minimum delay between operations (ms) */
+    delayMs?: number;
+    /** Maximum queue size (0 = unlimited) */
+    maxQueueSize?: number;
+}
+
+/**
+ * Simple rate limiter with concurrency control
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({ maxConcurrent: 5, delayMs: 200 });
+ *
+ * // Schedule multiple operations
+ * const results = await Promise.all(
+ *   addresses.map(addr =>
+ *     limiter.schedule(() => provider.getBalance(addr))
+ *   )
+ * );
+ * ```
+ */
+export class RateLimiter {
+    private running = 0;
+    private queue: Array<() => void> = [];
+    private lastExecutionTime = 0;
+
+    constructor(
+        protected options: RateLimiterOptions = {}
+    ) {
+        this.options.maxConcurrent = options.maxConcurrent || 5;
+        this.options.delayMs = options.delayMs || 100;
+        this.options.maxQueueSize = options.maxQueueSize || 0; // 0 = unlimited
+    }
+
+    /**
+     * Schedule an async operation with rate limiting
+     *
+     * @param fn - Async function to execute
+     * @returns Promise resolving to function result
+     * @throws Error if queue is full
+     */
+    async schedule<T>(fn: () => Promise<T>): Promise<T> {
+        // Check queue size
+        if (this.options.maxQueueSize! > 0 && this.queue.length >= this.options.maxQueueSize!) {
+            throw new Error(`Rate limiter queue full (${this.queue.length}/${this.options.maxQueueSize})`);
+        }
+
+        // Wait for available slot
+        await this.waitForSlot();
+
+        this.running++;
+
+        try {
+            // Enforce minimum delay between operations
+            const now = Date.now();
+            const timeSinceLastExecution = now - this.lastExecutionTime;
+
+            if (timeSinceLastExecution < this.options.delayMs!) {
+                await new Promise(resolve =>
+                    setTimeout(resolve, this.options.delayMs! - timeSinceLastExecution)
+                );
+            }
+
+            this.lastExecutionTime = Date.now();
+
+            // Execute the function
+            return await fn();
+        } finally {
+            this.running--;
+            this.processQueue();
+        }
+    }
+
+    /**
+     * Wait for an available execution slot
+     */
+    private async waitForSlot(): Promise<void> {
+        if (this.running < this.options.maxConcurrent!) {
+            return;
+        }
+
+        return new Promise<void>(resolve => {
+            this.queue.push(resolve);
+        });
+    }
+
+    /**
+     * Process queued operations
+     */
+    private processQueue(): void {
+        if (this.queue.length > 0 && this.running < this.options.maxConcurrent!) {
+            const resolve = this.queue.shift();
+            if (resolve) {
+                resolve();
+            }
+        }
+    }
+
+    /**
+     * Get current stats
+     */
+    getStats() {
+        return {
+            running: this.running,
+            queued: this.queue.length,
+            maxConcurrent: this.options.maxConcurrent
+        };
+    }
+
+    /**
+     * Clear the queue
+     */
+    clear(): void {
+        this.queue = [];
+    }
+}
+
+/**
+ * Adaptive rate limiter that adjusts based on errors
+ *
+ * Automatically backs off when rate limit errors are detected.
+ */
+export class AdaptiveRateLimiter extends RateLimiter {
+    private consecutiveErrors = 0;
+    private baseDelayMs: number;
+
+    constructor(options: RateLimiterOptions = {}) {
+        super(options);
+        this.baseDelayMs = options.delayMs || 100;
+    }
+
+    async schedule<T>(fn: () => Promise<T>): Promise<T> {
+        try {
+            const result = await super.schedule(fn);
+            // Success - reset error count
+            this.consecutiveErrors = 0;
+            this.options.delayMs = this.baseDelayMs;
+            return result;
+        } catch (error: any) {
+            // Check if it's a rate limit error
+            if (this.isRateLimitError(error)) {
+                this.consecutiveErrors++;
+
+                // Exponential backoff
+                this.options.delayMs = Math.min(
+                    this.baseDelayMs * Math.pow(2, this.consecutiveErrors),
+                    10000 // Max 10 seconds
+                );
+
+                console.warn(
+                    `Rate limit detected. Backing off to ${this.options.delayMs}ms delay`
+                );
+            }
+
+            throw error;
+        }
+    }
+
+    private isRateLimitError(error: any): boolean {
+        const message = error.message?.toLowerCase() || '';
+        return (
+            message.includes('rate limit') ||
+            message.includes('too many requests') ||
+            message.includes('429') ||
+            error.code === 'RATE_LIMIT' ||
+            error.code === 429
+        );
+    }
+}

package/utils/retry-logic.ts

@@ -0,0 +1,271 @@
+/**
+ * Intelligent retry logic for blockchain operations
+ *
+ * Distinguishes between transient and permanent errors,
+ * only retrying operations that have a chance of success.
+ */
+
+export interface RetryOptions {
+    /** Maximum number of retries */
+    maxRetries?: number;
+    /** Initial delay in ms */
+    initialDelay?: number;
+    /** Maximum delay in ms */
+    maxDelay?: number;
+    /** Backoff multiplier */
+    backoffMultiplier?: number;
+    /** Custom retry predicate */
+    shouldRetry?: (error: any, attempt: number) => boolean;
+    /** Callback for retry attempts */
+    onRetry?: (error: any, attempt: number, delay: number) => void;
+}
+
+/**
+ * Retryable error codes
+ */
+export const RETRYABLE_ERROR_CODES = new Set([
+    // Network errors
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'ECONNREFUSED',
+    'ENETUNREACH',
+    'EAI_AGAIN',
+
+    // HTTP errors
+    'NETWORK_ERROR',
+    'TIMEOUT',
+    'SERVER_ERROR',
+
+    // RPC errors
+    'RATE_LIMIT',
+    'TOO_MANY_REQUESTS',
+    'SERVICE_UNAVAILABLE',
+    'GATEWAY_TIMEOUT',
+
+    // Blockchain errors
+    'NONCE_EXPIRED',
+    'REPLACEMENT_UNDERPRICED',
+    'NETWORK_CHANGED'
+]);
+
+/**
+ * Non-retryable error patterns
+ */
+const NON_RETRYABLE_PATTERNS = [
+    'insufficient funds',
+    'invalid address',
+    'invalid signature',
+    'nonce too low',
+    'gas too low',
+    'execution reverted',
+    'invalid opcode',
+    'out of gas',
+    'user denied',
+    'user rejected',
+    'already known',
+    'intrinsic gas too low'
+];
+
+/**
+ * Check if an error is retryable
+ *
+ * @param error - Error to check
+ * @returns true if error might be transient
+ */
+export function isRetryableError(error: any): boolean {
+    // Check error code
+    if (error.code && RETRYABLE_ERROR_CODES.has(error.code)) {
+        return true;
+    }
+
+    // Check status code
+    if (error.status === 429 || error.status === 503 || error.status === 504) {
+        return true;
+    }
+
+    // Check error message
+    const message = error.message?.toLowerCase() || '';
+
+    // Check for retryable patterns
+    if (
+        message.includes('rate limit') ||
+        message.includes('timeout') ||
+        message.includes('network') ||
+        message.includes('connection') ||
+        message.includes('temporary') ||
+        message.includes('try again')
+    ) {
+        return true;
+    }
+
+    // Check for non-retryable patterns
+    for (const pattern of NON_RETRYABLE_PATTERNS) {
+        if (message.includes(pattern)) {
+            return false;
+        }
+    }
+
+    // Default: don't retry unknown errors
+    return false;
+}
+
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (1-based)
+ * @param initialDelay - Initial delay in ms
+ * @param maxDelay - Maximum delay in ms
+ * @param multiplier - Backoff multiplier
+ * @returns Delay in ms
+ */
+export function calculateBackoffDelay(
+    attempt: number,
+    initialDelay: number = 1000,
+    maxDelay: number = 30000,
+    multiplier: number = 2
+): number {
+    // Exponential backoff: initialDelay * multiplier^(attempt-1)
+    const exponentialDelay = initialDelay * Math.pow(multiplier, attempt - 1);
+
+    // Cap at maxDelay
+    const cappedDelay = Math.min(exponentialDelay, maxDelay);
+
+    // Add jitter (±20%) to prevent thundering herd
+    const jitter = cappedDelay * 0.2 * (Math.random() - 0.5);
+
+    return Math.floor(cappedDelay + jitter);
+}
+
+/**
+ * Retry an async operation with intelligent backoff
+ *
+ * @param operation - Async function to retry
+ * @param options - Retry options
+ * @returns Result of the operation
+ * @throws Last error if all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * const balance = await retryWithBackoff(
+ *   () => provider.getBalance(address),
+ *   {
+ *     maxRetries: 3,
+ *     initialDelay: 1000,
+ *     onRetry: (error, attempt, delay) => {
+ *       console.log(`Retry ${attempt} after ${delay}ms:`, error.message);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function retryWithBackoff<T>(
+    operation: () => Promise<T>,
+    options: RetryOptions = {}
+): Promise<T> {
+    const {
+        maxRetries = 3,
+        initialDelay = 1000,
+        maxDelay = 30000,
+        backoffMultiplier = 2,
+        shouldRetry = isRetryableError,
+        onRetry
+    } = options;
+
+    let lastError: any;
+
+    for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+        try {
+            return await operation();
+        } catch (error: any) {
+            lastError = error;
+
+            // Check if we should retry
+            const isLastAttempt = attempt === maxRetries + 1;
+            const canRetry = shouldRetry(error, attempt);
+
+            if (isLastAttempt || !canRetry) {
+                // Attach retry metadata to error
+                error.attempts = attempt;
+                error.retryable = canRetry;
+                throw error;
+            }
+
+            // Calculate delay
+            const delay = calculateBackoffDelay(
+                attempt,
+                initialDelay,
+                maxDelay,
+                backoffMultiplier
+            );
+
+            // Notify caller
+            if (onRetry) {
+                onRetry(error, attempt, delay);
+            }
+
+            // Wait before retry
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+
+    // Should not reach here, but TypeScript needs it
+    throw lastError;
+}
+
+/**
+ * Retry with linear backoff (simpler, more predictable)
+ *
+ * @param operation - Async function to retry
+ * @param maxRetries - Maximum retries
+ * @param delayMs - Fixed delay between retries
+ * @returns Result of the operation
+ */
+export async function retryWithLinearBackoff<T>(
+    operation: () => Promise<T>,
+    maxRetries: number = 3,
+    delayMs: number = 1000
+): Promise<T> {
+    return retryWithBackoff(operation, {
+        maxRetries,
+        initialDelay: delayMs,
+        maxDelay: delayMs,
+        backoffMultiplier: 1 // No exponential growth
+    });
+}
+
+/**
+ * Retry for blockchain transactions with custom logic
+ *
+ * @param operation - Transaction operation
+ * @param options - Retry options
+ * @returns Transaction result
+ */
+export async function retryTransaction<T>(
+    operation: () => Promise<T>,
+    options: RetryOptions = {}
+): Promise<T> {
+    return retryWithBackoff(operation, {
+        maxRetries: 5, // More retries for transactions
+        initialDelay: 2000, // Longer initial delay
+        maxDelay: 60000, // Up to 1 minute
+        ...options,
+        shouldRetry: (error, attempt) => {
+            // Custom logic for transactions
+            const message = error.message?.toLowerCase() || '';
+
+            // Don't retry user rejections
+            if (message.includes('user denied') || message.includes('user rejected')) {
+                return false;
+            }
+
+            // Don't retry if transaction already mined
+            if (message.includes('already known') || message.includes('nonce too low')) {
+                return false;
+            }
+
+            // Retry network/rate limit errors
+            return isRetryableError(error);
+        }
+    });
+}