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

package/dist/hydra/types.d.ts

@@ -0,0 +1,486 @@
+/** A Cardano transaction in Hydra's wire format. */
+export type HydraTransaction = {
+    type: 'Tx ConwayEra' | 'Unwitnessed Tx ConwayEra' | 'Witnessed Tx ConwayEra';
+    description: string;
+    cborHex: string;
+    txId?: string;
+};
+/** @deprecated Use HydraTransaction */
+export type hydraTransaction = HydraTransaction;
+/** Hydra's nested asset value format: `{ lovelace: N, policyId: { assetNameHex: N } }`. */
+export type HydraAssets = {
+    lovelace: number;
+} & {
+    [policyId: string]: number | {
+        [assetNameHex: string]: number;
+    };
+};
+export interface HydraReferenceScript {
+    script: {
+        cborHex: string;
+        description: string;
+        type: string | null;
+    };
+    scriptLanguage: string;
+}
+/** A single UTxO entry in Hydra's wire format. */
+export interface HydraUTxOEntry {
+    address: string;
+    datum: string | null;
+    inlineDatum: object | null;
+    inlineDatumRaw: string | null;
+    inlineDatumhash: string | null;
+    referenceScript: HydraReferenceScript | null;
+    value: HydraAssets;
+}
+/** A set of UTxOs keyed by `"txHash#outputIndex"`. */
+export type HydraUTxOs = {
+    [txRef: string]: HydraUTxOEntry;
+};
+/** Payload for blueprint-based commits. */
+export interface CommitBlueprintPayload {
+    blueprintTx: HydraTransaction;
+    utxo: HydraUTxOs;
+}
+/**
+ * Possible Hydra head states as reported in the `Greetings` message (mixed-case).
+ *
+ * As of Hydra v2 (ADR-33) the head opens directly into `Open` — there is no
+ * longer an `Initializing` phase.
+ */
+export type HeadStatus = 'Idle' | 'Open' | 'Closed' | 'FanoutPossible' | 'Final';
+/** Hydra status values (uppercase, as used by HydraProvider status tracking). */
+export type HydraStatus = 'IDLE' | 'OPEN' | 'CLOSED' | 'FANOUT_POSSIBLE' | 'FINAL';
+/** @deprecated Use HydraStatus */
+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';
+} | {
+    tag: 'NewTx';
+    transaction: HydraTransaction;
+} | {
+    tag: 'Close';
+} | {
+    tag: 'SafeClose';
+} | {
+    tag: 'Contest';
+} | {
+    tag: 'Fanout';
+} | {
+    tag: 'Decommit';
+    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';
+    me: {
+        vkey: string;
+    };
+    headStatus: HeadStatus;
+    hydraHeadId?: string;
+    snapshotUtxo?: HydraUTxOs;
+    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 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 HeadIsFinalizedMessage {
+    tag: 'HeadIsFinalized';
+    headId: string;
+    utxo: HydraUTxOs;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface TxValidMessage {
+    tag: 'TxValid';
+    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 SnapshotSideLoadedMessage {
+    tag: 'SnapshotSideLoaded';
+    headId: string;
+    snapshotNumber: number;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+export interface CommitRecordedMessage {
+    tag: 'CommitRecorded';
+    headId: string;
+    utxoToCommit: HydraUTxOs;
+    pendingDeposit: string;
+    deadline: string;
+    seq: number;
+    timestamp: string;
+    [key: string]: unknown;
+}
+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 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 EventLogRotatedMessage {
+    tag: 'EventLogRotated';
+    seq: number;
+    checkpoint: unknown;
+    timestamp: string;
+    [key: string]: unknown;
+}
+/** Catch-all for message types not explicitly defined above. */
+export interface UnknownMessage {
+    tag: string;
+    [key: string]: unknown;
+}
+/** All possible messages the Hydra node can send over its WebSocket API. */
+export type ServerOutput = GreetingsMessage | HeadIsOpenMessage | HeadIsClosedMessage | HeadIsContestedMessage | ReadyToFanoutMessage | 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 | EventLogRotatedMessage | UnknownMessage;
+/** Client echo messages (errors, command failures). */
+export type ClientMessage = CommandFailedMessage | PostTxOnChainFailedMessage;
+/** Any message received via the Hydra WebSocket. */
+export type HydraWsMessage = ServerOutput | ClientMessage;
+/**
+ * Extract a specific message type from the `ServerOutput` union by its `tag`.
+ *
+ * @example
+ * ```ts
+ * type Greetings = HydraMessage<"Greetings">;
+ * ```
+ */
+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/types.js

@@ -0,0 +1,2 @@
+// ── Hydra Transaction ────────────────────────────────────────────────
+export {};

package/dist/hydra/utxo-conversion.d.ts

@@ -0,0 +1,10 @@
+import type { Asset, UTxO } from '@meshsdk/common';
+import type { HydraAssets, HydraUTxOEntry, HydraUTxOs } from './types.js';
+/** Convert MeshSDK `Asset[]` to Hydra's nested value format. */
+export declare function toHydraAssets(assets: Asset[]): HydraAssets;
+/** Convert Hydra's nested value format back to MeshSDK `Asset[]`. */
+export declare function fromHydraAssets(assetsObj: HydraAssets): Asset[];
+/** Convert a single MeshSDK UTxO to Hydra wire format. */
+export declare function toHydraUTxO(utxo: UTxO): HydraUTxOEntry;
+/** Convert multiple MeshSDK UTxOs to Hydra wire format (keyed by `"txHash#outputIndex"`). */
+export declare function toHydraUTxOs(utxos: UTxO[]): HydraUTxOs;

package/dist/hydra/utxo-conversion.js

@@ -0,0 +1,111 @@
+import { fromScriptRef, parseDatumCbor } from '@meshsdk/core-cst';
+// ── Asset Conversion ─────────────────────────────────────────────────
+/** Convert MeshSDK `Asset[]` to Hydra's nested value format. */
+export function toHydraAssets(assets) {
+    return assets.reduce((acc, asset) => {
+        if (asset.unit === '' || asset.unit === 'lovelace') {
+            acc.lovelace += Number(asset.quantity);
+        }
+        else {
+            const policyId = asset.unit.slice(0, 56);
+            const assetNameHex = asset.unit.slice(56) || '';
+            if (!acc[policyId] || typeof acc[policyId] === 'number') {
+                acc[policyId] = {};
+            }
+            const policy = acc[policyId];
+            policy[assetNameHex] = (policy[assetNameHex] ?? 0) + Number(asset.quantity);
+        }
+        return acc;
+    }, { lovelace: 0 });
+}
+/** Convert Hydra's nested value format back to MeshSDK `Asset[]`. */
+export function fromHydraAssets(assetsObj) {
+    const result = [];
+    if (assetsObj.lovelace && assetsObj.lovelace > 0) {
+        result.push({ unit: 'lovelace', quantity: String(assetsObj.lovelace) });
+    }
+    for (const [policyId, assets] of Object.entries(assetsObj)) {
+        if (policyId === 'lovelace')
+            continue;
+        if (typeof assets !== 'object')
+            continue;
+        for (const [assetNameHex, quantity] of Object.entries(assets)) {
+            result.push({ unit: policyId + assetNameHex, quantity: String(quantity) });
+        }
+    }
+    return result;
+}
+// ── Reference Script Conversion ──────────────────────────────────────
+function resolveReferenceScript(scriptRef) {
+    if (!scriptRef)
+        return null;
+    const scriptInstance = fromScriptRef(scriptRef);
+    if (!scriptInstance)
+        return null;
+    let scriptType = 'Unknown';
+    let scriptLanguage = null;
+    if ('code' in scriptInstance) {
+        switch (scriptInstance.version) {
+            case 'V1':
+                scriptType = 'PlutusScriptV1';
+                scriptLanguage = 'PlutusScriptLanguage PlutusScriptV1';
+                break;
+            case 'V2':
+                scriptType = 'PlutusScriptV2';
+                scriptLanguage = 'PlutusScriptLanguage PlutusScriptV2';
+                break;
+            case 'V3':
+                scriptType = 'PlutusScriptV3';
+                scriptLanguage = 'PlutusScriptLanguage PlutusScriptV3';
+                break;
+        }
+    }
+    else {
+        scriptType = 'SimpleScript';
+        scriptLanguage = 'NativeScriptLanguage SimpleScript';
+    }
+    if (!scriptLanguage || scriptType === 'Unknown')
+        return null;
+    return {
+        script: {
+            cborHex: scriptRef,
+            description: '',
+            type: scriptType,
+        },
+        scriptLanguage,
+    };
+}
+// ── Datum Resolution ─────────────────────────────────────────────────
+function resolvePlutusData(datumCbor) {
+    const data = parseDatumCbor(datumCbor);
+    function normalize(value) {
+        if (typeof value === 'bigint') {
+            return value <= Number.MAX_SAFE_INTEGER && value >= Number.MIN_SAFE_INTEGER ? Number(value) : value.toString();
+        }
+        if (Array.isArray(value)) {
+            return value.map(normalize);
+        }
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, normalize(v)]));
+        }
+        return value;
+    }
+    return { inlineDatum: normalize(data) };
+}
+// ── UTxO Conversion ──────────────────────────────────────────────────
+/** Convert a single MeshSDK UTxO to Hydra wire format. */
+export function toHydraUTxO(utxo) {
+    return {
+        address: utxo.output.address,
+        datum: null,
+        inlineDatum: utxo.output.plutusData ? resolvePlutusData(utxo.output.plutusData).inlineDatum : null,
+        inlineDatumRaw: utxo.output.plutusData ?? null,
+        inlineDatumhash: utxo.output.dataHash ?? null,
+        referenceScript: utxo.output.scriptRef ? resolveReferenceScript(utxo.output.scriptRef) : null,
+        value: toHydraAssets(utxo.output.amount),
+    };
+}
+/** Convert multiple MeshSDK UTxOs to Hydra wire format (keyed by `"txHash#outputIndex"`). */
+export function toHydraUTxOs(utxos) {
+    return Object.fromEntries(utxos.map((utxo) => [`${utxo.input.txHash}#${utxo.input.outputIndex}`, toHydraUTxO(utxo)]));
+}

package/dist/hydra/utxo.d.ts

@@ -1,4 +1,5 @@
-interface ParsedUtxo {
+/** A UTxO entry parsed from the Hydra snapshot. */
+export interface ParsedUtxo {
     tx_hash: string;
     output_index: number;
     address: string;
@@ -6,10 +7,29 @@ interface ParsedUtxo {
         unit: string;
         quantity: string;
     }[];
+    datum?: string | null;
+    datumHash?: string | null;
+    inlineDatum?: unknown | null;
+    referenceScript?: unknown | null;
 }
-export declare function getUtxoSet(): Promise<ParsedUtxo[]>;
+/** 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(options?: UtxoQueryOptions): Promise<ParsedUtxo[]>;
 /**
- * Fetches the full UTxO snapshot and filters by address.
+ * 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 {};
+export declare function queryUtxoByAddress(address: string, options?: UtxoQueryOptions): Promise<ParsedUtxo[]>;