@orbinum/sdk 0.17.0 → 0.18.0

package/dist/index.d.mts

@@ -105,6 +105,18 @@ declare class SubstrateClient {
     private constructor();
     private _dynamicBuilder;
     private _extDecoder;
+    private _inflightTxCount;
+    /**
+     * `true` while any submitted transaction is still waiting for finalization.
+     * Connection managers use this to defer destroying the client — killing the
+     * WS mid-submit rejects the pending tx with "Client destroyed" even though
+     * it may still land on-chain.
+     *
+     * Only covers promise-based submits (`submit`, `submitUnsignedAndWatch`,
+     * `signAndSubmit`); observable-based `submitAndWatch` callers are not tracked.
+     */
+    get hasInflightTx(): boolean;
+    private trackTx;
     /**
      * Connects to the Orbinum node via WebSocket.
      * Throws if the node does not respond within `timeoutMs`.
@@ -285,14 +297,25 @@ declare class EvmClient {
     }): Promise<bigint>;
     /** Returns a transaction receipt by hash, or `null` if the transaction has not been mined yet. */
     getTransactionReceipt(txHash: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Fetches a transaction by hash, or `null` when the node no longer knows it
+     * (never mined and evicted from the pool). Unlike `request`, a `null`
+     * result is a valid answer here, not an error.
+     */
+    getTransactionByHash(txHash: string): Promise<Record<string, unknown> | null>;
     /**
      * Polls `eth_getTransactionReceipt` until the transaction is included in a block.
      *
+     * After `timeoutMs`, the tx-pool is consulted: a tx no longer known to the
+     * node is reported as dropped (safe to retry), while a tx still in the pool
+     * gets an extended grace window (up to 4× `timeoutMs`) before a "still
+     * pending" error — it may confirm later, so callers must NOT blindly retry.
+     *
      * @param txHash - The transaction hash to wait for.
      * @param intervalMs - Polling interval in milliseconds (default: 500).
      * @param timeoutMs - Maximum time to wait in milliseconds (default: 60_000).
      * @returns The transaction receipt once mined.
-     * @throws If the transaction is not mined within `timeoutMs` or if it reverted (`status == 0x0`).
+     * @throws If the transaction dropped, is still pending after the grace window, or reverted (`status == 0x0`).
      */
     waitForReceipt(txHash: string, intervalMs?: number, timeoutMs?: number): Promise<Record<string, unknown>>;
 }
@@ -1776,6 +1799,7 @@ declare class OrbinumClientProvider {
     private _reconnectTimer;
     private _stableTimer;
     private _reconnectAttempt;
+    private _probeFailures;
     private _listeners;
     /** Creates a new provider with the given configuration. Does not connect automatically — call `connect()` to initiate. */
     constructor(config: ClientProviderConfig);
@@ -1806,6 +1830,21 @@ declare class OrbinumClientProvider {
      * On failure: destroys any orphaned client and transitions to `'disconnected'`.
      */
     private attemptConnect;
+    /**
+     * Consecutive failed probes required before the client is torn down. A
+     * single missed probe is routine (throttled background tab, node busy
+     * verifying a ZK proof, transient network blip) — destroying the client on
+     * it rejects every in-flight request with "Client destroyed" even though
+     * the tx may still land on-chain.
+     */
+    private static readonly PROBE_FAILURE_THRESHOLD;
+    /**
+     * With a tx awaiting finalization, tolerate more missed probes: an unsigned
+     * private_transfer/unshield makes the node CPU-bound on proof verification,
+     * which is exactly when probes time out — tearing down then kills the very
+     * tx being processed.
+     */
+    private static readonly PROBE_FAILURE_THRESHOLD_INFLIGHT;
     /** Starts the periodic heartbeat loop. Replaces any existing timer. */
     private startHeartbeat;
     /** Clears the heartbeat interval timer if active. */

package/dist/index.d.ts

@@ -105,6 +105,18 @@ declare class SubstrateClient {
     private constructor();
     private _dynamicBuilder;
     private _extDecoder;
+    private _inflightTxCount;
+    /**
+     * `true` while any submitted transaction is still waiting for finalization.
+     * Connection managers use this to defer destroying the client — killing the
+     * WS mid-submit rejects the pending tx with "Client destroyed" even though
+     * it may still land on-chain.
+     *
+     * Only covers promise-based submits (`submit`, `submitUnsignedAndWatch`,
+     * `signAndSubmit`); observable-based `submitAndWatch` callers are not tracked.
+     */
+    get hasInflightTx(): boolean;
+    private trackTx;
     /**
      * Connects to the Orbinum node via WebSocket.
      * Throws if the node does not respond within `timeoutMs`.
@@ -285,14 +297,25 @@ declare class EvmClient {
     }): Promise<bigint>;
     /** Returns a transaction receipt by hash, or `null` if the transaction has not been mined yet. */
     getTransactionReceipt(txHash: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Fetches a transaction by hash, or `null` when the node no longer knows it
+     * (never mined and evicted from the pool). Unlike `request`, a `null`
+     * result is a valid answer here, not an error.
+     */
+    getTransactionByHash(txHash: string): Promise<Record<string, unknown> | null>;
     /**
      * Polls `eth_getTransactionReceipt` until the transaction is included in a block.
      *
+     * After `timeoutMs`, the tx-pool is consulted: a tx no longer known to the
+     * node is reported as dropped (safe to retry), while a tx still in the pool
+     * gets an extended grace window (up to 4× `timeoutMs`) before a "still
+     * pending" error — it may confirm later, so callers must NOT blindly retry.
+     *
      * @param txHash - The transaction hash to wait for.
      * @param intervalMs - Polling interval in milliseconds (default: 500).
      * @param timeoutMs - Maximum time to wait in milliseconds (default: 60_000).
      * @returns The transaction receipt once mined.
-     * @throws If the transaction is not mined within `timeoutMs` or if it reverted (`status == 0x0`).
+     * @throws If the transaction dropped, is still pending after the grace window, or reverted (`status == 0x0`).
      */
     waitForReceipt(txHash: string, intervalMs?: number, timeoutMs?: number): Promise<Record<string, unknown>>;
 }
@@ -1776,6 +1799,7 @@ declare class OrbinumClientProvider {
     private _reconnectTimer;
     private _stableTimer;
     private _reconnectAttempt;
+    private _probeFailures;
     private _listeners;
     /** Creates a new provider with the given configuration. Does not connect automatically — call `connect()` to initiate. */
     constructor(config: ClientProviderConfig);
@@ -1806,6 +1830,21 @@ declare class OrbinumClientProvider {
      * On failure: destroys any orphaned client and transitions to `'disconnected'`.
      */
     private attemptConnect;
+    /**
+     * Consecutive failed probes required before the client is torn down. A
+     * single missed probe is routine (throttled background tab, node busy
+     * verifying a ZK proof, transient network blip) — destroying the client on
+     * it rejects every in-flight request with "Client destroyed" even though
+     * the tx may still land on-chain.
+     */
+    private static readonly PROBE_FAILURE_THRESHOLD;
+    /**
+     * With a tx awaiting finalization, tolerate more missed probes: an unsigned
+     * private_transfer/unshield makes the node CPU-bound on proof verification,
+     * which is exactly when probes time out — tearing down then kills the very
+     * tx being processed.
+     */
+    private static readonly PROBE_FAILURE_THRESHOLD_INFLIGHT;
     /** Starts the periodic heartbeat loop. Replaces any existing timer. */
     private startHeartbeat;
     /** Clears the heartbeat interval timer if active. */

package/dist/index.js

@@ -225,6 +225,27 @@ var SubstrateClient = class _SubstrateClient {
   _httpUrl;
   _dynamicBuilder = null;
   _extDecoder = null;
+  _inflightTxCount = 0;
+  /**
+   * `true` while any submitted transaction is still waiting for finalization.
+   * Connection managers use this to defer destroying the client — killing the
+   * WS mid-submit rejects the pending tx with "Client destroyed" even though
+   * it may still land on-chain.
+   *
+   * Only covers promise-based submits (`submit`, `submitUnsignedAndWatch`,
+   * `signAndSubmit`); observable-based `submitAndWatch` callers are not tracked.
+   */
+  get hasInflightTx() {
+    return this._inflightTxCount > 0;
+  }
+  async trackTx(p) {
+    this._inflightTxCount++;
+    try {
+      return await p;
+    } finally {
+      this._inflightTxCount--;
+    }
+  }
   /**
    * Connects to the Orbinum node via WebSocket.
    * Throws if the node does not respond within `timeoutMs`.
@@ -437,7 +458,7 @@ var SubstrateClient = class _SubstrateClient {
    * Submits a pre-signed extrinsic (hex string) and waits for finalization.
    */
   async submit(signedHex) {
-    return this._papi.submit(import_polkadot_api.Binary.fromHex(signedHex));
+    return this.trackTx(this._papi.submit(import_polkadot_api.Binary.fromHex(signedHex)));
   }
   /**
    * Submits a pre-signed extrinsic and returns an Observable of tx lifecycle events.
@@ -452,14 +473,14 @@ var SubstrateClient = class _SubstrateClient {
    * The bare tx bytes are produced by `tx.getBareTx()` from polkadot-api.
    */
   async submitUnsignedAndWatch(bareTx) {
-    return this._papi.submit(bareTx);
+    return this.trackTx(this._papi.submit(bareTx));
   }
   /**
    * Convenience: wrap raw call bytes and sign+submit in one step.
    */
   async signAndSubmit(callData, signer) {
     const tx = await this.txFromCallData(callData);
-    return tx.signAndSubmit(signer);
+    return this.trackTx(tx.signAndSubmit(signer));
   }
   /** Closes the WebSocket connection. */
   destroy() {
@@ -716,17 +737,46 @@ var EvmClient = class {
     }
     return json.result ?? null;
   }
+  /**
+   * Fetches a transaction by hash, or `null` when the node no longer knows it
+   * (never mined and evicted from the pool). Unlike `request`, a `null`
+   * result is a valid answer here, not an error.
+   */
+  async getTransactionByHash(txHash) {
+    const res = await postJsonWithRetry(
+      this.rpcUrl,
+      JSON.stringify({
+        id: 1,
+        jsonrpc: "2.0",
+        method: "eth_getTransactionByHash",
+        params: [txHash]
+      })
+    );
+    if (!res.ok) throw new Error(`EVM HTTP ${res.status}: ${res.statusText}`);
+    const json = await res.json();
+    if (json.error) {
+      throw new Error(`EVM RPC [${json.error.code}]: ${json.error.message}`);
+    }
+    return json.result ?? null;
+  }
   /**
    * Polls `eth_getTransactionReceipt` until the transaction is included in a block.
    *
+   * After `timeoutMs`, the tx-pool is consulted: a tx no longer known to the
+   * node is reported as dropped (safe to retry), while a tx still in the pool
+   * gets an extended grace window (up to 4× `timeoutMs`) before a "still
+   * pending" error — it may confirm later, so callers must NOT blindly retry.
+   *
    * @param txHash - The transaction hash to wait for.
    * @param intervalMs - Polling interval in milliseconds (default: 500).
    * @param timeoutMs - Maximum time to wait in milliseconds (default: 60_000).
    * @returns The transaction receipt once mined.
-   * @throws If the transaction is not mined within `timeoutMs` or if it reverted (`status == 0x0`).
+   * @throws If the transaction dropped, is still pending after the grace window, or reverted (`status == 0x0`).
    */
   async waitForReceipt(txHash, intervalMs = 500, timeoutMs = 6e4) {
-    const deadline = Date.now() + timeoutMs;
+    const start = Date.now();
+    const hardDeadline = start + timeoutMs * 4;
+    let deadline = start + timeoutMs;
     while (Date.now() < deadline) {
       const receipt = await this.getTransactionReceipt(txHash);
       if (receipt !== null) {
@@ -737,10 +787,7 @@ var EvmClient = class {
           if (!revertDetail) {
             try {
               const blockParam = receipt["blockNumber"] ?? "latest";
-              const rawTx = await this.request(
-                "eth_getTransactionByHash",
-                [txHash]
-              ).catch(() => null);
+              const rawTx = await this.getTransactionByHash(txHash).catch(() => null);
               if (rawTx) {
                 const calldata = rawTx["input"] ?? rawTx["data"];
                 if (calldata) {
@@ -763,8 +810,19 @@ var EvmClient = class {
         return receipt;
       }
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      if (Date.now() >= deadline && Date.now() < hardDeadline) {
+        const known = await this.getTransactionByHash(txHash).catch(() => void 0);
+        if (known === null) {
+          throw new Error(
+            `Transaction dropped from the tx pool (not mined within ${Date.now() - start}ms): ${txHash}`
+          );
+        }
+        deadline = Math.min(deadline + timeoutMs, hardDeadline);
+      }
     }
-    throw new Error(`Transaction not mined within ${timeoutMs}ms: ${txHash}`);
+    throw new Error(
+      `Transaction still pending after ${Date.now() - start}ms: ${txHash} \u2014 it may still confirm; check the hash on the explorer before retrying`
+    );
   }
 };
 
@@ -3368,7 +3426,7 @@ var DEFAULT_HEARTBEAT_TIMEOUT_MS = 4e3;
 var DEFAULT_RECONNECT_BASE_MS = 3e3;
 var DEFAULT_RECONNECT_MAX_MS = 3e4;
 var DEFAULT_STABLE_AFTER_MS = 1e4;
-var OrbinumClientProvider = class {
+var OrbinumClientProvider = class _OrbinumClientProvider {
   config;
   connectTimeoutMs;
   heartbeatIntervalMs;
@@ -3385,6 +3443,7 @@ var OrbinumClientProvider = class {
   _reconnectTimer = null;
   _stableTimer = null;
   _reconnectAttempt = 0;
+  _probeFailures = 0;
   // ─── Events ─────────────────────────────────────────────────────────────
   _listeners = /* @__PURE__ */ new Set();
   /** Creates a new provider with the given configuration. Does not connect automatically — call `connect()` to initiate. */
@@ -3517,13 +3576,36 @@ var OrbinumClientProvider = class {
     }
   }
   // ─── Heartbeat ──────────────────────────────────────────────────────────
+  /**
+   * Consecutive failed probes required before the client is torn down. A
+   * single missed probe is routine (throttled background tab, node busy
+   * verifying a ZK proof, transient network blip) — destroying the client on
+   * it rejects every in-flight request with "Client destroyed" even though
+   * the tx may still land on-chain.
+   */
+  static PROBE_FAILURE_THRESHOLD = 2;
+  /**
+   * With a tx awaiting finalization, tolerate more missed probes: an unsigned
+   * private_transfer/unshield makes the node CPU-bound on proof verification,
+   * which is exactly when probes time out — tearing down then kills the very
+   * tx being processed.
+   */
+  static PROBE_FAILURE_THRESHOLD_INFLIGHT = 6;
   /** Starts the periodic heartbeat loop. Replaces any existing timer. */
   startHeartbeat() {
     this.stopHeartbeat();
+    this._probeFailures = 0;
     this._heartbeatTimer = setInterval(async () => {
       if (this._status !== "connected" || !this._orbinumClient) return;
       const alive = await this.probe();
-      if (!alive && this._status === "connected") {
+      if (this._status !== "connected") return;
+      if (alive) {
+        this._probeFailures = 0;
+        return;
+      }
+      this._probeFailures++;
+      const threshold = this._orbinumClient?.substrate.hasInflightTx ? _OrbinumClientProvider.PROBE_FAILURE_THRESHOLD_INFLIGHT : _OrbinumClientProvider.PROBE_FAILURE_THRESHOLD;
+      if (this._probeFailures >= threshold) {
         this.setStatus("disconnected", "Node is unreachable");
         this.teardownClient();
         this.scheduleReconnect();

package/dist/index.mjs

@@ -90,6 +90,27 @@ var SubstrateClient = class _SubstrateClient {
   _httpUrl;
   _dynamicBuilder = null;
   _extDecoder = null;
+  _inflightTxCount = 0;
+  /**
+   * `true` while any submitted transaction is still waiting for finalization.
+   * Connection managers use this to defer destroying the client — killing the
+   * WS mid-submit rejects the pending tx with "Client destroyed" even though
+   * it may still land on-chain.
+   *
+   * Only covers promise-based submits (`submit`, `submitUnsignedAndWatch`,
+   * `signAndSubmit`); observable-based `submitAndWatch` callers are not tracked.
+   */
+  get hasInflightTx() {
+    return this._inflightTxCount > 0;
+  }
+  async trackTx(p) {
+    this._inflightTxCount++;
+    try {
+      return await p;
+    } finally {
+      this._inflightTxCount--;
+    }
+  }
   /**
    * Connects to the Orbinum node via WebSocket.
    * Throws if the node does not respond within `timeoutMs`.
@@ -302,7 +323,7 @@ var SubstrateClient = class _SubstrateClient {
    * Submits a pre-signed extrinsic (hex string) and waits for finalization.
    */
   async submit(signedHex) {
-    return this._papi.submit(Binary.fromHex(signedHex));
+    return this.trackTx(this._papi.submit(Binary.fromHex(signedHex)));
   }
   /**
    * Submits a pre-signed extrinsic and returns an Observable of tx lifecycle events.
@@ -317,14 +338,14 @@ var SubstrateClient = class _SubstrateClient {
    * The bare tx bytes are produced by `tx.getBareTx()` from polkadot-api.
    */
   async submitUnsignedAndWatch(bareTx) {
-    return this._papi.submit(bareTx);
+    return this.trackTx(this._papi.submit(bareTx));
   }
   /**
    * Convenience: wrap raw call bytes and sign+submit in one step.
    */
   async signAndSubmit(callData, signer) {
     const tx = await this.txFromCallData(callData);
-    return tx.signAndSubmit(signer);
+    return this.trackTx(tx.signAndSubmit(signer));
   }
   /** Closes the WebSocket connection. */
   destroy() {
@@ -581,17 +602,46 @@ var EvmClient = class {
     }
     return json.result ?? null;
   }
+  /**
+   * Fetches a transaction by hash, or `null` when the node no longer knows it
+   * (never mined and evicted from the pool). Unlike `request`, a `null`
+   * result is a valid answer here, not an error.
+   */
+  async getTransactionByHash(txHash) {
+    const res = await postJsonWithRetry(
+      this.rpcUrl,
+      JSON.stringify({
+        id: 1,
+        jsonrpc: "2.0",
+        method: "eth_getTransactionByHash",
+        params: [txHash]
+      })
+    );
+    if (!res.ok) throw new Error(`EVM HTTP ${res.status}: ${res.statusText}`);
+    const json = await res.json();
+    if (json.error) {
+      throw new Error(`EVM RPC [${json.error.code}]: ${json.error.message}`);
+    }
+    return json.result ?? null;
+  }
   /**
    * Polls `eth_getTransactionReceipt` until the transaction is included in a block.
    *
+   * After `timeoutMs`, the tx-pool is consulted: a tx no longer known to the
+   * node is reported as dropped (safe to retry), while a tx still in the pool
+   * gets an extended grace window (up to 4× `timeoutMs`) before a "still
+   * pending" error — it may confirm later, so callers must NOT blindly retry.
+   *
    * @param txHash - The transaction hash to wait for.
    * @param intervalMs - Polling interval in milliseconds (default: 500).
    * @param timeoutMs - Maximum time to wait in milliseconds (default: 60_000).
    * @returns The transaction receipt once mined.
-   * @throws If the transaction is not mined within `timeoutMs` or if it reverted (`status == 0x0`).
+   * @throws If the transaction dropped, is still pending after the grace window, or reverted (`status == 0x0`).
    */
   async waitForReceipt(txHash, intervalMs = 500, timeoutMs = 6e4) {
-    const deadline = Date.now() + timeoutMs;
+    const start = Date.now();
+    const hardDeadline = start + timeoutMs * 4;
+    let deadline = start + timeoutMs;
     while (Date.now() < deadline) {
       const receipt = await this.getTransactionReceipt(txHash);
       if (receipt !== null) {
@@ -602,10 +652,7 @@ var EvmClient = class {
           if (!revertDetail) {
             try {
               const blockParam = receipt["blockNumber"] ?? "latest";
-              const rawTx = await this.request(
-                "eth_getTransactionByHash",
-                [txHash]
-              ).catch(() => null);
+              const rawTx = await this.getTransactionByHash(txHash).catch(() => null);
               if (rawTx) {
                 const calldata = rawTx["input"] ?? rawTx["data"];
                 if (calldata) {
@@ -628,8 +675,19 @@ var EvmClient = class {
         return receipt;
       }
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      if (Date.now() >= deadline && Date.now() < hardDeadline) {
+        const known = await this.getTransactionByHash(txHash).catch(() => void 0);
+        if (known === null) {
+          throw new Error(
+            `Transaction dropped from the tx pool (not mined within ${Date.now() - start}ms): ${txHash}`
+          );
+        }
+        deadline = Math.min(deadline + timeoutMs, hardDeadline);
+      }
     }
-    throw new Error(`Transaction not mined within ${timeoutMs}ms: ${txHash}`);
+    throw new Error(
+      `Transaction still pending after ${Date.now() - start}ms: ${txHash} \u2014 it may still confirm; check the hash on the explorer before retrying`
+    );
   }
 };
 
@@ -3236,7 +3294,7 @@ var DEFAULT_HEARTBEAT_TIMEOUT_MS = 4e3;
 var DEFAULT_RECONNECT_BASE_MS = 3e3;
 var DEFAULT_RECONNECT_MAX_MS = 3e4;
 var DEFAULT_STABLE_AFTER_MS = 1e4;
-var OrbinumClientProvider = class {
+var OrbinumClientProvider = class _OrbinumClientProvider {
   config;
   connectTimeoutMs;
   heartbeatIntervalMs;
@@ -3253,6 +3311,7 @@ var OrbinumClientProvider = class {
   _reconnectTimer = null;
   _stableTimer = null;
   _reconnectAttempt = 0;
+  _probeFailures = 0;
   // ─── Events ─────────────────────────────────────────────────────────────
   _listeners = /* @__PURE__ */ new Set();
   /** Creates a new provider with the given configuration. Does not connect automatically — call `connect()` to initiate. */
@@ -3385,13 +3444,36 @@ var OrbinumClientProvider = class {
     }
   }
   // ─── Heartbeat ──────────────────────────────────────────────────────────
+  /**
+   * Consecutive failed probes required before the client is torn down. A
+   * single missed probe is routine (throttled background tab, node busy
+   * verifying a ZK proof, transient network blip) — destroying the client on
+   * it rejects every in-flight request with "Client destroyed" even though
+   * the tx may still land on-chain.
+   */
+  static PROBE_FAILURE_THRESHOLD = 2;
+  /**
+   * With a tx awaiting finalization, tolerate more missed probes: an unsigned
+   * private_transfer/unshield makes the node CPU-bound on proof verification,
+   * which is exactly when probes time out — tearing down then kills the very
+   * tx being processed.
+   */
+  static PROBE_FAILURE_THRESHOLD_INFLIGHT = 6;
   /** Starts the periodic heartbeat loop. Replaces any existing timer. */
   startHeartbeat() {
     this.stopHeartbeat();
+    this._probeFailures = 0;
     this._heartbeatTimer = setInterval(async () => {
       if (this._status !== "connected" || !this._orbinumClient) return;
       const alive = await this.probe();
-      if (!alive && this._status === "connected") {
+      if (this._status !== "connected") return;
+      if (alive) {
+        this._probeFailures = 0;
+        return;
+      }
+      this._probeFailures++;
+      const threshold = this._orbinumClient?.substrate.hasInflightTx ? _OrbinumClientProvider.PROBE_FAILURE_THRESHOLD_INFLIGHT : _OrbinumClientProvider.PROBE_FAILURE_THRESHOLD;
+      if (this._probeFailures >= threshold) {
         this.setStatus("disconnected", "Node is unreachable");
         this.teardownClient();
         this.scheduleReconnect();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbinum/sdk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Official TypeScript SDK for Orbinum.",
   "author": "Orbinum",
   "license": "MIT",