@pythnetwork/pyth-lazer-sdk 0.1.1 → 0.2.0

package/dist/cjs/client.d.ts

@@ -0,0 +1,32 @@
+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;
+    solana?: Buffer | undefined;
+    parsed?: ParsedPayload | undefined;
+};
+export type JsonOrBinaryResponse = {
+    type: "json";
+    value: Response;
+} | {
+    type: "binary";
+    value: BinaryResponse;
+};
+export declare class PythLazerClient {
+    wsp: WebSocketPool;
+    /**
+     * 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 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);
+    addMessageListener(handler: (event: JsonOrBinaryResponse) => void): void;
+    subscribe(request: Request): Promise<void>;
+    unsubscribe(subscriptionId: number): Promise<void>;
+    send(request: Request): Promise<void>;
+    shutdown(): void;
+}

package/dist/cjs/client.js

@@ -0,0 +1,84 @@
+"use strict";
+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 UINT16_NUM_BYTES = 2;
+const UINT32_NUM_BYTES = 4;
+const UINT64_NUM_BYTES = 8;
+class PythLazerClient {
+    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 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);
+    }
+    addMessageListener(handler) {
+        this.wsp.addMessageListener((data) => {
+            if (typeof data == "string") {
+                handler({
+                    type: "json",
+                    value: JSON.parse(data),
+                });
+            }
+            else if (Buffer.isBuffer(data)) {
+                let pos = 0;
+                const magic = data.subarray(pos, pos + UINT32_NUM_BYTES).readUint32BE();
+                pos += UINT32_NUM_BYTES;
+                if (magic != protocol_js_1.BINARY_UPDATE_FORMAT_MAGIC) {
+                    throw new Error("binary update format magic mismatch");
+                }
+                // TODO: some uint64 values may not be representable as Number.
+                const subscriptionId = Number(data.subarray(pos, pos + UINT64_NUM_BYTES).readBigInt64BE());
+                pos += UINT64_NUM_BYTES;
+                const value = { subscriptionId };
+                while (pos < data.length) {
+                    const len = data.subarray(pos, pos + UINT16_NUM_BYTES).readUint16BE();
+                    pos += UINT16_NUM_BYTES;
+                    const magic = data
+                        .subarray(pos, pos + UINT32_NUM_BYTES)
+                        .readUint32BE();
+                    if (magic == protocol_js_1.EVM_FORMAT_MAGIC) {
+                        value.evm = data.subarray(pos, pos + len);
+                    }
+                    else if (magic == protocol_js_1.SOLANA_FORMAT_MAGIC_BE) {
+                        value.solana = data.subarray(pos, pos + len);
+                    }
+                    else if (magic == protocol_js_1.PARSED_FORMAT_MAGIC) {
+                        value.parsed = JSON.parse(data.subarray(pos + UINT32_NUM_BYTES, pos + len).toString());
+                    }
+                    else {
+                        throw new Error("unknown magic: " + magic.toString());
+                    }
+                    pos += len;
+                }
+                handler({ type: "binary", value });
+            }
+            else {
+                throw new TypeError("unexpected event data type");
+            }
+        });
+    }
+    async subscribe(request) {
+        if (request.type !== "subscribe") {
+            throw new Error("Request must be a subscribe request");
+        }
+        await this.wsp.addSubscription(request);
+    }
+    async unsubscribe(subscriptionId) {
+        await this.wsp.removeSubscription(subscriptionId);
+    }
+    async send(request) {
+        await this.wsp.sendRequest(request);
+    }
+    shutdown() {
+        this.wsp.shutdown();
+    }
+}
+exports.PythLazerClient = PythLazerClient;

package/dist/cjs/ed25519.d.ts

@@ -0,0 +1,2 @@
+import { TransactionInstruction } from "@solana/web3.js";
+export declare const createEd25519Instruction: (message: Buffer, instructionIndex: number, startingOffset: number) => TransactionInstruction;

package/dist/cjs/ed25519.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEd25519Instruction = void 0;
+const BufferLayout = __importStar(require("@solana/buffer-layout"));
+const web3_js_1 = require("@solana/web3.js");
+const ED25519_INSTRUCTION_LEN = 16;
+const SIGNATURE_LEN = 64;
+const PUBKEY_LEN = 32;
+const MAGIC_LEN = 4;
+const MESSAGE_SIZE_LEN = 2;
+const ED25519_INSTRUCTION_LAYOUT = BufferLayout.struct([
+    BufferLayout.u8("numSignatures"),
+    BufferLayout.u8("padding"),
+    BufferLayout.u16("signatureOffset"),
+    BufferLayout.u16("signatureInstructionIndex"),
+    BufferLayout.u16("publicKeyOffset"),
+    BufferLayout.u16("publicKeyInstructionIndex"),
+    BufferLayout.u16("messageDataOffset"),
+    BufferLayout.u16("messageDataSize"),
+    BufferLayout.u16("messageInstructionIndex"),
+]);
+const createEd25519Instruction = (message, instructionIndex, startingOffset) => {
+    const signatureOffset = startingOffset + MAGIC_LEN;
+    const publicKeyOffset = signatureOffset + SIGNATURE_LEN;
+    const messageDataSizeOffset = publicKeyOffset + PUBKEY_LEN;
+    const messageDataOffset = messageDataSizeOffset + MESSAGE_SIZE_LEN;
+    const messageDataSize = message.readUInt16LE(messageDataSizeOffset - startingOffset);
+    const instructionData = Buffer.alloc(ED25519_INSTRUCTION_LEN);
+    ED25519_INSTRUCTION_LAYOUT.encode({
+        numSignatures: 1,
+        padding: 0,
+        signatureOffset,
+        signatureInstructionIndex: instructionIndex,
+        publicKeyOffset,
+        publicKeyInstructionIndex: instructionIndex,
+        messageDataOffset,
+        messageDataSize: messageDataSize,
+        messageInstructionIndex: instructionIndex,
+    }, instructionData);
+    return new web3_js_1.TransactionInstruction({
+        keys: [],
+        programId: web3_js_1.Ed25519Program.programId,
+        data: instructionData,
+    });
+};
+exports.createEd25519Instruction = createEd25519Instruction;

package/dist/cjs/index.d.ts

@@ -1,21 +1,3 @@
-import WebSocket from "isomorphic-ws";
-import { type ParsedPayload, type Request, type Response } from "./protocol.js";
-export type BinaryResponse = {
-    subscriptionId: number;
-    evm?: Buffer | undefined;
-    solana?: Buffer | undefined;
-    parsed?: ParsedPayload | undefined;
-};
-export type JsonOrBinaryResponse = {
-    type: "json";
-    value: Response;
-} | {
-    type: "binary";
-    value: BinaryResponse;
-};
-export declare class PythLazerClient {
-    ws: WebSocket;
-    constructor(url: string, token: string);
-    addMessageListener(handler: (event: JsonOrBinaryResponse) => void): void;
-    send(request: Request): void;
-}
+export * from "./client.js";
+export * from "./protocol.js";
+export * from "./ed25519.js";

package/dist/cjs/index.js

@@ -1,73 +1,19 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PythLazerClient = void 0;
-const isomorphic_ws_1 = __importDefault(require("isomorphic-ws"));
-const protocol_js_1 = require("./protocol.js");
-const UINT16_NUM_BYTES = 2;
-const UINT32_NUM_BYTES = 4;
-const UINT64_NUM_BYTES = 8;
-class PythLazerClient {
-    ws;
-    constructor(url, token) {
-        const finalUrl = new URL(url);
-        finalUrl.searchParams.append("ACCESS_TOKEN", token);
-        this.ws = new isomorphic_ws_1.default(finalUrl);
-    }
-    addMessageListener(handler) {
-        this.ws.addEventListener("message", (event) => {
-            if (typeof event.data == "string") {
-                handler({
-                    type: "json",
-                    value: JSON.parse(event.data),
-                });
-            }
-            else if (Buffer.isBuffer(event.data)) {
-                let pos = 0;
-                const magic = event.data
-                    .subarray(pos, pos + UINT32_NUM_BYTES)
-                    .readUint32BE();
-                pos += UINT32_NUM_BYTES;
-                if (magic != protocol_js_1.BINARY_UPDATE_FORMAT_MAGIC) {
-                    throw new Error("binary update format magic mismatch");
-                }
-                // TODO: some uint64 values may not be representable as Number.
-                const subscriptionId = Number(event.data.subarray(pos, pos + UINT64_NUM_BYTES).readBigInt64BE());
-                pos += UINT64_NUM_BYTES;
-                const value = { subscriptionId };
-                while (pos < event.data.length) {
-                    const len = event.data
-                        .subarray(pos, pos + UINT16_NUM_BYTES)
-                        .readUint16BE();
-                    pos += UINT16_NUM_BYTES;
-                    const magic = event.data
-                        .subarray(pos, pos + UINT32_NUM_BYTES)
-                        .readUint32BE();
-                    if (magic == protocol_js_1.EVM_FORMAT_MAGIC) {
-                        value.evm = event.data.subarray(pos, pos + len);
-                    }
-                    else if (magic == protocol_js_1.SOLANA_FORMAT_MAGIC_BE) {
-                        value.solana = event.data.subarray(pos, pos + len);
-                    }
-                    else if (magic == protocol_js_1.PARSED_FORMAT_MAGIC) {
-                        value.parsed = JSON.parse(event.data.subarray(pos + UINT32_NUM_BYTES, pos + len).toString());
-                    }
-                    else {
-                        throw new Error("unknown magic: " + magic.toString());
-                    }
-                    pos += len;
-                }
-                handler({ type: "binary", value });
-            }
-            else {
-                throw new TypeError("unexpected event data type");
-            }
-        });
-    }
-    send(request) {
-        this.ws.send(JSON.stringify(request));
-    }
-}
-exports.PythLazerClient = PythLazerClient;
+__exportStar(require("./client.js"), exports);
+__exportStar(require("./protocol.js"), exports);
+__exportStar(require("./ed25519.js"), exports);

package/dist/cjs/socket/resilient-web-socket.d.ts

@@ -0,0 +1,38 @@
+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;
+    wsUserClosed: boolean;
+    private wsOptions;
+    private wsFailedAttempts;
+    private heartbeatTimeout;
+    private logger;
+    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.
+     */
+    private resetHeartbeat;
+    private waitForMaybeReadyWebSocket;
+    private handleClose;
+    private restartUnexpectedClosedWebsocket;
+    closeWebSocket(): void;
+}

package/dist/cjs/socket/resilient-web-socket.js

@@ -0,0 +1,161 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": 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).
+ */
+class ResilientWebSocket {
+    endpoint;
+    wsClient;
+    wsUserClosed;
+    wsOptions;
+    wsFailedAttempts;
+    heartbeatTimeout;
+    logger;
+    onError;
+    onMessage;
+    onReconnect;
+    constructor(endpoint, wsOptions, logger) {
+        this.endpoint = endpoint;
+        this.wsOptions = wsOptions;
+        this.logger = logger;
+        this.wsFailedAttempts = 0;
+        this.onError = (error) => {
+            this.logger?.error(error.error);
+        };
+        this.wsUserClosed = true;
+        this.onMessage = (data) => {
+            void data;
+        };
+        this.onReconnect = () => {
+            // Empty function, can be set by the user.
+        };
+    }
+    async send(data) {
+        this.logger?.info(`Sending message`);
+        await this.waitForMaybeReadyWebSocket();
+        if (this.wsClient === undefined) {
+            this.logger?.error("Couldn't connect to the websocket server. Error callback is called.");
+        }
+        else {
+            this.wsClient.send(data);
+        }
+    }
+    startWebSocket() {
+        if (this.wsClient !== undefined) {
+            return;
+        }
+        this.logger?.info(`Creating Web Socket client`);
+        this.wsClient = new isomorphic_ws_1.default(this.endpoint, this.wsOptions);
+        this.wsUserClosed = false;
+        this.wsClient.addEventListener("open", () => {
+            this.wsFailedAttempts = 0;
+            this.resetHeartbeat();
+        });
+        this.wsClient.addEventListener("error", (event) => {
+            this.onError(event);
+        });
+        this.wsClient.addEventListener("message", (event) => {
+            this.resetHeartbeat();
+            this.onMessage(event.data);
+        });
+        this.wsClient.addEventListener("close", () => {
+            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();
+            });
+        }
+    }
+    /**
+     * 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);
+        }
+        this.heartbeatTimeout = setTimeout(() => {
+            this.logger?.warn("Connection timed out. Reconnecting...");
+            this.wsClient?.terminate();
+            void this.restartUnexpectedClosedWebsocket();
+        }, HEARTBEAT_TIMEOUT_DURATION);
+    }
+    async waitForMaybeReadyWebSocket() {
+        let waitedTime = 0;
+        while (this.wsClient !== undefined &&
+            this.wsClient.readyState !== this.wsClient.OPEN) {
+            if (waitedTime > 5000) {
+                this.wsClient.close();
+                return;
+            }
+            else {
+                waitedTime += 10;
+                await sleep(10);
+            }
+        }
+    }
+    async handleClose() {
+        if (this.heartbeatTimeout !== undefined) {
+            clearTimeout(this.heartbeatTimeout);
+        }
+        if (this.wsUserClosed) {
+            this.logger?.info("The connection has been closed successfully.");
+        }
+        else {
+            this.wsFailedAttempts += 1;
+            this.wsClient = undefined;
+            const waitTime = expoBackoff(this.wsFailedAttempts);
+            this.logger?.error("Connection closed unexpectedly or because of timeout. Reconnecting after " +
+                String(waitTime) +
+                "ms.");
+            await sleep(waitTime);
+            await this.restartUnexpectedClosedWebsocket();
+        }
+    }
+    async restartUnexpectedClosedWebsocket() {
+        if (this.wsUserClosed) {
+            return;
+        }
+        this.startWebSocket();
+        await this.waitForMaybeReadyWebSocket();
+        if (this.wsClient === undefined) {
+            this.logger?.error("Couldn't reconnect to websocket. Error callback is called.");
+            return;
+        }
+        this.onReconnect();
+    }
+    closeWebSocket() {
+        if (this.wsClient !== undefined) {
+            const client = this.wsClient;
+            this.wsClient = undefined;
+            client.close();
+        }
+        this.wsUserClosed = true;
+    }
+}
+exports.ResilientWebSocket = ResilientWebSocket;
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function expoBackoff(attempts) {
+    return 2 ** attempts * 100;
+}

package/dist/cjs/socket/web-socket-pool.d.ts

@@ -0,0 +1,55 @@
+import WebSocket from "isomorphic-ws";
+import { type Logger } from "ts-log";
+import { ResilientWebSocket } from "./resilient-web-socket.js";
+import type { Request } from "../protocol.js";
+export declare class WebSocketPool {
+    private readonly logger;
+    rwsPool: ResilientWebSocket[];
+    private cache;
+    private subscriptions;
+    private messageListeners;
+    /**
+     * Creates a new WebSocketPool instance that uses multiple redundant WebSocket connections for reliability.
+     * Usage semantics are similar to using a regular WebSocket client.
+     * @param urls - List of WebSocket URLs to connect to
+     * @param token - Authentication token to use for the connections
+     * @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);
+    /**
+     * Checks for error responses in JSON messages and throws appropriate errors
+     */
+    private handleErrorMessages;
+    /**
+     * Handles incoming websocket messages by deduplicating identical messages received across
+     * 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
+     */
+    shutdown(): void;
+}