@pythnetwork/pyth-lazer-sdk 0.2.0 → 0.3.1

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2024 Pyth Data Association.
+Copyright 2025 Pyth Data Association.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/dist/cjs/client.d.ts

@@ -1,6 +1,5 @@
 import { type Logger } from "ts-log";
 import { type ParsedPayload, type Request, type Response } from "./protocol.js";
-import { WebSocketPool } from "./socket/web-socket-pool.js";
 export type BinaryResponse = {
     subscriptionId: number;
     evm?: Buffer | undefined;
@@ -15,18 +14,31 @@ export type JsonOrBinaryResponse = {
     value: BinaryResponse;
 };
 export declare class PythLazerClient {
-    wsp: WebSocketPool;
+    private readonly wsp;
+    private constructor();
     /**
      * Creates a new PythLazerClient instance.
      * @param urls - List of WebSocket URLs of the Pyth Lazer service
      * @param token - The access token for authentication
-     * @param numConnections - The number of parallel WebSocket connections to establish (default: 3). A higher number gives a more reliable stream.
+     * @param numConnections - The number of parallel WebSocket connections to establish (default: 3). A higher number gives a more reliable stream. The connections will round-robin across the provided URLs.
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
-    constructor(urls: string[], token: string, numConnections?: number, logger?: Logger);
+    static create(urls: string[], token: string, numConnections?: number, logger?: Logger): Promise<PythLazerClient>;
+    /**
+     * Adds a message listener that receives either JSON or binary responses from the WebSocket connections.
+     * The listener will be called for each message received, with deduplication across redundant connections.
+     * @param handler - Callback function that receives the parsed message. The message can be either a JSON response
+     * or a binary response containing EVM, Solana, or parsed payload data.
+     */
     addMessageListener(handler: (event: JsonOrBinaryResponse) => void): void;
     subscribe(request: Request): Promise<void>;
     unsubscribe(subscriptionId: number): Promise<void>;
     send(request: Request): Promise<void>;
+    /**
+     * Registers a handler function that will be called whenever all WebSocket connections are down or attempting to reconnect.
+     * The connections may still try to reconnect in the background. To shut down the pool, call `shutdown()`.
+     * @param handler - Function to be called when all connections are down
+     */
+    addAllConnectionsDownListener(handler: () => void): void;
     shutdown(): void;
 }

package/dist/cjs/client.js

@@ -3,22 +3,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PythLazerClient = void 0;
 const ts_log_1 = require("ts-log");
 const protocol_js_1 = require("./protocol.js");
-const web_socket_pool_js_1 = require("./socket/web-socket-pool.js");
+const websocket_pool_js_1 = require("./socket/websocket-pool.js");
 const UINT16_NUM_BYTES = 2;
 const UINT32_NUM_BYTES = 4;
 const UINT64_NUM_BYTES = 8;
 class PythLazerClient {
     wsp;
+    constructor(wsp) {
+        this.wsp = wsp;
+    }
     /**
      * Creates a new PythLazerClient instance.
      * @param urls - List of WebSocket URLs of the Pyth Lazer service
      * @param token - The access token for authentication
-     * @param numConnections - The number of parallel WebSocket connections to establish (default: 3). A higher number gives a more reliable stream.
+     * @param numConnections - The number of parallel WebSocket connections to establish (default: 3). A higher number gives a more reliable stream. The connections will round-robin across the provided URLs.
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
-    constructor(urls, token, numConnections = 3, logger = ts_log_1.dummyLogger) {
-        this.wsp = new web_socket_pool_js_1.WebSocketPool(urls, token, numConnections, logger);
+    static async create(urls, token, numConnections = 3, logger = ts_log_1.dummyLogger) {
+        const wsp = await websocket_pool_js_1.WebSocketPool.create(urls, token, numConnections, logger);
+        return new PythLazerClient(wsp);
     }
+    /**
+     * Adds a message listener that receives either JSON or binary responses from the WebSocket connections.
+     * The listener will be called for each message received, with deduplication across redundant connections.
+     * @param handler - Callback function that receives the parsed message. The message can be either a JSON response
+     * or a binary response containing EVM, Solana, or parsed payload data.
+     */
     addMessageListener(handler) {
         this.wsp.addMessageListener((data) => {
             if (typeof data == "string") {
@@ -77,6 +87,14 @@ class PythLazerClient {
     async send(request) {
         await this.wsp.sendRequest(request);
     }
+    /**
+     * Registers a handler function that will be called whenever all WebSocket connections are down or attempting to reconnect.
+     * The connections may still try to reconnect in the background. To shut down the pool, call `shutdown()`.
+     * @param handler - Function to be called when all connections are down
+     */
+    addAllConnectionsDownListener(handler) {
+        this.wsp.addAllConnectionsDownListener(handler);
+    }
     shutdown() {
         this.wsp.shutdown();
     }

package/dist/cjs/constants.d.ts

@@ -0,0 +1,3 @@
+import { PublicKey } from "@solana/web3.js";
+export declare const SOLANA_LAZER_PROGRAM_ID: PublicKey;
+export declare const SOLANA_STORAGE_ID: PublicKey;

package/dist/cjs/constants.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOLANA_STORAGE_ID = exports.SOLANA_LAZER_PROGRAM_ID = void 0;
+const web3_js_1 = require("@solana/web3.js");
+exports.SOLANA_LAZER_PROGRAM_ID = new web3_js_1.PublicKey("pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt");
+exports.SOLANA_STORAGE_ID = new web3_js_1.PublicKey("3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL");

package/dist/cjs/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./client.js";
 export * from "./protocol.js";
 export * from "./ed25519.js";
+export * from "./constants.js";

package/dist/cjs/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./client.js"), exports);
 __exportStar(require("./protocol.js"), exports);
 __exportStar(require("./ed25519.js"), exports);
+__exportStar(require("./constants.js"), exports);

package/dist/cjs/socket/{resilient-web-socket.d.ts → resilient-websocket.d.ts}

@@ -1,16 +1,6 @@
 import type { ClientRequestArgs } from "node:http";
 import WebSocket, { type ClientOptions, type ErrorEvent } from "isomorphic-ws";
 import type { Logger } from "ts-log";
-/**
- * This class wraps websocket to provide a resilient web socket client.
- *
- * It will reconnect if connection fails with exponential backoff. Also, it will reconnect
- * if it receives no ping request or regular message from server within a while as indication
- * of timeout (assuming the server sends either regularly).
- *
- * This class also logs events if logger is given and by replacing onError method you can handle
- * connection errors yourself (e.g: do not retry and close the connection).
- */
 export declare class ResilientWebSocket {
     endpoint: string;
     wsClient: undefined | WebSocket;
@@ -19,17 +9,18 @@ export declare class ResilientWebSocket {
     private wsFailedAttempts;
     private heartbeatTimeout;
     private logger;
+    private connectionPromise;
+    private resolveConnection;
+    private rejectConnection;
+    private _isReconnecting;
+    get isReconnecting(): boolean;
+    get isConnected(): boolean;
     onError: (error: ErrorEvent) => void;
     onMessage: (data: WebSocket.Data) => void;
     onReconnect: () => void;
     constructor(endpoint: string, wsOptions?: ClientOptions | ClientRequestArgs, logger?: Logger);
     send(data: string | Buffer): Promise<void>;
-    startWebSocket(): void;
-    /**
-     * Reset the heartbeat timeout. This is called when we receive any message (ping or regular)
-     * from the server. If we don't receive any message within HEARTBEAT_TIMEOUT_DURATION,
-     * we assume the connection is dead and reconnect.
-     */
+    startWebSocket(): Promise<void>;
     private resetHeartbeat;
     private waitForMaybeReadyWebSocket;
     private handleClose;

package/dist/cjs/socket/{resilient-web-socket.js → resilient-websocket.js}

@@ -5,18 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResilientWebSocket = void 0;
 const isomorphic_ws_1 = __importDefault(require("isomorphic-ws"));
-// Reconnect with expo backoff if we don't get a message or ping for 10 seconds
 const HEARTBEAT_TIMEOUT_DURATION = 10_000;
-/**
- * This class wraps websocket to provide a resilient web socket client.
- *
- * It will reconnect if connection fails with exponential backoff. Also, it will reconnect
- * if it receives no ping request or regular message from server within a while as indication
- * of timeout (assuming the server sends either regularly).
- *
- * This class also logs events if logger is given and by replacing onError method you can handle
- * connection errors yourself (e.g: do not retry and close the connection).
- */
+const CONNECTION_TIMEOUT = 5000;
 class ResilientWebSocket {
     endpoint;
     wsClient;
@@ -25,6 +15,16 @@ class ResilientWebSocket {
     wsFailedAttempts;
     heartbeatTimeout;
     logger;
+    connectionPromise;
+    resolveConnection;
+    rejectConnection;
+    _isReconnecting = false;
+    get isReconnecting() {
+        return this._isReconnecting;
+    }
+    get isConnected() {
+        return this.wsClient?.readyState === isomorphic_ws_1.default.OPEN;
+    }
     onError;
     onMessage;
     onReconnect;
@@ -54,41 +54,60 @@ class ResilientWebSocket {
             this.wsClient.send(data);
         }
     }
-    startWebSocket() {
+    async startWebSocket() {
         if (this.wsClient !== undefined) {
+            // If there's an existing connection attempt, wait for it
+            if (this.connectionPromise) {
+                return this.connectionPromise;
+            }
             return;
         }
         this.logger?.info(`Creating Web Socket client`);
+        // Create a new promise for this connection attempt
+        this.connectionPromise = new Promise((resolve, reject) => {
+            this.resolveConnection = resolve;
+            this.rejectConnection = reject;
+        });
+        // Set a connection timeout
+        const timeoutId = setTimeout(() => {
+            if (this.rejectConnection) {
+                this.rejectConnection(new Error(`Connection timeout after ${String(CONNECTION_TIMEOUT)}ms`));
+            }
+        }, CONNECTION_TIMEOUT);
         this.wsClient = new isomorphic_ws_1.default(this.endpoint, this.wsOptions);
         this.wsUserClosed = false;
         this.wsClient.addEventListener("open", () => {
             this.wsFailedAttempts = 0;
             this.resetHeartbeat();
+            clearTimeout(timeoutId);
+            this._isReconnecting = false;
+            this.resolveConnection?.();
         });
         this.wsClient.addEventListener("error", (event) => {
             this.onError(event);
+            if (this.rejectConnection) {
+                this.rejectConnection(new Error("WebSocket connection failed"));
+            }
         });
         this.wsClient.addEventListener("message", (event) => {
             this.resetHeartbeat();
             this.onMessage(event.data);
         });
         this.wsClient.addEventListener("close", () => {
+            clearTimeout(timeoutId);
+            if (this.rejectConnection) {
+                this.rejectConnection(new Error("WebSocket closed before connecting"));
+            }
             void this.handleClose();
         });
-        // Handle ping events if supported (Node.js only)
         if ("on" in this.wsClient) {
-            // Ping handler is undefined in browser side
             this.wsClient.on("ping", () => {
                 this.logger?.info("Ping received");
                 this.resetHeartbeat();
             });
         }
+        return this.connectionPromise;
     }
-    /**
-     * Reset the heartbeat timeout. This is called when we receive any message (ping or regular)
-     * from the server. If we don't receive any message within HEARTBEAT_TIMEOUT_DURATION,
-     * we assume the connection is dead and reconnect.
-     */
     resetHeartbeat() {
         if (this.heartbeatTimeout !== undefined) {
             clearTimeout(this.heartbeatTimeout);
@@ -123,7 +142,11 @@ class ResilientWebSocket {
         else {
             this.wsFailedAttempts += 1;
             this.wsClient = undefined;
+            this.connectionPromise = undefined;
+            this.resolveConnection = undefined;
+            this.rejectConnection = undefined;
             const waitTime = expoBackoff(this.wsFailedAttempts);
+            this._isReconnecting = true;
             this.logger?.error("Connection closed unexpectedly or because of timeout. Reconnecting after " +
                 String(waitTime) +
                 "ms.");
@@ -135,7 +158,7 @@ class ResilientWebSocket {
         if (this.wsUserClosed) {
             return;
         }
-        this.startWebSocket();
+        await this.startWebSocket();
         await this.waitForMaybeReadyWebSocket();
         if (this.wsClient === undefined) {
             this.logger?.error("Couldn't reconnect to websocket. Error callback is called.");
@@ -147,6 +170,9 @@ class ResilientWebSocket {
         if (this.wsClient !== undefined) {
             const client = this.wsClient;
             this.wsClient = undefined;
+            this.connectionPromise = undefined;
+            this.resolveConnection = undefined;
+            this.rejectConnection = undefined;
             client.close();
         }
         this.wsUserClosed = true;

package/dist/cjs/socket/{web-socket-pool.d.ts → websocket-pool.d.ts}

@@ -1,6 +1,6 @@
 import WebSocket from "isomorphic-ws";
 import { type Logger } from "ts-log";
-import { ResilientWebSocket } from "./resilient-web-socket.js";
+import { ResilientWebSocket } from "./resilient-websocket.js";
 import type { Request } from "../protocol.js";
 export declare class WebSocketPool {
     private readonly logger;
@@ -8,6 +8,10 @@ export declare class WebSocketPool {
     private cache;
     private subscriptions;
     private messageListeners;
+    private allConnectionsDownListeners;
+    private wasAllDown;
+    private checkConnectionStatesInterval;
+    private constructor();
     /**
      * Creates a new WebSocketPool instance that uses multiple redundant WebSocket connections for reliability.
      * Usage semantics are similar to using a regular WebSocket client.
@@ -16,7 +20,7 @@ export declare class WebSocketPool {
      * @param numConnections - Number of parallel WebSocket connections to maintain (default: 3)
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
-    constructor(urls: string[], token: string, numConnections?: number, logger?: Logger);
+    static create(urls: string[], token: string, numConnections?: number, logger?: Logger): Promise<WebSocketPool>;
     /**
      * Checks for error responses in JSON messages and throws appropriate errors
      */
@@ -26,30 +30,16 @@ export declare class WebSocketPool {
      * multiple connections before forwarding to registered handlers
      */
     dedupeHandler: (data: WebSocket.Data) => void;
-    /**
-     * Sends a message to all websockets in the pool
-     * @param request - The request to send
-     */
     sendRequest(request: Request): Promise<void>;
-    /**
-     * Adds a subscription by sending a subscribe request to all websockets in the pool
-     * and storing it for replay on reconnection
-     * @param request - The subscription request to send
-     */
     addSubscription(request: Request): Promise<void>;
-    /**
-     * Removes a subscription by sending an unsubscribe request to all websockets in the pool
-     * and removing it from stored subscriptions
-     * @param subscriptionId - The ID of the subscription to remove
-     */
     removeSubscription(subscriptionId: number): Promise<void>;
-    /**
-     * Adds a message handler function to receive websocket messages
-     * @param handler - Function that will be called with each received message
-     */
     addMessageListener(handler: (data: WebSocket.Data) => void): void;
     /**
-     * Elegantly closes all websocket connections in the pool
+     * Calls the handler if all websocket connections are currently down or in reconnecting state.
+     * The connections may still try to reconnect in the background.
      */
+    addAllConnectionsDownListener(handler: () => void): void;
+    private areAllConnectionsDown;
+    private checkConnectionStates;
     shutdown(): void;
 }

package/dist/cjs/socket/{web-socket-pool.js → websocket-pool.js}

@@ -6,8 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebSocketPool = void 0;
 const ttlcache_1 = __importDefault(require("@isaacs/ttlcache"));
 const ts_log_1 = require("ts-log");
-const resilient_web_socket_js_1 = require("./resilient-web-socket.js");
-// Number of redundant parallel WebSocket connections
+const resilient_websocket_js_1 = require("./resilient-websocket.js");
 const DEFAULT_NUM_CONNECTIONS = 3;
 class WebSocketPool {
     logger;
@@ -15,6 +14,21 @@ class WebSocketPool {
     cache;
     subscriptions; // id -> subscription Request
     messageListeners;
+    allConnectionsDownListeners;
+    wasAllDown = true;
+    checkConnectionStatesInterval;
+    constructor(logger = ts_log_1.dummyLogger) {
+        this.logger = logger;
+        this.rwsPool = [];
+        this.cache = new ttlcache_1.default({ ttl: 1000 * 10 }); // TTL of 10 seconds
+        this.subscriptions = new Map();
+        this.messageListeners = [];
+        this.allConnectionsDownListeners = [];
+        // Start monitoring connection states
+        this.checkConnectionStatesInterval = setInterval(() => {
+            this.checkConnectionStates();
+        }, 100);
+    }
     /**
      * Creates a new WebSocketPool instance that uses multiple redundant WebSocket connections for reliability.
      * Usage semantics are similar to using a regular WebSocket client.
@@ -23,18 +37,13 @@ class WebSocketPool {
      * @param numConnections - Number of parallel WebSocket connections to maintain (default: 3)
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
-    constructor(urls, token, numConnections = DEFAULT_NUM_CONNECTIONS, logger = ts_log_1.dummyLogger) {
-        this.logger = logger;
+    static async create(urls, token, numConnections = DEFAULT_NUM_CONNECTIONS, logger = ts_log_1.dummyLogger) {
         if (urls.length === 0) {
             throw new Error("No URLs provided");
         }
-        // This cache is used to deduplicate messages received across different websocket clients in the pool.
-        // A TTL cache is used to prevent unbounded memory usage. A very short TTL of 10 seconds is chosen since
-        // deduplication only needs to happen between messages received very close together in time.
-        this.cache = new ttlcache_1.default({ ttl: 1000 * 10 }); // TTL of 10 seconds
-        this.rwsPool = [];
-        this.subscriptions = new Map();
-        this.messageListeners = [];
+        const pool = new WebSocketPool(logger);
+        // Create all websocket instances
+        const connectionPromises = [];
         for (let i = 0; i < numConnections; i++) {
             const url = urls[i % urls.length];
             if (!url) {
@@ -45,33 +54,39 @@ class WebSocketPool {
                     Authorization: `Bearer ${token}`,
                 },
             };
-            const rws = new resilient_web_socket_js_1.ResilientWebSocket(url, wsOptions, logger);
+            const rws = new resilient_websocket_js_1.ResilientWebSocket(url, wsOptions, logger);
             // If a websocket client unexpectedly disconnects, ResilientWebSocket will reestablish
             // the connection and call the onReconnect callback.
-            // When we reconnect, replay all subscription messages to resume the data stream.
             rws.onReconnect = () => {
                 if (rws.wsUserClosed) {
                     return;
                 }
-                for (const [, request] of this.subscriptions) {
+                for (const [, request] of pool.subscriptions) {
                     try {
                         void rws.send(JSON.stringify(request));
                     }
                     catch (error) {
-                        this.logger.error("Failed to resend subscription on reconnect:", error);
+                        pool.logger.error("Failed to resend subscription on reconnect:", error);
                     }
                 }
             };
             // Handle all client messages ourselves. Dedupe before sending to registered message handlers.
-            rws.onMessage = this.dedupeHandler;
-            this.rwsPool.push(rws);
+            rws.onMessage = pool.dedupeHandler;
+            pool.rwsPool.push(rws);
+            // Start the websocket and collect the promise
+            connectionPromises.push(rws.startWebSocket());
         }
-        // Let it rip
-        // TODO: wait for sockets to receive `open` msg before subscribing?
-        for (const rws of this.rwsPool) {
-            rws.startWebSocket();
+        // Wait for all connections to be established
+        try {
+            await Promise.all(connectionPromises);
+        }
+        catch (error) {
+            // If any connection fails, clean up and throw
+            pool.shutdown();
+            throw error;
         }
-        this.logger.info(`Using ${numConnections.toString()} redundant WebSocket connections`);
+        pool.logger.info(`Successfully established ${numConnections.toString()} redundant WebSocket connections`);
+        return pool;
     }
     /**
      * Checks for error responses in JSON messages and throws appropriate errors
@@ -90,19 +105,14 @@ class WebSocketPool {
      * multiple connections before forwarding to registered handlers
      */
     dedupeHandler = (data) => {
-        // For string data, use the whole string as the cache key. This avoids expensive JSON parsing during deduping.
-        // For binary data, use the hex string representation as the cache key
         const cacheKey = typeof data === "string"
             ? data
             : Buffer.from(data).toString("hex");
-        // If we've seen this exact message recently, drop it
         if (this.cache.has(cacheKey)) {
             this.logger.debug("Dropping duplicate message");
             return;
         }
-        // Haven't seen this message, cache it and forward to handlers
         this.cache.set(cacheKey, true);
-        // Check for errors in JSON responses
         if (typeof data === "string") {
             this.handleErrorMessages(data);
         }
@@ -110,28 +120,18 @@ class WebSocketPool {
             handler(data);
         }
     };
-    /**
-     * Sends a message to all websockets in the pool
-     * @param request - The request to send
-     */
     async sendRequest(request) {
-        // Send to all websockets in the pool
         const sendPromises = this.rwsPool.map(async (rws) => {
             try {
                 await rws.send(JSON.stringify(request));
             }
             catch (error) {
                 this.logger.error("Failed to send request:", error);
-                throw error; // Re-throw the error
+                throw error;
             }
         });
         await Promise.all(sendPromises);
     }
-    /**
-     * Adds a subscription by sending a subscribe request to all websockets in the pool
-     * and storing it for replay on reconnection
-     * @param request - The subscription request to send
-     */
     async addSubscription(request) {
         if (request.type !== "subscribe") {
             throw new Error("Request must be a subscribe request");
@@ -139,11 +139,6 @@ class WebSocketPool {
         this.subscriptions.set(request.subscriptionId, request);
         await this.sendRequest(request);
     }
-    /**
-     * Removes a subscription by sending an unsubscribe request to all websockets in the pool
-     * and removing it from stored subscriptions
-     * @param subscriptionId - The ID of the subscription to remove
-     */
     async removeSubscription(subscriptionId) {
         this.subscriptions.delete(subscriptionId);
         const request = {
@@ -152,16 +147,35 @@ class WebSocketPool {
         };
         await this.sendRequest(request);
     }
-    /**
-     * Adds a message handler function to receive websocket messages
-     * @param handler - Function that will be called with each received message
-     */
     addMessageListener(handler) {
         this.messageListeners.push(handler);
     }
     /**
-     * Elegantly closes all websocket connections in the pool
+     * Calls the handler if all websocket connections are currently down or in reconnecting state.
+     * The connections may still try to reconnect in the background.
      */
+    addAllConnectionsDownListener(handler) {
+        this.allConnectionsDownListeners.push(handler);
+    }
+    areAllConnectionsDown() {
+        return this.rwsPool.every((ws) => !ws.isConnected || ws.isReconnecting);
+    }
+    checkConnectionStates() {
+        const allDown = this.areAllConnectionsDown();
+        // If all connections just went down
+        if (allDown && !this.wasAllDown) {
+            this.wasAllDown = true;
+            this.logger.error("All WebSocket connections are down or reconnecting");
+            // Notify all listeners
+            for (const listener of this.allConnectionsDownListeners) {
+                listener();
+            }
+        }
+        // If at least one connection was restored
+        if (!allDown && this.wasAllDown) {
+            this.wasAllDown = false;
+        }
+    }
     shutdown() {
         for (const rws of this.rwsPool) {
             rws.closeWebSocket();
@@ -169,6 +183,8 @@ class WebSocketPool {
         this.rwsPool = [];
         this.subscriptions.clear();
         this.messageListeners = [];
+        this.allConnectionsDownListeners = [];
+        clearInterval(this.checkConnectionStatesInterval);
     }
 }
 exports.WebSocketPool = WebSocketPool;

package/dist/esm/client.d.ts

@@ -1,6 +1,5 @@
 import { type Logger } from "ts-log";
 import { type ParsedPayload, type Request, type Response } from "./protocol.js";
-import { WebSocketPool } from "./socket/web-socket-pool.js";
 export type BinaryResponse = {
     subscriptionId: number;
     evm?: Buffer | undefined;
@@ -15,18 +14,31 @@ export type JsonOrBinaryResponse = {
     value: BinaryResponse;
 };
 export declare class PythLazerClient {
-    wsp: WebSocketPool;
+    private readonly wsp;
+    private constructor();
     /**
      * Creates a new PythLazerClient instance.
      * @param urls - List of WebSocket URLs of the Pyth Lazer service
      * @param token - The access token for authentication
-     * @param numConnections - The number of parallel WebSocket connections to establish (default: 3). A higher number gives a more reliable stream.
+     * @param numConnections - The number of parallel WebSocket connections to establish (default: 3). A higher number gives a more reliable stream. The connections will round-robin across the provided URLs.
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
-    constructor(urls: string[], token: string, numConnections?: number, logger?: Logger);
+    static create(urls: string[], token: string, numConnections?: number, logger?: Logger): Promise<PythLazerClient>;
+    /**
+     * Adds a message listener that receives either JSON or binary responses from the WebSocket connections.
+     * The listener will be called for each message received, with deduplication across redundant connections.
+     * @param handler - Callback function that receives the parsed message. The message can be either a JSON response
+     * or a binary response containing EVM, Solana, or parsed payload data.
+     */
     addMessageListener(handler: (event: JsonOrBinaryResponse) => void): void;
     subscribe(request: Request): Promise<void>;
     unsubscribe(subscriptionId: number): Promise<void>;
     send(request: Request): Promise<void>;
+    /**
+     * Registers a handler function that will be called whenever all WebSocket connections are down or attempting to reconnect.
+     * The connections may still try to reconnect in the background. To shut down the pool, call `shutdown()`.
+     * @param handler - Function to be called when all connections are down
+     */
+    addAllConnectionsDownListener(handler: () => void): void;
     shutdown(): void;
 }

package/dist/esm/client.js

@@ -1,22 +1,32 @@
 import WebSocket from "isomorphic-ws";
 import { dummyLogger } from "ts-log";
 import { BINARY_UPDATE_FORMAT_MAGIC, EVM_FORMAT_MAGIC, PARSED_FORMAT_MAGIC, SOLANA_FORMAT_MAGIC_BE, } from "./protocol.js";
-import { WebSocketPool } from "./socket/web-socket-pool.js";
+import { WebSocketPool } from "./socket/websocket-pool.js";
 const UINT16_NUM_BYTES = 2;
 const UINT32_NUM_BYTES = 4;
 const UINT64_NUM_BYTES = 8;
 export class PythLazerClient {
     wsp;
+    constructor(wsp) {
+        this.wsp = wsp;
+    }
     /**
      * Creates a new PythLazerClient instance.
      * @param urls - List of WebSocket URLs of the Pyth Lazer service
      * @param token - The access token for authentication
-     * @param numConnections - The number of parallel WebSocket connections to establish (default: 3). A higher number gives a more reliable stream.
+     * @param numConnections - The number of parallel WebSocket connections to establish (default: 3). A higher number gives a more reliable stream. The connections will round-robin across the provided URLs.
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
-    constructor(urls, token, numConnections = 3, logger = dummyLogger) {
-        this.wsp = new WebSocketPool(urls, token, numConnections, logger);
+    static async create(urls, token, numConnections = 3, logger = dummyLogger) {
+        const wsp = await WebSocketPool.create(urls, token, numConnections, logger);
+        return new PythLazerClient(wsp);
     }
+    /**
+     * Adds a message listener that receives either JSON or binary responses from the WebSocket connections.
+     * The listener will be called for each message received, with deduplication across redundant connections.
+     * @param handler - Callback function that receives the parsed message. The message can be either a JSON response
+     * or a binary response containing EVM, Solana, or parsed payload data.
+     */
     addMessageListener(handler) {
         this.wsp.addMessageListener((data) => {
             if (typeof data == "string") {
@@ -75,6 +85,14 @@ export class PythLazerClient {
     async send(request) {
         await this.wsp.sendRequest(request);
     }
+    /**
+     * Registers a handler function that will be called whenever all WebSocket connections are down or attempting to reconnect.
+     * The connections may still try to reconnect in the background. To shut down the pool, call `shutdown()`.
+     * @param handler - Function to be called when all connections are down
+     */
+    addAllConnectionsDownListener(handler) {
+        this.wsp.addAllConnectionsDownListener(handler);
+    }
     shutdown() {
         this.wsp.shutdown();
     }

package/dist/esm/constants.d.ts

@@ -0,0 +1,3 @@
+import { PublicKey } from "@solana/web3.js";
+export declare const SOLANA_LAZER_PROGRAM_ID: PublicKey;
+export declare const SOLANA_STORAGE_ID: PublicKey;

package/dist/esm/constants.js

@@ -0,0 +1,3 @@
+import { PublicKey } from "@solana/web3.js";
+export const SOLANA_LAZER_PROGRAM_ID = new PublicKey("pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt");
+export const SOLANA_STORAGE_ID = new PublicKey("3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL");

package/dist/esm/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./client.js";
 export * from "./protocol.js";
 export * from "./ed25519.js";
+export * from "./constants.js";

package/dist/esm/index.js

@@ -1,3 +1,4 @@
 export * from "./client.js";
 export * from "./protocol.js";
 export * from "./ed25519.js";
+export * from "./constants.js";

package/dist/esm/socket/{resilient-web-socket.d.ts → resilient-websocket.d.ts}

@@ -1,16 +1,6 @@
 import type { ClientRequestArgs } from "node:http";
 import WebSocket, { type ClientOptions, type ErrorEvent } from "isomorphic-ws";
 import type { Logger } from "ts-log";
-/**
- * This class wraps websocket to provide a resilient web socket client.
- *
- * It will reconnect if connection fails with exponential backoff. Also, it will reconnect
- * if it receives no ping request or regular message from server within a while as indication
- * of timeout (assuming the server sends either regularly).
- *
- * This class also logs events if logger is given and by replacing onError method you can handle
- * connection errors yourself (e.g: do not retry and close the connection).
- */
 export declare class ResilientWebSocket {
     endpoint: string;
     wsClient: undefined | WebSocket;
@@ -19,17 +9,18 @@ export declare class ResilientWebSocket {
     private wsFailedAttempts;
     private heartbeatTimeout;
     private logger;
+    private connectionPromise;
+    private resolveConnection;
+    private rejectConnection;
+    private _isReconnecting;
+    get isReconnecting(): boolean;
+    get isConnected(): boolean;
     onError: (error: ErrorEvent) => void;
     onMessage: (data: WebSocket.Data) => void;
     onReconnect: () => void;
     constructor(endpoint: string, wsOptions?: ClientOptions | ClientRequestArgs, logger?: Logger);
     send(data: string | Buffer): Promise<void>;
-    startWebSocket(): void;
-    /**
-     * Reset the heartbeat timeout. This is called when we receive any message (ping or regular)
-     * from the server. If we don't receive any message within HEARTBEAT_TIMEOUT_DURATION,
-     * we assume the connection is dead and reconnect.
-     */
+    startWebSocket(): Promise<void>;
     private resetHeartbeat;
     private waitForMaybeReadyWebSocket;
     private handleClose;

package/dist/esm/socket/{resilient-web-socket.js → resilient-websocket.js}

@@ -1,16 +1,6 @@
 import WebSocket, {} from "isomorphic-ws";
-// Reconnect with expo backoff if we don't get a message or ping for 10 seconds
 const HEARTBEAT_TIMEOUT_DURATION = 10_000;
-/**
- * This class wraps websocket to provide a resilient web socket client.
- *
- * It will reconnect if connection fails with exponential backoff. Also, it will reconnect
- * if it receives no ping request or regular message from server within a while as indication
- * of timeout (assuming the server sends either regularly).
- *
- * This class also logs events if logger is given and by replacing onError method you can handle
- * connection errors yourself (e.g: do not retry and close the connection).
- */
+const CONNECTION_TIMEOUT = 5000;
 export class ResilientWebSocket {
     endpoint;
     wsClient;
@@ -19,6 +9,16 @@ export class ResilientWebSocket {
     wsFailedAttempts;
     heartbeatTimeout;
     logger;
+    connectionPromise;
+    resolveConnection;
+    rejectConnection;
+    _isReconnecting = false;
+    get isReconnecting() {
+        return this._isReconnecting;
+    }
+    get isConnected() {
+        return this.wsClient?.readyState === WebSocket.OPEN;
+    }
     onError;
     onMessage;
     onReconnect;
@@ -48,41 +48,60 @@ export class ResilientWebSocket {
             this.wsClient.send(data);
         }
     }
-    startWebSocket() {
+    async startWebSocket() {
         if (this.wsClient !== undefined) {
+            // If there's an existing connection attempt, wait for it
+            if (this.connectionPromise) {
+                return this.connectionPromise;
+            }
             return;
         }
         this.logger?.info(`Creating Web Socket client`);
+        // Create a new promise for this connection attempt
+        this.connectionPromise = new Promise((resolve, reject) => {
+            this.resolveConnection = resolve;
+            this.rejectConnection = reject;
+        });
+        // Set a connection timeout
+        const timeoutId = setTimeout(() => {
+            if (this.rejectConnection) {
+                this.rejectConnection(new Error(`Connection timeout after ${String(CONNECTION_TIMEOUT)}ms`));
+            }
+        }, CONNECTION_TIMEOUT);
         this.wsClient = new WebSocket(this.endpoint, this.wsOptions);
         this.wsUserClosed = false;
         this.wsClient.addEventListener("open", () => {
             this.wsFailedAttempts = 0;
             this.resetHeartbeat();
+            clearTimeout(timeoutId);
+            this._isReconnecting = false;
+            this.resolveConnection?.();
         });
         this.wsClient.addEventListener("error", (event) => {
             this.onError(event);
+            if (this.rejectConnection) {
+                this.rejectConnection(new Error("WebSocket connection failed"));
+            }
         });
         this.wsClient.addEventListener("message", (event) => {
             this.resetHeartbeat();
             this.onMessage(event.data);
         });
         this.wsClient.addEventListener("close", () => {
+            clearTimeout(timeoutId);
+            if (this.rejectConnection) {
+                this.rejectConnection(new Error("WebSocket closed before connecting"));
+            }
             void this.handleClose();
         });
-        // Handle ping events if supported (Node.js only)
         if ("on" in this.wsClient) {
-            // Ping handler is undefined in browser side
             this.wsClient.on("ping", () => {
                 this.logger?.info("Ping received");
                 this.resetHeartbeat();
             });
         }
+        return this.connectionPromise;
     }
-    /**
-     * Reset the heartbeat timeout. This is called when we receive any message (ping or regular)
-     * from the server. If we don't receive any message within HEARTBEAT_TIMEOUT_DURATION,
-     * we assume the connection is dead and reconnect.
-     */
     resetHeartbeat() {
         if (this.heartbeatTimeout !== undefined) {
             clearTimeout(this.heartbeatTimeout);
@@ -117,7 +136,11 @@ export class ResilientWebSocket {
         else {
             this.wsFailedAttempts += 1;
             this.wsClient = undefined;
+            this.connectionPromise = undefined;
+            this.resolveConnection = undefined;
+            this.rejectConnection = undefined;
             const waitTime = expoBackoff(this.wsFailedAttempts);
+            this._isReconnecting = true;
             this.logger?.error("Connection closed unexpectedly or because of timeout. Reconnecting after " +
                 String(waitTime) +
                 "ms.");
@@ -129,7 +152,7 @@ export class ResilientWebSocket {
         if (this.wsUserClosed) {
             return;
         }
-        this.startWebSocket();
+        await this.startWebSocket();
         await this.waitForMaybeReadyWebSocket();
         if (this.wsClient === undefined) {
             this.logger?.error("Couldn't reconnect to websocket. Error callback is called.");
@@ -141,6 +164,9 @@ export class ResilientWebSocket {
         if (this.wsClient !== undefined) {
             const client = this.wsClient;
             this.wsClient = undefined;
+            this.connectionPromise = undefined;
+            this.resolveConnection = undefined;
+            this.rejectConnection = undefined;
             client.close();
         }
         this.wsUserClosed = true;

package/dist/esm/socket/{web-socket-pool.d.ts → websocket-pool.d.ts}

@@ -1,6 +1,6 @@
 import WebSocket from "isomorphic-ws";
 import { type Logger } from "ts-log";
-import { ResilientWebSocket } from "./resilient-web-socket.js";
+import { ResilientWebSocket } from "./resilient-websocket.js";
 import type { Request } from "../protocol.js";
 export declare class WebSocketPool {
     private readonly logger;
@@ -8,6 +8,10 @@ export declare class WebSocketPool {
     private cache;
     private subscriptions;
     private messageListeners;
+    private allConnectionsDownListeners;
+    private wasAllDown;
+    private checkConnectionStatesInterval;
+    private constructor();
     /**
      * Creates a new WebSocketPool instance that uses multiple redundant WebSocket connections for reliability.
      * Usage semantics are similar to using a regular WebSocket client.
@@ -16,7 +20,7 @@ export declare class WebSocketPool {
      * @param numConnections - Number of parallel WebSocket connections to maintain (default: 3)
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
-    constructor(urls: string[], token: string, numConnections?: number, logger?: Logger);
+    static create(urls: string[], token: string, numConnections?: number, logger?: Logger): Promise<WebSocketPool>;
     /**
      * Checks for error responses in JSON messages and throws appropriate errors
      */
@@ -26,30 +30,16 @@ export declare class WebSocketPool {
      * multiple connections before forwarding to registered handlers
      */
     dedupeHandler: (data: WebSocket.Data) => void;
-    /**
-     * Sends a message to all websockets in the pool
-     * @param request - The request to send
-     */
     sendRequest(request: Request): Promise<void>;
-    /**
-     * Adds a subscription by sending a subscribe request to all websockets in the pool
-     * and storing it for replay on reconnection
-     * @param request - The subscription request to send
-     */
     addSubscription(request: Request): Promise<void>;
-    /**
-     * Removes a subscription by sending an unsubscribe request to all websockets in the pool
-     * and removing it from stored subscriptions
-     * @param subscriptionId - The ID of the subscription to remove
-     */
     removeSubscription(subscriptionId: number): Promise<void>;
-    /**
-     * Adds a message handler function to receive websocket messages
-     * @param handler - Function that will be called with each received message
-     */
     addMessageListener(handler: (data: WebSocket.Data) => void): void;
     /**
-     * Elegantly closes all websocket connections in the pool
+     * Calls the handler if all websocket connections are currently down or in reconnecting state.
+     * The connections may still try to reconnect in the background.
      */
+    addAllConnectionsDownListener(handler: () => void): void;
+    private areAllConnectionsDown;
+    private checkConnectionStates;
     shutdown(): void;
 }

package/dist/esm/socket/{web-socket-pool.js → websocket-pool.js}

@@ -1,8 +1,7 @@
 import TTLCache from "@isaacs/ttlcache";
 import WebSocket from "isomorphic-ws";
 import { dummyLogger } from "ts-log";
-import { ResilientWebSocket } from "./resilient-web-socket.js";
-// Number of redundant parallel WebSocket connections
+import { ResilientWebSocket } from "./resilient-websocket.js";
 const DEFAULT_NUM_CONNECTIONS = 3;
 export class WebSocketPool {
     logger;
@@ -10,6 +9,21 @@ export class WebSocketPool {
     cache;
     subscriptions; // id -> subscription Request
     messageListeners;
+    allConnectionsDownListeners;
+    wasAllDown = true;
+    checkConnectionStatesInterval;
+    constructor(logger = dummyLogger) {
+        this.logger = logger;
+        this.rwsPool = [];
+        this.cache = new TTLCache({ ttl: 1000 * 10 }); // TTL of 10 seconds
+        this.subscriptions = new Map();
+        this.messageListeners = [];
+        this.allConnectionsDownListeners = [];
+        // Start monitoring connection states
+        this.checkConnectionStatesInterval = setInterval(() => {
+            this.checkConnectionStates();
+        }, 100);
+    }
     /**
      * Creates a new WebSocketPool instance that uses multiple redundant WebSocket connections for reliability.
      * Usage semantics are similar to using a regular WebSocket client.
@@ -18,18 +32,13 @@ export class WebSocketPool {
      * @param numConnections - Number of parallel WebSocket connections to maintain (default: 3)
      * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
      */
-    constructor(urls, token, numConnections = DEFAULT_NUM_CONNECTIONS, logger = dummyLogger) {
-        this.logger = logger;
+    static async create(urls, token, numConnections = DEFAULT_NUM_CONNECTIONS, logger = dummyLogger) {
         if (urls.length === 0) {
             throw new Error("No URLs provided");
         }
-        // This cache is used to deduplicate messages received across different websocket clients in the pool.
-        // A TTL cache is used to prevent unbounded memory usage. A very short TTL of 10 seconds is chosen since
-        // deduplication only needs to happen between messages received very close together in time.
-        this.cache = new TTLCache({ ttl: 1000 * 10 }); // TTL of 10 seconds
-        this.rwsPool = [];
-        this.subscriptions = new Map();
-        this.messageListeners = [];
+        const pool = new WebSocketPool(logger);
+        // Create all websocket instances
+        const connectionPromises = [];
         for (let i = 0; i < numConnections; i++) {
             const url = urls[i % urls.length];
             if (!url) {
@@ -43,30 +52,36 @@ export class WebSocketPool {
             const rws = new ResilientWebSocket(url, wsOptions, logger);
             // If a websocket client unexpectedly disconnects, ResilientWebSocket will reestablish
             // the connection and call the onReconnect callback.
-            // When we reconnect, replay all subscription messages to resume the data stream.
             rws.onReconnect = () => {
                 if (rws.wsUserClosed) {
                     return;
                 }
-                for (const [, request] of this.subscriptions) {
+                for (const [, request] of pool.subscriptions) {
                     try {
                         void rws.send(JSON.stringify(request));
                     }
                     catch (error) {
-                        this.logger.error("Failed to resend subscription on reconnect:", error);
+                        pool.logger.error("Failed to resend subscription on reconnect:", error);
                     }
                 }
             };
             // Handle all client messages ourselves. Dedupe before sending to registered message handlers.
-            rws.onMessage = this.dedupeHandler;
-            this.rwsPool.push(rws);
+            rws.onMessage = pool.dedupeHandler;
+            pool.rwsPool.push(rws);
+            // Start the websocket and collect the promise
+            connectionPromises.push(rws.startWebSocket());
         }
-        // Let it rip
-        // TODO: wait for sockets to receive `open` msg before subscribing?
-        for (const rws of this.rwsPool) {
-            rws.startWebSocket();
+        // Wait for all connections to be established
+        try {
+            await Promise.all(connectionPromises);
+        }
+        catch (error) {
+            // If any connection fails, clean up and throw
+            pool.shutdown();
+            throw error;
         }
-        this.logger.info(`Using ${numConnections.toString()} redundant WebSocket connections`);
+        pool.logger.info(`Successfully established ${numConnections.toString()} redundant WebSocket connections`);
+        return pool;
     }
     /**
      * Checks for error responses in JSON messages and throws appropriate errors
@@ -85,19 +100,14 @@ export class WebSocketPool {
      * multiple connections before forwarding to registered handlers
      */
     dedupeHandler = (data) => {
-        // For string data, use the whole string as the cache key. This avoids expensive JSON parsing during deduping.
-        // For binary data, use the hex string representation as the cache key
         const cacheKey = typeof data === "string"
             ? data
             : Buffer.from(data).toString("hex");
-        // If we've seen this exact message recently, drop it
         if (this.cache.has(cacheKey)) {
             this.logger.debug("Dropping duplicate message");
             return;
         }
-        // Haven't seen this message, cache it and forward to handlers
         this.cache.set(cacheKey, true);
-        // Check for errors in JSON responses
         if (typeof data === "string") {
             this.handleErrorMessages(data);
         }
@@ -105,28 +115,18 @@ export class WebSocketPool {
             handler(data);
         }
     };
-    /**
-     * Sends a message to all websockets in the pool
-     * @param request - The request to send
-     */
     async sendRequest(request) {
-        // Send to all websockets in the pool
         const sendPromises = this.rwsPool.map(async (rws) => {
             try {
                 await rws.send(JSON.stringify(request));
             }
             catch (error) {
                 this.logger.error("Failed to send request:", error);
-                throw error; // Re-throw the error
+                throw error;
             }
         });
         await Promise.all(sendPromises);
     }
-    /**
-     * Adds a subscription by sending a subscribe request to all websockets in the pool
-     * and storing it for replay on reconnection
-     * @param request - The subscription request to send
-     */
     async addSubscription(request) {
         if (request.type !== "subscribe") {
             throw new Error("Request must be a subscribe request");
@@ -134,11 +134,6 @@ export class WebSocketPool {
         this.subscriptions.set(request.subscriptionId, request);
         await this.sendRequest(request);
     }
-    /**
-     * Removes a subscription by sending an unsubscribe request to all websockets in the pool
-     * and removing it from stored subscriptions
-     * @param subscriptionId - The ID of the subscription to remove
-     */
     async removeSubscription(subscriptionId) {
         this.subscriptions.delete(subscriptionId);
         const request = {
@@ -147,16 +142,35 @@ export class WebSocketPool {
         };
         await this.sendRequest(request);
     }
-    /**
-     * Adds a message handler function to receive websocket messages
-     * @param handler - Function that will be called with each received message
-     */
     addMessageListener(handler) {
         this.messageListeners.push(handler);
     }
     /**
-     * Elegantly closes all websocket connections in the pool
+     * Calls the handler if all websocket connections are currently down or in reconnecting state.
+     * The connections may still try to reconnect in the background.
      */
+    addAllConnectionsDownListener(handler) {
+        this.allConnectionsDownListeners.push(handler);
+    }
+    areAllConnectionsDown() {
+        return this.rwsPool.every((ws) => !ws.isConnected || ws.isReconnecting);
+    }
+    checkConnectionStates() {
+        const allDown = this.areAllConnectionsDown();
+        // If all connections just went down
+        if (allDown && !this.wasAllDown) {
+            this.wasAllDown = true;
+            this.logger.error("All WebSocket connections are down or reconnecting");
+            // Notify all listeners
+            for (const listener of this.allConnectionsDownListeners) {
+                listener();
+            }
+        }
+        // If at least one connection was restored
+        if (!allDown && this.wasAllDown) {
+            this.wasAllDown = false;
+        }
+    }
     shutdown() {
         for (const rws of this.rwsPool) {
             rws.closeWebSocket();
@@ -164,5 +178,7 @@ export class WebSocketPool {
         this.rwsPool = [];
         this.subscriptions.clear();
         this.messageListeners = [];
+        this.allConnectionsDownListeners = [];
+        clearInterval(this.checkConnectionStatesInterval);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pythnetwork/pyth-lazer-sdk",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Pyth Lazer SDK",
   "publishConfig": {
     "access": "public"
@@ -67,5 +67,5 @@
     "ts-log": "^2.2.7",
     "ws": "^8.18.0"
   },
-  "gitHead": "7cb1725be86f01810025b6ceac1a8d6df2c37285"
+  "gitHead": "bf18253126f281a3ae0606ac748ca5496795fbc9"
 }