@lerna-labs/hydra-sdk 1.0.0-beta.27 → 1.0.0-beta.29

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

@@ -30,6 +30,7 @@ export declare class HydraMonitor extends EventEmitter {
     readonly ws: HydraWebSocket;
     private _headStatus;
     private _previousStatus;
+    private _headId;
     private _events;
     private _stopped;
     private _reconnecting;
@@ -54,7 +55,14 @@ export declare class HydraMonitor extends EventEmitter {
     /** The full Greetings message from the most recent connection. */
     get greetings(): GreetingsMessage | null;
     /**
-     * Summary of Hydra head info extracted from the last Greetings.
+     * Summary of Hydra head info derived from live state plus the last Greetings.
+     *
+     * `headStatus` and `headId` reflect the current state tracked from transition
+     * messages (`HeadIsInitializing`, `HeadIsOpen`, 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.
      */

package/dist/hydra/hydra-monitor.js

@@ -37,6 +37,7 @@ export class HydraMonitor extends EventEmitter {
     ws;
     _headStatus = 'IDLE';
     _previousStatus = 'IDLE';
+    _headId = null;
     _events = [];
     _stopped = true;
     _reconnecting = false;
@@ -93,7 +94,14 @@ export class HydraMonitor extends EventEmitter {
         return this.ws.lastGreetings;
     }
     /**
-     * Summary of Hydra head info extracted from the last Greetings.
+     * Summary of Hydra head info derived from live state plus the last Greetings.
+     *
+     * `headStatus` and `headId` reflect the current state tracked from transition
+     * messages (`HeadIsInitializing`, `HeadIsOpen`, 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.
      */
@@ -104,8 +112,8 @@ export class HydraMonitor extends EventEmitter {
         const peers = g.env?.configuredPeers;
         const peerCount = peers ? peers.split(',').filter(Boolean).length : 0;
         return {
-            headStatus: g.headStatus,
-            headId: g.hydraHeadId ?? null,
+            headStatus: HYDRA_TO_HEAD_STATUS[this._headStatus],
+            headId: this._headId,
             nodeVersion: g.hydraNodeVersion ?? null,
             me: g.me.vkey,
             contestationPeriod: g.env?.contestationPeriod ?? null,
@@ -178,14 +186,25 @@ export class HydraMonitor extends EventEmitter {
             const mapped = HEAD_STATUS_TO_HYDRA[msg.headStatus];
             if (mapped)
                 this.updateStatus(mapped);
+            const greetingHeadId = msg.hydraHeadId;
+            if (greetingHeadId)
+                this._headId = greetingHeadId;
         }
         else if (msg.tag === 'HeadIsAborted') {
             this.updateStatus('IDLE');
+            this._headId = null;
         }
         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 — HeadIsInitializing is the first place it
+            // reliably appears). Skipped for HeadIsAborted, which clears it above.
+            const msgHeadId = msg.headId;
+            if (typeof msgHeadId === 'string' && msgHeadId) {
+                this._headId = msgHeadId;
+            }
         }
         // Error routing
         if (msg.tag === 'PostTxOnChainFailed' || msg.tag === 'TxInvalid') {

package/dist/wrangler.d.ts

@@ -70,11 +70,22 @@ export declare class Wrangler {
     shutdownHead(): Promise<void>;
     /**
      * Wait for the Hydra head to fully close and finalize.
+     *
+     * Resolves on the `HeadIsClosed` / `HeadIsFinalized` transition events, **and**
+     * on the initial `Greetings` replay if the head is already at `Closed` or
+     * `Final`. Rejects fast if the head is `Idle` (no head exists to close).
+     *
      * @param timeoutMs - Maximum time to wait in milliseconds.
      */
     waitForHeadClose(timeoutMs?: number): Promise<void>;
     /**
      * Wait for the Hydra head to reach the `Open` state.
+     *
+     * Resolves on the `HeadIsOpen` transition event, **and** on the initial
+     * `Greetings` replay if the head is already `Open`. Rejects fast if the
+     * head is in a terminal or shutting-down state (`Closed`, `FanoutPossible`,
+     * `Final`) — a new head must be started from a fresh node.
+     *
      * @param commitArgs - UTxO to commit into the head during initialization.
      * @param timeoutMs - Maximum time to wait in milliseconds.
      */

package/dist/wrangler.js

@@ -140,6 +140,11 @@ export class Wrangler {
     }
     /**
      * Wait for the Hydra head to fully close and finalize.
+     *
+     * Resolves on the `HeadIsClosed` / `HeadIsFinalized` transition events, **and**
+     * on the initial `Greetings` replay if the head is already at `Closed` or
+     * `Final`. Rejects fast if the head is `Idle` (no head exists to close).
+     *
      * @param timeoutMs - Maximum time to wait in milliseconds.
      */
     async waitForHeadClose(timeoutMs = 180000) {
@@ -153,14 +158,30 @@ export class Wrangler {
                 case 'ReadyToFanout':
                     this.ws.send({ tag: 'Fanout' });
                     break;
-                case 'Greetings':
-                    this.onGreetings(message.headStatus).catch((err) => reject(new Error(`Greetings handler failed: ${String(err)}`)));
+                case 'Greetings': {
+                    const status = message.headStatus;
+                    if (status === 'Closed' || status === 'Final') {
+                        resolve();
+                        return;
+                    }
+                    if (status === 'Idle') {
+                        reject(new Error(`Cannot wait for head to close: head is "Idle" — no head exists to close`));
+                        return;
+                    }
+                    this.onGreetings(status).catch((err) => reject(new Error(`Greetings handler failed: ${String(err)}`)));
                     break;
+                }
             }
         }, timeoutMs, 'Timeout waiting for head to close!');
     }
     /**
      * Wait for the Hydra head to reach the `Open` state.
+     *
+     * Resolves on the `HeadIsOpen` transition event, **and** on the initial
+     * `Greetings` replay if the head is already `Open`. Rejects fast if the
+     * head is in a terminal or shutting-down state (`Closed`, `FanoutPossible`,
+     * `Final`) — a new head must be started from a fresh node.
+     *
      * @param commitArgs - UTxO to commit into the head during initialization.
      * @param timeoutMs - Maximum time to wait in milliseconds.
      */
@@ -176,7 +197,16 @@ export class Wrangler {
                 this.doCommit(commitArgs).catch((err) => reject(new Error(`Commit failed: ${String(err)}`)));
             }
             else if (message.tag === 'Greetings') {
-                this.onGreetings(message.headStatus, commitArgs).catch((err) => reject(new Error(`Greetings handler failed: ${String(err)}`)));
+                const status = message.headStatus;
+                if (status === 'Open') {
+                    resolve();
+                    return;
+                }
+                if (status === 'Closed' || status === 'FanoutPossible' || status === 'Final') {
+                    reject(new Error(`Cannot wait for head to open: head is "${status}" (terminal or shutting down)`));
+                    return;
+                }
+                this.onGreetings(status, commitArgs).catch((err) => reject(new Error(`Greetings handler failed: ${String(err)}`)));
             }
         }, timeoutMs, 'Timeout waiting for head to open');
     }

package/package.json

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