ton-provider-system 0.2.2 → 0.3.0

package/dist/index.js

@@ -1035,6 +1035,238 @@ function createProvider(provider) {
   }
 }
 
+// src/utils/endpoint.ts
+function normalizeV2Endpoint(endpoint, provider) {
+  if (provider) {
+    const providerImpl = createProvider(provider);
+    return providerImpl.normalizeEndpoint(endpoint);
+  }
+  return normalizeV2EndpointFallback(endpoint);
+}
+function normalizeV2EndpointFallback(endpoint) {
+  let normalized = endpoint.trim();
+  if (normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  if (normalized.toLowerCase().endsWith("/jsonrpc")) {
+    return normalized;
+  }
+  if (normalized.includes("gateway.tatum.io")) {
+    try {
+      const url = new URL(normalized);
+      if (!url.pathname || url.pathname === "/") {
+        return normalized + "/jsonRPC";
+      }
+      if (!url.pathname.toLowerCase().endsWith("/jsonrpc")) {
+        return normalized + "/jsonRPC";
+      }
+    } catch {
+      return normalized + "/jsonRPC";
+    }
+  }
+  if (normalized.includes("onfinality.io")) {
+    try {
+      const url = new URL(normalized);
+      const baseUrl = normalized.split("?")[0];
+      if (!url.pathname || url.pathname === "/") {
+        const apikey = url.searchParams.get("apikey");
+        if (apikey && apikey !== "{key}" && apikey.length > 0) {
+          return baseUrl.replace(/\/?$/, "/rpc");
+        }
+        return baseUrl.replace(/\/?$/, "/public");
+      }
+      if (url.pathname === "/rpc" || url.pathname === "/public") {
+        return baseUrl;
+      }
+      return baseUrl;
+    } catch {
+      if (normalized.includes("{key}")) {
+        return normalized.split("?")[0].replace(/\/?$/, "/public");
+      }
+      if (!normalized.includes("/rpc") && !normalized.includes("/public")) {
+        return normalized.split("?")[0] + "/public";
+      }
+      return normalized.split("?")[0];
+    }
+  }
+  if (normalized.endsWith("/api/v2")) {
+    return normalized + "/jsonRPC";
+  }
+  if (normalized.endsWith("/api/v3")) {
+    return normalized.replace("/api/v3", "/api/v2/jsonRPC");
+  }
+  if (normalized.includes("quiknode.pro") || normalized.includes("getblock.io")) {
+    try {
+      const url = new URL(normalized);
+      if (!url.pathname || url.pathname === "/") {
+        return normalized + "/jsonRPC";
+      }
+      if (!url.pathname.toLowerCase().endsWith("/jsonrpc")) {
+        return normalized + "/jsonRPC";
+      }
+    } catch {
+      return normalized + "/jsonRPC";
+    }
+  }
+  try {
+    const url = new URL(normalized);
+    if (!url.pathname || url.pathname === "/") {
+      return normalized + "/jsonRPC";
+    }
+  } catch {
+  }
+  return normalized;
+}
+function toV2Base(endpoint) {
+  let normalized = endpoint.trim();
+  if (normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  if (normalized.toLowerCase().endsWith("/jsonrpc")) {
+    normalized = normalized.slice(0, -8);
+  }
+  normalized = normalized.replace(/\/api\/v3\b/, "/api/v2");
+  if (!normalized.endsWith("/api/v2")) {
+    if (normalized.includes("/api/v2")) {
+      const idx = normalized.indexOf("/api/v2");
+      normalized = normalized.slice(0, idx + 7);
+    }
+  }
+  return normalized;
+}
+function toV3Base(endpoint) {
+  const normalized = toV2Base(endpoint);
+  return normalized.replace("/api/v2", "/api/v3");
+}
+function getBaseUrl(endpoint) {
+  try {
+    const url = new URL(endpoint);
+    return `${url.protocol}//${url.host}`;
+  } catch {
+    return endpoint;
+  }
+}
+function isChainstackUrl(url) {
+  try {
+    const parsed = new URL(url.trim());
+    return parsed.hostname.includes("chainstack.com");
+  } catch {
+    return false;
+  }
+}
+function isQuickNodeUrl(url) {
+  try {
+    const parsed = new URL(url.trim());
+    return parsed.hostname.includes("quiknode.pro");
+  } catch {
+    return false;
+  }
+}
+function isTonCenterUrl(url) {
+  try {
+    const parsed = new URL(url.trim());
+    return parsed.hostname.includes("toncenter.com");
+  } catch {
+    return false;
+  }
+}
+function isOrbsUrl(url) {
+  try {
+    const parsed = new URL(url.trim());
+    return parsed.hostname.includes("orbs.network") || parsed.hostname.includes("ton-access");
+  } catch {
+    return false;
+  }
+}
+function buildRestUrl(baseEndpoint, method) {
+  const base = toV2Base(baseEndpoint);
+  return `${base}/${method}`;
+}
+function buildGetAddressStateUrl(baseEndpoint, address) {
+  const base = toV2Base(baseEndpoint);
+  return `${base}/getAddressState?address=${encodeURIComponent(address)}`;
+}
+function buildGetAddressBalanceUrl(baseEndpoint, address) {
+  const base = toV2Base(baseEndpoint);
+  return `${base}/getAddressBalance?address=${encodeURIComponent(address)}`;
+}
+function buildGetAddressInfoUrl(baseEndpoint, address) {
+  const base = toV2Base(baseEndpoint);
+  return `${base}/getAddressInformation?address=${encodeURIComponent(address)}`;
+}
+function detectNetworkFromEndpoint(endpoint) {
+  const lower = endpoint.toLowerCase();
+  if (lower.includes("testnet") || lower.includes("test") || lower.includes("sandbox")) {
+    return "testnet";
+  }
+  if (lower.includes("mainnet") || lower.includes("main") || // TonCenter mainnet doesn't have 'mainnet' in URL
+  lower.includes("toncenter.com") && !lower.includes("testnet")) {
+    return "mainnet";
+  }
+  return null;
+}
+function isValidHttpUrl(str) {
+  try {
+    const url = new URL(str);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function isValidWsUrl(str) {
+  try {
+    const url = new URL(str);
+    return url.protocol === "ws:" || url.protocol === "wss:";
+  } catch {
+    return false;
+  }
+}
+function isCredentialLike(segment) {
+  return /^[0-9a-f]{16,}$/i.test(segment) || // hex API keys (e.g. Chainstack/GetBlock)
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(segment) || // UUID
+  /^[A-Za-z0-9_-]{20,}$/.test(segment);
+}
+function redactUrl(url) {
+  const MASK = "***";
+  const SENSITIVE_PARAM = /^(apikey|api[-_]?key|key|token|secret|password)$/i;
+  const STRUCTURAL = /* @__PURE__ */ new Set([
+    "api",
+    "v1",
+    "v2",
+    "v3",
+    "v4",
+    "jsonrpc",
+    "rpc",
+    "public",
+    "ws",
+    "testnet",
+    "mainnet",
+    "toncenter-api-v2"
+  ]);
+  try {
+    const u = new URL(url);
+    for (const name of Array.from(u.searchParams.keys())) {
+      if (SENSITIVE_PARAM.test(name)) {
+        u.searchParams.set(name, MASK);
+      }
+    }
+    u.pathname = u.pathname.split("/").map(
+      (seg) => seg && !STRUCTURAL.has(seg.toLowerCase()) && isCredentialLike(seg) ? MASK : seg
+    ).join("/");
+    const hostParts = u.hostname.split(".");
+    if (hostParts.length > 2 && isCredentialLike(hostParts[0])) {
+      hostParts[0] = MASK;
+      u.hostname = hostParts.join(".");
+    }
+    return u.toString();
+  } catch {
+    return url.replace(
+      /\b(apikey|api[-_]?key|key|token|secret|password)=[^&\s]+/gi,
+      `$1=${MASK}`
+    );
+  }
+}
+
 // src/core/healthChecker.ts
 var consoleLogger2 = {
   debug: (msg, data) => console.debug(`[HealthChecker] ${msg}`, data || ""),
@@ -1051,6 +1283,8 @@ var HealthChecker = class {
   constructor(config, logger, rateLimiter) {
     this.results = /* @__PURE__ */ new Map();
     this.highestSeqno = /* @__PURE__ */ new Map();
+    /** Rolling window of recent valid seqnos per network (for outlier-robust blocksBehind). */
+    this.seqnoSamples = /* @__PURE__ */ new Map();
     this.rateLimiter = null;
     this.config = { ...DEFAULT_CONFIG, ...config };
     this.logger = logger || consoleLogger2;
@@ -1096,22 +1330,36 @@ var HealthChecker = class {
       if (!validation.valid) {
         throw new Error(validation.error || "Provider configuration invalid");
       }
-      const normalizedEndpoint = providerImpl.normalizeEndpoint(endpoint);
+      let normalizedEndpoint = providerImpl.normalizeEndpoint(endpoint);
       if (provider.type === "onfinality") {
-        this.logger.debug(`OnFinality endpoint: ${endpoint} -> ${normalizedEndpoint}, API key: ${provider.apiKey ? "set" : "not set"}`);
+        this.logger.debug(`OnFinality endpoint: ${redactUrl(endpoint)} -> ${redactUrl(normalizedEndpoint)}, API key: ${provider.apiKey ? "set" : "not set"}`);
       }
+      const orbsRetries = provider.isDynamic && provider.type === "orbs" ? 2 : 0;
       let info;
-      try {
-        info = await this.callGetMasterchainInfo(normalizedEndpoint, provider, providerImpl);
-      } catch (error) {
-        if (provider.type === "onfinality" && normalizedEndpoint.includes("/rpc") && provider.apiKey && error.message?.includes("backend error")) {
-          this.logger.debug(`OnFinality /rpc failed, retrying with /public endpoint`);
-          const baseUrl = normalizedEndpoint.split("?")[0];
-          const publicEndpoint = baseUrl.replace("/rpc", "/public");
-          const publicProvider = { ...provider, apiKey: void 0 };
-          const publicProviderImpl = createProvider(publicProvider);
-          info = await this.callGetMasterchainInfo(publicEndpoint, publicProvider, publicProviderImpl);
-        } else {
+      for (let attempt = 0; ; attempt++) {
+        try {
+          info = await this.callGetMasterchainInfo(normalizedEndpoint, provider, providerImpl);
+          break;
+        } catch (error) {
+          if (provider.type === "onfinality" && normalizedEndpoint.includes("/rpc") && provider.apiKey && error.message?.includes("backend error")) {
+            this.logger.debug(`OnFinality /rpc failed, retrying with /public endpoint`);
+            const baseUrl = normalizedEndpoint.split("?")[0];
+            const publicEndpoint = baseUrl.replace("/rpc", "/public");
+            const publicProvider = { ...provider, apiKey: void 0 };
+            const publicProviderImpl = createProvider(publicProvider);
+            info = await this.callGetMasterchainInfo(publicEndpoint, publicProvider, publicProviderImpl);
+            break;
+          }
+          if (attempt < orbsRetries && this.isNonJsonResponseError(error)) {
+            this.logger.debug(
+              `Orbs gateway returned a non-JSON response; re-discovering endpoint (retry ${attempt + 1}/${orbsRetries})`
+            );
+            const freshEndpoint = await this.getEndpoint(provider);
+            if (freshEndpoint) {
+              normalizedEndpoint = providerImpl.normalizeEndpoint(freshEndpoint);
+              continue;
+            }
+          }
           throw error;
         }
       }
@@ -1126,7 +1374,8 @@ var HealthChecker = class {
       if (seqno > currentHighest) {
         this.highestSeqno.set(provider.network, seqno);
       }
-      const blocksBehind = Math.max(0, (this.highestSeqno.get(provider.network) || seqno) - seqno);
+      const baselineSeqno = this.recordSeqnoAndGetBaseline(provider.network, seqno);
+      const blocksBehind = Math.max(0, baselineSeqno - seqno);
       let status = "available";
       if (blocksBehind > this.config.maxBlocksBehind) {
         status = "stale";
@@ -1154,17 +1403,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";
@@ -1192,8 +1450,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);
@@ -1201,8 +1460,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;
@@ -1253,6 +1519,7 @@ var HealthChecker = class {
   clearResults() {
     this.results.clear();
     this.highestSeqno.clear();
+    this.seqnoSamples.clear();
   }
   /**
    * Mark a provider as degraded (e.g., on 429 error)
@@ -1322,6 +1589,31 @@ var HealthChecker = class {
   getResultKey(providerId, network) {
     return `${providerId}-${network}`;
   }
+  /**
+   * Record a valid seqno sample and return an outlier-robust freshness baseline
+   * (median of recent samples for the network). Using the median instead of the
+   * raw maximum prevents a single provider that reports an inflated seqno from
+   * poisoning `blocksBehind` for every other (healthy) provider. See P2-2.
+   */
+  recordSeqnoAndGetBaseline(network, seqno) {
+    const samples = this.seqnoSamples.get(network) ?? [];
+    samples.push(seqno);
+    if (samples.length > 20) {
+      samples.shift();
+    }
+    this.seqnoSamples.set(network, samples);
+    const sorted = [...samples].sort((a, b) => a - b);
+    const mid = Math.floor((sorted.length - 1) / 2);
+    return sorted[mid];
+  }
+  /**
+   * Detect a "non-JSON response" error (e.g. an HTML error page returned by a
+   * misbehaving gateway), used to decide whether to re-discover an Orbs endpoint.
+   */
+  isNonJsonResponseError(error) {
+    const msg = (error?.message || String(error) || "").toLowerCase();
+    return msg.includes("invalid response type") || msg.includes("expected json") || msg.includes("got text/html");
+  }
   /**
    * Get endpoint URL for a provider (handles dynamic providers like Orbs)
    */
@@ -1591,24 +1883,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;
@@ -1616,24 +1920,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;
@@ -1651,10 +1956,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;
   }
   /**
@@ -1845,7 +2161,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") {
@@ -1939,14 +2257,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;
           }
         }
       }
@@ -1960,14 +2283,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;
           }
         }
       }
@@ -1982,6 +2310,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(
@@ -2032,11 +2366,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;
@@ -2120,7 +2455,7 @@ var ProviderSelector = class {
    */
   setCustomEndpoint(endpoint) {
     this.customEndpoint = endpoint?.trim() || null;
-    this.logger.info(`Custom endpoint: ${this.customEndpoint || "(none)"}`);
+    this.logger.info(`Custom endpoint: ${this.customEndpoint ? redactUrl(this.customEndpoint) : "(none)"}`);
   }
   /**
    * Get custom endpoint
@@ -2231,196 +2566,37 @@ var ProviderSelector = class {
       return true;
     });
   }
-};
-function createSelector(registry, healthChecker, config, logger, adapter = "node") {
-  return new ProviderSelector(registry, healthChecker, config, logger, adapter);
-}
-
-// src/utils/endpoint.ts
-function normalizeV2Endpoint(endpoint, provider) {
-  if (provider) {
-    const providerImpl = createProvider(provider);
-    return providerImpl.normalizeEndpoint(endpoint);
-  }
-  return normalizeV2EndpointFallback(endpoint);
-}
-function normalizeV2EndpointFallback(endpoint) {
-  let normalized = endpoint.trim();
-  if (normalized.endsWith("/")) {
-    normalized = normalized.slice(0, -1);
-  }
-  if (normalized.toLowerCase().endsWith("/jsonrpc")) {
-    return normalized;
-  }
-  if (normalized.includes("gateway.tatum.io")) {
-    try {
-      const url = new URL(normalized);
-      if (!url.pathname || url.pathname === "/") {
-        return normalized + "/jsonRPC";
-      }
-      if (!url.pathname.toLowerCase().endsWith("/jsonrpc")) {
-        return normalized + "/jsonRPC";
-      }
-    } catch {
-      return normalized + "/jsonRPC";
-    }
-  }
-  if (normalized.includes("onfinality.io")) {
-    try {
-      const url = new URL(normalized);
-      const baseUrl = normalized.split("?")[0];
-      if (!url.pathname || url.pathname === "/") {
-        const apikey = url.searchParams.get("apikey");
-        if (apikey && apikey !== "{key}" && apikey.length > 0) {
-          return baseUrl.replace(/\/?$/, "/rpc");
-        }
-        return baseUrl.replace(/\/?$/, "/public");
-      }
-      if (url.pathname === "/rpc" || url.pathname === "/public") {
-        return baseUrl;
-      }
-      return baseUrl;
-    } catch {
-      if (normalized.includes("{key}")) {
-        return normalized.split("?")[0].replace(/\/?$/, "/public");
-      }
-      if (!normalized.includes("/rpc") && !normalized.includes("/public")) {
-        return normalized.split("?")[0] + "/public";
-      }
-      return normalized.split("?")[0];
-    }
-  }
-  if (normalized.endsWith("/api/v2")) {
-    return normalized + "/jsonRPC";
-  }
-  if (normalized.endsWith("/api/v3")) {
-    return normalized.replace("/api/v3", "/api/v2/jsonRPC");
-  }
-  if (normalized.includes("quiknode.pro") || normalized.includes("getblock.io")) {
-    try {
-      const url = new URL(normalized);
-      if (!url.pathname || url.pathname === "/") {
-        return normalized + "/jsonRPC";
-      }
-      if (!url.pathname.toLowerCase().endsWith("/jsonrpc")) {
-        return normalized + "/jsonRPC";
-      }
-    } catch {
-      return normalized + "/jsonRPC";
+  /**
+   * 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;
     }
-  }
-  try {
-    const url = new URL(normalized);
-    if (!url.pathname || url.pathname === "/") {
-      return normalized + "/jsonRPC";
+    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;
     }
-  } catch {
-  }
-  return normalized;
-}
-function toV2Base(endpoint) {
-  let normalized = endpoint.trim();
-  if (normalized.endsWith("/")) {
-    normalized = normalized.slice(0, -1);
-  }
-  if (normalized.toLowerCase().endsWith("/jsonrpc")) {
-    normalized = normalized.slice(0, -8);
-  }
-  normalized = normalized.replace(/\/api\/v3\b/, "/api/v2");
-  if (!normalized.endsWith("/api/v2")) {
-    if (normalized.includes("/api/v2")) {
-      const idx = normalized.indexOf("/api/v2");
-      normalized = normalized.slice(0, idx + 7);
+    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;
   }
-  return normalized;
-}
-function toV3Base(endpoint) {
-  const normalized = toV2Base(endpoint);
-  return normalized.replace("/api/v2", "/api/v3");
-}
-function getBaseUrl(endpoint) {
-  try {
-    const url = new URL(endpoint);
-    return `${url.protocol}//${url.host}`;
-  } catch {
-    return endpoint;
-  }
-}
-function isChainstackUrl(url) {
-  try {
-    const parsed = new URL(url.trim());
-    return parsed.hostname.includes("chainstack.com");
-  } catch {
-    return false;
-  }
-}
-function isQuickNodeUrl(url) {
-  try {
-    const parsed = new URL(url.trim());
-    return parsed.hostname.includes("quiknode.pro");
-  } catch {
-    return false;
-  }
-}
-function isTonCenterUrl(url) {
-  try {
-    const parsed = new URL(url.trim());
-    return parsed.hostname.includes("toncenter.com");
-  } catch {
-    return false;
-  }
-}
-function isOrbsUrl(url) {
-  try {
-    const parsed = new URL(url.trim());
-    return parsed.hostname.includes("orbs.network") || parsed.hostname.includes("ton-access");
-  } catch {
-    return false;
-  }
-}
-function buildRestUrl(baseEndpoint, method) {
-  const base = toV2Base(baseEndpoint);
-  return `${base}/${method}`;
-}
-function buildGetAddressStateUrl(baseEndpoint, address) {
-  const base = toV2Base(baseEndpoint);
-  return `${base}/getAddressState?address=${encodeURIComponent(address)}`;
-}
-function buildGetAddressBalanceUrl(baseEndpoint, address) {
-  const base = toV2Base(baseEndpoint);
-  return `${base}/getAddressBalance?address=${encodeURIComponent(address)}`;
-}
-function buildGetAddressInfoUrl(baseEndpoint, address) {
-  const base = toV2Base(baseEndpoint);
-  return `${base}/getAddressInformation?address=${encodeURIComponent(address)}`;
-}
-function detectNetworkFromEndpoint(endpoint) {
-  const lower = endpoint.toLowerCase();
-  if (lower.includes("testnet") || lower.includes("test") || lower.includes("sandbox")) {
-    return "testnet";
-  }
-  if (lower.includes("mainnet") || lower.includes("main") || // TonCenter mainnet doesn't have 'mainnet' in URL
-  lower.includes("toncenter.com") && !lower.includes("testnet")) {
-    return "mainnet";
-  }
-  return null;
-}
-function isValidHttpUrl(str) {
-  try {
-    const url = new URL(str);
-    return url.protocol === "http:" || url.protocol === "https:";
-  } catch {
-    return false;
-  }
-}
-function isValidWsUrl(str) {
-  try {
-    const url = new URL(str);
-    return url.protocol === "ws:" || url.protocol === "wss:";
-  } catch {
-    return false;
-  }
+};
+function createSelector(registry, healthChecker, config, logger, adapter = "node") {
+  return new ProviderSelector(registry, healthChecker, config, logger, adapter);
 }
 
 // src/core/manager.ts
@@ -2654,10 +2830,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();
     }
@@ -2707,26 +2890,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();
   }
   // ========================================================================
@@ -2993,7 +3198,7 @@ var NodeAdapter = class {
       network,
       createdAt: Date.now()
     };
-    this.logger.debug(`Created TonClient for ${network}`, { endpoint });
+    this.logger.debug(`Created TonClient for ${network}`, { endpoint: redactUrl(endpoint) });
     return client;
   }
   /**
@@ -3277,9 +3482,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 {
@@ -3318,9 +3525,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();
@@ -3350,9 +3559,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();
@@ -3382,9 +3593,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();
@@ -3412,9 +3625,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();
@@ -3520,6 +3735,6 @@ async function createBrowserAdapterForNetwork(network, configPath, logger) {
   return new BrowserAdapter(manager, logger);
 }
 
-export { ApiVersionSchema, BaseProvider, BrowserAdapter, CHAINSTACK_RATE_LIMIT, ChainstackProvider, ConfigError, DEFAULT_CONTRACT_TIMEOUT_MS, DEFAULT_HEALTH_CHECK_TIMEOUT_MS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_TIMEOUT_MS, DEFAULT_RATE_LIMIT, GenericProvider, GetBlockProvider, HealthChecker, NetworkSchema, NodeAdapter, ORBS_RATE_LIMIT, OnFinalityProvider, OrbsProvider, ProviderConfigSchema, ProviderError, ProviderManager, ProviderRegistry, ProviderSelector, ProviderTypeSchema, QUICKNODE_RATE_LIMIT, QuickNodeProvider, RateLimitError, RateLimiterManager, RpcConfigSchema, TatumProvider, TimeoutError, TokenBucketRateLimiter, TonCenterProvider, buildGetAddressBalanceUrl, buildGetAddressInfoUrl, buildGetAddressStateUrl, buildRestUrl, createBrowserAdapter, createBrowserAdapterForNetwork, createDefaultConfig, createDefaultRegistry, createEmptyConfig, createHealthChecker, createNodeAdapter, createProvider, createProviderManager, createRateLimiter, createRateLimiterManager, createRegistry, createRegistryFromData, createRegistryFromFile, createSelector, createTimeoutController, detectNetworkFromEndpoint, fetchWithTimeout, getBaseUrl, getDefaultProvidersForNetwork, getEnvVar, getProviderManager, getProvidersForNetwork, getRateLimitForType, getTonClient, getTonClientForNetwork, getTonClientWithRateLimit, isApiVersion, isChainstackUrl, isNetwork, isOrbsUrl, isProviderType, isQuickNodeUrl, isRateLimitError, isTimeoutError, isTonCenterUrl, isValidHttpUrl, isValidWsUrl, loadBuiltinConfig, loadConfig, loadConfigFromData, loadConfigFromUrl, mergeConfigs, mergeWithDefaults, normalizeV2Endpoint, parseProviderConfig, parseRpcConfig, resetNodeAdapter, resolveAllProviders, resolveEndpoints, resolveKeyPlaceholder, resolveProvider, sleep, toV2Base, toV3Base, withRetry, withTimeout, withTimeoutAndRetry, withTimeoutFn };
+export { ApiVersionSchema, BaseProvider, BrowserAdapter, CHAINSTACK_RATE_LIMIT, ChainstackProvider, ConfigError, DEFAULT_CONTRACT_TIMEOUT_MS, DEFAULT_HEALTH_CHECK_TIMEOUT_MS, DEFAULT_PROVIDERS, DEFAULT_PROVIDER_TIMEOUT_MS, DEFAULT_RATE_LIMIT, GenericProvider, GetBlockProvider, HealthChecker, NetworkSchema, NodeAdapter, ORBS_RATE_LIMIT, OnFinalityProvider, OrbsProvider, ProviderConfigSchema, ProviderError, ProviderManager, ProviderRegistry, ProviderSelector, ProviderTypeSchema, QUICKNODE_RATE_LIMIT, QuickNodeProvider, RateLimitError, RateLimiterManager, RpcConfigSchema, TatumProvider, TimeoutError, TokenBucketRateLimiter, TonCenterProvider, buildGetAddressBalanceUrl, buildGetAddressInfoUrl, buildGetAddressStateUrl, buildRestUrl, createBrowserAdapter, createBrowserAdapterForNetwork, createDefaultConfig, createDefaultRegistry, createEmptyConfig, createHealthChecker, createNodeAdapter, createProvider, createProviderManager, createRateLimiter, createRateLimiterManager, createRegistry, createRegistryFromData, createRegistryFromFile, createSelector, createTimeoutController, detectNetworkFromEndpoint, fetchWithTimeout, getBaseUrl, getDefaultProvidersForNetwork, getEnvVar, getProviderManager, getProvidersForNetwork, getRateLimitForType, getTonClient, getTonClientForNetwork, getTonClientWithRateLimit, isApiVersion, isChainstackUrl, isNetwork, isOrbsUrl, isProviderType, isQuickNodeUrl, isRateLimitError, isTimeoutError, isTonCenterUrl, isValidHttpUrl, isValidWsUrl, loadBuiltinConfig, loadConfig, loadConfigFromData, loadConfigFromUrl, mergeConfigs, mergeWithDefaults, normalizeV2Endpoint, parseProviderConfig, parseRpcConfig, redactUrl, resetNodeAdapter, resolveAllProviders, resolveEndpoints, resolveKeyPlaceholder, resolveProvider, sleep, toV2Base, toV3Base, withRetry, withTimeout, withTimeoutAndRetry, withTimeoutFn };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map