ton-provider-system 0.2.2 → 0.2.4

package/README.md

@@ -53,17 +53,23 @@ Or add to your `package.json`:
 ### Node.js (Scripts, Telegram Bot)
 
 ```typescript
-import { ProviderManager, getTonClient } from 'ton-provider-system';
+import { ProviderManager, getTonClient, NodeAdapter } from 'ton-provider-system';
 
 // Initialize
 const pm = ProviderManager.getInstance();
 await pm.init('testnet');
 
-// Get TonClient for blockchain operations
-const client = await getTonClient(pm);
+// Option 1: Use adapter (RECOMMENDED - handles rate limiting automatically)
+const adapter = new NodeAdapter(pm);
+const balance = await adapter.getAddressBalance(address);
+const state = await adapter.getAddressState(address);
 
-// Use the client
-const balance = await client.getBalance(address);
+// Option 2: Use TonClient with rate limiting
+const client = await getTonClient(pm);
+// Always use getEndpointWithRateLimit() before operations
+const endpoint = await pm.getEndpointWithRateLimit();
+// Note: TonClient doesn't automatically respect rate limits
+// Consider using adapter methods instead
 ```
 
 ### Browser (React/Next.js)
@@ -72,12 +78,16 @@ const balance = await client.getBalance(address);
 import { ProviderManager, BrowserAdapter } from 'ton-provider-system';
 
 // Create instance (not singleton for React)
+// IMPORTANT: Use 'browser' adapter to filter CORS-incompatible providers
 const pm = new ProviderManager({ adapter: 'browser' });
 await pm.init(network);
 
 // Use browser adapter for fetch-based operations
+// Adapter methods automatically handle rate limiting
 const adapter = new BrowserAdapter(pm);
 const balance = await adapter.getAddressBalance(address);
+const state = await adapter.getAddressState(address);
+const result = await adapter.runGetMethod(address, 'method', []);
 ```
 
 ## Configuration
@@ -140,10 +150,11 @@ const pm = new ProviderManager({ adapter: 'browser' });
 await pm.init('testnet');
 await pm.init('mainnet');
 
-// Get endpoint URL
+// Get endpoint URL (no rate limiting - use for one-off requests)
 const endpoint = await pm.getEndpoint();
 
-// Get endpoint with rate limiting
+// Get endpoint with rate limiting (RECOMMENDED for production)
+// Waits for rate limit token before returning endpoint
 const endpoint = await pm.getEndpointWithRateLimit(5000);
 
 // Test all providers
@@ -394,18 +405,104 @@ pnpm test:verbose
 
 ### No providers available
 
-1. Check `.env` file has API keys configured
-2. Run `pnpm check-connection` to test providers
+**Symptoms**: `No providers available, using fallback` warning
+
+**Solutions**:
+1. Check `.env` file has API keys configured for at least one provider
+2. Verify environment variables are loaded (use `dotenv` or similar)
+3. Run `pnpm test` to test all providers
+4. Check provider health: `const results = await pm.testAllProviders()`
 
-### Rate limit errors
+### Rate limit errors (429)
 
-1. The system automatically switches to next provider on 429 errors
-2. Configure more providers in `.env` for redundancy
+**Symptoms**: Frequent 429 errors, requests failing
+
+**Solutions**:
+1. **Use `getEndpointWithRateLimit()`** instead of `getEndpoint()` - this is the recommended approach
+2. Use adapter methods (`adapter.getAddressState()`) which automatically handle rate limiting
+3. The system automatically switches to next provider on 429 errors
+4. Configure more providers in `.env` for redundancy
+5. Check RPS limits in `rpc.json` - some providers have very low limits (e.g., Tatum: 3 RPS)
+
+**Example**:
+```typescript
+// ❌ BAD - bypasses rate limiting
+const endpoint = await pm.getEndpoint();
+const client = new TonClient({ endpoint });
+await client.getBalance(address); // May hit rate limit
+
+// ✅ GOOD - respects rate limiting
+const endpoint = await pm.getEndpointWithRateLimit();
+const client = new TonClient({ endpoint });
+await client.getBalance(address);
+
+// ✅ BEST - adapter handles everything
+const adapter = new NodeAdapter(pm);
+const balance = await adapter.getAddressBalance(address);
+```
 
 ### Block height mismatch (stale provider)
 
-1. Provider is returning old data
-2. System marks it as `stale` and prefers fresh providers
+**Symptoms**: Provider returns old block data
+
+**Solutions**:
+1. System automatically marks stale providers and prefers fresh ones
+2. Stale providers are still used if no fresh providers available
+3. Check provider health: `const health = pm.getHealthChecker()?.getResult(providerId, network)`
+
+### Provider failures (503, 502, timeout)
+
+**Symptoms**: Providers marked as offline, frequent failovers
+
+**Solutions**:
+1. These are usually temporary infrastructure issues
+2. System automatically fails over to next provider
+3. Failed providers are retried after cooldown period (default: 30 seconds)
+4. Check provider status: `const results = await pm.testAllProviders()`
+5. Permanent errors (404, 401) are not retried - check API keys
+
+### Browser compatibility (CORS errors)
+
+**Symptoms**: CORS errors in browser, providers not working
+
+**Solutions**:
+1. Use `BrowserAdapter` instead of direct `TonClient` in browser
+2. Some providers are not browser-compatible (e.g., Tatum) - they're automatically filtered
+3. Check browser compatibility: `const providers = pm.getProviders()` (already filtered)
+4. Use `adapter: 'browser'` when creating `ProviderManager` in browser environment
+
+**Example**:
+```typescript
+// ✅ Correct for browser
+const pm = new ProviderManager({ adapter: 'browser' });
+await pm.init('testnet');
+const adapter = new BrowserAdapter(pm);
+const balance = await adapter.getAddressBalance(address);
+```
+
+### Error handling and failover
+
+**Symptoms**: Need to handle provider failures gracefully
+
+**Solutions**:
+1. Always wrap operations in try-catch
+2. Call `pm.reportError(error)` on failures to trigger failover
+3. Call `pm.reportSuccess()` on success to update rate limiter
+4. System automatically fails over, but manual reporting improves accuracy
+
+**Example**:
+```typescript
+try {
+    const endpoint = await pm.getEndpointWithRateLimit();
+    const client = new TonClient({ endpoint });
+    const result = await client.someMethod();
+    pm.reportSuccess(); // Update rate limiter
+    return result;
+} catch (error) {
+    pm.reportError(error); // Trigger failover
+    throw error;
+}
+```
 
 ## Publishing
 

package/dist/index.cjs

@@ -1157,17 +1157,26 @@ var HealthChecker = class {
       const endTime = performance.now();
       const latencyMs = Math.round(endTime - startTime);
       const errorMsg = error.message || String(error) || "Unknown error";
+      const errorMsgLower = errorMsg.toLowerCase();
       const isCorsError = this.isCorsError(error, errorMsg);
-      const is429 = errorMsg.includes("429") || errorMsg.toLowerCase().includes("rate limit");
-      const is404 = errorMsg.includes("404") || errorMsg.toLowerCase().includes("not found");
-      const is503 = errorMsg.includes("503") || errorMsg.toLowerCase().includes("service unavailable");
-      const is502 = errorMsg.includes("502") || errorMsg.toLowerCase().includes("bad gateway");
-      const isTimeout = error.name === "AbortError" || errorMsg.includes("timeout");
-      const isOnFinalityBackendError = provider.type === "onfinality" && (errorMsg.includes("Backend error") || errorMsg.includes("backend error"));
+      const responseStatus = error?.response?.status || error?.status || error?.statusCode || null;
+      const statusMatch = errorMsg.match(/\b(\d{3})\b/);
+      const statusFromMsg = statusMatch ? parseInt(statusMatch[1], 10) : null;
+      const httpStatus = responseStatus || statusFromMsg;
+      const is429 = httpStatus === 429 || errorMsgLower.includes("429") || errorMsgLower.includes("rate limit") || errorMsgLower.includes("too many requests");
+      const is404 = httpStatus === 404 || errorMsgLower.includes("404") || errorMsgLower.includes("not found");
+      const is401 = httpStatus === 401 || errorMsgLower.includes("401") || errorMsgLower.includes("unauthorized") || errorMsgLower.includes("invalid api key") || errorMsgLower.includes("authentication failed");
+      const is403 = httpStatus === 403 || errorMsgLower.includes("403") || errorMsgLower.includes("forbidden");
+      const is503 = httpStatus === 503 || errorMsgLower.includes("503") || errorMsgLower.includes("service unavailable");
+      const is502 = httpStatus === 502 || errorMsgLower.includes("502") || errorMsgLower.includes("bad gateway");
+      const isTimeout = error.name === "AbortError" || errorMsgLower.includes("timeout") || errorMsgLower.includes("timed out") || errorMsgLower.includes("aborted");
+      const isOnFinalityBackendError = provider.type === "onfinality" && (errorMsgLower.includes("backend error") || errorMsgLower.includes("backend error"));
       let status = "offline";
       if (is429) {
         status = "degraded";
-      } else if (is404 || is503 || is502 || isOnFinalityBackendError) {
+      } else if (is404 || is401 || is403) {
+        status = "offline";
+      } else if (is503 || is502 || isOnFinalityBackendError) {
         status = "offline";
       } else if (isTimeout) {
         status = "offline";
@@ -1195,8 +1204,9 @@ var HealthChecker = class {
    * 
    * @param batchSize - Number of providers to test in parallel (default: 2)
    * @param batchDelayMs - Delay between batches in milliseconds (default: 500 to avoid rate limits)
+   *                       If not provided, calculates delay based on lowest RPS in batch
    */
-  async testProviders(providers, batchSize = 2, batchDelayMs = 500) {
+  async testProviders(providers, batchSize = 2, batchDelayMs) {
     const results = [];
     for (let i = 0; i < providers.length; i += batchSize) {
       const batch = providers.slice(i, i + batchSize);
@@ -1204,8 +1214,15 @@ var HealthChecker = class {
         batch.map((p) => this.testProvider(p))
       );
       results.push(...batchResults);
-      if (i + batchSize < providers.length && batchDelayMs > 0) {
-        await this.sleep(batchDelayMs);
+      if (i + batchSize < providers.length) {
+        let delay = batchDelayMs;
+        if (delay === void 0) {
+          const minRps = Math.min(...batch.map((p) => p.rps || 1));
+          delay = Math.max(500, Math.ceil(1e3 / minRps * 1.5));
+        }
+        if (delay > 0) {
+          await this.sleep(delay);
+        }
       }
     }
     return results;
@@ -1594,24 +1611,36 @@ var TokenBucketRateLimiter = class {
     const startTime = Date.now();
     if (this.processing) {
       const acquired = await new Promise((resolve) => {
+        let timeoutInterval = null;
+        let resolved = false;
+        const cleanup = () => {
+          if (timeoutInterval !== null) {
+            clearInterval(timeoutInterval);
+            timeoutInterval = null;
+          }
+        };
         const checkTimeout = () => {
           if (Date.now() - startTime > timeoutMs) {
             const idx = this.requestQueue.indexOf(resolveCallback);
             if (idx >= 0) {
               this.requestQueue.splice(idx, 1);
             }
-            resolve(false);
+            if (!resolved) {
+              resolved = true;
+              cleanup();
+              resolve(false);
+            }
           }
         };
-        const resolveCallback = () => resolve(true);
-        this.requestQueue.push(resolveCallback);
-        const timeoutInterval = setInterval(checkTimeout, 1e3);
-        const cleanup = () => clearInterval(timeoutInterval);
-        Promise.resolve().then(() => {
-          if (this.requestQueue.includes(resolveCallback)) ; else {
+        const resolveCallback = () => {
+          if (!resolved) {
+            resolved = true;
             cleanup();
+            resolve(true);
           }
-        });
+        };
+        this.requestQueue.push(resolveCallback);
+        timeoutInterval = setInterval(checkTimeout, 1e3);
       });
       if (!acquired) {
         return false;
@@ -1619,24 +1648,25 @@ var TokenBucketRateLimiter = class {
     }
     this.processing = true;
     try {
-      this.refill();
       if (this.currentBackoff > 0) {
         this.logger.debug(`Applying backoff: ${this.currentBackoff}ms`);
         await sleep(this.currentBackoff);
         this.lastRefill = Date.now();
-        this.currentBackoff = 0;
       }
+      this.refill();
       while (this.tokens <= 0) {
         if (Date.now() - startTime > timeoutMs) {
           return false;
         }
-        await sleep(Math.min(100, this.config.minDelayMs));
+        const waitTime = Math.min(100, this.config.minDelayMs);
+        await sleep(waitTime);
         this.refill();
       }
       this.tokens--;
       const timeSinceLastRefill = Date.now() - this.lastRefill;
       if (timeSinceLastRefill < this.config.minDelayMs) {
-        await sleep(this.config.minDelayMs - timeSinceLastRefill);
+        const remainingDelay = this.config.minDelayMs - timeSinceLastRefill;
+        await sleep(remainingDelay);
       }
       this.lastRefill = Date.now();
       return true;
@@ -1654,10 +1684,21 @@ var TokenBucketRateLimiter = class {
   release() {
   }
   /**
-   * Report a successful request (resets backoff)
+   * Report a successful request (gradually reduces backoff)
+   * 
+   * Instead of immediately clearing backoff, we gradually reduce it to prevent
+   * immediately hitting the rate limit again after a single success.
    */
   reportSuccess() {
-    this.currentBackoff = 0;
+    if (this.currentBackoff > 0) {
+      this.currentBackoff = Math.max(
+        this.config.minDelayMs,
+        Math.floor(this.currentBackoff / 2)
+      );
+      if (this.currentBackoff <= this.config.minDelayMs) {
+        this.currentBackoff = 0;
+      }
+    }
     this.consecutiveErrors = 0;
   }
   /**
@@ -1848,7 +1889,9 @@ var DEFAULT_CONFIG2 = {
   latencyWeight: 0.4,
   priorityWeight: 0.3,
   freshnessWeight: 0.3,
-  minStatus: ["available", "degraded"]
+  minStatus: ["available", "degraded"],
+  retryCooldownMs: 3e4
+  // 30 seconds
 };
 var ProviderSelector = class {
   constructor(registry, healthChecker, config, logger, adapter = "node") {
@@ -1942,14 +1985,19 @@ var ProviderSelector = class {
           return defaultProvider;
         }
         if (health.success === false && health.lastTested) {
-          const timeSinceFailure = Date.now() - health.lastTested.getTime();
-          const cooldownMs = 3e4;
-          if (timeSinceFailure > cooldownMs) {
-            this.logger.warn(
-              `No healthy providers for ${network}, retrying failed default after cooldown: ${defaultProvider.id}`
+          if (this.isRetryableError(health.error)) {
+            const timeSinceFailure = Date.now() - health.lastTested.getTime();
+            if (timeSinceFailure > this.config.retryCooldownMs) {
+              this.logger.warn(
+                `No healthy providers for ${network}, retrying failed default after cooldown: ${defaultProvider.id}`
+              );
+              this.activeProviderByNetwork.set(network, defaultProvider.id);
+              return defaultProvider;
+            }
+          } else {
+            this.logger.debug(
+              `Skipping provider ${defaultProvider.id} with permanent error: ${health.error}`
             );
-            this.activeProviderByNetwork.set(network, defaultProvider.id);
-            return defaultProvider;
           }
         }
       }
@@ -1963,14 +2011,19 @@ var ProviderSelector = class {
           return provider;
         }
         if (health.success === false && health.lastTested) {
-          const timeSinceFailure = Date.now() - health.lastTested.getTime();
-          const cooldownMs = 3e4;
-          if (timeSinceFailure > cooldownMs) {
-            this.logger.warn(
-              `No healthy providers for ${network}, retrying failed provider after cooldown: ${provider.id}`
+          if (this.isRetryableError(health.error)) {
+            const timeSinceFailure = Date.now() - health.lastTested.getTime();
+            if (timeSinceFailure > this.config.retryCooldownMs) {
+              this.logger.warn(
+                `No healthy providers for ${network}, retrying failed provider after cooldown: ${provider.id}`
+              );
+              this.activeProviderByNetwork.set(network, provider.id);
+              return provider;
+            }
+          } else {
+            this.logger.debug(
+              `Skipping provider ${provider.id} with permanent error: ${health.error}`
             );
-            this.activeProviderByNetwork.set(network, provider.id);
-            return provider;
           }
         }
       }
@@ -1985,6 +2038,12 @@ var ProviderSelector = class {
       this.logger.debug(
         `Best provider for ${network}: ${best.id} (score: ${scored[0].score.toFixed(2)})`
       );
+    } else if (bestHealth && bestHealth.success === false) {
+      this.bestProviderByNetwork.delete(network);
+      this.activeProviderByNetwork.set(network, best.id);
+      this.logger.debug(
+        `Best provider for ${network}: ${best.id} (score: ${scored[0].score.toFixed(2)}, failed - not cached)`
+      );
     } else {
       this.activeProviderByNetwork.set(network, best.id);
       this.logger.debug(
@@ -2035,11 +2094,12 @@ var ProviderSelector = class {
       return 0.01 * (1 / (provider.priority + 1));
     }
     if (health.success === false) {
-      if (health.lastTested) {
-        const timeSinceFailure = Date.now() - health.lastTested.getTime();
-        const cooldownMs = 3e4;
-        if (timeSinceFailure > cooldownMs) {
-          return 1e-3 * (1 / (provider.priority + 1));
+      if (this.isRetryableError(health.error)) {
+        if (health.lastTested) {
+          const timeSinceFailure = Date.now() - health.lastTested.getTime();
+          if (timeSinceFailure > this.config.retryCooldownMs) {
+            return 1e-3 * (1 / (provider.priority + 1));
+          }
         }
       }
       return 0;
@@ -2234,6 +2294,34 @@ var ProviderSelector = class {
       return true;
     });
   }
+  /**
+   * Check if an error is retryable (temporary) or permanent
+   * 
+   * Permanent errors (never retry):
+   * - 404 (Not Found) - endpoint doesn't exist
+   * - 401 (Unauthorized) - invalid API key
+   * - Invalid API key errors
+   * 
+   * Retryable errors (can retry after cooldown):
+   * - 503 (Service Unavailable) - temporary server issue
+   * - 502 (Bad Gateway) - temporary gateway issue
+   * - Timeout errors - network issues
+   * - Network errors - connection issues
+   * - 429 (Rate Limit) - temporary rate limit (handled separately)
+   */
+  isRetryableError(error) {
+    if (!error) {
+      return true;
+    }
+    const errorLower = error.toLowerCase();
+    if (errorLower.includes("404") || errorLower.includes("not found") || errorLower.includes("401") || errorLower.includes("unauthorized") || errorLower.includes("invalid api key") || errorLower.includes("api key is invalid") || errorLower.includes("authentication failed") || errorLower.includes("forbidden")) {
+      return false;
+    }
+    if (errorLower.includes("503") || errorLower.includes("service unavailable") || errorLower.includes("502") || errorLower.includes("bad gateway") || errorLower.includes("timeout") || errorLower.includes("network error") || errorLower.includes("connection") || errorLower.includes("econnrefused") || errorLower.includes("enotfound")) {
+      return true;
+    }
+    return true;
+  }
 };
 function createSelector(registry, healthChecker, config, logger, adapter = "node") {
   return new ProviderSelector(registry, healthChecker, config, logger, adapter);
@@ -2657,10 +2745,17 @@ var _ProviderManager = class _ProviderManager {
     }
     const acquired = await this.rateLimiter.acquire(provider.id, timeoutMs);
     if (!acquired) {
-      this.options.logger.warn(`Rate limit timeout for ${provider.id}`);
+      const timeoutError = new Error(`Rate limit token acquisition timeout for ${provider.id} after ${timeoutMs || 6e4}ms`);
+      this.options.logger.warn(timeoutError.message);
+      this.reportError(timeoutError);
       const next = this.selector.getNextProvider(this.network, [provider.id]);
       if (next) {
-        return normalizeV2Endpoint(next.endpointV2, next);
+        const nextTimeout = timeoutMs ? Math.min(timeoutMs, 1e4) : 1e4;
+        const nextAcquired = await this.rateLimiter.acquire(next.id, nextTimeout);
+        if (nextAcquired) {
+          return normalizeV2Endpoint(next.endpointV2, next);
+        }
+        this.options.logger.warn(`Rate limit timeout for next provider ${next.id}, using fallback`);
       }
       return this.getFallbackEndpoint();
     }
@@ -2710,26 +2805,48 @@ var _ProviderManager = class _ProviderManager {
     if (!provider) {
       provider = this.selector.getBestProvider(this.network);
     }
-    if (!provider) return;
+    if (!provider) {
+      this.options.logger.warn(`Cannot report error: no provider available for ${this.network}`);
+      return;
+    }
     const errorMsg = error instanceof Error ? error.message : String(error);
     const errorMsgLower = errorMsg.toLowerCase();
-    const is429 = errorMsgLower.includes("429") || errorMsgLower.includes("rate limit");
-    const is503 = errorMsgLower.includes("503") || errorMsgLower.includes("service unavailable");
-    const is502 = errorMsgLower.includes("502") || errorMsgLower.includes("bad gateway");
-    const is404 = errorMsgLower.includes("404") || errorMsgLower.includes("not found");
-    const isTimeout = errorMsgLower.includes("timeout") || errorMsgLower.includes("abort");
+    const enhancedErrorMsg = `Provider ${provider.id} (${provider.name}): ${errorMsg}`;
+    const responseStatus = error instanceof Error && error?.response?.status || error instanceof Error && error?.status || error instanceof Error && error?.statusCode || null;
+    const statusMatch = errorMsg.match(/\b(\d{3})\b/);
+    const statusFromMsg = statusMatch ? parseInt(statusMatch[1], 10) : null;
+    const httpStatus = responseStatus || statusFromMsg;
+    const is429 = httpStatus === 429 || errorMsgLower.includes("429") || errorMsgLower.includes("rate limit") || errorMsgLower.includes("too many requests");
+    const is503 = httpStatus === 503 || errorMsgLower.includes("503") || errorMsgLower.includes("service unavailable");
+    const is502 = httpStatus === 502 || errorMsgLower.includes("502") || errorMsgLower.includes("bad gateway");
+    const is404 = httpStatus === 404 || errorMsgLower.includes("404") || errorMsgLower.includes("not found");
+    const is401 = httpStatus === 401 || errorMsgLower.includes("401") || errorMsgLower.includes("unauthorized") || errorMsgLower.includes("invalid api key") || errorMsgLower.includes("authentication failed");
+    const isTimeout = error instanceof Error && error.name === "AbortError" || errorMsgLower.includes("timeout") || errorMsgLower.includes("timed out") || errorMsgLower.includes("abort");
     if (isRateLimitError(error) || is429) {
       this.rateLimiter.reportRateLimitError(provider.id);
-      this.healthChecker.markDegraded(provider.id, this.network, errorMsg);
-    } else if (is503 || is502 || is404 || isTimeout) {
+      this.healthChecker.markDegraded(provider.id, this.network, enhancedErrorMsg);
+      this.options.logger.warn(`${enhancedErrorMsg} - Rate limit detected, switching to next provider`);
+    } else if (is404 || is401) {
+      this.rateLimiter.reportError(provider.id);
+      this.healthChecker.markOffline(provider.id, this.network, enhancedErrorMsg);
+      this.options.logger.error(`${enhancedErrorMsg} - Permanent error (${is404 ? "404" : "401"}), provider marked offline`);
+    } else if (is503 || is502 || isTimeout) {
       this.rateLimiter.reportError(provider.id);
-      this.healthChecker.markOffline(provider.id, this.network, errorMsg);
+      this.healthChecker.markOffline(provider.id, this.network, enhancedErrorMsg);
+      const errorType = is503 ? "503" : is502 ? "502" : "timeout";
+      this.options.logger.warn(`${enhancedErrorMsg} - Server error (${errorType}), switching to next provider`);
     } else {
       this.rateLimiter.reportError(provider.id);
-      this.healthChecker.markDegraded(provider.id, this.network, errorMsg);
+      this.healthChecker.markDegraded(provider.id, this.network, enhancedErrorMsg);
+      this.options.logger.warn(`${enhancedErrorMsg} - Unknown error, switching to next provider`);
+    }
+    const nextProvider = this.selector.handleProviderFailure(provider.id, this.network);
+    if (nextProvider) {
+      this.options.logger.info(`Failover: switched from ${provider.id} to ${nextProvider.id}`);
+    } else {
+      this.options.logger.warn(`Failover: no alternative provider available for ${this.network}`);
     }
     this.selector.clearCache(this.network);
-    this.selector.handleProviderFailure(provider.id, this.network);
     this.notifyListeners();
   }
   // ========================================================================
@@ -3280,9 +3397,11 @@ var BrowserAdapter = class {
   // ========================================================================
   /**
    * Make a JSON-RPC call to the TON API
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async jsonRpc(method, params = {}, timeoutMs = 1e4) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -3321,9 +3440,11 @@ var BrowserAdapter = class {
   // ========================================================================
   /**
    * Get address state
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async getAddressState(address, timeoutMs = 1e4) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const baseV2 = toV2Base(endpoint);
     const url = `${baseV2}/getAddressState?address=${encodeURIComponent(address)}`;
     const controller = new AbortController();
@@ -3353,9 +3474,11 @@ var BrowserAdapter = class {
   }
   /**
    * Get address balance
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async getAddressBalance(address, timeoutMs = 1e4) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const baseV2 = toV2Base(endpoint);
     const url = `${baseV2}/getAddressBalance?address=${encodeURIComponent(address)}`;
     const controller = new AbortController();
@@ -3385,9 +3508,11 @@ var BrowserAdapter = class {
   }
   /**
    * Get address information
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async getAddressInfo(address, timeoutMs = 1e4) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const baseV2 = toV2Base(endpoint);
     const url = `${baseV2}/getAddressInformation?address=${encodeURIComponent(address)}`;
     const controller = new AbortController();
@@ -3415,9 +3540,11 @@ var BrowserAdapter = class {
   }
   /**
    * Run get method
+   * 
+   * Note: Uses rate limiting to prevent 429 errors.
    */
   async runGetMethod(address, method, stack = [], timeoutMs = 15e3) {
-    const endpoint = await this.manager.getEndpoint();
+    const endpoint = await this.manager.getEndpointWithRateLimit(timeoutMs);
     const baseV2 = toV2Base(endpoint);
     const url = `${baseV2}/runGetMethod`;
     const controller = new AbortController();