starknet 7.5.0 → 7.5.1

package/dist/index.global.js

@@ -38,7 +38,6 @@ var starknet = (() => {
     Contract: () => Contract,
     ContractFactory: () => ContractFactory,
     ContractInterface: () => ContractInterface,
-    CustomError: () => CustomError,
     EDAMode: () => EDAMode3,
     EDataAvailabilityMode: () => EDataAvailabilityMode3,
     ETH_ADDRESS: () => ETH_ADDRESS,
@@ -75,6 +74,8 @@ var starknet = (() => {
     RpcProvider: () => RpcProvider2,
     Signer: () => Signer,
     SignerInterface: () => SignerInterface,
+    Subscription: () => Subscription,
+    TimeoutError: () => TimeoutError,
     TransactionExecutionStatus: () => TransactionExecutionStatus,
     TransactionFinalityStatus: () => TransactionFinalityStatus,
     TransactionType: () => TransactionType,
@@ -91,9 +92,9 @@ var starknet = (() => {
     UINT_512_MIN: () => UINT_512_MIN,
     Uint: () => Uint,
     ValidateType: () => ValidateType,
-    WSSubscriptions: () => WSSubscriptions,
     WalletAccount: () => WalletAccount,
     WebSocketChannel: () => WebSocketChannel,
+    WebSocketNotConnectedError: () => WebSocketNotConnectedError,
     addAddressPadding: () => addAddressPadding,
     byteArray: () => byteArray_exports,
     cairo: () => cairo_exports,
@@ -107,8 +108,6 @@ var starknet = (() => {
     eth: () => eth_exports,
     events: () => events_exports,
     extractContractHashes: () => extractContractHashes,
-    fixProto: () => fixProto,
-    fixStack: () => fixStack,
     getCalldata: () => getCalldata,
     getChecksumAddress: () => getChecksumAddress,
     getLedgerPathBuffer: () => getLedgerPathBuffer111,
@@ -12047,6 +12046,18 @@ ${indent}}` : "}";
       return rpc_default[typeName] === this.code;
     }
   };
+  var TimeoutError = class extends LibraryError {
+    constructor(message) {
+      super(message);
+      this.name = "TimeoutError";
+    }
+  };
+  var WebSocketNotConnectedError = class extends LibraryError {
+    constructor(message) {
+      super(message);
+      this.name = "WebSocketNotConnectedError";
+    }
+  };
 
   // src/utils/eth.ts
   var eth_exports = {};
@@ -13615,6 +13626,31 @@ ${indent}}` : "}";
     }
   };
 
+  // src/utils/eventEmitter.ts
+  var EventEmitter = class {
+    listeners = {};
+    on(event, listener) {
+      if (!this.listeners[event]) {
+        this.listeners[event] = [];
+      }
+      this.listeners[event].push(listener);
+    }
+    off(event, listener) {
+      if (!this.listeners[event]) {
+        return;
+      }
+      this.listeners[event] = this.listeners[event].filter((l) => l !== listener);
+    }
+    emit(event, data) {
+      if (this.listeners[event]) {
+        this.listeners[event].forEach((listener) => listener(data));
+      }
+    }
+    clear() {
+      this.listeners = {};
+    }
+  };
+
   // src/utils/connect/ws.ts
   var ws_default = typeof WebSocket !== "undefined" && WebSocket || typeof globalThis !== "undefined" && globalThis.WebSocket || typeof window !== "undefined" && window.WebSocket.bind(window) || typeof global !== "undefined" && global.WebSocket || class {
     constructor() {
@@ -13624,152 +13660,184 @@ ${indent}}` : "}";
     }
   };
 
-  // src/channel/ws_0_8.ts
-  var WSSubscriptions = {
-    NEW_HEADS: "newHeads",
-    EVENTS: "events",
-    TRANSACTION_STATUS: "transactionStatus",
-    PENDING_TRANSACTION: "pendingTransactions"
-  };
-  var WebSocketChannel = class {
-    /**
-     * WebSocket RPC Node URL
-     * @example 'wss://starknet-node.io/rpc/v0_8'
-     */
-    nodeUrl;
-    // public headers: object;
-    // readonly retries: number;
-    // public requestId: number;
-    // readonly blockIdentifier: BlockIdentifier;
-    // private chainId?: StarknetChainId;
-    // private specVersion?: string;
-    // private transactionRetryIntervalFallback?: number;
-    // readonly waitMode: Boolean; // behave like web2 rpc and return when tx is processed
-    // private batchClient?: BatchClient;
+  // src/channel/ws/subscription.ts
+  var Subscription = class {
     /**
-     * ws library object
+     * The containing `WebSocketChannel` instance.
+     * @internal
      */
-    websocket;
+    channel;
     /**
-     * Assign implementation method to get 'on reorg event data'
-     * @example
-     * ```typescript
-     * webSocketChannel.onReorg = async function (data) {
-     *  // ... do something when reorg happens
-     * }
-     * ```
+     * The JSON-RPC method used to create this subscription.
+     * @internal
      */
-    onReorg = () => {
-    };
+    method;
     /**
-     * Assign implementation method to get 'starknet block heads'
-     * @example
-     * ```typescript
-     * webSocketChannel.onNewHeads = async function (data) {
-     *  // ... do something with head data
-     * }
-     * ```
+     * The parameters used to create this subscription.
+     * @internal
      */
-    onNewHeads = () => {
-    };
+    params;
     /**
-     * Assign implementation method to get 'starknet events'
-     * @example
-     * ```typescript
-     * webSocketChannel.onEvents = async function (data) {
-     *  // ... do something with event data
-     * }
-     * ```
+     * The unique identifier for this subscription.
+     * @internal
      */
-    onEvents = () => {
-    };
+    id;
+    events = new EventEmitter();
+    buffer = [];
+    maxBufferSize;
+    handler = null;
+    _isClosed = false;
     /**
-     * Assign method to get 'starknet transactions status'
-     * @example
-     * ```typescript
-     * webSocketChannel.onTransactionStatus = async function (data) {
-     *  // ... do something with tx status data
-     * }
-     * ```
+     * @internal
+     * @param {WebSocketChannel} channel - The WebSocketChannel instance.
+     * @param {string} method - The RPC method used for the subscription.
+     * @param {any} params - The parameters for the subscription.
+     * @param {SUBSCRIPTION_ID} id - The subscription ID.
+     * @param {number} maxBufferSize - The maximum number of events to buffer.
      */
-    onTransactionStatus = () => {
-    };
+    constructor(channel, method, params, id, maxBufferSize) {
+      this.channel = channel;
+      this.method = method;
+      this.params = params;
+      this.id = id;
+      this.maxBufferSize = maxBufferSize;
+    }
     /**
-     * Assign implementation method to get 'starknet pending transactions (mempool)'
-     * @example
-     * ```typescript
-     * webSocketChannel.onPendingTransaction = async function (data) {
-     *  // ... do something with pending tx data
-     * }
-     * ```
+     * Indicates if the subscription has been closed.
+     * @returns {boolean} `true` if unsubscribed, `false` otherwise.
      */
-    onPendingTransaction = () => {
-    };
+    get isClosed() {
+      return this._isClosed;
+    }
     /**
-     * Assign implementation to this method to listen open Event
+     * Internal method to handle incoming events from the WebSocket channel.
+     * If a handler is attached, it's invoked immediately. Otherwise, the event is buffered.
+     * @internal
+     * @param {T} data - The event data.
      */
-    onOpen = () => {
-    };
+    _handleEvent(data) {
+      if (this.handler) {
+        this.handler(data);
+      } else {
+        if (this.buffer.length >= this.maxBufferSize) {
+          const droppedEvent = this.buffer.shift();
+          logger.warn(`Subscription ${this.id}: Buffer full. Dropping oldest event:`, droppedEvent);
+        }
+        this.buffer.push(data);
+      }
+    }
     /**
-     * Assign implementation to this method to listen close CloseEvent
+     * Attaches a handler function to be called for each event.
+     *
+     * When a handler is attached, any buffered events will be passed to it sequentially.
+     * Subsequent events will be passed directly as they arrive.
+     *
+     * @param {(data: T) => void} handler - The function to call with event data.
+     * @throws {Error} If a handler is already attached to this subscription.
      */
-    onClose = () => {
-    };
+    on(handler) {
+      if (this.handler) {
+        throw new Error("A handler is already attached to this subscription.");
+      }
+      this.handler = handler;
+      while (this.buffer.length > 0) {
+        const event = this.buffer.shift();
+        if (event) {
+          this.handler(event);
+        }
+      }
+    }
     /**
-     * Assign implementation to this method to listen message MessageEvent
+     * Sends an unsubscribe request to the node and cleans up local resources.
+     * @returns {Promise<boolean>} A Promise that resolves to `true` if the unsubscription was successful.
      */
-    onMessage = () => {
-    };
+    async unsubscribe() {
+      if (this._isClosed) {
+        return true;
+      }
+      const success = await this.channel.unsubscribe(this.id);
+      if (success) {
+        this._isClosed = true;
+        this.channel.removeSubscription(this.id);
+        this.events.emit("unsubscribe", void 0);
+        this.events.clear();
+      }
+      return success;
+    }
+  };
+
+  // src/channel/ws/ws_0_8.ts
+  var WebSocketChannel = class {
     /**
-     * Assign implementation to this method to listen error Event
+     * The URL of the WebSocket RPC Node.
+     * @example 'wss://starknet-sepolia.public.blastapi.io/rpc/v0_8'
      */
-    onError = () => {
-    };
+    nodeUrl;
     /**
-     * Assign implementation to this method to listen unsubscription
+     * The underlying WebSocket instance.
      */
-    onUnsubscribe = () => {
-    };
-    onUnsubscribeLocal = () => {
-    };
+    websocket;
+    // Store the WebSocket implementation class to allow for custom implementations.
+    WsImplementation;
+    // Map of active subscriptions, keyed by their ID.
+    activeSubscriptions = /* @__PURE__ */ new Map();
+    maxBufferSize;
+    autoReconnect;
+    reconnectOptions;
+    requestTimeout;
+    isReconnecting = false;
+    reconnectAttempts = 0;
+    userInitiatedClose = false;
+    reconnectTimeoutId = null;
+    requestQueue = [];
+    events = new EventEmitter();
+    openListener = (ev) => this.events.emit("open", ev);
+    closeListener = this.onCloseProxy.bind(this);
+    messageListener = this.onMessageProxy.bind(this);
+    errorListener = (ev) => this.events.emit("error", ev);
     /**
-     * JSON RPC latest sent message id
-     * expecting receiving message to contain same id
+     * JSON RPC latest sent message ID.
+     * The receiving message is expected to contain the same ID.
      */
     sendId = 0;
     /**
-     * subscriptions ids
-     * mapped by keys WSSubscriptions
+     * Creates an instance of WebSocketChannel.
+     * @param {WebSocketOptions} options - The options for configuring the channel.
      */
-    subscriptions = /* @__PURE__ */ new Map();
-    /**
-     * Construct class and event listeners
-     * @param options WebSocketOptions
-     */
-    constructor(options = {}) {
-      const nodeUrl = options.nodeUrl || "http://localhost:3000 ";
-      this.nodeUrl = options.websocket ? options.websocket.url : nodeUrl;
-      this.websocket = options.websocket || config.get("websocket") || new ws_default(nodeUrl);
-      this.websocket.addEventListener("open", this.onOpen.bind(this));
-      this.websocket.addEventListener("close", this.onCloseProxy.bind(this));
-      this.websocket.addEventListener("message", this.onMessageProxy.bind(this));
-      this.websocket.addEventListener("error", this.onError.bind(this));
+    constructor(options) {
+      this.nodeUrl = options.nodeUrl;
+      this.maxBufferSize = options.maxBufferSize ?? 1e3;
+      this.autoReconnect = options.autoReconnect ?? true;
+      this.reconnectOptions = {
+        retries: options.reconnectOptions?.retries ?? 5,
+        delay: options.reconnectOptions?.delay ?? 2e3
+      };
+      this.requestTimeout = options.requestTimeout ?? 6e4;
+      this.WsImplementation = options.websocket || config.get("websocket") || ws_default;
+      this.websocket = new this.WsImplementation(this.nodeUrl);
+      this.websocket.addEventListener("open", this.openListener);
+      this.websocket.addEventListener("close", this.closeListener);
+      this.websocket.addEventListener("message", this.messageListener);
+      this.websocket.addEventListener("error", this.errorListener);
     }
     idResolver(id) {
       if (id) return id;
       return this.sendId++;
     }
     /**
-     * Send data over open ws connection
-     * * this would only send data on the line without awaiting 'response message'
-     * @example
-     * ```typescript
-     * const sentId = await this.send('starknet_method', params);
-     * ```
+     * Sends a JSON-RPC request over the WebSocket connection without waiting for a response.
+     * This is a low-level method. Prefer `sendReceive` for most use cases.
+     * @param {string} method - The RPC method name.
+     * @param {object} [params] - The parameters for the RPC method.
+     * @param {number} [id] - A specific request ID. If not provided, an auto-incrementing ID is used.
+     * @returns {number} The ID of the sent request.
+     * @throws {WebSocketNotConnectedError} If the WebSocket is not connected.
      */
     send(method, params, id) {
       if (!this.isConnected()) {
-        throw Error("WebSocketChannel.send() fail due to socket disconnected");
+        throw new WebSocketNotConnectedError(
+          "WebSocketChannel.send() failed due to socket being disconnected"
+        );
       }
       const usedId = this.idResolver(id);
       const rpcRequestBody = {
@@ -13782,50 +13850,88 @@ ${indent}}` : "}";
       return usedId;
     }
     /**
-     * Any Starknet method not just websocket override
-     */
-    sendReceiveAny(method, params) {
-      return this.sendReceive(method, params);
-    }
-    /**
-     * Send request and receive response over ws line
-     * This method abstract ws messages into request/response model
-     * @param method rpc method name
-     * @param params rpc method parameters
-     * @example
-     * ```typescript
-     * const response = await this.sendReceive('starknet_method', params);
-     * ```
+     * Sends a JSON-RPC request and returns a Promise that resolves with the result.
+     * This method abstracts the request/response cycle over WebSockets.
+     * If the connection is lost, it will queue the request and send it upon reconnection.
+     * @template T - The expected type of the result.
+     * @param {string} method - The RPC method name.
+     * @param {object} [params] - The parameters for the RPC method.
+     * @returns {Promise<T>} A Promise that resolves with the RPC response result.
+     * @throws {TimeoutError} If the request does not receive a response within the configured `requestTimeout`.
+     * @throws {WebSocketNotConnectedError} If the WebSocket is not connected and auto-reconnect is disabled.
      */
     sendReceive(method, params) {
+      if (this.isReconnecting || !this.isConnected() && this.autoReconnect && !this.userInitiatedClose) {
+        logger.info(`WebSocket: Connection unavailable, queueing request: ${method}`);
+        return new Promise((resolve, reject) => {
+          this.requestQueue.push({ method, params, resolve, reject });
+        });
+      }
       const sendId = this.send(method, params);
       return new Promise((resolve, reject) => {
-        if (!this.websocket) return;
-        this.websocket.onmessage = ({ data }) => {
-          const message = JSON.parse(data);
+        let timeoutId;
+        if (!this.websocket || this.websocket.readyState !== ws_default.OPEN) {
+          reject(new WebSocketNotConnectedError("WebSocket not available or not connected."));
+          return;
+        }
+        const messageHandler = (event) => {
+          if (!isString(event.data)) {
+            logger.warn("WebSocket received non-string message data:", event.data);
+            return;
+          }
+          const message = JSON.parse(event.data);
           if (message.id === sendId) {
+            clearTimeout(timeoutId);
+            this.websocket.removeEventListener("message", messageHandler);
+            this.websocket.removeEventListener("error", errorHandler);
             if ("result" in message) {
               resolve(message.result);
             } else {
-              reject(Error(`error on ${method}, ${message.error}`));
+              reject(
+                new Error(`Error on ${method} (id: ${sendId}): ${JSON.stringify(message.error)}`)
+              );
             }
           }
         };
-        this.websocket.onerror = reject;
+        const errorHandler = (event) => {
+          clearTimeout(timeoutId);
+          this.websocket.removeEventListener("message", messageHandler);
+          this.websocket.removeEventListener("error", errorHandler);
+          reject(
+            new Error(
+              `WebSocket error during ${method} (id: ${sendId}): ${event.type || "Unknown error"}`
+            )
+          );
+        };
+        this.websocket.addEventListener("message", messageHandler);
+        this.websocket.addEventListener("error", errorHandler);
+        timeoutId = setTimeout(() => {
+          this.websocket.removeEventListener("message", messageHandler);
+          this.websocket.removeEventListener("error", errorHandler);
+          reject(
+            new TimeoutError(
+              `Request ${method} (id: ${sendId}) timed out after ${this.requestTimeout}ms`
+            )
+          );
+        }, this.requestTimeout);
       });
     }
     /**
-     * Helper to check connection is open
+     * Checks if the WebSocket connection is currently open.
+     * @returns {boolean} `true` if the connection is open, `false` otherwise.
      */
     isConnected() {
       return this.websocket.readyState === ws_default.OPEN;
     }
     /**
-     * await while websocket is connected
-     * * could be used to block the flow until websocket is open
+     * Returns a Promise that resolves when the WebSocket connection is open.
+     * Can be used to block execution until the connection is established.
+     * @returns {Promise<number>} A Promise that resolves with the WebSocket's `readyState` when connected.
      * @example
      * ```typescript
-     * const readyState = await webSocketChannel.waitForConnection();
+     * const channel = new WebSocketChannel({ nodeUrl: '...' });
+     * await channel.waitForConnection();
+     * console.log('Connected!');
      * ```
      */
     async waitForConnection() {
@@ -13841,17 +13947,22 @@ ${indent}}` : "}";
       return this.websocket.readyState;
     }
     /**
-     * Disconnect the WebSocket connection, optionally using code as the the WebSocket connection close code and reason as the the WebSocket connection close reason.
+     * Closes the WebSocket connection.
+     * This method is user-initiated and will prevent automatic reconnection for this closure.
+     * @param {number} [code] - The WebSocket connection close code.
+     * @param {string} [reason] - The WebSocket connection close reason.
      */
     disconnect(code, reason) {
+      if (this.reconnectTimeoutId) {
+        clearTimeout(this.reconnectTimeoutId);
+        this.reconnectTimeoutId = null;
+      }
       this.websocket.close(code, reason);
+      this.userInitiatedClose = true;
     }
     /**
-     * await while websocket is disconnected
-     * @example
-     * ```typescript
-     * const readyState = await webSocketChannel.waitForDisconnection();
-     * ```
+     * Returns a Promise that resolves when the WebSocket connection is closed.
+     * @returns {Promise<number | Event>} A Promise that resolves with the WebSocket's `readyState` or a `CloseEvent` when disconnected.
      */
     async waitForDisconnection() {
       if (this.websocket.readyState !== ws_default.CLOSED) {
@@ -13864,206 +13975,233 @@ ${indent}}` : "}";
       return this.websocket.readyState;
     }
     /**
-     * Unsubscribe from starknet subscription
-     * @param subscriptionId
-     * @param ref internal usage, only for managed subscriptions
+     * Unsubscribes from a Starknet subscription.
+     * It is recommended to use the `unsubscribe()` method on the `Subscription` object instead.
+     * @internal
+     * @param {SUBSCRIPTION_ID} subscriptionId - The ID of the subscription to unsubscribe from.
+     * @returns {Promise<boolean>} A Promise that resolves with `true` if the unsubscription was successful.
      */
-    async unsubscribe(subscriptionId, ref) {
+    async unsubscribe(subscriptionId) {
       const status = await this.sendReceive("starknet_unsubscribe", {
         subscription_id: subscriptionId
       });
       if (status) {
-        if (ref) {
-          this.subscriptions.delete(ref);
-        }
-        this.onUnsubscribeLocal(subscriptionId);
-        this.onUnsubscribe(subscriptionId);
+        this.events.emit("unsubscribe", subscriptionId);
       }
       return status;
     }
     /**
-     * await while subscription is unsubscribed
-     * @param forSubscriptionId if defined trigger on subscriptionId else trigger on any
-     * @returns subscriptionId | onerror(Event)
+     * Returns a Promise that resolves when a specific subscription is successfully unsubscribed.
+     * @param {SUBSCRIPTION_ID} targetId - The ID of the subscription to wait for.
+     * @returns {Promise<void>}
      * @example
      * ```typescript
-     * const subscriptionId = await webSocketChannel.waitForUnsubscription();
+     * await channel.waitForUnsubscription(mySubscription.id);
+     * console.log('Successfully unsubscribed.');
      * ```
      */
-    async waitForUnsubscription(forSubscriptionId) {
-      return new Promise((resolve, reject) => {
-        if (!this.websocket) return;
-        this.onUnsubscribeLocal = (subscriptionId) => {
-          if (forSubscriptionId === void 0) {
-            resolve(subscriptionId);
-          } else if (subscriptionId === forSubscriptionId) {
-            resolve(subscriptionId);
+    waitForUnsubscription(targetId) {
+      return new Promise((resolve) => {
+        const listener = (unsubId) => {
+          if (unsubId === targetId) {
+            this.events.off("unsubscribe", listener);
+            resolve();
           }
         };
-        this.websocket.onerror = reject;
+        this.events.on("unsubscribe", listener);
       });
     }
     /**
-     * Reconnect re-create this.websocket instance
+     * Manually initiates a reconnection attempt.
+     * This creates a new WebSocket instance and re-establishes listeners.
      */
     reconnect() {
-      this.websocket = new ws_default(this.nodeUrl);
-      this.websocket.addEventListener("open", this.onOpen.bind(this));
-      this.websocket.addEventListener("close", this.onCloseProxy.bind(this));
-      this.websocket.addEventListener("message", this.onMessageProxy.bind(this));
-      this.websocket.addEventListener("error", this.onError.bind(this));
+      this.userInitiatedClose = false;
+      this.websocket = new this.WsImplementation(this.nodeUrl);
+      this.websocket.addEventListener("open", this.openListener);
+      this.websocket.addEventListener("close", this.closeListener);
+      this.websocket.addEventListener("message", this.messageListener);
+      this.websocket.addEventListener("error", this.errorListener);
+    }
+    _processRequestQueue() {
+      logger.info(`WebSocket: Processing ${this.requestQueue.length} queued requests.`);
+      while (this.requestQueue.length > 0) {
+        const { method, params, resolve, reject } = this.requestQueue.shift();
+        this.sendReceive(method, params).then(resolve).catch(reject);
+      }
+    }
+    async _restoreSubscriptions() {
+      const oldSubscriptions = Array.from(this.activeSubscriptions.values());
+      this.activeSubscriptions.clear();
+      const restorePromises = oldSubscriptions.map(async (sub) => {
+        try {
+          const newSubId = await this.sendReceive(sub.method, sub.params);
+          sub.id = newSubId;
+          this.activeSubscriptions.set(newSubId, sub);
+          logger.info(`Subscription ${sub.method} restored with new ID: ${newSubId}`);
+        } catch (error) {
+          logger.error(`Failed to restore subscription ${sub.method}:`, error);
+        }
+      });
+      await Promise.all(restorePromises);
     }
-    // TODO: Add/Test ping service. It seems this work out of the box from pathfinder. If net disc. it will auto replay.
-    reconnectAndUpdate() {
-      this.reconnect();
+    _startReconnect() {
+      if (this.isReconnecting || !this.autoReconnect) {
+        return;
+      }
+      this.isReconnecting = true;
+      this.reconnectAttempts = 0;
+      const tryReconnect = () => {
+        if (this.reconnectAttempts >= this.reconnectOptions.retries) {
+          logger.error("WebSocket: Maximum reconnection retries reached. Giving up.");
+          this.isReconnecting = false;
+          return;
+        }
+        this.reconnectAttempts += 1;
+        logger.info(
+          `WebSocket: Connection lost. Attempting to reconnect... (${this.reconnectAttempts}/${this.reconnectOptions.retries})`
+        );
+        this.reconnect();
+        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"));
+        };
+        this.websocket.onerror = () => {
+          const delay = this.reconnectOptions.delay * 2 ** (this.reconnectAttempts - 1);
+          logger.info(`WebSocket: Reconnect attempt failed. Retrying in ${delay}ms.`);
+          this.reconnectTimeoutId = setTimeout(tryReconnect, delay);
+        };
+      };
+      tryReconnect();
     }
     onCloseProxy(ev) {
-      this.websocket.removeEventListener("open", this.onOpen);
-      this.websocket.removeEventListener("close", this.onCloseProxy);
-      this.websocket.removeEventListener("message", this.onMessageProxy);
-      this.websocket.removeEventListener("error", this.onError);
-      this.onClose(ev);
+      this.websocket.removeEventListener("open", this.openListener);
+      this.websocket.removeEventListener("close", this.closeListener);
+      this.websocket.removeEventListener("message", this.messageListener);
+      this.websocket.removeEventListener("error", this.errorListener);
+      this.events.emit("close", ev);
+      if (!this.userInitiatedClose) {
+        this._startReconnect();
+      }
     }
     onMessageProxy(event) {
-      const message = JSON.parse(event.data);
-      const eventName = message.method;
-      switch (eventName) {
-        case "starknet_subscriptionReorg":
-          this.onReorg(message.params);
-          break;
-        case "starknet_subscriptionNewHeads":
-          this.onNewHeads(message.params);
-          break;
-        case "starknet_subscriptionEvents":
-          this.onEvents(message.params);
-          break;
-        case "starknet_subscriptionTransactionStatus":
-          this.onTransactionStatus(message.params);
-          break;
-        case "starknet_subscriptionPendingTransactions":
-          this.onPendingTransaction(message.params);
-          break;
-        default:
-          break;
+      let message;
+      try {
+        message = JSON.parse(event.data);
+      } catch (error) {
+        logger.error(
+          `WebSocketChannel: Error parsing incoming message: ${event.data}, Error: ${error}`
+        );
+        return;
       }
-      this.onMessage(event);
-    }
-    /**
-     * subscribe to new block heads
-     * * you can subscribe to this event multiple times and you need to manage subscriptions manually
-     */
-    subscribeNewHeadsUnmanaged(blockIdentifier) {
-      const block_id = blockIdentifier ? new Block(blockIdentifier).identifier : void 0;
-      return this.sendReceive("starknet_subscribeNewHeads", {
-        ...{ block_id }
-      });
+      if (message.method && isObject2(message.params) && "subscription_id" in message.params) {
+        const { result, subscription_id } = message.params;
+        const subscription = this.activeSubscriptions.get(subscription_id);
+        if (subscription) {
+          subscription._handleEvent(result);
+        } else {
+          logger.warn(
+            `WebSocketChannel: Received event for untracked subscription ID: ${subscription_id}.`
+          );
+        }
+      }
+      logger.debug("onMessageProxy:", event.data);
+      this.events.emit("message", event);
     }
     /**
-     * subscribe to new block heads
+     * Subscribes to new block headers.
+     * @param {SubscriptionBlockIdentifier} [blockIdentifier] - The block to start receiving notifications from. Defaults to 'latest'.
+     * @returns {Promise<Subscription<BLOCK_HEADER>>} A Promise that resolves with a `Subscription` object for new block headers.
      */
     async subscribeNewHeads(blockIdentifier) {
-      if (this.subscriptions.get(WSSubscriptions.NEW_HEADS)) return false;
-      const subId = await this.subscribeNewHeadsUnmanaged(blockIdentifier);
-      this.subscriptions.set(WSSubscriptions.NEW_HEADS, subId);
-      return subId;
-    }
-    /**
-     * Unsubscribe newHeads subscription
-     */
-    async unsubscribeNewHeads() {
-      const subId = this.subscriptions.get(WSSubscriptions.NEW_HEADS);
-      if (!subId) throw Error("There is no subscription on this event");
-      return this.unsubscribe(subId, WSSubscriptions.NEW_HEADS);
-    }
-    /**
-     * subscribe to 'starknet events'
-     * * you can subscribe to this event multiple times and you need to manage subscriptions manually
-     */
-    subscribeEventsUnmanaged(fromAddress, keys, blockIdentifier) {
-      const block_id = blockIdentifier ? new Block(blockIdentifier).identifier : void 0;
-      return this.sendReceive("starknet_subscribeEvents", {
-        ...{ from_address: fromAddress !== void 0 ? toHex(fromAddress) : void 0 },
-        ...{ keys },
-        ...{ block_id }
-      });
+      const method = "starknet_subscribeNewHeads";
+      const params = {
+        block_id: blockIdentifier ? new Block(blockIdentifier).identifier : void 0
+      };
+      const subId = await this.sendReceive(method, params);
+      const subscription = new Subscription(this, method, params, subId, this.maxBufferSize);
+      this.activeSubscriptions.set(subId, subscription);
+      return subscription;
     }
     /**
-     * subscribe to 'starknet events'
+     * Subscribes to events matching a given filter.
+     * @param {BigNumberish} [fromAddress] - The contract address to filter by.
+     * @param {string[][]} [keys] - The event keys to filter by.
+     * @param {SubscriptionBlockIdentifier} [blockIdentifier] - The block to start receiving notifications from. Defaults to 'latest'.
+     * @returns {Promise<Subscription<EMITTED_EVENT>>} A Promise that resolves with a `Subscription` object for the specified events.
      */
     async subscribeEvents(fromAddress, keys, blockIdentifier) {
-      if (this.subscriptions.get(WSSubscriptions.EVENTS)) return false;
-      const subId = await this.subscribeEventsUnmanaged(fromAddress, keys, blockIdentifier);
-      this.subscriptions.set(WSSubscriptions.EVENTS, subId);
-      return subId;
-    }
-    /**
-     * Unsubscribe 'starknet events' subscription
-     */
-    unsubscribeEvents() {
-      const subId = this.subscriptions.get(WSSubscriptions.EVENTS);
-      if (!subId) throw Error("There is no subscription ID for this event");
-      return this.unsubscribe(subId, WSSubscriptions.EVENTS);
-    }
-    /**
-     * subscribe to transaction status
-     * * you can subscribe to this event multiple times and you need to manage subscriptions manually
-     */
-    subscribeTransactionStatusUnmanaged(transactionHash, blockIdentifier) {
-      const transaction_hash = toHex(transactionHash);
-      const block_id = blockIdentifier ? new Block(blockIdentifier).identifier : void 0;
-      return this.sendReceive("starknet_subscribeTransactionStatus", {
-        transaction_hash,
-        ...{ block_id }
-      });
+      const method = "starknet_subscribeEvents";
+      const params = {
+        from_address: fromAddress !== void 0 ? toHex(fromAddress) : void 0,
+        keys,
+        block_id: blockIdentifier ? new Block(blockIdentifier).identifier : void 0
+      };
+      const subId = await this.sendReceive(method, params);
+      const subscription = new Subscription(this, method, params, subId, this.maxBufferSize);
+      this.activeSubscriptions.set(subId, subscription);
+      return subscription;
     }
     /**
-     * subscribe to transaction status
+     * Subscribes to status updates for a specific transaction.
+     * @param {BigNumberish} transactionHash - The hash of the transaction to monitor.
+     * @param {SubscriptionBlockIdentifier} [blockIdentifier] - The block context. Not typically required.
+     * @returns {Promise<Subscription<NEW_TXN_STATUS>>} A Promise that resolves with a `Subscription` object for the transaction's status.
      */
-    async subscribeTransactionStatus(transactionHash) {
-      if (this.subscriptions.get(WSSubscriptions.TRANSACTION_STATUS)) return false;
-      const subId = await this.subscribeTransactionStatusUnmanaged(transactionHash);
-      this.subscriptions.set(WSSubscriptions.TRANSACTION_STATUS, subId);
-      return subId;
+    async subscribeTransactionStatus(transactionHash, blockIdentifier) {
+      const method = "starknet_subscribeTransactionStatus";
+      const params = {
+        transaction_hash: toHex(transactionHash),
+        block_id: blockIdentifier ? new Block(blockIdentifier).identifier : void 0
+      };
+      const subId = await this.sendReceive(method, params);
+      const subscription = new Subscription(this, method, params, subId, this.maxBufferSize);
+      this.activeSubscriptions.set(subId, subscription);
+      return subscription;
     }
     /**
-     * unsubscribe 'transaction status' subscription
+     * Subscribes to pending transactions.
+     * @param {boolean} [transactionDetails] - If `true`, the full transaction details are included. Defaults to `false` (hash only).
+     * @param {BigNumberish[]} [senderAddress] - An array of sender addresses to filter by.
+     * @returns {Promise<Subscription<TXN_HASH | TXN_WITH_HASH>>} A Promise that resolves with a `Subscription` object for pending transactions.
      */
-    async unsubscribeTransactionStatus() {
-      const subId = this.subscriptions.get(WSSubscriptions.TRANSACTION_STATUS);
-      if (!subId) throw Error("There is no subscription ID for this event");
-      return this.unsubscribe(subId, WSSubscriptions.TRANSACTION_STATUS);
+    async subscribePendingTransaction(transactionDetails, senderAddress) {
+      const method = "starknet_subscribePendingTransactions";
+      const params = {
+        transaction_details: transactionDetails,
+        sender_address: senderAddress && bigNumberishArrayToHexadecimalStringArray(senderAddress)
+      };
+      const subId = await this.sendReceive(method, params);
+      const subscription = new Subscription(this, method, params, subId, this.maxBufferSize);
+      this.activeSubscriptions.set(subId, subscription);
+      return subscription;
     }
     /**
-     * subscribe to pending transactions (mempool)
-     * * you can subscribe to this event multiple times and you need to manage subscriptions manually
+     * Internal method to remove subscription from active map.
+     * @internal
      */
-    subscribePendingTransactionUnmanaged(transactionDetails, senderAddress) {
-      return this.sendReceive("starknet_subscribePendingTransactions", {
-        ...{ transaction_details: transactionDetails },
-        ...{
-          sender_address: senderAddress && bigNumberishArrayToHexadecimalStringArray(senderAddress)
-        }
-      });
+    removeSubscription(id) {
+      this.activeSubscriptions.delete(id);
     }
     /**
-     * subscribe to pending transactions (mempool)
+     * Adds a listener for a given event.
+     * @param event The event name.
+     * @param listener The listener function to add.
      */
-    async subscribePendingTransaction(transactionDetails, senderAddress) {
-      if (this.subscriptions.get(WSSubscriptions.TRANSACTION_STATUS)) return false;
-      const subId = await this.subscribePendingTransactionUnmanaged(
-        transactionDetails,
-        senderAddress
-      );
-      this.subscriptions.set(WSSubscriptions.PENDING_TRANSACTION, subId);
-      return subId;
+    on(event, listener) {
+      this.events.on(event, listener);
     }
     /**
-     * unsubscribe 'pending transaction' subscription
+     * Removes a listener for a given event.
+     * @param event The event name.
+     * @param listener The listener function to remove.
      */
-    async unsubscribePendingTransaction() {
-      const subId = this.subscriptions.get(WSSubscriptions.PENDING_TRANSACTION);
-      if (!subId) throw Error("There is no subscription ID for this event");
-      return this.unsubscribe(subId, WSSubscriptions.PENDING_TRANSACTION);
+    off(event, listener) {
+      this.events.off(event, listener);
     }
   };