starknet 10.5.0 → 10.5.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [10.5.2](https://github.com/starknet-io/starknet.js/compare/v10.5.1...v10.5.2) (2026-07-22)
+
+### Bug Fixes
+
+- provider: correct getBlock() default return type and add JSDoc ([b161c46](https://github.com/starknet-io/starknet.js/commit/b161c468613133c9325c4fe38d20bb09524afbea))
+
+## [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

@@ -1,5 +1,5 @@
 import * as RPCSPEC0103 from '@starknet-io/starknet-types-0103';
-import { PAYMASTER_API, CONTRACT, EDataAvailabilityMode as EDataAvailabilityMode$1, ETransactionType, SUBSCRIPTION_BLOCK_ID, TypedData, CONTRACT_STORAGE_KEYS, StorageProof, CASM_COMPILED_CONTRACT_CLASS, OutsideExecutionTypedData, ETransactionVersion3 as ETransactionVersion3$1, IsType, TransactionReceipt as TransactionReceipt$1, IsSucceeded, IsReverted, PRE_CONFIRMED_BLOCK_WITH_TX_HASHES, BLOCK_WITH_TX_HASHES, TransactionHash, BlockHash, FAILED_TO_RECEIVE_TXN, NO_TRACE_AVAILABLE, CONTRACT_NOT_FOUND, ENTRYPOINT_NOT_FOUND, BLOCK_NOT_FOUND, INVALID_TXN_INDEX, CLASS_HASH_NOT_FOUND, TXN_HASH_NOT_FOUND, PAGE_SIZE_TOO_BIG, NO_BLOCKS, INVALID_CONTINUATION_TOKEN, TOO_MANY_KEYS_IN_FILTER, CONTRACT_ERROR, TRANSACTION_EXECUTION_ERROR, STORAGE_PROOF_NOT_SUPPORTED, CLASS_ALREADY_DECLARED, INVALID_TRANSACTION_NONCE, INSUFFICIENT_RESOURCES_FOR_VALIDATE, INSUFFICIENT_ACCOUNT_BALANCE, VALIDATION_FAILURE, COMPILATION_FAILED, CONTRACT_CLASS_SIZE_IS_TOO_LARGE, NON_ACCOUNT, DUPLICATE_TX, COMPILED_CLASS_HASH_MISMATCH, UNSUPPORTED_TX_VERSION, UNSUPPORTED_CONTRACT_CLASS_VERSION, UNEXPECTED_ERROR, REPLACEMENT_TRANSACTION_UNDERPRICED, FEE_BELOW_MINIMUM, INVALID_SUBSCRIPTION_ID, TOO_MANY_ADDRESSES_IN_FILTER, TOO_MANY_BLOCKS_BACK, COMPILATION_ERROR, ETransactionVersion as ETransactionVersion$1, SUBSCRIPTION_ID, TXN_FINALITY_STATUS, STATUS_ACCEPTED_ON_L1, TXN_STATUS_WITHOUT_L1, StarknetEventsEvent, TransactionsStatusEvent, NewTransactionReceiptsEvent, NewTransactionEvent, NewHeadsEvent, STORAGE_RESULT, INVOKE_TXN_V3, StarknetWindowObject, AccountChangeEventHandler, NetworkChangeEventHandler, WatchAssetParameters, AddStarknetChainParameters, Signature as Signature$1, STRK20_PROOF, Address, STRK20_BALANCE_ENTRY, STRK20_ACTION, STRK20_CALL_AND_PROOF, EDAMode as EDAMode$1, StarknetType, StarknetMerkleType, TypedDataRevision, OutsideCallV1, OutsideCallV2, EmittedEvent as EmittedEvent$1, Event as Event$2, Permission, ChainId, AccountDeploymentData, AddInvokeTransactionParameters, AddInvokeTransactionResult, AddDeclareTransactionParameters, AddDeclareTransactionResult, SpecVersion, API_VERSION as API_VERSION$1 } from '@starknet-io/starknet-types-0103';
+import { PAYMASTER_API, CONTRACT, EDataAvailabilityMode as EDataAvailabilityMode$1, ETransactionType, SUBSCRIPTION_BLOCK_ID, TypedData, CONTRACT_STORAGE_KEYS, StorageProof, CASM_COMPILED_CONTRACT_CLASS, OutsideExecutionTypedData, ETransactionVersion3 as ETransactionVersion3$1, IsType, TransactionReceipt as TransactionReceipt$1, IsSucceeded, IsReverted, BLOCK_WITH_TX_HASHES, PRE_CONFIRMED_BLOCK_WITH_TX_HASHES, TransactionHash, BlockHash, FAILED_TO_RECEIVE_TXN, NO_TRACE_AVAILABLE, CONTRACT_NOT_FOUND, ENTRYPOINT_NOT_FOUND, BLOCK_NOT_FOUND, INVALID_TXN_INDEX, CLASS_HASH_NOT_FOUND, TXN_HASH_NOT_FOUND, PAGE_SIZE_TOO_BIG, NO_BLOCKS, INVALID_CONTINUATION_TOKEN, TOO_MANY_KEYS_IN_FILTER, CONTRACT_ERROR, TRANSACTION_EXECUTION_ERROR, STORAGE_PROOF_NOT_SUPPORTED, CLASS_ALREADY_DECLARED, INVALID_TRANSACTION_NONCE, INSUFFICIENT_RESOURCES_FOR_VALIDATE, INSUFFICIENT_ACCOUNT_BALANCE, VALIDATION_FAILURE, COMPILATION_FAILED, CONTRACT_CLASS_SIZE_IS_TOO_LARGE, NON_ACCOUNT, DUPLICATE_TX, COMPILED_CLASS_HASH_MISMATCH, UNSUPPORTED_TX_VERSION, UNSUPPORTED_CONTRACT_CLASS_VERSION, UNEXPECTED_ERROR, REPLACEMENT_TRANSACTION_UNDERPRICED, FEE_BELOW_MINIMUM, INVALID_SUBSCRIPTION_ID, TOO_MANY_ADDRESSES_IN_FILTER, TOO_MANY_BLOCKS_BACK, COMPILATION_ERROR, ETransactionVersion as ETransactionVersion$1, SUBSCRIPTION_ID, TXN_FINALITY_STATUS, STATUS_ACCEPTED_ON_L1, TXN_STATUS_WITHOUT_L1, StarknetEventsEvent, TransactionsStatusEvent, NewTransactionReceiptsEvent, NewTransactionEvent, NewHeadsEvent, STORAGE_RESULT, INVOKE_TXN_V3, StarknetWindowObject, AccountChangeEventHandler, NetworkChangeEventHandler, WatchAssetParameters, AddStarknetChainParameters, Signature as Signature$1, STRK20_PROOF, Address, STRK20_BALANCE_ENTRY, STRK20_ACTION, STRK20_CALL_AND_PROOF, EDAMode as EDAMode$1, StarknetType, StarknetMerkleType, TypedDataRevision, OutsideCallV1, OutsideCallV2, EmittedEvent as EmittedEvent$1, Event as Event$2, Permission, ChainId, AccountDeploymentData, AddInvokeTransactionParameters, AddInvokeTransactionResult, AddDeclareTransactionParameters, AddDeclareTransactionResult, SpecVersion, API_VERSION as API_VERSION$1 } from '@starknet-io/starknet-types-0103';
 export { STRK20_ACTION, STRK20_BALANCE_ENTRY, STRK20_CALLDATA_ITEM, STRK20_CALLDATA_PLACEHOLDER, STRK20_CALL_AND_PROOF, STRK20_DEPOSIT_ACTION, STRK20_INVOKE_ACTION, STRK20_PROOF, STRK20_TRANSFER_ACTION, STRK20_WITHDRAW_ACTION, StarknetDomain, StarknetEnumType, StarknetMerkleType, StarknetType, TypedData, TypedDataRevision } from '@starknet-io/starknet-types-0103';
 import * as RPC$1 from '@starknet-io/starknet-types-0101';
 import { WatchAssetParameters as WatchAssetParameters$1, AddStarknetChainParameters as AddStarknetChainParameters$1, Signature as Signature$2, Address as Address$1, Permission as Permission$1, ChainId as ChainId$1, AccountDeploymentData as AccountDeploymentData$1, AddInvokeTransactionParameters as AddInvokeTransactionParameters$1, AddInvokeTransactionResult as AddInvokeTransactionResult$1, AddDeclareTransactionParameters as AddDeclareTransactionParameters$1, AddDeclareTransactionResult as AddDeclareTransactionResult$1, TypedData as TypedData$1, SpecVersion as SpecVersion$1, API_VERSION as API_VERSION$2 } from '@starknet-io/starknet-types-0101';
@@ -1008,11 +1008,50 @@ declare abstract class ProviderInterface {
      */
     abstract callContract(call: Call, blockIdentifier?: BlockIdentifier): Promise<CallContractResponse>;
     /**
-     * Gets the block information
+     * Gets the header and the transaction hashes of a block (RPC `starknet_getBlockWithTxHashes`).
      *
-     * @returns the block object
+     * The response contains the block metadata (hash, number, parent hash, timestamp, status,
+     * gas prices, sequencer address, ...) plus a `transactions` array holding only the **hashes**
+     * of the transactions included in the block — not their content.
+     * To get the full transactions use {@link getBlockWithTxs}, and for their receipts use
+     * {@link getBlockWithReceipts}.
+     *
+     * @param blockIdentifier - which block to fetch. Accepts:
+     * - a block number: `number` or decimal `string` (e.g. `123456`)
+     * - a block hash: hex `string` or `bigint` (e.g. `'0x3a1b...'`)
+     * - a block tag `string`:
+     *   - `'latest'` — the most recent block already accepted on L2
+     *   - `'pre_confirmed'` — the block currently being built, not yet closed (its fields differ:
+     *     no `block_hash`/`status`, hence the dedicated {@link PreConfirmedBlock} return type)
+     * - `null` — resolved as the `'latest'` tag
+     *
+     * When omitted, the provider's default block identifier is used (`'latest'`).
+     *
+     * @returns the block header together with the list of its transaction hashes
+     *
+     * @example
+     * ```typescript
+     * const block = await provider.getBlock('latest');
+     * // {
+     * //   status: 'ACCEPTED_ON_L2',
+     * //   block_hash: '0x3a1b...',
+     * //   block_number: 123456,
+     * //   parent_hash: '0x28f5...',
+     * //   timestamp: 1700000000,
+     * //   sequencer_address: '0x1176a1...',
+     * //   transactions: ['0x1d2c...', '0x5e8f...'],  // transaction hashes only
+     * //   ...
+     * // }
+     *
+     * // By block number or hash:
+     * await provider.getBlock(123456);
+     * await provider.getBlock('0x3a1b...');
+     *
+     * // Block still being built (fields differ from a closed block):
+     * const pending = await provider.getBlock('pre_confirmed');
+     * ```
      */
-    abstract getBlock(): Promise<PreConfirmedBlock>;
+    abstract getBlock(): Promise<Block$1>;
     abstract getBlock(blockIdentifier: 'pre_confirmed'): Promise<PreConfirmedBlock>;
     abstract getBlock(blockIdentifier: 'latest'): Promise<Block$1>;
     abstract getBlock(blockIdentifier: BlockIdentifier): Promise<GetBlockResponse>;
@@ -5006,6 +5045,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 +5145,7 @@ declare class WebSocketChannel {
     private reconnectAttempts;
     private userInitiatedClose;
     private reconnectTimeoutId;
+    private reconnectStabilityTimeoutId;
     private requestQueue;
     private events;
     private openListener;
@@ -5192,6 +5240,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;
@@ -5543,7 +5598,7 @@ declare class RpcProvider implements ProviderInterface {
     setUpSpecVersion(): Promise<"0.9.0" | "0.10.0" | "0.10.2" | "0.10.3">;
     getStarknetVersion(blockIdentifier?: BlockIdentifier): Promise<string>;
     getNonceForAddress(contractAddress: BigNumberish, blockIdentifier?: BlockIdentifier): Promise<string>;
-    getBlock(): Promise<PreConfirmedBlock>;
+    getBlock(): Promise<Block$1>;
     getBlock(blockIdentifier: 'pre_confirmed'): Promise<PreConfirmedBlock>;
     getBlock(blockIdentifier: 'latest'): Promise<Block$1>;
     getBlock(blockIdentifier: BlockIdentifier): Promise<GetBlockResponse>;

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"));