ton-provider-system 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -72,6 +72,7 @@ var ProviderConfigSchema = zod.z.object({
   enabled: zod.z.boolean().default(true),
   isDynamic: zod.z.boolean().optional().default(false),
   browserCompatible: zod.z.boolean().optional(),
+  servesGetTransactions: zod.z.boolean().optional(),
   description: zod.z.string().optional()
 });
 var NetworkDefaultsSchema = zod.z.object({
@@ -220,7 +221,10 @@ function resolveProvider(id, config) {
     rps: config.rps,
     priority: config.priority,
     isDynamic: config.isDynamic || false,
-    browserCompatible: config.browserCompatible !== void 0 ? config.browserCompatible : true
+    browserCompatible: config.browserCompatible !== void 0 ? config.browserCompatible : true,
+    // Default true: a provider is assumed to serve getTransactions unless the
+    // config explicitly opts out (e.g. Chainstack/Orbs testnet liteserver proxies).
+    servesGetTransactions: config.servesGetTransactions !== false
   };
 }
 function resolveAllProviders(config) {
@@ -2554,8 +2558,10 @@ var ProviderSelector = class {
       rps: 10,
       priority: 0,
       isDynamic: false,
-      browserCompatible: true
+      browserCompatible: true,
       // Custom endpoints are assumed compatible
+      servesGetTransactions: true
+      // Custom endpoints are assumed fully capable
     };
   }
   /**
@@ -2886,26 +2892,39 @@ var _ProviderManager = class _ProviderManager {
   // ========================================================================
   /**
    * Report a successful request
+   *
+   * @param providerId - Optionally attribute the success to a SPECIFIC provider
+   *   (used by callers that drive their own candidate list, e.g.
+   *   NodeAdapter.getTransactions, where the provider used is not necessarily the
+   *   selector's current best). Defaults to the current best provider.
    */
-  reportSuccess() {
+  reportSuccess(providerId) {
     if (!this.initialized || !this.network) return;
-    const provider = this.selector.getBestProvider(this.network);
-    if (provider) {
-      this.rateLimiter.reportSuccess(provider.id);
+    const id = providerId ?? this.selector.getBestProvider(this.network)?.id;
+    if (id) {
+      this.rateLimiter.reportSuccess(id);
     }
   }
   /**
    * Report an error (triggers provider switch if needed)
+   *
+   * @param providerId - Optionally attribute the error to a SPECIFIC provider
+   *   (used by callers that drive their own candidate list, e.g.
+   *   NodeAdapter.getTransactions). Defaults to the current active/best provider.
    */
-  reportError(error) {
+  reportError(error, providerId) {
     if (!this.initialized || !this.network) return;
-    const activeProviderId = this.selector.getActiveProviderId(this.network);
     let provider = null;
-    if (activeProviderId) {
-      provider = this.registry.getProvider(activeProviderId) || null;
-    }
-    if (!provider) {
-      provider = this.selector.getBestProvider(this.network);
+    if (providerId) {
+      provider = this.registry.getProvider(providerId) || null;
+    } else {
+      const activeProviderId = this.selector.getActiveProviderId(this.network);
+      if (activeProviderId) {
+        provider = this.registry.getProvider(activeProviderId) || null;
+      }
+      if (!provider) {
+        provider = this.selector.getBestProvider(this.network);
+      }
     }
     if (!provider) {
       this.options.logger.warn(`Cannot report error: no provider available for ${this.network}`);
@@ -3035,6 +3054,21 @@ var _ProviderManager = class _ProviderManager {
     }
     return providers;
   }
+  /**
+   * Get transaction-capable providers for the current network, in selector
+   * score order (best first).
+   *
+   * Read-only: enumerates the score-ordered available providers and excludes any
+   * flagged `servesGetTransactions: false` (Chainstack/Orbs testnet liteserver
+   * proxies, which 403 on v2 getTransactions). Used by
+   * NodeAdapter.getTransactions to build its candidate set WITHOUT poisoning the
+   * incapable providers' global health — so the get-method path keeps using them.
+   * Returns [] when no capable provider is currently selectable.
+   */
+  getTransactionCapableProviders() {
+    if (!this.initialized || !this.network) return [];
+    return this.selector.getAvailableProviders(this.network).filter((p) => p.servesGetTransactions !== false);
+  }
   /**
    * Get provider health results for current network
    */
@@ -3253,24 +3287,27 @@ var NodeAdapter = class {
   // Failover-aware high-level reads
   // ========================================================================
   /**
-   * Get account transactions with provider failover.
+   * Get account transactions with capability-aware provider failover.
    *
-   * Unlike `getClient().getTransactions(...)`, this loops across the network's
-   * providers: a provider that passes the `getMasterchainInfo` health probe but
-   * fails the v2 `getTransactions` call (e.g. Chainstack/Orbs testnet, which
-   * 403 on transaction reads) is no longer able to permanently break this path.
+   * Unlike `getClient().getTransactions(...)`, this builds a candidate set of the
+   * network's *transaction-capable* providers (score-ordered, best first) and
+   * loops over THAT set. Providers known not to serve the v2 `getTransactions`
+   * shape — flagged `servesGetTransactions: false` in config (Chainstack/Orbs
+   * testnet, which pass the `getMasterchainInfo` health probe but 403 on
+   * transaction reads) — are excluded UP FRONT. They are never called and never
+   * `reportError`-ed here, so their global health stays intact and the fast
+   * get-method path keeps using them (a wasted 403 would otherwise evict them).
    *
-   * Semantics:
-   *  1. Pick the current best provider (the selector's scored top).
-   *  2. Acquire a rate-limit token for THAT provider, bind a short-lived
+   * Semantics (per capable candidate, in score order):
+   *  1. Acquire a rate-limit token for THAT provider, bind a short-lived
    *     `TonClient` to its endpoint, and call `getTransactions`.
-   *  3. On success → `reportSuccess()` and return.
-   *  4. On error → `reportError()` (marks the provider success:false, scoring 0
-   *     within its cooldown, and clears the selection cache) so the next pick is
-   *     a DIFFERENT, still-eligible provider, then retry.
-   *  5. When every candidate has been tried, re-throw the last error so the
-   *     caller's retry/dead-letter logic still triggers — but only after a
-   *     genuine failover across all providers.
+   *  2. On success → `reportSuccess(provider.id)` and return.
+   *  3. On a GENUINE error → `reportError(error, provider.id)` (marks THAT
+   *     provider success:false + clears the selection cache) and try the next
+   *     capable candidate.
+   *  4. When every capable candidate has been tried, re-throw the last error so
+   *     the caller's retry/dead-letter logic still triggers.
+   *  5. If there is NO capable provider at all, throw a clear error.
    *
    * Returns the same `Transaction[]` `TonClient.getTransactions` returns, so a
    * consumer can swap `client.getTransactions(addr, opts)` for
@@ -3283,28 +3320,27 @@ var NodeAdapter = class {
     }
     const addr = typeof address === "string" ? core.Address.parse(address) : address;
     const reqOpts = { limit: opts.limit ?? 20, ...opts };
-    const maxAttempts = Math.max(1, this.manager.getProviders().length);
+    const candidates = this.manager.getTransactionCapableProviders();
+    if (candidates.length === 0) {
+      throw new Error(
+        `getTransactions: no transaction-capable provider for ${network}`
+      );
+    }
     const rateLimiter = this.manager.getRateLimiter();
-    const tried = /* @__PURE__ */ new Set();
     let lastError;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-      const provider = this.manager.getActiveProvider();
-      if (!provider) break;
-      if (tried.has(provider.id)) break;
-      tried.add(provider.id);
+    for (const provider of candidates) {
       if (rateLimiter) {
         await rateLimiter.acquire(provider.id, timeoutMs);
       }
-      const endpoint = await this.manager.getEndpoint();
-      const apiKey = this.manager.getActiveProvider()?.apiKey;
-      const client = new ton.TonClient({ endpoint, apiKey });
+      const endpoint = normalizeV2Endpoint(provider.endpointV2, provider);
+      const client = new ton.TonClient({ endpoint, apiKey: provider.apiKey });
       try {
         const result = await withTimeout(
           client.getTransactions(addr, reqOpts),
           timeoutMs,
           `getTransactions(${provider.id})`
         );
-        this.manager.reportSuccess();
+        this.manager.reportSuccess(provider.id);
         return result;
       } catch (error) {
         lastError = error;
@@ -3312,10 +3348,10 @@ var NodeAdapter = class {
           `getTransactions failed on ${provider.id}, failing over`,
           { error: error?.message || String(error) }
         );
-        this.manager.reportError(error);
+        this.manager.reportError(error, provider.id);
       }
     }
-    throw lastError || new Error(`getTransactions: no available provider for ${network}`);
+    throw lastError || new Error(`getTransactions: all transaction-capable providers failed for ${network}`);
   }
   // ========================================================================
   // Direct REST API Methods