ton-provider-system 0.3.1 → 0.4.0

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var zod = require('zod');
 var ton = require('@ton/ton');
+var core = require('@ton/core');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 // src/types.ts
@@ -3249,6 +3250,74 @@ var NodeAdapter = class {
     };
   }
   // ========================================================================
+  // Failover-aware high-level reads
+  // ========================================================================
+  /**
+   * Get account transactions with 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.
+   *
+   * 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
+   *     `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.
+   *
+   * Returns the same `Transaction[]` `TonClient.getTransactions` returns, so a
+   * consumer can swap `client.getTransactions(addr, opts)` for
+   * `adapter.getTransactions(addr, opts)` with no shape change.
+   */
+  async getTransactions(address, opts = {}, timeoutMs = 15e3) {
+    const network = this.manager.getNetwork();
+    if (!network) {
+      throw new Error("ProviderManager not initialized");
+    }
+    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 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);
+      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 });
+      try {
+        const result = await withTimeout(
+          client.getTransactions(addr, reqOpts),
+          timeoutMs,
+          `getTransactions(${provider.id})`
+        );
+        this.manager.reportSuccess();
+        return result;
+      } catch (error) {
+        lastError = error;
+        this.logger.warn(
+          `getTransactions failed on ${provider.id}, failing over`,
+          { error: error?.message || String(error) }
+        );
+        this.manager.reportError(error);
+      }
+    }
+    throw lastError || new Error(`getTransactions: no available provider for ${network}`);
+  }
+  // ========================================================================
   // Direct REST API Methods
   // ========================================================================
   /**