starknet 7.5.0 → 7.5.1

package/dist/index.mjs

@@ -3843,6 +3843,18 @@ var RpcError = class extends LibraryError {
     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 = {};
@@ -5330,6 +5342,31 @@ var RpcChannel2 = class {
   }
 };
 
+// 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() {
@@ -5339,152 +5376,184 @@ var ws_default = typeof WebSocket !== "undefined" && WebSocket || typeof globalT
   }
 };
 
-// src/channel/ws_0_8.ts
-var WSSubscriptions = {
-  NEW_HEADS: "newHeads",
-  EVENTS: "events",
-  TRANSACTION_STATUS: "transactionStatus",
-  PENDING_TRANSACTION: "pendingTransactions"
-};
-var WebSocketChannel = class {
+// src/channel/ws/subscription.ts
+var Subscription = class {
   /**
-   * WebSocket RPC Node URL
-   * @example 'wss://starknet-node.io/rpc/v0_8'
+   * The containing `WebSocketChannel` instance.
+   * @internal
    */
-  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;
-  /**
-   * ws library object
-   */
-  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
-   */
-  onClose = () => {
-  };
+   * 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.
+   */
+  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 = () => {
-  };
-  /**
-   * JSON RPC latest sent message id
-   * expecting receiving message to contain same id
+  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.
+   * The receiving message is expected to contain the same ID.
    */
   sendId = 0;
   /**
-   * subscriptions ids
-   * mapped by keys WSSubscriptions
-   */
-  subscriptions = /* @__PURE__ */ new Map();
-  /**
-   * Construct class and event listeners
-   * @param options WebSocketOptions
+   * Creates an instance of WebSocketChannel.
+   * @param {WebSocketOptions} options - The options for configuring the channel.
    */
-  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 = {
@@ -5497,50 +5566,88 @@ var WebSocketChannel = class {
     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() {
@@ -5556,17 +5663,22 @@ var WebSocketChannel = class {
     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) {
@@ -5579,206 +5691,233 @@ var WebSocketChannel = class {
     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 && isObject(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);
   }
 };
 
@@ -10645,7 +10784,6 @@ export {
   Contract,
   ContractFactory,
   ContractInterface,
-  CustomError,
   EDAMode,
   EDataAvailabilityMode,
   ETH_ADDRESS,
@@ -10682,6 +10820,8 @@ export {
   RpcProvider2 as RpcProvider,
   Signer,
   SignerInterface,
+  Subscription,
+  TimeoutError,
   TransactionExecutionStatus,
   TransactionFinalityStatus,
   TransactionType,
@@ -10698,9 +10838,9 @@ export {
   UINT_512_MIN,
   Uint,
   ValidateType,
-  WSSubscriptions,
   WalletAccount,
   WebSocketChannel,
+  WebSocketNotConnectedError,
   addAddressPadding,
   byteArray_exports as byteArray,
   cairo_exports as cairo,
@@ -10714,8 +10854,6 @@ export {
   eth_exports as eth,
   events_exports as events,
   extractContractHashes,
-  fixProto,
-  fixStack,
   getCalldata,
   getChecksumAddress,
   getLedgerPathBuffer111 as getLedgerPathBuffer,