ton-provider-system 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -329,30 +329,28 @@ var DEFAULT_PROVIDERS = {
     },
     rps: 1,
     // Without API key
-    // 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,
+    // Primary testnet provider: Toncenter serves the full v2 surface incl.
+    // getTransactions (curl-proven 200). Selection is score-based and priority
+    // is the lever (lower = better), so priority 1 keeps it ahead of Tatum.
+    priority: 1,
     enabled: true,
     description: "Official TON Center public endpoint"
   },
-  orbs_testnet: {
-    name: "Orbs TON Access Testnet",
-    type: "orbs",
+  tatum_testnet: {
+    name: "Tatum Testnet",
+    type: "tatum",
     network: "testnet",
     endpoints: {
-      v2: "https://ton-testnet.orbs.network/api/v2"
+      v2: "https://ton-testnet.gateway.tatum.io"
     },
-    rps: 10,
-    // Demoted below toncenter_testnet (priority 10): Orbs is the decentralised
-    // fallback for non-transaction (get-method/state) testnet reads only.
-    priority: 90,
+    apiKeyEnvVar: "TATUM_API_KEY_TESTNET",
+    rps: 3,
+    // Secondary testnet provider (priority 2): also serves the full workload
+    // (getTransactions/sendBoc 200), so it backs up Toncenter on failover.
+    priority: 2,
     enabled: true,
-    isDynamic: true,
-    description: "Decentralized gateway - no API key needed"
+    browserCompatible: false,
+    description: "Tatum testnet gateway - requires TATUM_API_KEY_TESTNET"
   },
   toncenter_mainnet: {
     name: "TON Center Mainnet",
@@ -386,12 +384,12 @@ function createDefaultConfig() {
     version: "1.0",
     providers: { ...DEFAULT_PROVIDERS },
     defaults: {
-      // 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
+      // Testnet: only the transaction-capable providers — Toncenter first,
+      // Tatum as failover. This default order governs the no-healthy-providers
+      // fallback path; the primary, score-based selection is driven by priority
+      // (see toncenter_testnet/tatum_testnet above). Mainnet order is left
       // unchanged (Orbs stays primary there — no regression).
-      testnet: ["toncenter_testnet", "orbs_testnet"],
+      testnet: ["toncenter_testnet", "tatum_testnet"],
       mainnet: ["orbs_mainnet", "toncenter_mainnet"]
     }
   };
@@ -3069,6 +3067,22 @@ var _ProviderManager = class _ProviderManager {
     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
    */
@@ -3457,30 +3471,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