@lerna-labs/hydra-sdk 1.0.0-beta.9 → 2.0.0-beta.1

package/dist/hydra/hydra-monitor.js

@@ -0,0 +1,270 @@
+import { EventEmitter } from 'node:events';
+import { HEAD_STATUS_TO_HYDRA, HydraWebSocket, TAG_TO_HYDRA } from './hydra-websocket.js';
+const HYDRA_TO_HEAD_STATUS = {
+    IDLE: 'Idle',
+    OPEN: 'Open',
+    CLOSED: 'Closed',
+    FANOUT_POSSIBLE: 'FanoutPossible',
+    FINAL: 'Final',
+};
+/**
+ * Persistent WebSocket monitor for a Hydra head.
+ *
+ * Maintains a single long-lived WebSocket connection with auto-reconnect,
+ * real-time head state tracking, and proactive error surfacing.
+ *
+ * Events emitted:
+ * - `'message'`        — `(msg: HydraWsMessage)` for every incoming message
+ * - `'status'`         — `(status: HydraStatus, previous: HydraStatus)` on head-status changes
+ * - `'error:tx'`       — `(msg)` on PostTxOnChainFailed or TxInvalid
+ * - `'error:command'`  — `(msg)` on CommandFailed
+ * - `'error:decommit'` — `(msg)` on DecommitInvalid
+ * - `'connected'`      — `()` WebSocket open + Greetings received
+ * - `'disconnected'`   — `()` WebSocket closed (reconnect may follow)
+ * - `'reconnecting'`   — `(attempt: number, delayMs: number)`
+ * - `'reconnect_failed'` — `()` maxAttempts exhausted
+ *
+ * @example
+ * ```ts
+ * const monitor = new HydraMonitor({ wsUrl: 'ws://hydra-node:4102' });
+ * await monitor.start();
+ * console.log(monitor.headStatus); // 'IDLE'
+ * monitor.on('status', (s, prev) => console.log(`${prev} → ${s}`));
+ * ```
+ */
+export class HydraMonitor extends EventEmitter {
+    ws;
+    _headStatus = 'IDLE';
+    _previousStatus = 'IDLE';
+    _headId = null;
+    _events = [];
+    _stopped = true;
+    _reconnecting = false;
+    reconnectEnabled;
+    baseDelayMs;
+    maxDelayMs;
+    maxAttempts;
+    eventBufferSize;
+    boundOnMessage = (msg) => this.onMessage(msg);
+    boundOnClose = () => this.onClose();
+    constructor(options) {
+        super();
+        this.ws = new HydraWebSocket(options.wsUrl);
+        this.reconnectEnabled = options.reconnect?.enabled ?? true;
+        this.baseDelayMs = options.reconnect?.baseDelayMs ?? 1000;
+        this.maxDelayMs = options.reconnect?.maxDelayMs ?? 30_000;
+        this.maxAttempts = options.reconnect?.maxAttempts ?? Number.POSITIVE_INFINITY;
+        this.eventBufferSize = options.eventBufferSize ?? 100;
+    }
+    /** Connect to the Hydra node. Resolves after Greetings received. */
+    async start() {
+        this._stopped = false;
+        await this.ws.waitForGreetings();
+        this.ws.on('message', this.boundOnMessage);
+        this.ws.on('close', this.boundOnClose);
+        // Process the Greetings that was received during waitForGreetings
+        if (this.ws.lastGreetings) {
+            this.onMessage(this.ws.lastGreetings);
+        }
+        this.emit('connected');
+    }
+    /** Disconnect and stop reconnecting. */
+    async stop() {
+        this._stopped = true;
+        this.ws.removeListener('message', this.boundOnMessage);
+        this.ws.removeListener('close', this.boundOnClose);
+        await this.ws.disconnect();
+        this.emit('disconnected');
+    }
+    /** Whether the monitor is actively connected and listening. */
+    get connected() {
+        return this.ws.connectionState === 'CONNECTED';
+    }
+    /** Current head status (uppercase). */
+    get headStatus() {
+        return this._headStatus;
+    }
+    /** Current head status (mixed-case, as reported in Greetings). */
+    get headStatusMixed() {
+        return HYDRA_TO_HEAD_STATUS[this._headStatus];
+    }
+    /** The full Greetings message from the most recent connection. */
+    get greetings() {
+        return this.ws.lastGreetings;
+    }
+    /**
+     * Summary of Hydra head info derived from live state plus the last Greetings.
+     *
+     * `headStatus` and `headId` reflect the current state tracked from transition
+     * messages (`HeadIsOpen`, `HeadIsClosed`, etc.), not the snapshot taken
+     * at connection time. The remaining fields (node version, participants,
+     * contestation period, network info) come from the cached Greetings since
+     * they are static for the life of the head.
+     *
+     * Excludes the full UTxO snapshot to keep payloads small.
+     * Returns `null` if no Greetings has been received yet.
+     */
+    get headInfo() {
+        const g = this.greetings;
+        if (!g)
+            return null;
+        const peers = g.env?.configuredPeers;
+        const peerCount = peers ? peers.split(',').filter(Boolean).length : 0;
+        return {
+            headStatus: HYDRA_TO_HEAD_STATUS[this._headStatus],
+            headId: this._headId,
+            nodeVersion: g.hydraNodeVersion ?? null,
+            me: g.me.vkey,
+            contestationPeriod: g.env?.contestationPeriod ?? null,
+            depositPeriod: g.env?.depositPeriod ?? null,
+            participants: g.env?.participants ?? [],
+            networkConnected: g.networkInfo?.networkConnected ?? false,
+            peerCount,
+            chainSyncedStatus: g.chainSyncedStatus ?? null,
+            currentSlot: g.currentSlot ?? null,
+        };
+    }
+    /** The last N events (configurable via eventBufferSize). Most recent last. */
+    get recentEvents() {
+        return this._events;
+    }
+    /**
+     * Wait for headStatus to reach the target. Resolves immediately if already there.
+     * @param target - The HydraStatus to wait for.
+     * @param timeoutMs - Maximum wait time (default 60s).
+     */
+    waitForStatus(target, timeoutMs = 60_000) {
+        if (this._headStatus === target)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.removeListener('status', onStatus);
+                reject(new Error(`Timeout waiting for status "${target}" (current: "${this._headStatus}")`));
+            }, timeoutMs);
+            const onStatus = (status) => {
+                if (status === target) {
+                    clearTimeout(timer);
+                    this.removeListener('status', onStatus);
+                    resolve();
+                }
+            };
+            this.on('status', onStatus);
+        });
+    }
+    /**
+     * Wait for the next message matching the given tag.
+     * @param tag - The message tag to wait for.
+     * @param timeoutMs - Maximum wait time (default 60s).
+     */
+    waitForMessage(tag, timeoutMs = 60_000) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.removeListener('message', onMsg);
+                reject(new Error(`Timeout waiting for message "${tag}"`));
+            }, timeoutMs);
+            const onMsg = (msg) => {
+                if (msg.tag === tag) {
+                    clearTimeout(timer);
+                    this.removeListener('message', onMsg);
+                    resolve(msg);
+                }
+            };
+            this.on('message', onMsg);
+        });
+    }
+    onMessage(msg) {
+        // Ring buffer
+        this._events.push({ timestamp: Date.now(), message: msg });
+        if (this._events.length > this.eventBufferSize) {
+            this._events.shift();
+        }
+        // Forward to listeners
+        this.emit('message', msg);
+        // Status tracking
+        if (msg.tag === 'Greetings' && 'headStatus' in msg) {
+            const mapped = HEAD_STATUS_TO_HYDRA[msg.headStatus];
+            if (mapped)
+                this.updateStatus(mapped);
+            const greetingHeadId = msg.hydraHeadId;
+            if (greetingHeadId)
+                this._headId = greetingHeadId;
+        }
+        else {
+            const mapped = TAG_TO_HYDRA[msg.tag];
+            if (mapped)
+                this.updateStatus(mapped);
+            // Track headId from transition messages (Greetings may not include
+            // it for a fresh node — under Hydra v2's direct-open flow, HeadIsOpen
+            // is the first place it reliably appears).
+            const msgHeadId = msg.headId;
+            if (typeof msgHeadId === 'string' && msgHeadId) {
+                this._headId = msgHeadId;
+            }
+        }
+        // Error routing
+        if (msg.tag === 'PostTxOnChainFailed' || msg.tag === 'TxInvalid') {
+            this.emit('error:tx', msg);
+        }
+        else if (msg.tag === 'CommandFailed') {
+            this.emit('error:command', msg);
+        }
+        else if (msg.tag === 'DecommitInvalid') {
+            this.emit('error:decommit', msg);
+        }
+    }
+    updateStatus(newStatus) {
+        if (this._headStatus !== newStatus) {
+            this._previousStatus = this._headStatus;
+            this._headStatus = newStatus;
+            this.emit('status', newStatus, this._previousStatus);
+        }
+    }
+    onClose() {
+        if (this._stopped)
+            return;
+        this.ws.removeListener('message', this.boundOnMessage);
+        this.ws.removeListener('close', this.boundOnClose);
+        if (this.reconnectEnabled) {
+            this.reconnectLoop();
+        }
+        else {
+            this.emit('disconnected');
+        }
+    }
+    async reconnectLoop() {
+        if (this._reconnecting)
+            return;
+        this._reconnecting = true;
+        this.emit('disconnected');
+        for (let attempt = 0; attempt < this.maxAttempts; attempt++) {
+            if (this._stopped) {
+                this._reconnecting = false;
+                return;
+            }
+            const delay = Math.min(this.baseDelayMs * 2 ** attempt, this.maxDelayMs);
+            this.emit('reconnecting', attempt + 1, delay);
+            await new Promise((r) => setTimeout(r, delay));
+            if (this._stopped) {
+                this._reconnecting = false;
+                return;
+            }
+            try {
+                await this.ws.waitForGreetings();
+                this.ws.on('message', this.boundOnMessage);
+                this.ws.on('close', this.boundOnClose);
+                // Process the Greetings from the new connection
+                if (this.ws.lastGreetings) {
+                    this.onMessage(this.ws.lastGreetings);
+                }
+                this._reconnecting = false;
+                this.emit('connected');
+                return;
+            }
+            catch {
+                // Retry on next iteration
+            }
+        }
+        this._reconnecting = false;
+        this.emit('reconnect_failed');
+    }
+}

package/dist/hydra/hydra-websocket.d.ts

@@ -0,0 +1,46 @@
+import { EventEmitter } from 'node:events';
+import type { ClientInput, ConnectionState, HeadStatus, HydraStatus, HydraWsMessage } from './types.js';
+export declare const HEAD_STATUS_TO_HYDRA: Record<HeadStatus, HydraStatus>;
+export declare const TAG_TO_HYDRA: Record<string, HydraStatus>;
+/**
+ * Thin WebSocket wrapper for the Hydra node.
+ *
+ * Uses `EventEmitter` for multi-listener message dispatch (no single-callback
+ * overwrite). Emits:
+ *
+ * - `'message'`  — `(msg: HydraWsMessage)` for every incoming message
+ * - `'status'`   — `(status: HydraStatus)` on head-status changes
+ * - `'error'`    — `(err: Error)`
+ * - `'close'`    — `()`
+ */
+export declare class HydraWebSocket extends EventEmitter {
+    private ws;
+    private readonly url;
+    private _status;
+    private _connectionState;
+    private _lastGreetings;
+    constructor(wsUrl: string);
+    /** Current connection state. */
+    get connectionState(): ConnectionState;
+    /** Open the WebSocket connection. Resolves when the socket is open. */
+    connect(): Promise<void>;
+    /**
+     * Connect and wait for the Greetings message from the Hydra node.
+     *
+     * Unlike `HydraProvider.isConnected()`, this does NOT overwrite existing
+     * message handlers — it uses a one-time EventEmitter listener.
+     */
+    waitForGreetings(timeoutMs?: number): Promise<boolean>;
+    /** Close the WebSocket. */
+    disconnect(timeoutMs?: number): Promise<void>;
+    /** Send a ClientInput message as JSON over the WebSocket. */
+    send(message: ClientInput): void;
+    /** Current Hydra head status derived from messages. */
+    getStatus(): HydraStatus;
+    /** Register a status-change listener. Returns current status. */
+    onStatusChange(callback: (status: HydraStatus) => void): HydraStatus;
+    /** The last Greetings message received, if any. */
+    get lastGreetings(): HydraWsMessage | null;
+    private handleMessage;
+    private updateStatus;
+}

package/dist/hydra/hydra-websocket.js

@@ -0,0 +1,181 @@
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+export const HEAD_STATUS_TO_HYDRA = {
+    Idle: 'IDLE',
+    Open: 'OPEN',
+    Closed: 'CLOSED',
+    FanoutPossible: 'FANOUT_POSSIBLE',
+    Final: 'FINAL',
+};
+export const TAG_TO_HYDRA = {
+    HeadIsOpen: 'OPEN',
+    HeadIsClosed: 'CLOSED',
+    ReadyToFanout: 'FANOUT_POSSIBLE',
+    HeadIsFinalized: 'FINAL',
+};
+/**
+ * Thin WebSocket wrapper for the Hydra node.
+ *
+ * Uses `EventEmitter` for multi-listener message dispatch (no single-callback
+ * overwrite). Emits:
+ *
+ * - `'message'`  — `(msg: HydraWsMessage)` for every incoming message
+ * - `'status'`   — `(status: HydraStatus)` on head-status changes
+ * - `'error'`    — `(err: Error)`
+ * - `'close'`    — `()`
+ */
+export class HydraWebSocket extends EventEmitter {
+    ws = null;
+    url;
+    _status = 'IDLE';
+    _connectionState = 'IDLE';
+    _lastGreetings = null;
+    constructor(wsUrl) {
+        super();
+        this.url = wsUrl;
+    }
+    /** Current connection state. */
+    get connectionState() {
+        return this._connectionState;
+    }
+    /** Open the WebSocket connection. Resolves when the socket is open. */
+    async connect() {
+        if (this.ws?.readyState === WebSocket.OPEN)
+            return;
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(this.url);
+            ws.on('open', () => {
+                this.ws = ws;
+                this._connectionState = 'CONNECTING';
+                resolve();
+            });
+            ws.on('message', (data) => {
+                try {
+                    const msg = JSON.parse(data.toString());
+                    this.handleMessage(msg);
+                }
+                catch {
+                    // Ignore non-JSON messages
+                }
+            });
+            ws.on('error', (err) => {
+                this._connectionState = 'FAILED';
+                this.emit('error', err);
+                reject(new Error(`WebSocket error: ${err.message}`));
+            });
+            ws.on('close', () => {
+                this._connectionState = 'DISCONNECTED';
+                this.ws = null;
+                this.emit('close');
+            });
+        });
+    }
+    /**
+     * Connect and wait for the Greetings message from the Hydra node.
+     *
+     * Unlike `HydraProvider.isConnected()`, this does NOT overwrite existing
+     * message handlers — it uses a one-time EventEmitter listener.
+     */
+    async waitForGreetings(timeoutMs = 30_000) {
+        if (this._connectionState === 'CONNECTED')
+            return true;
+        // Register the listener BEFORE connecting so the Greetings message
+        // (which the Hydra node sends immediately after the socket opens)
+        // cannot arrive before we're listening for it.
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.removeListener('message', onMsg);
+                this._connectionState = 'FAILED';
+                reject(new Error('Connection timed out: no Greetings from Hydra node'));
+            }, timeoutMs);
+            const onMsg = (msg) => {
+                if (msg.tag === 'Greetings') {
+                    clearTimeout(timer);
+                    this.removeListener('message', onMsg);
+                    this._connectionState = 'CONNECTED';
+                    resolve(true);
+                }
+            };
+            this.on('message', onMsg);
+            this.connect().catch((err) => {
+                clearTimeout(timer);
+                this.removeListener('message', onMsg);
+                reject(err);
+            });
+        });
+    }
+    /** Close the WebSocket. */
+    async disconnect(timeoutMs = 5000) {
+        if (!this.ws || this.ws.readyState === WebSocket.CLOSED) {
+            this._connectionState = 'DISCONNECTED';
+            return;
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.ws?.terminate();
+                this._connectionState = 'DISCONNECTED';
+                this.ws = null;
+                resolve();
+            }, timeoutMs);
+            this.ws.on('close', () => {
+                clearTimeout(timer);
+                this._connectionState = 'DISCONNECTED';
+                this.ws = null;
+                resolve();
+            });
+            this.ws.close();
+        });
+    }
+    /** Send a ClientInput message as JSON over the WebSocket. */
+    send(message) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('WebSocket is not connected');
+        }
+        this.ws.send(JSON.stringify(message));
+    }
+    /** Current Hydra head status derived from messages. */
+    getStatus() {
+        return this._status;
+    }
+    /** Register a status-change listener. Returns current status. */
+    onStatusChange(callback) {
+        this.on('status', callback);
+        return this._status;
+    }
+    /** The last Greetings message received, if any. */
+    get lastGreetings() {
+        return this._lastGreetings;
+    }
+    handleMessage(msg) {
+        // Strip sensitive fields before caching or emitting
+        if (msg.tag === 'Greetings') {
+            const sanitized = { ...msg };
+            if (sanitized.env && typeof sanitized.env === 'object') {
+                const { signingKey: _, ...safeEnv } = sanitized.env;
+                sanitized.env = safeEnv;
+            }
+            this._lastGreetings = sanitized;
+            this.emit('message', sanitized);
+        }
+        else {
+            this.emit('message', msg);
+        }
+        // Update status from Greetings headStatus
+        if (msg.tag === 'Greetings' && 'headStatus' in msg) {
+            const mapped = HEAD_STATUS_TO_HYDRA[msg.headStatus];
+            if (mapped)
+                this.updateStatus(mapped);
+            return;
+        }
+        // Update status from state transition messages
+        const mapped = TAG_TO_HYDRA[msg.tag];
+        if (mapped)
+            this.updateStatus(mapped);
+    }
+    updateStatus(newStatus) {
+        if (this._status !== newStatus) {
+            this._status = newStatus;
+            this.emit('status', newStatus);
+        }
+    }
+}

package/dist/hydra/messages.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Re-exported Hydra WebSocket message types.
+ *
+ * `ServerOutput` is a discriminated union (on `.tag`) of all possible messages
+ * the Hydra node can send over its WebSocket API. Use `Extract` to narrow:
+ *
+ * @example
+ * ```ts
+ * function handleOpen(msg: HydraMessage<"HeadIsOpen">) {
+ *   console.log(msg.tag);
+ * }
+ * ```
+ */
+export type { ClientInput, ClientMessage, ConfirmedSnapshot, ConnectionState, HeadStatus, HydraHeadInfo, HydraMessage, HydraMonitorOptions, HydraSnapshot, HydraStatus, HydraTransaction, HydraWsMessage, hydraStatus, hydraTransaction, ServerOutput, TimestampedEvent, } from './types.js';

package/dist/hydra/messages.js

@@ -0,0 +1 @@
+export {};