@orbinum/sdk 0.7.8 → 0.7.10

package/dist/index.d.mts

@@ -2073,6 +2073,13 @@ interface ClientProviderConfig {
     reconnectBaseMs?: number;
     /** Maximum reconnect delay cap in milliseconds. Default: `30_000`. */
     reconnectMaxMs?: number;
+    /**
+     * How long a connection must stay live before the reconnect backoff is reset
+     * to base, in milliseconds. Prevents a flapping node (connect → drop →
+     * connect) from resetting the backoff on every brief connect and hammering
+     * the node every `reconnectBaseMs`. Default: `10_000`.
+     */
+    stableAfterMs?: number;
 }
 /**
  * Manages the lifecycle of an `OrbinumClient` with heartbeat monitoring,
@@ -2100,11 +2107,13 @@ declare class OrbinumClientProvider {
     private readonly heartbeatTimeoutMs;
     private readonly reconnectBaseMs;
     private readonly reconnectMaxMs;
+    private readonly stableAfterMs;
     private _status;
     private _orbinumClient;
     private _connectingPromise;
     private _heartbeatTimer;
     private _reconnectTimer;
+    private _stableTimer;
     private _reconnectAttempt;
     private _listeners;
     /** Creates a new provider with the given configuration. Does not connect automatically — call `connect()` to initiate. */
@@ -2145,9 +2154,20 @@ declare class OrbinumClientProvider {
      * Returns `true` if the node responds in time, `false` otherwise.
      */
     private probe;
+    /**
+     * After a successful connect, wait `stableAfterMs` before resetting the
+     * backoff. If the connection survives that long it's considered stable and
+     * the next drop starts from base delay again; if it drops sooner the backoff
+     * keeps growing, so a flapping node backs off instead of hammering.
+     */
+    private startStableTimer;
+    /** Clears the stability timer if active (on disconnect/teardown/reset). */
+    private stopStableTimer;
     /**
      * Schedules the next connection attempt using exponential backoff
-     * (capped at `reconnectMaxMs`), then transitions to `'reconnecting'`.
+     * (capped at `reconnectMaxMs`) with full jitter, then transitions to
+     * `'reconnecting'`. Jitter (a random fraction of the delay) spreads out
+     * reconnects so many clients don't retry in lockstep after a shared outage.
      */
     private scheduleReconnect;
     /** Clears any pending reconnect timer without triggering a new attempt. */

package/dist/index.d.ts

@@ -2073,6 +2073,13 @@ interface ClientProviderConfig {
     reconnectBaseMs?: number;
     /** Maximum reconnect delay cap in milliseconds. Default: `30_000`. */
     reconnectMaxMs?: number;
+    /**
+     * How long a connection must stay live before the reconnect backoff is reset
+     * to base, in milliseconds. Prevents a flapping node (connect → drop →
+     * connect) from resetting the backoff on every brief connect and hammering
+     * the node every `reconnectBaseMs`. Default: `10_000`.
+     */
+    stableAfterMs?: number;
 }
 /**
  * Manages the lifecycle of an `OrbinumClient` with heartbeat monitoring,
@@ -2100,11 +2107,13 @@ declare class OrbinumClientProvider {
     private readonly heartbeatTimeoutMs;
     private readonly reconnectBaseMs;
     private readonly reconnectMaxMs;
+    private readonly stableAfterMs;
     private _status;
     private _orbinumClient;
     private _connectingPromise;
     private _heartbeatTimer;
     private _reconnectTimer;
+    private _stableTimer;
     private _reconnectAttempt;
     private _listeners;
     /** Creates a new provider with the given configuration. Does not connect automatically — call `connect()` to initiate. */
@@ -2145,9 +2154,20 @@ declare class OrbinumClientProvider {
      * Returns `true` if the node responds in time, `false` otherwise.
      */
     private probe;
+    /**
+     * After a successful connect, wait `stableAfterMs` before resetting the
+     * backoff. If the connection survives that long it's considered stable and
+     * the next drop starts from base delay again; if it drops sooner the backoff
+     * keeps growing, so a flapping node backs off instead of hammering.
+     */
+    private startStableTimer;
+    /** Clears the stability timer if active (on disconnect/teardown/reset). */
+    private stopStableTimer;
     /**
      * Schedules the next connection attempt using exponential backoff
-     * (capped at `reconnectMaxMs`), then transitions to `'reconnecting'`.
+     * (capped at `reconnectMaxMs`) with full jitter, then transitions to
+     * `'reconnecting'`. Jitter (a random fraction of the delay) spreads out
+     * reconnects so many clients don't retry in lockstep after a shared outage.
      */
     private scheduleReconnect;
     /** Clears any pending reconnect timer without triggering a new attempt. */

package/dist/index.js

@@ -1355,7 +1355,7 @@ var IndexerClient = class {
   async getAddressShieldedActivity(address, params) {
     const qs = this.buildQuery({ page: params?.page, limit: params?.limit });
     return this.get(
-      `/shielded/address/${encodeURIComponent(address.toLowerCase())}${qs}`
+      `/shielded/address/${encodeURIComponent(address)}${qs}`
     );
   }
   // ─── Relayers ──────────────────────────────────────────────────────────────
@@ -3526,6 +3526,7 @@ var DEFAULT_HEARTBEAT_INTERVAL_MS = 5e3;
 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 {
   config;
   connectTimeoutMs;
@@ -3533,6 +3534,7 @@ var OrbinumClientProvider = class {
   heartbeatTimeoutMs;
   reconnectBaseMs;
   reconnectMaxMs;
+  stableAfterMs;
   // ─── State ──────────────────────────────────────────────────────────────
   _status = "idle";
   _orbinumClient = null;
@@ -3540,6 +3542,7 @@ var OrbinumClientProvider = class {
   // ─── Timers ─────────────────────────────────────────────────────────────
   _heartbeatTimer = null;
   _reconnectTimer = null;
+  _stableTimer = null;
   _reconnectAttempt = 0;
   // ─── Events ─────────────────────────────────────────────────────────────
   _listeners = /* @__PURE__ */ new Set();
@@ -3551,6 +3554,7 @@ var OrbinumClientProvider = class {
     this.heartbeatTimeoutMs = config.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
     this.reconnectBaseMs = config.reconnectBaseMs ?? DEFAULT_RECONNECT_BASE_MS;
     this.reconnectMaxMs = config.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
+    this.stableAfterMs = config.stableAfterMs ?? DEFAULT_STABLE_AFTER_MS;
   }
   // ─── Status ─────────────────────────────────────────────────────────────
   /** Current connection status. Reflects the last state set by the provider internals. */
@@ -3637,9 +3641,9 @@ var OrbinumClientProvider = class {
       orphanClient = null;
       this._orbinumClient = client;
       this._connectingPromise = null;
-      this._reconnectAttempt = 0;
       this.setStatus("connected");
       this.startHeartbeat();
+      this.startStableTimer();
       return client;
     } catch (err) {
       clearTimeout(timeoutId);
@@ -3696,17 +3700,41 @@ var OrbinumClientProvider = class {
       return false;
     }
   }
+  // ─── Connection stability ───────────────────────────────────────────────
+  /**
+   * After a successful connect, wait `stableAfterMs` before resetting the
+   * backoff. If the connection survives that long it's considered stable and
+   * the next drop starts from base delay again; if it drops sooner the backoff
+   * keeps growing, so a flapping node backs off instead of hammering.
+   */
+  startStableTimer() {
+    this.stopStableTimer();
+    this._stableTimer = setTimeout(() => {
+      this._stableTimer = null;
+      if (this._status === "connected") this._reconnectAttempt = 0;
+    }, this.stableAfterMs);
+  }
+  /** Clears the stability timer if active (on disconnect/teardown/reset). */
+  stopStableTimer() {
+    if (this._stableTimer) {
+      clearTimeout(this._stableTimer);
+      this._stableTimer = null;
+    }
+  }
   // ─── Reconnection ───────────────────────────────────────────────────────
   /**
    * Schedules the next connection attempt using exponential backoff
-   * (capped at `reconnectMaxMs`), then transitions to `'reconnecting'`.
+   * (capped at `reconnectMaxMs`) with full jitter, then transitions to
+   * `'reconnecting'`. Jitter (a random fraction of the delay) spreads out
+   * reconnects so many clients don't retry in lockstep after a shared outage.
    */
   scheduleReconnect() {
     if (this._reconnectTimer) clearTimeout(this._reconnectTimer);
-    const delay = Math.min(
+    const capped = Math.min(
       this.reconnectBaseMs * 2 ** this._reconnectAttempt,
       this.reconnectMaxMs
     );
+    const delay = capped / 2 + Math.random() * (capped / 2);
     this._reconnectAttempt++;
     this.setStatus("reconnecting");
     this._reconnectTimer = setTimeout(() => {
@@ -3725,6 +3753,7 @@ var OrbinumClientProvider = class {
   /** Stops the heartbeat, destroys the active client, and clears all in-progress promises. */
   teardownClient() {
     this.stopHeartbeat();
+    this.stopStableTimer();
     try {
       this._orbinumClient?.destroy();
     } catch {

package/dist/index.mjs

@@ -1228,7 +1228,7 @@ var IndexerClient = class {
   async getAddressShieldedActivity(address, params) {
     const qs = this.buildQuery({ page: params?.page, limit: params?.limit });
     return this.get(
-      `/shielded/address/${encodeURIComponent(address.toLowerCase())}${qs}`
+      `/shielded/address/${encodeURIComponent(address)}${qs}`
     );
   }
   // ─── Relayers ──────────────────────────────────────────────────────────────
@@ -3399,6 +3399,7 @@ var DEFAULT_HEARTBEAT_INTERVAL_MS = 5e3;
 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 {
   config;
   connectTimeoutMs;
@@ -3406,6 +3407,7 @@ var OrbinumClientProvider = class {
   heartbeatTimeoutMs;
   reconnectBaseMs;
   reconnectMaxMs;
+  stableAfterMs;
   // ─── State ──────────────────────────────────────────────────────────────
   _status = "idle";
   _orbinumClient = null;
@@ -3413,6 +3415,7 @@ var OrbinumClientProvider = class {
   // ─── Timers ─────────────────────────────────────────────────────────────
   _heartbeatTimer = null;
   _reconnectTimer = null;
+  _stableTimer = null;
   _reconnectAttempt = 0;
   // ─── Events ─────────────────────────────────────────────────────────────
   _listeners = /* @__PURE__ */ new Set();
@@ -3424,6 +3427,7 @@ var OrbinumClientProvider = class {
     this.heartbeatTimeoutMs = config.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
     this.reconnectBaseMs = config.reconnectBaseMs ?? DEFAULT_RECONNECT_BASE_MS;
     this.reconnectMaxMs = config.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
+    this.stableAfterMs = config.stableAfterMs ?? DEFAULT_STABLE_AFTER_MS;
   }
   // ─── Status ─────────────────────────────────────────────────────────────
   /** Current connection status. Reflects the last state set by the provider internals. */
@@ -3510,9 +3514,9 @@ var OrbinumClientProvider = class {
       orphanClient = null;
       this._orbinumClient = client;
       this._connectingPromise = null;
-      this._reconnectAttempt = 0;
       this.setStatus("connected");
       this.startHeartbeat();
+      this.startStableTimer();
       return client;
     } catch (err) {
       clearTimeout(timeoutId);
@@ -3569,17 +3573,41 @@ var OrbinumClientProvider = class {
       return false;
     }
   }
+  // ─── Connection stability ───────────────────────────────────────────────
+  /**
+   * After a successful connect, wait `stableAfterMs` before resetting the
+   * backoff. If the connection survives that long it's considered stable and
+   * the next drop starts from base delay again; if it drops sooner the backoff
+   * keeps growing, so a flapping node backs off instead of hammering.
+   */
+  startStableTimer() {
+    this.stopStableTimer();
+    this._stableTimer = setTimeout(() => {
+      this._stableTimer = null;
+      if (this._status === "connected") this._reconnectAttempt = 0;
+    }, this.stableAfterMs);
+  }
+  /** Clears the stability timer if active (on disconnect/teardown/reset). */
+  stopStableTimer() {
+    if (this._stableTimer) {
+      clearTimeout(this._stableTimer);
+      this._stableTimer = null;
+    }
+  }
   // ─── Reconnection ───────────────────────────────────────────────────────
   /**
    * Schedules the next connection attempt using exponential backoff
-   * (capped at `reconnectMaxMs`), then transitions to `'reconnecting'`.
+   * (capped at `reconnectMaxMs`) with full jitter, then transitions to
+   * `'reconnecting'`. Jitter (a random fraction of the delay) spreads out
+   * reconnects so many clients don't retry in lockstep after a shared outage.
    */
   scheduleReconnect() {
     if (this._reconnectTimer) clearTimeout(this._reconnectTimer);
-    const delay = Math.min(
+    const capped = Math.min(
       this.reconnectBaseMs * 2 ** this._reconnectAttempt,
       this.reconnectMaxMs
     );
+    const delay = capped / 2 + Math.random() * (capped / 2);
     this._reconnectAttempt++;
     this.setStatus("reconnecting");
     this._reconnectTimer = setTimeout(() => {
@@ -3598,6 +3626,7 @@ var OrbinumClientProvider = class {
   /** Stops the heartbeat, destroys the active client, and clears all in-progress promises. */
   teardownClient() {
     this.stopHeartbeat();
+    this.stopStableTimer();
     try {
       this._orbinumClient?.destroy();
     } catch {

package/package.json

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