ton-provider-system 0.4.0 → 0.6.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,37 @@ 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 broadcast-capable providers for the current network, in selector score
+   * order (best first).
+   *
+   * Unlike getTransactionCapableProviders, this applies NO capability filter:
+   * `sendBoc` (forwarding an already-signed external message) works on EVERY
+   * provider type — including the liteserver-proxy providers (Chainstack/Orbs)
+   * that 403 only on the v2 `getTransactions` shape. The list is the plain
+   * score-ordered available set, so a broadcast walks best→worst and a provider
+   * that 429s/5xxs on sendBoc is skipped in favour of the next one.
+   * Returns [] when no provider is currently selectable.
+   */
+  getBroadcastCapableProviders() {
+    if (!this.initialized || !this.network) return [];
+    return this.selector.getAvailableProviders(this.network);
+  }
   /**
    * Get provider health results for current network
    */
@@ -3253,24 +3303,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 +3336,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 +3364,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
@@ -3421,30 +3473,106 @@ var NodeAdapter = class {
     }
   }
   /**
-   * Send BOC via REST API
+   * Broadcast an already-signed external message BOC, with provider failover.
+   *
+   * Unlike a single-endpoint `client.sendFile`/raw POST, this walks the network's
+   * score-ordered providers (best first; see ProviderManager.getBroadcastCapableProviders)
+   * and fails over to the next provider when one returns a TRANSIENT failure — a
+   * 429 (rate limit), a 5xx (gateway/server error, e.g. the testnet chainstack
+   * free plan 500ing on sendBoc), a timeout, or a network error. This closes the
+   * broadcast half of the failover story: the getTransactions capability flag only
+   * diverted reads, so a demoted-but-still-reachable provider could still 500 a
+   * broadcast — now the broadcast itself moves on to a healthy provider.
+   *
+   * Safety: re-broadcasting is idempotent at the TON level — the external message
+   * has a deterministic hash, so forwarding the SAME signed BOC to another provider
+   * after a transient failure is safe (the network dedups; a duplicate is a no-op).
+   * A 4xx that means "this BOC is invalid" (400/413/422) is therefore NOT failed
+   * over: it is the payload, not the provider — surfaced immediately, without
+   * poisoning the provider's health or spraying a bad BOC across the fleet.
    */
   async sendBoc(boc, timeoutMs = 3e4) {
-    const endpoint = await this.manager.getEndpoint();
+    const network = this.manager.getNetwork();
+    if (!network) {
+      throw new Error("ProviderManager not initialized");
+    }
+    const bocBase64 = typeof boc === "string" ? boc : boc.toString("base64");
+    const candidates = this.manager.getBroadcastCapableProviders();
+    if (candidates.length === 0) {
+      const endpoint = await this.manager.getEndpoint();
+      try {
+        await this.sendBocToEndpoint(endpoint, bocBase64, timeoutMs);
+        this.manager.reportSuccess();
+      } catch (error) {
+        if (!this.isInvalidPayloadError(error)) {
+          this.manager.reportError(error);
+        }
+        throw error;
+      }
+      return;
+    }
+    const rateLimiter = this.manager.getRateLimiter();
+    let lastError;
+    for (const provider of candidates) {
+      if (rateLimiter) {
+        await rateLimiter.acquire(provider.id, timeoutMs);
+      }
+      const endpoint = normalizeV2Endpoint(provider.endpointV2, provider);
+      try {
+        await this.sendBocToEndpoint(endpoint, bocBase64, timeoutMs);
+        this.manager.reportSuccess(provider.id);
+        return;
+      } catch (error) {
+        if (this.isInvalidPayloadError(error)) {
+          throw error;
+        }
+        lastError = error;
+        this.manager.reportError(error, provider.id);
+        this.logger.warn(
+          `sendBoc failed on ${provider.id}, failing over`,
+          { error: error?.message || String(error) }
+        );
+      }
+    }
+    throw lastError || new Error(`sendBoc: all providers failed for ${network}`);
+  }
+  /**
+   * POST a base64 BOC to one provider's REST `/sendBoc`. Throws on a non-2xx
+   * response with the HTTP `status` attached (so the caller can classify
+   * transient vs invalid-payload), and on an `ok:false` JSON body.
+   */
+  async sendBocToEndpoint(endpoint, bocBase64, timeoutMs) {
     const baseV2 = toV2Base(endpoint);
     const url = `${baseV2}/sendBoc`;
-    const bocBase64 = typeof boc === "string" ? boc : boc.toString("base64");
-    try {
-      const response = await fetchWithTimeout(
-        url,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ boc: bocBase64 })
-        },
-        timeoutMs
+    const response = await fetchWithTimeout(
+      url,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ boc: bocBase64 })
+      },
+      timeoutMs
+    );
+    if (!response.ok) {
+      const err = new Error(
+        `HTTP ${response.status} ${response.statusText} on sendBoc`
       );
-      const json = await response.json();
-      this.unwrapResponse(json);
-      this.manager.reportSuccess();
-    } catch (error) {
-      this.manager.reportError(error);
-      throw error;
+      err.status = response.status;
+      throw err;
     }
+    const json = await response.json();
+    this.unwrapResponse(json);
+  }
+  /**
+   * True only for a 4xx that means the BOC payload itself is invalid (400 Bad
+   * Request, 413 Payload Too Large, 422 Unprocessable) — these must NOT fail over
+   * (the next provider would reject the same BOC identically). Auth/availability
+   * 4xx (401/403/404), 429, 5xx, timeouts and network errors are all transient
+   * for an idempotent broadcast and DO fail over.
+   */
+  isInvalidPayloadError(error) {
+    const status = error?.status;
+    return typeof status === "number" && (status === 400 || status === 413 || status === 422);
   }
   /**
    * Check if contract is deployed