starknet 10.5.0 → 10.5.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [10.5.1](https://github.com/starknet-io/starknet.js/compare/v10.5.0...v10.5.1) (2026-07-21)
+
+### Bug Fixes
+
+- ws bound reconnection of a flapping connection ([#1650](https://github.com/starknet-io/starknet.js/issues/1650)) ([241c6c1](https://github.com/starknet-io/starknet.js/commit/241c6c11301a29a22e09a4b8873c236e39326d29))
+
 # [10.5.0](https://github.com/starknet-io/starknet.js/compare/v10.4.0...v10.5.0) (2026-07-06)
 
 ### Features

package/README.md

@@ -29,9 +29,6 @@
   <a href="https://starkware.co/">
     <img src="https://img.shields.io/badge/powered_by-StarkWare-navy">
   </a>
-  <a href="https://twitter.com/starknetjs">
-    <img src="https://img.shields.io/badge/follow_us-Twitter-blue">
-  </a>
   <a href="https://www.drips.network/app/projects/github/starknet-io/starknet.js" target="_blank">
     <img src="https://www.drips.network/api/embed/project/https%3A%2F%2Fgithub.com%2Fstarknet-io%2Fstarknet.js/support.png?background=light&style=github&text=project&stat=none" alt="Support starknet.js on drips.network" height="20">
   </a>
@@ -58,6 +55,22 @@ How to [Guides](https://starknet-io.github.io/starknet.js/docs/guides/intro) :bo
 
 Play with [Code Examples](https://github.com/PhilippeR26/starknet.js-workshop-typescript) :video_game:
 
+## 🤖 Using AI
+
+AI training data about starknet.js is often outdated. To give your AI coding agent accurate, up-to-date guidance, install the official starknet.js skill ([`skills/starknet-js/`](./skills/starknet-js/)). It works with Claude Code, Codex, Cursor, Gemini CLI, and any other agent supporting the open [Agent Skills](https://agentskills.io/) standard.
+
+```bash
+npx skills add starknet-io/starknet.js
+```
+
+or copy the skill files directly:
+
+```bash
+mkdir -p ~/.claude/skills/starknet-js && curl -s --output-dir ~/.claude/skills/starknet-js --remote-name-all "https://raw.githubusercontent.com/starknet-io/starknet.js/develop/skills/starknet-js/{SKILL.md,calldata.md,interacting.md}"
+```
+
+> This command installs into Claude Code's skills folder — adapt the target directory for other agents.
+
 ## ✏️ Contributing
 
 If you consider to contribute to this project please read [CONTRIBUTING.md](https://github.com/starknet-io/starknet.js/blob/main/CONTRIBUTING.md) first.

package/dist/index.d.ts

@@ -5006,6 +5006,14 @@ type ReconnectOptions = {
      * @default true
      */
     exponential?: number | boolean;
+    /**
+     * The minimum time in milliseconds a reconnected connection must stay open before
+     * it is considered stable and the retry counter is reset. This prevents a gateway
+     * that accepts the connection then immediately drops it (a "flapping" connection)
+     * from resetting the counter on every cycle and reconnecting forever.
+     * @default 5000
+     */
+    stableConnectionThreshold?: number;
 };
 /**
  * The type of the WebSocket implementation.
@@ -5098,6 +5106,7 @@ declare class WebSocketChannel {
     private reconnectAttempts;
     private userInitiatedClose;
     private reconnectTimeoutId;
+    private reconnectStabilityTimeoutId;
     private requestQueue;
     private events;
     private openListener;
@@ -5192,6 +5201,13 @@ declare class WebSocketChannel {
     reconnect(): void;
     private _processRequestQueue;
     private _restoreSubscriptions;
+    /**
+     * Reset the reconnection attempt counter, but only once the current connection has
+     * stayed open for `stableConnectionThreshold` ms. A connection that opens and then
+     * immediately drops (a flapping gateway) never reaches this point, so its attempts
+     * keep accumulating toward the retry cap instead of resetting every cycle.
+     */
+    private scheduleReconnectAttemptsReset;
     private _startReconnect;
     private onCloseProxy;
     private onMessageProxy;

package/dist/index.global.js

@@ -12608,9 +12608,15 @@ ${indent}}` : "}";
     reconnectAttempts = 0;
     userInitiatedClose = false;
     reconnectTimeoutId = null;
+    // Fires once a (re)connection has stayed open long enough to be considered stable,
+    // resetting the reconnection attempt counter.
+    reconnectStabilityTimeoutId = null;
     requestQueue = [];
     events = new EventEmitter();
-    openListener = (ev) => this.events.emit("open", ev);
+    openListener = (ev) => {
+      this.scheduleReconnectAttemptsReset();
+      this.events.emit("open", ev);
+    };
     closeListener = this.onCloseProxy.bind(this);
     messageListener = this.onMessageProxy.bind(this);
     errorListener = (ev) => this.events.emit("error", ev);
@@ -12630,7 +12636,8 @@ ${indent}}` : "}";
       this.reconnectOptions = {
         retries: options.reconnectOptions?.retries ?? 5,
         delay: options.reconnectOptions?.delay ?? 2e3,
-        exponential: options.reconnectOptions?.exponential ?? true
+        exponential: options.reconnectOptions?.exponential ?? true,
+        stableConnectionThreshold: options.reconnectOptions?.stableConnectionThreshold ?? 5e3
       };
       this.requestTimeout = options.requestTimeout ?? 6e4;
       this.WsImplementation = options.websocket || config.get("websocket") || ws_default;
@@ -12777,8 +12784,12 @@ ${indent}}` : "}";
         clearTimeout(this.reconnectTimeoutId);
         this.reconnectTimeoutId = null;
       }
-      this.websocket.close(code, reason);
+      if (this.reconnectStabilityTimeoutId) {
+        clearTimeout(this.reconnectStabilityTimeoutId);
+        this.reconnectStabilityTimeoutId = null;
+      }
       this.userInitiatedClose = true;
+      this.websocket.close(code, reason);
     }
     /**
      * Returns a Promise that resolves when the WebSocket connection is closed.
@@ -12865,12 +12876,30 @@ ${indent}}` : "}";
       });
       await Promise.all(restorePromises);
     }
+    /**
+     * Reset the reconnection attempt counter, but only once the current connection has
+     * stayed open for `stableConnectionThreshold` ms. A connection that opens and then
+     * immediately drops (a flapping gateway) never reaches this point, so its attempts
+     * keep accumulating toward the retry cap instead of resetting every cycle.
+     */
+    scheduleReconnectAttemptsReset() {
+      if (this.reconnectStabilityTimeoutId) {
+        clearTimeout(this.reconnectStabilityTimeoutId);
+      }
+      this.reconnectStabilityTimeoutId = setTimeout(() => {
+        this.reconnectAttempts = 0;
+        this.reconnectStabilityTimeoutId = null;
+      }, this.reconnectOptions.stableConnectionThreshold);
+    }
     _startReconnect() {
       if (this.isReconnecting || !this.autoReconnect) {
         return;
       }
+      if (this.reconnectStabilityTimeoutId) {
+        clearTimeout(this.reconnectStabilityTimeoutId);
+        this.reconnectStabilityTimeoutId = null;
+      }
       this.isReconnecting = true;
-      this.reconnectAttempts = 0;
       const tryReconnect = () => {
         if (this.reconnectAttempts >= this.reconnectOptions.retries) {
           logger.error("WebSocket: Maximum reconnection retries reached. Giving up.");
@@ -12885,7 +12914,6 @@ ${indent}}` : "}";
         this.websocket.onopen = async () => {
           logger.info("WebSocket: Reconnection successful.");
           this.isReconnecting = false;
-          this.reconnectAttempts = 0;
           await this._restoreSubscriptions();
           this._processRequestQueue();
           this.events.emit("open", new Event("open"));