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

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

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import { HydraWebSocket } from './hydra-websocket.js';
-import type { GreetingsMessage, HeadStatus, HydraMessage, HydraMonitorOptions, HydraStatus, ServerOutput, TimestampedEvent } from './types.js';
+import type { GreetingsMessage, HeadStatus, HydraHeadInfo, HydraMessage, HydraMonitorOptions, HydraStatus, ServerOutput, TimestampedEvent } from './types.js';
 /**
  * Persistent WebSocket monitor for a Hydra head.
  *
@@ -53,6 +53,12 @@ export declare class HydraMonitor extends EventEmitter {
     get headStatusMixed(): HeadStatus;
     /** The full Greetings message from the most recent connection. */
     get greetings(): GreetingsMessage | null;
+    /**
+     * Summary of Hydra head info extracted from the last Greetings.
+     * Excludes the full UTxO snapshot to keep payloads small.
+     * Returns `null` if no Greetings has been received yet.
+     */
+    get headInfo(): HydraHeadInfo | null;
     /** The last N events (configurable via eventBufferSize). Most recent last. */
     get recentEvents(): readonly TimestampedEvent[];
     /**

package/dist/hydra/hydra-monitor.js

@@ -92,6 +92,31 @@ export class HydraMonitor extends EventEmitter {
     get greetings() {
         return this.ws.lastGreetings;
     }
+    /**
+     * Summary of Hydra head info extracted from the last Greetings.
+     * 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: g.headStatus,
+            headId: g.hydraHeadId ?? null,
+            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;

package/dist/hydra/hydra-websocket.js

@@ -149,10 +149,19 @@ export class HydraWebSocket extends EventEmitter {
         return this._lastGreetings;
     }
     handleMessage(msg) {
+        // Strip sensitive fields before caching or emitting
         if (msg.tag === 'Greetings') {
-            this._lastGreetings = msg;
+            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);
         }
-        this.emit('message', msg);
         // Update status from Greetings headStatus
         if (msg.tag === 'Greetings' && 'headStatus' in msg) {
             const mapped = HEAD_STATUS_TO_HYDRA[msg.headStatus];

package/dist/hydra/messages.d.ts

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

package/dist/hydra/types.d.ts

@@ -50,6 +50,28 @@ export type HydraStatus = 'IDLE' | 'INITIALIZING' | 'OPEN' | 'CLOSED' | 'FANOUT_
 export type hydraStatus = HydraStatus;
 /** Connection state of the WebSocket. */
 export type ConnectionState = 'IDLE' | 'CONNECTING' | 'CONNECTED' | 'FAILED' | 'DISCONNECTED';
+/** A confirmed Hydra L2 snapshot. */
+export interface HydraSnapshot {
+    headId: string;
+    version: number;
+    number: number;
+    confirmed: HydraTransaction[];
+    utxo: HydraUTxOs;
+    utxoToCommit: HydraUTxOs | null;
+    utxoToDecommit: HydraUTxOs | null;
+}
+/** Multi-party aggregate signature map. */
+export type MultiSignature = Record<string, string>;
+/** Discriminated union for confirmed snapshot variants. */
+export type ConfirmedSnapshot = {
+    tag: 'InitialSnapshot';
+    headId: string;
+    initialUTxO?: HydraUTxOs;
+} | {
+    tag: 'ConfirmedSnapshot';
+    snapshot: HydraSnapshot;
+    signatures: MultiSignature;
+};
 /** Messages that can be sent to the Hydra node over WebSocket. */
 export type ClientInput = {
     tag: 'Init';
@@ -60,17 +82,44 @@ export type ClientInput = {
     transaction: HydraTransaction;
 } | {
     tag: 'Close';
+} | {
+    tag: 'SafeClose';
 } | {
     tag: 'Contest';
 } | {
     tag: 'Fanout';
 } | {
     tag: 'Decommit';
-    transaction: HydraTransaction;
+    decommitTx: HydraTransaction;
 } | {
     tag: 'Recover';
     recoverTxId: string;
+} | {
+    tag: 'SideLoadSnapshot';
+    snapshot: ConfirmedSnapshot;
 };
+/** Hydra node environment info reported in Greetings. */
+export interface HydraEnv {
+    party: {
+        vkey: string;
+    };
+    signingKey?: string;
+    otherParties: {
+        vkey: string;
+    }[];
+    participants: string[];
+    contestationPeriod: number;
+    depositPeriod: number;
+    unsyncedPeriod?: number;
+    configuredPeers: string;
+    [key: string]: unknown;
+}
+/** Network connectivity info reported in Greetings. */
+export interface HydraNetworkInfo {
+    networkConnected: boolean;
+    peersInfo: Record<string, unknown>;
+    [key: string]: unknown;
+}
 /** Greetings message received on initial WebSocket connection. */
 export interface GreetingsMessage {
     tag: 'Greetings';
@@ -80,9 +129,29 @@ export interface GreetingsMessage {
     headStatus: HeadStatus;
     hydraHeadId?: string;
     snapshotUtxo?: HydraUTxOs;
-    hydraNodeVersion?: string;
-    env?: Record<string, unknown>;
-    networkInfo?: Record<string, unknown>;
+    timestamp?: string;
+    hydraNodeVersion: string;
+    env: HydraEnv;
+    networkInfo: HydraNetworkInfo;
+    chainSyncedStatus: string;
+    currentSlot: number;
+}
+/**
+ * Summary of Hydra head info extracted from the Greetings message.
+ * Excludes the full UTxO snapshot to keep payloads small.
+ */
+export interface HydraHeadInfo {
+    headStatus: HeadStatus;
+    headId: string | null;
+    nodeVersion: string | null;
+    me: string;
+    contestationPeriod: number | null;
+    depositPeriod: number | null;
+    participants: string[];
+    networkConnected: boolean;
+    peerCount: number;
+    chainSyncedStatus: string | null;
+    currentSlot: number | null;
 }
 export interface HeadIsInitializingMessage {
     tag: 'HeadIsInitializing';
@@ -90,6 +159,8 @@ export interface HeadIsInitializingMessage {
     parties: {
         vkey: string;
     }[];
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface CommittedMessage {
@@ -98,78 +169,309 @@ export interface CommittedMessage {
         vkey: string;
     };
     utxo: HydraUTxOs;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface HeadIsOpenMessage {
     tag: 'HeadIsOpen';
+    headId: string;
     utxo: HydraUTxOs;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface HeadIsClosedMessage {
     tag: 'HeadIsClosed';
+    headId: string;
+    snapshotNumber: number;
+    contestationDeadline: string;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface HeadIsContestedMessage {
     tag: 'HeadIsContested';
+    headId: string;
+    snapshotNumber: number;
+    contestationDeadline: string;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface ReadyToFanoutMessage {
     tag: 'ReadyToFanout';
+    headId: string;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface HeadIsAbortedMessage {
     tag: 'HeadIsAborted';
+    headId: string;
+    utxo: HydraUTxOs;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface HeadIsFinalizedMessage {
     tag: 'HeadIsFinalized';
+    headId: string;
+    utxo: HydraUTxOs;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface TxValidMessage {
     tag: 'TxValid';
-    transaction: HydraTransaction;
+    headId: string;
+    transactionId: string;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface TxInvalidMessage {
     tag: 'TxInvalid';
+    headId: string;
+    utxo: HydraUTxOs;
     transaction: HydraTransaction;
     validationError: {
         reason: string;
     };
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface SnapshotConfirmedMessage {
     tag: 'SnapshotConfirmed';
+    headId: string;
+    snapshot: HydraSnapshot;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
-export interface DecommitApprovedMessage {
-    tag: 'DecommitApproved';
+export interface SnapshotSideLoadedMessage {
+    tag: 'SnapshotSideLoaded';
+    headId: string;
+    snapshotNumber: number;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
-export interface DecommitInvalidMessage {
-    tag: 'DecommitInvalid';
-    decommitInvalidReason: unknown;
+export interface CommitRecordedMessage {
+    tag: 'CommitRecorded';
+    headId: string;
+    utxoToCommit: HydraUTxOs;
+    pendingDeposit: string;
+    deadline: string;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
-export interface DecommitFinalizedMessage {
-    tag: 'DecommitFinalized';
+export interface CommitApprovedMessage {
+    tag: 'CommitApproved';
+    headId: string;
+    utxoToCommit: HydraUTxOs;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface CommitFinalizedMessage {
     tag: 'CommitFinalized';
+    headId: string;
+    depositTxId: string;
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
-export interface CommitApprovedMessage {
-    tag: 'CommitApproved';
+export interface CommitRecoveredMessage {
+    tag: 'CommitRecovered';
+    headId: string;
+    recoveredUTxO: HydraUTxOs;
+    recoveredTxId: string;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface DepositActivatedMessage {
+    tag: 'DepositActivated';
+    headId: string;
+    depositTxId: string;
+    deadline: string;
+    chainTime: string;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface DepositExpiredMessage {
+    tag: 'DepositExpired';
+    headId: string;
+    depositTxId: string;
+    deadline: string;
+    chainTime: string;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface DecommitRequestedMessage {
+    tag: 'DecommitRequested';
+    headId: string;
+    decommitTx: HydraTransaction;
+    utxoToDecommit: HydraUTxOs;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface DecommitApprovedMessage {
+    tag: 'DecommitApproved';
+    headId: string;
+    decommitTxId: string;
+    utxoToDecommit: HydraUTxOs;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface DecommitFinalizedMessage {
+    tag: 'DecommitFinalized';
+    headId: string;
+    distributedUTxO: HydraUTxOs;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface DecommitInvalidMessage {
+    tag: 'DecommitInvalid';
+    headId: string;
+    decommitTx: HydraTransaction;
+    decommitInvalidReason: {
+        tag: 'DecommitTxInvalid';
+        localUTxO: HydraUTxOs;
+        validationError: {
+            reason: string;
+        };
+    } | {
+        tag: 'DecommitAlreadyInFlight';
+        otherDecommitTxId: string;
+    };
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface CommandFailedMessage {
     tag: 'CommandFailed';
     clientInput: ClientInput;
+    state: unknown;
     [key: string]: unknown;
 }
 export interface PostTxOnChainFailedMessage {
     tag: 'PostTxOnChainFailed';
+    postChainTx: unknown;
+    postTxError: unknown;
+    [key: string]: unknown;
+}
+export interface InvalidInputMessage {
+    tag: 'InvalidInput';
+    reason: string;
+    input: string;
+    [key: string]: unknown;
+}
+export interface RejectedInputBecauseUnsyncedMessage {
+    tag: 'RejectedInputBecauseUnsynced';
+    clientInput: ClientInput;
+    drift: number;
+    [key: string]: unknown;
+}
+export interface SideLoadSnapshotRejectedMessage {
+    tag: 'SideLoadSnapshotRejected';
+    clientInput: ClientInput;
+    requirementFailure: unknown;
+    [key: string]: unknown;
+}
+export interface PeerConnectedMessage {
+    tag: 'PeerConnected';
+    peer: string;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface PeerDisconnectedMessage {
+    tag: 'PeerDisconnected';
+    peer: string;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface NetworkConnectedMessage {
+    tag: 'NetworkConnected';
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface NetworkDisconnectedMessage {
+    tag: 'NetworkDisconnected';
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface NetworkVersionMismatchMessage {
+    tag: 'NetworkVersionMismatch';
+    ourVersion: unknown;
+    theirVersion: unknown;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface NetworkClusterIDMismatchMessage {
+    tag: 'NetworkClusterIDMismatch';
+    clusterPeers?: unknown;
+    misconfiguredPeers?: unknown;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface SyncedStatusReportMessage {
+    tag: 'SyncedStatusReport';
+    chainSlot: number;
+    chainTime: string;
+    drift: number;
+    synced: string;
+    [key: string]: unknown;
+}
+export interface NodeSyncedMessage {
+    tag: 'NodeSynced';
+    chainSlot: number;
+    chainTime: string;
+    drift: number;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface NodeUnsyncedMessage {
+    tag: 'NodeUnsynced';
+    chainSlot: number;
+    chainTime: string;
+    drift: number;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface IgnoredHeadInitializingMessage {
+    tag: 'IgnoredHeadInitializing';
+    headId: string;
+    contestationPeriod: number;
+    parties: {
+        vkey: string;
+    }[];
+    participants: string[];
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface EventLogRotatedMessage {
+    tag: 'EventLogRotated';
+    seq: number;
+    checkpoint: unknown;
+    timestamp: string;
     [key: string]: unknown;
 }
 /** Catch-all for message types not explicitly defined above. */
@@ -178,7 +480,7 @@ export interface UnknownMessage {
     [key: string]: unknown;
 }
 /** All possible messages the Hydra node can send over its WebSocket API. */
-export type ServerOutput = GreetingsMessage | HeadIsInitializingMessage | CommittedMessage | HeadIsOpenMessage | HeadIsClosedMessage | HeadIsContestedMessage | ReadyToFanoutMessage | HeadIsAbortedMessage | HeadIsFinalizedMessage | TxValidMessage | TxInvalidMessage | SnapshotConfirmedMessage | DecommitApprovedMessage | DecommitInvalidMessage | DecommitFinalizedMessage | CommitFinalizedMessage | CommitApprovedMessage | CommandFailedMessage | PostTxOnChainFailedMessage | UnknownMessage;
+export type ServerOutput = GreetingsMessage | HeadIsInitializingMessage | CommittedMessage | HeadIsOpenMessage | HeadIsClosedMessage | HeadIsContestedMessage | ReadyToFanoutMessage | HeadIsAbortedMessage | HeadIsFinalizedMessage | TxValidMessage | TxInvalidMessage | SnapshotConfirmedMessage | SnapshotSideLoadedMessage | CommitRecordedMessage | CommitApprovedMessage | CommitFinalizedMessage | CommitRecoveredMessage | DepositActivatedMessage | DepositExpiredMessage | DecommitRequestedMessage | DecommitApprovedMessage | DecommitFinalizedMessage | DecommitInvalidMessage | CommandFailedMessage | PostTxOnChainFailedMessage | InvalidInputMessage | RejectedInputBecauseUnsyncedMessage | SideLoadSnapshotRejectedMessage | PeerConnectedMessage | PeerDisconnectedMessage | NetworkConnectedMessage | NetworkDisconnectedMessage | NetworkVersionMismatchMessage | NetworkClusterIDMismatchMessage | SyncedStatusReportMessage | NodeSyncedMessage | NodeUnsyncedMessage | IgnoredHeadInitializingMessage | EventLogRotatedMessage | UnknownMessage;
 /** Client echo messages (errors, command failures). */
 export type ClientMessage = CommandFailedMessage | PostTxOnChainFailedMessage;
 /** Any message received via the Hydra WebSocket. */

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export type { DiskCache, DiskCacheConfig } from './cache/disk-cache.js';
 export { createDiskCache } from './cache/disk-cache.js';
 export { optionalEnv, requireEnv } from './config.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 { ConfirmedSnapshot, HeadStatus, HydraHeadInfo, HydraMessage, HydraMonitorOptions, HydraSnapshot, 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';

package/package.json

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