@lerna-labs/hydra-sdk 1.0.0-beta.13 → 1.0.0-beta.14

package/dist/mesh/native-script.js

@@ -1,10 +1,12 @@
-import { serializeNativeScript, resolveScriptHash, deserializeAddress, } from '@meshsdk/core';
+import { deserializeAddress, resolveScriptHash, serializeNativeScript } from '@meshsdk/core';
 /**
- * Create a multisig address using 'any' policy (AND logic)
- * @param address1 The first address to include in the script (staking or payment)
- * @param address2 The second address to include in the script (staking or payment)
- * @param networkId 0 = testnet, 1 = mainnet
- * @param scriptType
+ * Create a multisig script address from two Cardano addresses.
+ *
+ * @param address1 - First address (bech32) to include in the native script.
+ * @param address2 - Second address (bech32) to include in the native script.
+ * @param networkId - `0` for testnet, `1` for mainnet.
+ * @param scriptType - `"any"` requires one signature, `"all"` requires both.
+ * @returns The script address, serialized CBOR, and script hash.
  */
 export function createMultisigAddress(address1, address2, networkId = 0, scriptType = 'any') {
     const keyHash1 = deserializeAddress(address1).pubKeyHash;
@@ -23,14 +25,18 @@ export function createMultisigAddress(address1, address2, networkId = 0, scriptT
         ],
     };
     const { address, scriptCbor } = serializeNativeScript(script, undefined, networkId);
-    let scriptHash;
-    if (scriptCbor != null) {
-        scriptHash = resolveScriptHash(scriptCbor);
-    }
+    const scriptHash = scriptCbor != null ? resolveScriptHash(scriptCbor) : undefined;
     return { address, scriptCbor, scriptHash };
 }
 /**
- * Create a Native Script policy for minting tokens
+ * Create a native script policy for minting tokens.
+ *
+ * @param address1 - Address (bech32) whose key hash is the required signer.
+ * @param networkId - `0` for testnet, `1` for mainnet.
+ * @param scriptType - `"any"` or `"all"` when combined with time-lock scripts.
+ * @param invalidBefore - Optional slot number before which the script is invalid.
+ * @param invalidHereafter - Optional slot number after which the script is invalid.
+ * @returns The script address, serialized CBOR, and script hash.
  */
 export function createNativeScript(address1, networkId = 0, scriptType = 'all', invalidBefore = null, invalidHereafter = null) {
     const keyHash = deserializeAddress(address1).pubKeyHash;
@@ -56,9 +62,6 @@ export function createNativeScript(address1, networkId = 0, scriptType = 'all',
         });
     }
     const { address, scriptCbor } = serializeNativeScript(script, undefined, networkId);
-    let scriptHash;
-    if (scriptCbor != null) {
-        scriptHash = resolveScriptHash(scriptCbor);
-    }
+    const scriptHash = scriptCbor != null ? resolveScriptHash(scriptCbor) : undefined;
     return { address, scriptCbor, scriptHash };
 }

package/dist/mesh/wrangler.d.ts

@@ -1,10 +1,36 @@
-import { HydraProvider } from "@meshsdk/hydra";
-export interface CommitArgs {
+import type { hydraStatus, hydraTransaction } from '@meshsdk/hydra';
+import { HydraProvider } from '@meshsdk/hydra';
+import type { HeadStatus } from '../hydra/messages.js';
+/** UTxO reference for committing funds into a Hydra head. */
+export interface UTxORef {
+    /** Transaction hash containing the UTxO. */
     txHash: string;
-    txIndex: number;
+    /** Output index of the UTxO within the transaction. */
+    outputIndex: number;
+}
+/** Arguments for committing UTxOs into a Hydra head. */
+export interface CommitArgs {
+    /** One or more UTxO references to commit. */
+    utxos: UTxORef[];
+    /** Blueprint transaction that spends the committed UTxOs (CBOR-encoded, unsigned). Optional — omit for simple ADA-only commits. */
+    blueprintTx?: hydraTransaction;
 }
+/**
+ * High-level controller for Hydra head lifecycle operations.
+ *
+ * Wraps `HydraProvider` and `HydraInstance` to provide a simplified API
+ * for initializing, opening, and closing a Hydra head.
+ *
+ * @example
+ * ```ts
+ * const wrangler = new Wrangler("http://localhost:4001");
+ * await wrangler.waitForHeadOpen({
+ *   utxos: [{ txHash: "abc...", outputIndex: 0 }],
+ *   blueprintTx: { type: "Tx ConwayEra", cborHex: "...", description: "" },
+ * });
+ * ```
+ */
 export declare class Wrangler {
-    private readonly BLOCKFROST_KEY;
     private mode;
     readonly provider: HydraProvider;
     private instance;
@@ -14,16 +40,78 @@ export declare class Wrangler {
     constructor(url?: string, wsUrl?: string);
     private createHydraProvider;
     private createHydraInstance;
+    /**
+     * Connect to the Hydra node with exponential-backoff retry.
+     *
+     * Uses `HydraProvider.isConnected()` which establishes the WebSocket
+     * **and** waits for the Hydra `Greetings` handshake, unlike the raw
+     * `connect()` which only opens the socket.
+     *
+     * @param maxAttempts - Maximum number of connection attempts (default 5).
+     * @param baseDelayMs - Initial retry delay in milliseconds (default 1000). Doubles each attempt, capped at 30 s.
+     */
+    private connectWithRetry;
+    /**
+     * Shared helper for promise-based methods that wait for a specific
+     * Hydra message. Handles connection, timeout, and settlement in one place.
+     */
+    private awaitMessage;
+    /** Connect the underlying HydraProvider WebSocket with retry logic. */
     connect(): Promise<void>;
-    startHead(txHash: string, txIndex: number): Promise<void>;
+    /** Disconnect the underlying HydraProvider WebSocket. */
+    disconnect(timeout?: number): Promise<void>;
+    /** Return the current HydraProvider connection/head status. */
+    getStatus(): hydraStatus;
+    /** Register a callback for HydraProvider status changes. */
+    onStatusChange(callback: (status: hydraStatus) => void): hydraStatus;
+    /** Begin the head-opening sequence: init, commit, and listen for state changes. */
+    startHead(commitArgs: CommitArgs): Promise<void>;
+    /** Begin the head-closing sequence: close, fanout, and finalize. */
     shutdownHead(): Promise<void>;
-    waitForHeadClose(timeoutMs: 180000): Promise<void>;
-    waitForHeadOpen(commitArgs: {
-        txHash: string;
-        txIndex: number;
-    }, timeoutMs?: number): Promise<void>;
-    getHeadStatus(timeoutMs?: number): Promise<string>;
+    /**
+     * Wait for the Hydra head to fully close and finalize.
+     * @param timeoutMs - Maximum time to wait in milliseconds.
+     */
+    waitForHeadClose(timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for the Hydra head to reach the `Open` state.
+     * @param commitArgs - UTxO to commit into the head during initialization.
+     * @param timeoutMs - Maximum time to wait in milliseconds.
+     */
+    waitForHeadOpen(commitArgs: CommitArgs, timeoutMs?: number): Promise<void>;
+    /**
+     * Query the current Hydra head status via a `Greetings` message.
+     * @param timeoutMs - Maximum time to wait for the status response.
+     * @returns The head status string (e.g. `"Idle"`, `"Open"`, `"Closed"`).
+     */
+    getHeadStatus(timeoutMs?: number): Promise<HeadStatus>;
     private doCommit;
+    /**
+     * Decommit funds from an open Hydra head back to L1.
+     *
+     * Posts the decommit transaction via `provider.publishDecommit()` (HTTP POST)
+     * instead of `provider.decommit()` to avoid overwriting the Wrangler's
+     * `onMessage` handler (single-callback replacement pattern).
+     *
+     * Resolves on `DecommitApproved` — L1 settlement happens asynchronously.
+     *
+     * @param transaction - The decommit transaction (CBOR-encoded).
+     * @param timeoutMs - Maximum time to wait for approval (default 60s).
+     */
+    decommit(transaction: hydraTransaction, timeoutMs?: number): Promise<void>;
+    /**
+     * Incrementally commit funds into an already-open Hydra head.
+     *
+     * Only single-UTxO commits are supported (MeshJS limitation).
+     * The raw L1 transaction is submitted to Blockfrost automatically.
+     *
+     * Resolves on `CommitFinalized`.
+     *
+     * @param commitArgs - Single UTxO (with optional blueprint) to commit.
+     * @param timeoutMs - Maximum time to wait for finalization (default 120s).
+     */
+    incrementalCommit(commitArgs: CommitArgs, timeoutMs?: number): Promise<void>;
+    private doIncrementalCommit;
     private handleIncoming;
     private onGreetings;
 }