ton-provider-system 0.2.4 → 0.3.1

package/dist/index.cjs

@@ -324,7 +324,13 @@ var DEFAULT_PROVIDERS = {
     },
     rps: 1,
     // Without API key
-    priority: 100,
+    // Preferred on testnet: Toncenter serves the full v2 surface incl.
+    // getTransactions (curl-proven 200). Orbs only proxies liteserver
+    // get-methods/state and 403s on getTransactions, so it must NOT be the
+    // primary testnet provider (it stays a fallback for get-method reads).
+    // Selection is score-based and priority is the lever (lower = better),
+    // so this gives Toncenter the testnet edge over Orbs (priority 90).
+    priority: 10,
     enabled: true,
     description: "Official TON Center public endpoint"
   },
@@ -336,7 +342,9 @@ var DEFAULT_PROVIDERS = {
       v2: "https://ton-testnet.orbs.network/api/v2"
     },
     rps: 10,
-    priority: 50,
+    // Demoted below toncenter_testnet (priority 10): Orbs is the decentralised
+    // fallback for non-transaction (get-method/state) testnet reads only.
+    priority: 90,
     enabled: true,
     isDynamic: true,
     description: "Decentralized gateway - no API key needed"
@@ -373,7 +381,12 @@ function createDefaultConfig() {
     version: "1.0",
     providers: { ...DEFAULT_PROVIDERS },
     defaults: {
-      testnet: ["orbs_testnet", "toncenter_testnet"],
+      // Testnet: Toncenter first (transactions-capable), Orbs as fallback.
+      // This default order only governs the no-healthy-providers fallback
+      // path; the primary, score-based selection is driven by priority
+      // (see toncenter_testnet/orbs_testnet above). Mainnet order is left
+      // unchanged (Orbs stays primary there — no regression).
+      testnet: ["toncenter_testnet", "orbs_testnet"],
       mainnet: ["orbs_mainnet", "toncenter_mainnet"]
     }
   };
@@ -1038,6 +1051,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 || ""),
@@ -1054,6 +1299,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;
@@ -1099,22 +1346,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;
         }
       }
@@ -1129,7 +1390,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";
@@ -1273,6 +1535,7 @@ var HealthChecker = class {
   clearResults() {
     this.results.clear();
     this.highestSeqno.clear();
+    this.seqnoSamples.clear();
   }
   /**
    * Mark a provider as degraded (e.g., on 429 error)
@@ -1342,6 +1605,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)
    */
@@ -2183,7 +2471,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
@@ -2327,193 +2615,6 @@ 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 || ""),
@@ -3113,7 +3214,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;
   }
   /**
@@ -3735,6 +3836,7 @@ exports.mergeWithDefaults = mergeWithDefaults;
 exports.normalizeV2Endpoint = normalizeV2Endpoint;
 exports.parseProviderConfig = parseProviderConfig;
 exports.parseRpcConfig = parseRpcConfig;
+exports.redactUrl = redactUrl;
 exports.resetNodeAdapter = resetNodeAdapter;
 exports.resolveAllProviders = resolveAllProviders;
 exports.resolveEndpoints = resolveEndpoints;