ton-provider-system 0.3.0 → 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
@@ -324,7 +325,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 +343,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 +382,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"]
     }
   };
@@ -3236,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
   // ========================================================================
   /**