starknet 10.4.0 → 10.5.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+- add Contract.compile() to build calldata from the abi ([0cdcaf9](https://github.com/starknet-io/starknet.js/commit/0cdcaf927a75b4537ccc071794ae354f058c320c))
+
 # [10.4.0](https://github.com/starknet-io/starknet.js/compare/v10.3.3...v10.4.0) (2026-07-01)
 
 ### 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;
@@ -6278,6 +6294,27 @@ declare abstract class ContractInterface {
      * ```
      */
     abstract populate(method: string, args?: ArgsOrCalldata): Invocation;
+    /**
+     * Compile the calldata for a contract method, using the contract abi.
+     *
+     * Unlike {@link populate}, this returns only the compiled `Calldata` array, without wrapping it
+     * in an `Invocation` object (no `contractAddress` nor `entrypoint`). It is the contract-bound
+     * equivalent of `myCallData.compile(method, args)`.
+     *
+     * If `args` is already a compiled `Calldata`, it is returned as-is without recompilation.
+     *
+     * @param method - Name of the contract method, as defined in the abi
+     * @param args - Method arguments as array (in abi order) or object (free order), or an already
+     * compiled calldata
+     * @returns The compiled calldata
+     * @example
+     * ```typescript
+     * // 'amount' is a u256: the abi splits it into 2 felts automatically
+     * const calldata = contract.compile('transfer', { recipient: '0x123', amount: 100n });
+     * // calldata = ['0x123', '100', '0']
+     * ```
+     */
+    abstract compile(method: string, args?: ArgsOrCalldata): Calldata;
     /**
      * Parse events from a transaction receipt using the contract's ABI
      *
@@ -6404,6 +6441,7 @@ declare class Contract implements ContractInterface {
     }): Promise<InvokeFunctionResponse>;
     invoke(method: string, args?: ArgsOrCalldata, options?: ExecuteOptions): Promise<InvokeFunctionResponse>;
     estimate(method: string, args?: ArgsOrCalldata, estimateDetails?: ExecuteOptions): Promise<EstimateFeeResponseOverhead | PaymasterFeeEstimate>;
+    compile(method: string, args?: RawArgs): Calldata;
     populate(method: string, args?: RawArgs): Call;
     parseEvents(receipt: GetTransactionReceiptResponse): ParsedEvents;
     isCairo1(): boolean;

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"));
@@ -18548,12 +18576,14 @@ ${indent}}` : "}";
       }
       throw Error("Contract must be connected to the account contract to estimate");
     }
+    compile(method, args = []) {
+      return getCompiledCalldata(args, () => this.callData.compile(method, args));
+    }
     populate(method, args = []) {
-      const calldata = getCompiledCalldata(args, () => this.callData.compile(method, args));
       return {
         contractAddress: this.address,
         entrypoint: method,
-        calldata
+        calldata: this.compile(method, args)
       };
     }
     parseEvents(receipt) {