@lerna-labs/hydra-sdk 1.0.0-beta.20 → 1.0.0-beta.21

package/dist/hydra/hydra-http-client.js

@@ -23,7 +23,7 @@ export class HydraHttpClient {
      * `POST /decommit` — submits the decommit request to the Hydra node.
      */
     async publishDecommit(transaction) {
-        return this.post('/decommit', { tag: 'Decommit', transaction });
+        return this.post('/decommit', transaction);
     }
     /** Fetch the current UTxO snapshot. `GET /snapshot/utxo` */
     async getSnapshotUtxo() {

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

@@ -0,0 +1,74 @@
+import { EventEmitter } from 'node:events';
+import { HydraWebSocket } from './hydra-websocket.js';
+import type { GreetingsMessage, HeadStatus, HydraMessage, HydraMonitorOptions, HydraStatus, ServerOutput, TimestampedEvent } from './types.js';
+/**
+ * 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 declare class HydraMonitor extends EventEmitter {
+    readonly ws: HydraWebSocket;
+    private _headStatus;
+    private _previousStatus;
+    private _events;
+    private _stopped;
+    private _reconnecting;
+    private readonly reconnectEnabled;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly maxAttempts;
+    private readonly eventBufferSize;
+    private readonly boundOnMessage;
+    private readonly boundOnClose;
+    constructor(options: HydraMonitorOptions);
+    /** Connect to the Hydra node. Resolves after Greetings received. */
+    start(): Promise<void>;
+    /** Disconnect and stop reconnecting. */
+    stop(): Promise<void>;
+    /** Whether the monitor is actively connected and listening. */
+    get connected(): boolean;
+    /** Current head status (uppercase). */
+    get headStatus(): HydraStatus;
+    /** Current head status (mixed-case, as reported in Greetings). */
+    get headStatusMixed(): HeadStatus;
+    /** The full Greetings message from the most recent connection. */
+    get greetings(): GreetingsMessage | null;
+    /** The last N events (configurable via eventBufferSize). Most recent last. */
+    get recentEvents(): readonly TimestampedEvent[];
+    /**
+     * 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: HydraStatus, timeoutMs?: number): Promise<void>;
+    /**
+     * 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<T extends ServerOutput['tag']>(tag: T, timeoutMs?: number): Promise<HydraMessage<T>>;
+    private onMessage;
+    private updateStatus;
+    private onClose;
+    private reconnectLoop;
+}

package/dist/hydra/hydra-monitor.js

@@ -0,0 +1,231 @@
+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',
+    INITIALIZING: 'Initializing',
+    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';
+    _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;
+    }
+    /** 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);
+        }
+        else if (msg.tag === 'HeadIsAborted') {
+            this.updateStatus('IDLE');
+        }
+        else {
+            const mapped = TAG_TO_HYDRA[msg.tag];
+            if (mapped)
+                this.updateStatus(mapped);
+        }
+        // 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

@@ -1,5 +1,7 @@
 import { EventEmitter } from 'node:events';
-import type { ClientInput, ConnectionState, HydraStatus, HydraWsMessage } from './types.js';
+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.
  *

package/dist/hydra/hydra-websocket.js

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import WebSocket from 'ws';
-const HEAD_STATUS_TO_HYDRA = {
+export const HEAD_STATUS_TO_HYDRA = {
     Idle: 'IDLE',
     Initializing: 'INITIALIZING',
     Open: 'OPEN',
@@ -8,7 +8,7 @@ const HEAD_STATUS_TO_HYDRA = {
     FanoutPossible: 'FANOUT_POSSIBLE',
     Final: 'FINAL',
 };
-const TAG_TO_HYDRA = {
+export const TAG_TO_HYDRA = {
     HeadIsInitializing: 'INITIALIZING',
     HeadIsOpen: 'OPEN',
     HeadIsClosed: 'CLOSED',

package/dist/hydra/messages.d.ts

@@ -11,4 +11,4 @@
  * }
  * ```
  */
-export type { ClientInput, ClientMessage, ConnectionState, HeadStatus, HydraMessage, HydraStatus, HydraTransaction, HydraWsMessage, hydraStatus, hydraTransaction, ServerOutput, } from './types.js';
+export type { ClientInput, ClientMessage, ConnectionState, HeadStatus, HydraMessage, HydraMonitorOptions, HydraStatus, HydraTransaction, HydraWsMessage, hydraStatus, hydraTransaction, ServerOutput, TimestampedEvent, } from './types.js';

package/dist/hydra/types.d.ts

@@ -194,3 +194,28 @@ export type HydraWsMessage = ServerOutput | ClientMessage;
 export type HydraMessage<T extends ServerOutput['tag']> = Extract<ServerOutput, {
     tag: T;
 }>;
+/** Configuration options for HydraMonitor. */
+export interface HydraMonitorOptions {
+    /** Hydra node WebSocket URL. */
+    wsUrl: string;
+    /** Auto-reconnect configuration. */
+    reconnect?: {
+        /** Whether to reconnect on unexpected close. Default: `true`. */
+        enabled?: boolean;
+        /** Initial retry delay in milliseconds. Default: `1000`. */
+        baseDelayMs?: number;
+        /** Maximum retry delay in milliseconds. Default: `30000`. */
+        maxDelayMs?: number;
+        /** Maximum reconnect attempts. Default: `Infinity` (keep trying forever). */
+        maxAttempts?: number;
+    };
+    /** Number of recent events to retain in the ring buffer. Default: `100`. */
+    eventBufferSize?: number;
+}
+/** A timestamped Hydra WebSocket event for the recent events buffer. */
+export interface TimestampedEvent {
+    /** Unix timestamp (ms) when the message was received. */
+    timestamp: number;
+    /** The raw Hydra message. */
+    message: HydraWsMessage;
+}

package/dist/hydra/utxo.d.ts

@@ -7,19 +7,29 @@ export interface ParsedUtxo {
         unit: string;
         quantity: string;
     }[];
+    datum?: string | null;
+    datumHash?: string | null;
+    inlineDatum?: unknown | null;
+    referenceScript?: unknown | null;
+}
+/** Options for UTxO query functions. */
+export interface UtxoQueryOptions {
+    /** Include datum, datumHash, inlineDatum, and referenceScript fields. Defaults to `false`. */
+    includeDatums?: boolean;
 }
 /**
  * Fetch the full UTxO set from the Hydra head snapshot.
  *
  * Reads `HYDRA_API_URL` from the environment.
  *
+ * @param options - Query options. Set `includeDatums: true` to include datum/script fields.
  * @returns All UTxOs currently held in the Hydra head.
  */
-export declare function getUtxoSet(): Promise<ParsedUtxo[]>;
+export declare function getUtxoSet(options?: UtxoQueryOptions): Promise<ParsedUtxo[]>;
 /**
  * Fetch UTxOs belonging to a specific address from the Hydra head snapshot.
  *
  * @param address - Bech32 address to filter by.
  * @returns UTxOs matching the given address.
  */
-export declare function queryUtxoByAddress(address: string): Promise<ParsedUtxo[]>;
+export declare function queryUtxoByAddress(address: string, options?: UtxoQueryOptions): Promise<ParsedUtxo[]>;

package/dist/hydra/utxo.js

@@ -4,9 +4,10 @@ import { requireEnv } from '../config.js';
  *
  * Reads `HYDRA_API_URL` from the environment.
  *
+ * @param options - Query options. Set `includeDatums: true` to include datum/script fields.
  * @returns All UTxOs currently held in the Hydra head.
  */
-export async function getUtxoSet() {
+export async function getUtxoSet(options) {
     const baseUrl = requireEnv('HYDRA_API_URL');
     const url = `${baseUrl}/snapshot/utxo`;
     try {
@@ -23,12 +24,14 @@ export async function getUtxoSet() {
                 unit,
                 quantity,
             }));
-            UtxoSet.push({
-                tx_hash,
-                output_index,
-                address: utxo.address,
-                amount,
-            });
+            const parsed = { tx_hash, output_index, address: utxo.address, amount };
+            if (options?.includeDatums) {
+                parsed.datum = utxo.datum ?? null;
+                parsed.datumHash = utxo.datumHash ?? null;
+                parsed.inlineDatum = utxo.inlineDatum ?? null;
+                parsed.referenceScript = utxo.referenceScript ?? null;
+            }
+            UtxoSet.push(parsed);
         }
         return UtxoSet;
     }
@@ -43,9 +46,9 @@ export async function getUtxoSet() {
  * @param address - Bech32 address to filter by.
  * @returns UTxOs matching the given address.
  */
-export async function queryUtxoByAddress(address) {
+export async function queryUtxoByAddress(address, options) {
     const result = [];
-    const data = await getUtxoSet();
+    const data = await getUtxoSet(options);
     for (const utxo of data) {
         if (utxo.address === address) {
             result.push(utxo);

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export type { DiskCache, DiskCacheConfig } from './cache/disk-cache.js';
 export { createDiskCache } from './cache/disk-cache.js';
 export { optionalEnv, requireEnv } from './config.js';
-export type { HeadStatus, HydraMessage, HydraStatus, HydraTransaction, HydraWsMessage, hydraStatus, hydraTransaction, ServerOutput, } from './hydra/messages.js';
-export type { ParsedUtxo } from './hydra/utxo.js';
+export { HydraMonitor } from './hydra/hydra-monitor.js';
+export type { HeadStatus, HydraMessage, HydraMonitorOptions, HydraStatus, HydraTransaction, HydraWsMessage, hydraStatus, hydraTransaction, ServerOutput, TimestampedEvent, } from './hydra/messages.js';
+export type { ParsedUtxo, UtxoQueryOptions } from './hydra/utxo.js';
 export { getUtxoSet, queryUtxoByAddress } from './hydra/utxo.js';
 export type { IpfsClient, IpfsConfig, PinResult } from './ipfs/ipfs.js';
 export { createIpfsClient } from './ipfs/ipfs.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createDiskCache } from './cache/disk-cache.js';
 export { optionalEnv, requireEnv } from './config.js';
+export { HydraMonitor } from './hydra/hydra-monitor.js';
 export { getUtxoSet, queryUtxoByAddress } from './hydra/utxo.js';
 export { createIpfsClient } from './ipfs/ipfs.js';
 export { getAdmin } from './mesh/get-admin.js';

package/dist/wrangler.d.ts

@@ -1,4 +1,5 @@
 import { HydraHttpClient } from './hydra/hydra-http-client.js';
+import type { HydraMonitor } from './hydra/hydra-monitor.js';
 import { HydraWebSocket } from './hydra/hydra-websocket.js';
 import type { HeadStatus, HydraStatus, HydraTransaction } from './hydra/types.js';
 /** UTxO reference for committing funds into a Hydra head. */
@@ -35,7 +36,8 @@ export declare class Wrangler {
     readonly ws: HydraWebSocket;
     readonly http: HydraHttpClient;
     private readonly blockfrost;
-    constructor(url?: string, wsUrl?: string);
+    private readonly monitor;
+    constructor(url?: string, wsUrl?: string, monitor?: HydraMonitor);
     /**
      * Connect to the Hydra node with exponential-backoff retry.
      *

package/dist/wrangler.js

@@ -3,6 +3,14 @@ import { requireEnv } from './config.js';
 import { HydraHttpClient } from './hydra/hydra-http-client.js';
 import { HydraWebSocket } from './hydra/hydra-websocket.js';
 import { toHydraUTxO, toHydraUTxOs } from './hydra/utxo-conversion.js';
+const HYDRA_TO_HEAD_STATUS = {
+    IDLE: 'Idle',
+    INITIALIZING: 'Initializing',
+    OPEN: 'Open',
+    CLOSED: 'Closed',
+    FANOUT_POSSIBLE: 'FanoutPossible',
+    FINAL: 'Final',
+};
 /**
  * High-level controller for Hydra head lifecycle operations.
  *
@@ -23,12 +31,20 @@ export class Wrangler {
     ws;
     http;
     blockfrost;
-    constructor(url, wsUrl) {
+    monitor;
+    constructor(url, wsUrl, monitor) {
         const httpUrl = url || requireEnv('HYDRA_API_URL');
-        const socketUrl = wsUrl || requireEnv('HYDRA_WS_URL');
         this.blockfrost = new BlockfrostProvider(requireEnv('BLOCKFROST_API_KEY'));
-        this.ws = new HydraWebSocket(socketUrl);
         this.http = new HydraHttpClient(httpUrl);
+        this.monitor = monitor ?? null;
+        if (monitor) {
+            // Share the monitor's WebSocket — no new connections
+            this.ws = monitor.ws;
+        }
+        else {
+            const socketUrl = wsUrl || requireEnv('HYDRA_WS_URL');
+            this.ws = new HydraWebSocket(socketUrl);
+        }
     }
     /**
      * Connect to the Hydra node with exponential-backoff retry.
@@ -40,6 +56,9 @@ export class Wrangler {
      * @param baseDelayMs - Initial retry delay in milliseconds (default 1000). Doubles each attempt, capped at 30 s.
      */
     async connectWithRetry(maxAttempts = 5, baseDelayMs = 1000) {
+        // When using a monitor, the WebSocket is already connected
+        if (this.monitor?.connected)
+            return;
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
             try {
                 const connected = await this.ws.waitForGreetings();
@@ -167,6 +186,10 @@ export class Wrangler {
      * @returns The head status string (e.g. `"Idle"`, `"Open"`, `"Closed"`).
      */
     async getHeadStatus(timeoutMs = 5000) {
+        // When using a monitor, read the cached status directly — no new WebSocket
+        if (this.monitor?.connected) {
+            return HYDRA_TO_HEAD_STATUS[this.monitor.headStatus];
+        }
         return this.awaitMessage((message, resolve, _reject) => {
             if (message.tag === 'Greetings') {
                 resolve(message.headStatus);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lerna-labs/hydra-sdk",
-  "version": "1.0.0-beta.20",
+  "version": "1.0.0-beta.21",
   "description": "TypeScript SDK for managing Cardano Hydra Heads — lifecycle, UTxO queries, wallet management, transaction submission, and signature verification",
   "keywords": [
     "cardano",