ton-provider-system 0.1.13 → 0.2.1

package/dist/index.cjs

@@ -557,183 +557,461 @@ function createRegistryFromData(data, logger) {
   return new ProviderRegistry(mergedConfig, logger);
 }
 
-// src/utils/endpoint.ts
-function normalizeV2Endpoint(endpoint) {
-  let normalized = endpoint.trim();
-  if (normalized.endsWith("/")) {
-    normalized = normalized.slice(0, -1);
+// src/providers/base.ts
+var BaseProvider = class {
+  constructor(provider) {
+    this.provider = provider;
   }
-  if (normalized.toLowerCase().endsWith("/jsonrpc")) {
-    return normalized;
+  /**
+   * Get the provider instance
+   */
+  getProvider() {
+    return this.provider;
   }
-  if (normalized.includes("gateway.tatum.io")) {
-    try {
-      const url = new URL(normalized);
-      if (!url.pathname || url.pathname === "/") {
-        return normalized + "/jsonRPC";
+  /**
+   * Build a JSON-RPC request body.
+   * Most providers use standard JSON-RPC 2.0, but some may need modifications.
+   */
+  buildRequest(method, params = {}) {
+    return {
+      id: "1",
+      jsonrpc: "2.0",
+      method,
+      params
+    };
+  }
+  /**
+   * Parse response from provider.
+   * Handles provider-specific response formats.
+   */
+  parseResponse(data) {
+    if (data && typeof data === "object") {
+      const dataObj = data;
+      if ("ok" in dataObj) {
+        if (!dataObj.ok) {
+          const error = dataObj.error;
+          throw new Error(error || "API returned ok=false");
+        }
+        const result = dataObj.result;
+        return result || dataObj;
       }
-      if (!url.pathname.toLowerCase().endsWith("/jsonrpc")) {
-        return normalized + "/jsonRPC";
+      if ("result" in dataObj) {
+        return dataObj.result;
       }
-    } catch {
+      if ("last" in dataObj || "@type" in dataObj) {
+        return dataObj;
+      }
+      if ("error" in dataObj) {
+        const errorObj = dataObj.error;
+        const errorMsg = typeof errorObj === "string" ? errorObj : errorObj?.message || errorObj?.code || String(errorObj);
+        throw new Error(`API error: ${errorMsg}`);
+      }
+    }
+    return data;
+  }
+  /**
+   * Parse masterchain info from response.
+   * Validates the response structure and extracts seqno.
+   */
+  parseMasterchainInfo(data) {
+    const info = this.parseResponse(data);
+    if (!info || typeof info !== "object") {
+      throw new Error("Invalid response structure");
+    }
+    const infoObj = info;
+    const seqno = infoObj.last?.seqno;
+    if (seqno === void 0 || seqno === null || seqno <= 0 || !Number.isInteger(seqno)) {
+      throw new Error(`Invalid seqno: ${seqno} (must be positive integer)`);
+    }
+    return info;
+  }
+  /**
+   * Validate provider configuration.
+   * Checks if required API keys are present, etc.
+   */
+  validateConfig() {
+    return { valid: true };
+  }
+  /**
+   * Get the normalized endpoint for this provider.
+   */
+  getNormalizedEndpoint() {
+    return this.normalizeEndpoint(this.provider.endpointV2);
+  }
+  /**
+   * Check if this provider requires an API key.
+   */
+  requiresApiKey() {
+    return false;
+  }
+  /**
+   * Check if API key is present (if required).
+   */
+  hasApiKey() {
+    return !!this.provider.apiKey;
+  }
+};
+
+// src/providers/chainstack.ts
+var ChainstackProvider = class extends BaseProvider {
+  constructor(provider) {
+    super(provider);
+  }
+  normalizeEndpoint(endpoint) {
+    let normalized = endpoint.trim();
+    if (normalized.endsWith("/")) {
+      normalized = normalized.slice(0, -1);
+    }
+    if (normalized.toLowerCase().endsWith("/jsonrpc")) {
+      return normalized;
+    }
+    if (normalized.endsWith("/api/v2")) {
       return normalized + "/jsonRPC";
     }
+    if (normalized.endsWith("/api/v3")) {
+      return normalized.replace("/api/v3", "/api/v2/jsonRPC");
+    }
+    return normalized;
   }
-  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");
+  buildHeaders() {
+    return {
+      "Content-Type": "application/json"
+    };
+  }
+  validateConfig() {
+    if (this.provider.endpointV2.includes("{key}")) {
+      return {
+        valid: false,
+        error: "Chainstack API key not resolved in endpoint URL"
+      };
+    }
+    return { valid: true };
+  }
+};
+
+// src/providers/tatum.ts
+var TatumProvider = class extends BaseProvider {
+  constructor(provider) {
+    super(provider);
+  }
+  normalizeEndpoint(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";
         }
-        return baseUrl.replace(/\/?$/, "/public");
+        if (!url.pathname.toLowerCase().endsWith("/jsonrpc")) {
+          return normalized + "/jsonRPC";
+        }
+      } catch {
+        return normalized + "/jsonRPC";
       }
-      if (url.pathname === "/rpc" || url.pathname === "/public") {
+    }
+    return normalized;
+  }
+  buildHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.provider.apiKey) {
+      headers["x-api-key"] = this.provider.apiKey;
+    }
+    return headers;
+  }
+  requiresApiKey() {
+    return true;
+  }
+  validateConfig() {
+    if (!this.provider.apiKey) {
+      return {
+        valid: false,
+        error: "Tatum provider requires API key (set TATUM_API_KEY_TESTNET or TATUM_API_KEY_MAINNET)"
+      };
+    }
+    return { valid: true };
+  }
+};
+
+// src/providers/onfinality.ts
+var OnFinalityProvider = class extends BaseProvider {
+  constructor(provider) {
+    super(provider);
+  }
+  normalizeEndpoint(endpoint) {
+    let normalized = endpoint.trim();
+    if (normalized.endsWith("/")) {
+      normalized = normalized.slice(0, -1);
+    }
+    if (normalized.includes("onfinality.io")) {
+      try {
+        const url = new URL(normalized);
+        const baseUrl = normalized.split("?")[0];
+        if (!url.pathname || url.pathname === "/") {
+          if (this.provider.apiKey) {
+            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];
       }
-      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];
     }
+    return normalized;
   }
-  if (normalized.endsWith("/api/v2")) {
-    return normalized + "/jsonRPC";
+  buildHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.provider.apiKey) {
+      headers["apikey"] = this.provider.apiKey;
+    }
+    return headers;
   }
-  if (normalized.endsWith("/api/v3")) {
-    return normalized.replace("/api/v3", "/api/v2/jsonRPC");
+  parseResponse(data) {
+    if (typeof data === "string") {
+      if (data.includes("Backend error") || data.includes("backend error")) {
+        throw new Error(`OnFinality backend error: ${data}`);
+      }
+    }
+    return super.parseResponse(data);
   }
-  if (normalized.includes("quiknode.pro") || normalized.includes("getblock.io")) {
-    try {
-      const url = new URL(normalized);
-      if (!url.pathname || url.pathname === "/") {
+};
+
+// src/providers/quicknode.ts
+var QuickNodeProvider = class extends BaseProvider {
+  constructor(provider) {
+    super(provider);
+  }
+  normalizeEndpoint(endpoint) {
+    let normalized = endpoint.trim();
+    if (normalized.endsWith("/")) {
+      normalized = normalized.slice(0, -1);
+    }
+    if (normalized.toLowerCase().endsWith("/jsonrpc")) {
+      return normalized;
+    }
+    if (normalized.includes("quiknode.pro")) {
+      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 (!url.pathname.toLowerCase().endsWith("/jsonrpc")) {
+    }
+    return normalized;
+  }
+  buildHeaders() {
+    return {
+      "Content-Type": "application/json"
+    };
+  }
+  validateConfig() {
+    if (this.provider.endpointV2.includes("{key}")) {
+      return {
+        valid: false,
+        error: "QuickNode API key not resolved in endpoint URL"
+      };
+    }
+    return { valid: true };
+  }
+};
+
+// src/providers/getblock.ts
+var GetBlockProvider = class extends BaseProvider {
+  constructor(provider) {
+    super(provider);
+  }
+  normalizeEndpoint(endpoint) {
+    let normalized = endpoint.trim();
+    if (normalized.endsWith("/")) {
+      normalized = normalized.slice(0, -1);
+    }
+    if (normalized.toLowerCase().endsWith("/jsonrpc")) {
+      return normalized;
+    }
+    if (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";
       }
-    } catch {
-      return normalized + "/jsonRPC";
     }
+    return normalized;
   }
-  try {
-    const url = new URL(normalized);
-    if (!url.pathname || url.pathname === "/") {
-      return normalized + "/jsonRPC";
+  buildHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.provider.apiKey) {
+      headers["x-api-key"] = this.provider.apiKey;
     }
-  } catch {
-  }
-  return normalized;
-}
-function toV2Base(endpoint) {
-  let normalized = endpoint.trim();
-  if (normalized.endsWith("/")) {
-    normalized = normalized.slice(0, -1);
+    return headers;
   }
-  if (normalized.toLowerCase().endsWith("/jsonrpc")) {
-    normalized = normalized.slice(0, -8);
+  requiresApiKey() {
+    return true;
   }
-  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);
+  validateConfig() {
+    if (!this.provider.apiKey) {
+      return {
+        valid: false,
+        error: "GetBlock provider requires API key"
+      };
     }
+    return { valid: 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;
+};
+
+// src/providers/toncenter.ts
+var TonCenterProvider = class extends BaseProvider {
+  constructor(provider) {
+    super(provider);
   }
-}
-function isChainstackUrl(url) {
-  try {
-    const parsed = new URL(url.trim());
-    return parsed.hostname.includes("chainstack.com");
-  } catch {
-    return false;
+  normalizeEndpoint(endpoint) {
+    let normalized = endpoint.trim();
+    if (normalized.endsWith("/")) {
+      normalized = normalized.slice(0, -1);
+    }
+    if (normalized.toLowerCase().endsWith("/jsonrpc")) {
+      return normalized;
+    }
+    if (normalized.endsWith("/api/v2")) {
+      return normalized + "/jsonRPC";
+    }
+    if (normalized.endsWith("/api/v3")) {
+      return normalized.replace("/api/v3", "/api/v2/jsonRPC");
+    }
+    return normalized;
   }
-}
-function isQuickNodeUrl(url) {
-  try {
-    const parsed = new URL(url.trim());
-    return parsed.hostname.includes("quiknode.pro");
-  } catch {
-    return false;
+  buildHeaders() {
+    return {
+      "Content-Type": "application/json"
+    };
   }
-}
-function isTonCenterUrl(url) {
-  try {
-    const parsed = new URL(url.trim());
-    return parsed.hostname.includes("toncenter.com");
-  } catch {
+  // TON Center API key is optional (1 RPS without key, 10 RPS with key)
+  requiresApiKey() {
     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;
+};
+
+// src/providers/orbs.ts
+var OrbsProvider = class extends BaseProvider {
+  constructor(provider) {
+    super(provider);
   }
-}
-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";
+  normalizeEndpoint(endpoint) {
+    let normalized = endpoint.trim();
+    if (normalized.endsWith("/")) {
+      normalized = normalized.slice(0, -1);
+    }
+    if (normalized.endsWith("/api/v2")) {
+      return normalized;
+    }
+    return normalized;
+  }
+  buildHeaders() {
+    return {
+      "Content-Type": "application/json"
+    };
   }
-  if (lower.includes("mainnet") || lower.includes("main") || // TonCenter mainnet doesn't have 'mainnet' in URL
-  lower.includes("toncenter.com") && !lower.includes("testnet")) {
-    return "mainnet";
+  /**
+   * Get dynamic endpoint from Orbs TON Access.
+   * This should be called before making requests.
+   */
+  async getDynamicEndpoint() {
+    if (!this.provider.isDynamic) {
+      return this.normalizeEndpoint(this.provider.endpointV2);
+    }
+    try {
+      const { getHttpEndpoint } = await import('@orbs-network/ton-access');
+      const endpoint = await getHttpEndpoint({ network: this.provider.network });
+      return this.normalizeEndpoint(endpoint);
+    } catch (error) {
+      return this.normalizeEndpoint(this.provider.endpointV2);
+    }
   }
-  return null;
-}
-function isValidHttpUrl(str) {
-  try {
-    const url = new URL(str);
-    return url.protocol === "http:" || url.protocol === "https:";
-  } catch {
+  requiresApiKey() {
     return false;
   }
-}
-function isValidWsUrl(str) {
-  try {
-    const url = new URL(str);
-    return url.protocol === "ws:" || url.protocol === "wss:";
-  } catch {
-    return false;
+};
+
+// src/providers/index.ts
+var GenericProvider = class extends BaseProvider {
+  normalizeEndpoint(endpoint) {
+    let normalized = endpoint.trim();
+    if (normalized.endsWith("/")) {
+      normalized = normalized.slice(0, -1);
+    }
+    if (normalized.toLowerCase().endsWith("/jsonrpc")) {
+      return normalized;
+    }
+    try {
+      const url = new URL(normalized);
+      if (!url.pathname || url.pathname === "/") {
+        return normalized + "/jsonRPC";
+      }
+    } catch {
+    }
+    return normalized;
+  }
+  buildHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.provider.apiKey) {
+      headers["x-api-key"] = this.provider.apiKey;
+    }
+    return headers;
+  }
+};
+function createProvider(provider) {
+  switch (provider.type) {
+    case "chainstack":
+      return new ChainstackProvider(provider);
+    case "tatum":
+      return new TatumProvider(provider);
+    case "onfinality":
+      return new OnFinalityProvider(provider);
+    case "quicknode":
+      return new QuickNodeProvider(provider);
+    case "getblock":
+      return new GetBlockProvider(provider);
+    case "toncenter":
+      return new TonCenterProvider(provider);
+    case "orbs":
+      return new OrbsProvider(provider);
+    case "custom":
+      return new GenericProvider(provider);
+    default:
+      return new GenericProvider(provider);
   }
 }
 
@@ -793,21 +1071,25 @@ var HealthChecker = class {
       if (!endpoint) {
         throw new Error("No valid endpoint available");
       }
-      if (provider.type === "tatum" && !provider.apiKey) {
-        throw new Error("Tatum provider requires API key (set TATUM_API_KEY_TESTNET or TATUM_API_KEY_MAINNET)");
+      const providerImpl = createProvider(provider);
+      const validation = providerImpl.validateConfig();
+      if (!validation.valid) {
+        throw new Error(validation.error || "Provider configuration invalid");
       }
-      let normalizedEndpoint = this.normalizeEndpointForProvider(provider, endpoint);
+      const normalizedEndpoint = providerImpl.normalizeEndpoint(endpoint);
       if (provider.type === "onfinality") {
         this.logger.debug(`OnFinality endpoint: ${endpoint} -> ${normalizedEndpoint}, API key: ${provider.apiKey ? "set" : "not set"}`);
       }
       let info;
       try {
-        info = await this.callGetMasterchainInfo(normalizedEndpoint, provider);
+        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 publicEndpoint = normalizedEndpoint.replace("/rpc", "/public");
-          info = await this.callGetMasterchainInfo(publicEndpoint, { ...provider, apiKey: void 0 });
+          const publicProvider = { ...provider, apiKey: void 0 };
+          const publicProviderImpl = createProvider(publicProvider);
+          info = await this.callGetMasterchainInfo(publicEndpoint, publicProvider, publicProviderImpl);
         } else {
           throw error;
         }
@@ -953,14 +1235,17 @@ var HealthChecker = class {
   }
   /**
    * Mark a provider as degraded (e.g., on 429 error)
+   * 
+   * Providers marked as degraded have failed health checks (e.g., rate limit errors)
+   * and should not be selected. The system will failover to the next available provider.
    */
   markDegraded(providerId, network, error) {
     const key = this.getResultKey(providerId, network);
     const existing = this.results.get(key);
     const result = existing ? {
       ...existing,
-      success: true,
-      // Degraded providers are still usable, just slower/rate-limited
+      success: false,
+      // Degraded providers with errors should not be selected
       status: "degraded",
       error: error || "Marked as degraded",
       lastTested: /* @__PURE__ */ new Date(),
@@ -968,8 +1253,8 @@ var HealthChecker = class {
     } : {
       id: providerId,
       network,
-      success: true,
-      // Degraded providers are still usable
+      success: false,
+      // Degraded providers with errors should not be selected
       status: "degraded",
       latencyMs: null,
       seqno: null,
@@ -1032,44 +1317,19 @@ var HealthChecker = class {
     }
     return provider.endpointV2 || provider.endpointV3 || null;
   }
-  /**
-   * Normalize endpoint for provider-specific requirements
-   * 
-   * Note: normalizeV2Endpoint now handles all provider-specific cases correctly,
-   * including Tatum (/jsonRPC), OnFinality (/public or /rpc), QuickNode, and GetBlock.
-   */
-  normalizeEndpointForProvider(provider, endpoint) {
-    if (provider.type === "tatum" && endpoint.includes("api.tatum.io/v3/blockchain/node")) {
-      const network = provider.network === "testnet" ? "testnet" : "mainnet";
-      endpoint = `https://ton-${network}.gateway.tatum.io`;
-    }
-    return normalizeV2Endpoint(endpoint);
-  }
   /**
    * Call getMasterchainInfo API with provider-specific handling
    */
-  async callGetMasterchainInfo(endpoint, provider) {
+  async callGetMasterchainInfo(endpoint, provider, providerImpl) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
-    const headers = {
-      "Content-Type": "application/json"
-    };
-    if (provider.type === "tatum" && provider.apiKey) {
-      headers["x-api-key"] = provider.apiKey;
-    }
-    if (provider.type === "onfinality" && provider.apiKey) {
-      headers["apikey"] = provider.apiKey;
-    }
+    const headers = providerImpl.buildHeaders();
+    const requestBody = providerImpl.buildRequest("getMasterchainInfo", {});
     try {
       const response = await fetch(endpoint, {
         method: "POST",
         headers,
-        body: JSON.stringify({
-          id: "1",
-          jsonrpc: "2.0",
-          method: "getMasterchainInfo",
-          params: {}
-        }),
+        body: JSON.stringify(requestBody),
         signal: controller.signal
       });
       clearTimeout(timeoutId);
@@ -1095,40 +1355,7 @@ var HealthChecker = class {
         }
       }
       data = await response.json();
-      let info;
-      if (data && typeof data === "object") {
-        const dataObj = data;
-        if ("ok" in dataObj) {
-          if (!dataObj.ok) {
-            const error = dataObj.error;
-            throw new Error(error || "API returned ok=false");
-          }
-          const result = dataObj.result;
-          info = result || dataObj;
-        } else if ("result" in dataObj) {
-          info = dataObj.result;
-        } else if ("last" in dataObj || "@type" in dataObj) {
-          info = dataObj;
-        } else if ("error" in dataObj) {
-          const errorObj = dataObj.error;
-          const errorMsg = typeof errorObj === "string" ? errorObj : errorObj?.message || errorObj?.code || String(errorObj);
-          throw new Error(`API error: ${errorMsg}`);
-        } else {
-          throw new Error(`Unknown response format from ${provider.type}`);
-        }
-      } else {
-        throw new Error(`Invalid response type: ${typeof data}`);
-      }
-      if (!info || typeof info !== "object") {
-        this.logger.debug(`Invalid response structure from ${provider.type}: ${JSON.stringify(data)}`);
-        throw new Error("Invalid response structure");
-      }
-      const infoObj = info;
-      const seqno = infoObj.last?.seqno;
-      if (seqno === void 0 || seqno === null || seqno <= 0 || !Number.isInteger(seqno)) {
-        this.logger.debug(`Invalid seqno from ${provider.type}:`, { seqno, info });
-        throw new Error(`Invalid seqno: ${seqno} (must be positive integer)`);
-      }
+      const info = providerImpl.parseMasterchainInfo(data);
       return info;
     } catch (error) {
       clearTimeout(timeoutId);
@@ -1988,6 +2215,193 @@ 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";
+    }
+  }
+  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;
+  }
+}
+
 // src/core/manager.ts
 var consoleLogger5 = {
   debug: (msg, data) => console.debug(`[ProviderManager] ${msg}`, data || ""),
@@ -2186,17 +2600,20 @@ var _ProviderManager = class _ProviderManager {
       this.options.logger.warn("No providers available, using fallback");
       return this.getFallbackEndpoint();
     }
-    this.selector.getActiveProviderId(this.network) || this.selector.getBestProvider(this.network);
+    const activeProviderId = this.selector.getActiveProviderId(this.network);
+    if (!activeProviderId) {
+      this.selector.getBestProvider(this.network);
+    }
     if (provider.isDynamic && provider.type === "orbs") {
       try {
         const { getHttpEndpoint } = await import('@orbs-network/ton-access');
         const endpoint = await getHttpEndpoint({ network: this.network });
-        return normalizeV2Endpoint(endpoint);
+        return normalizeV2Endpoint(endpoint, provider);
       } catch (error) {
         this.options.logger.warn(`Failed to get Orbs endpoint: ${error.message}`);
       }
     }
-    return normalizeV2Endpoint(provider.endpointV2);
+    return normalizeV2Endpoint(provider.endpointV2, provider);
   }
   /**
    * Get endpoint with rate limiting
@@ -2219,11 +2636,11 @@ var _ProviderManager = class _ProviderManager {
       this.options.logger.warn(`Rate limit timeout for ${provider.id}`);
       const next = this.selector.getNextProvider(this.network, [provider.id]);
       if (next) {
-        return normalizeV2Endpoint(next.endpointV2);
+        return normalizeV2Endpoint(next.endpointV2, next);
       }
       return this.getFallbackEndpoint();
     }
-    return normalizeV2Endpoint(provider.endpointV2);
+    return normalizeV2Endpoint(provider.endpointV2, provider);
   }
   /**
    * Get current active provider
@@ -3083,18 +3500,24 @@ async function createBrowserAdapterForNetwork(network, configPath, logger) {
 }
 
 exports.ApiVersionSchema = ApiVersionSchema;
+exports.BaseProvider = BaseProvider;
 exports.BrowserAdapter = BrowserAdapter;
 exports.CHAINSTACK_RATE_LIMIT = CHAINSTACK_RATE_LIMIT;
+exports.ChainstackProvider = ChainstackProvider;
 exports.ConfigError = ConfigError;
 exports.DEFAULT_CONTRACT_TIMEOUT_MS = DEFAULT_CONTRACT_TIMEOUT_MS;
 exports.DEFAULT_HEALTH_CHECK_TIMEOUT_MS = DEFAULT_HEALTH_CHECK_TIMEOUT_MS;
 exports.DEFAULT_PROVIDERS = DEFAULT_PROVIDERS;
 exports.DEFAULT_PROVIDER_TIMEOUT_MS = DEFAULT_PROVIDER_TIMEOUT_MS;
 exports.DEFAULT_RATE_LIMIT = DEFAULT_RATE_LIMIT;
+exports.GenericProvider = GenericProvider;
+exports.GetBlockProvider = GetBlockProvider;
 exports.HealthChecker = HealthChecker;
 exports.NetworkSchema = NetworkSchema;
 exports.NodeAdapter = NodeAdapter;
 exports.ORBS_RATE_LIMIT = ORBS_RATE_LIMIT;
+exports.OnFinalityProvider = OnFinalityProvider;
+exports.OrbsProvider = OrbsProvider;
 exports.ProviderConfigSchema = ProviderConfigSchema;
 exports.ProviderError = ProviderError;
 exports.ProviderManager = ProviderManager;
@@ -3102,11 +3525,14 @@ exports.ProviderRegistry = ProviderRegistry;
 exports.ProviderSelector = ProviderSelector;
 exports.ProviderTypeSchema = ProviderTypeSchema;
 exports.QUICKNODE_RATE_LIMIT = QUICKNODE_RATE_LIMIT;
+exports.QuickNodeProvider = QuickNodeProvider;
 exports.RateLimitError = RateLimitError;
 exports.RateLimiterManager = RateLimiterManager;
 exports.RpcConfigSchema = RpcConfigSchema;
+exports.TatumProvider = TatumProvider;
 exports.TimeoutError = TimeoutError;
 exports.TokenBucketRateLimiter = TokenBucketRateLimiter;
+exports.TonCenterProvider = TonCenterProvider;
 exports.buildGetAddressBalanceUrl = buildGetAddressBalanceUrl;
 exports.buildGetAddressInfoUrl = buildGetAddressInfoUrl;
 exports.buildGetAddressStateUrl = buildGetAddressStateUrl;
@@ -3118,6 +3544,7 @@ exports.createDefaultRegistry = createDefaultRegistry;
 exports.createEmptyConfig = createEmptyConfig;
 exports.createHealthChecker = createHealthChecker;
 exports.createNodeAdapter = createNodeAdapter;
+exports.createProvider = createProvider;
 exports.createProviderManager = createProviderManager;
 exports.createRateLimiter = createRateLimiter;
 exports.createRateLimiterManager = createRateLimiterManager;