@lerna-labs/hydra-sdk 1.0.0-beta.22 → 1.0.0-beta.25

package/dist/hydra/messages.d.ts

@@ -11,4 +11,4 @@
  * }
  * ```
  */
-export type { ClientInput, ClientMessage, ConnectionState, HeadStatus, HydraHeadInfo, 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,43 +82,41 @@ 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;
 };
-/** Greetings message received on initial WebSocket connection. */
 /** Hydra node environment info reported in Greetings. */
 export interface HydraEnv {
-    /** Configured peer addresses (comma-separated or empty). */
-    configuredPeers: string;
-    /** Contestation period in seconds. */
-    contestationPeriod: number;
-    /** Deposit period in seconds. */
-    depositPeriod: number;
-    /** Other parties' verification keys. */
+    party: {
+        vkey: string;
+    };
+    signingKey?: string;
     otherParties: {
         vkey: string;
     }[];
-    /** All participant key hashes. */
     participants: string[];
-    /** This node's party identity. */
-    party: {
-        vkey: string;
-    };
+    contestationPeriod: number;
+    depositPeriod: number;
+    unsyncedPeriod?: number;
+    configuredPeers: string;
     [key: string]: unknown;
 }
 /** Network connectivity info reported in Greetings. */
 export interface HydraNetworkInfo {
-    /** Whether the node is connected to the Cardano network. */
     networkConnected: boolean;
-    /** Per-peer connection info. */
     peersInfo: Record<string, unknown>;
     [key: string]: unknown;
 }
@@ -109,40 +129,28 @@ export interface GreetingsMessage {
     headStatus: HeadStatus;
     hydraHeadId?: string;
     snapshotUtxo?: HydraUTxOs;
-    hydraNodeVersion?: string;
-    env?: HydraEnv;
-    networkInfo?: HydraNetworkInfo;
-    /** L1 chain sync status (e.g. `"InSync"`). Available in Hydra >= 1.3.0. */
-    chainSyncedStatus?: string;
-    /** Current L1 slot number. Available in Hydra >= 1.3.0. */
-    currentSlot?: number;
+    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 {
-    /** Current head status. */
     headStatus: HeadStatus;
-    /** On-chain head identifier / policy ID (null when head is Idle / not yet initialized). */
     headId: string | null;
-    /** Hydra node version string. */
     nodeVersion: string | null;
-    /** This node's verification key. */
     me: string;
-    /** Contestation period in seconds. */
     contestationPeriod: number | null;
-    /** Deposit period in seconds. */
     depositPeriod: number | null;
-    /** All participant key hashes. */
     participants: string[];
-    /** Whether the node is connected to the Cardano network. */
     networkConnected: boolean;
-    /** Number of configured peers. */
     peerCount: number;
-    /** L1 chain sync status (e.g. `"InSync"`). Null if not reported (Hydra < 1.3.0). */
     chainSyncedStatus: string | null;
-    /** Current L1 slot number. Null if not reported (Hydra < 1.3.0). */
     currentSlot: number | null;
 }
 export interface HeadIsInitializingMessage {
@@ -151,6 +159,8 @@ export interface HeadIsInitializingMessage {
     parties: {
         vkey: string;
     }[];
+    seq: number;
+    timestamp: string;
     [key: string]: unknown;
 }
 export interface CommittedMessage {
@@ -159,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. */
@@ -239,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, HydraHeadInfo, 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/dist/utils/verify-signature.js

@@ -23,13 +23,16 @@ export function verifySignature(signature, message, signingAddress, signatureKey
         const signatureBytes = coseSign1.signature();
         const [, , , payload1] = cbor.decode(bufferToHex(coseSign1.signed_data().to_bytes()));
         const signaturePayloadAscii = bufferToAscii(payload1);
-        const { words } = bech32.decode(signingAddress);
+        const { words, prefix } = bech32.decode(signingAddress);
         const addressBytes = Buffer.from(bech32.fromWords(words));
         const coseSigKey = cbor.decode(signatureKey);
         const cosePublicKey = coseSigKey.get(-2);
         const sigKey = CSL.PublicKey.from_bytes(cosePublicKey);
         const publicKeyHash = sigKey.hash();
-        const address_matches = addressBytes.toString('hex').slice(2) === publicKeyHash.to_hex();
+        // pool1... bech32 encodes the raw 28-byte key hash with no header byte.
+        // All other address types (addr, drep, stake) have a 1-byte header prefix.
+        const addressHex = addressBytes.toString('hex');
+        const address_matches = prefix === 'pool' ? addressHex === publicKeyHash.to_hex() : addressHex.slice(2) === publicKeyHash.to_hex();
         const sig = CSL.Ed25519Signature.from_bytes(signatureBytes);
         const validates = sigKey.verify(coseSign1.signed_data().to_bytes(), sig);
         const message_matches = signaturePayloadAscii === message;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lerna-labs/hydra-sdk",
-  "version": "1.0.0-beta.22",
+  "version": "1.0.0-beta.25",
   "description": "TypeScript SDK for managing Cardano Hydra Heads — lifecycle, UTxO queries, wallet management, transaction submission, and signature verification",
   "keywords": [
     "cardano",
@@ -48,13 +48,13 @@
   "devDependencies": {
     "@types/ws": "^8.18.1"
   },
-  "homepage": "https://github.com/Lerna-Labs/hydra-sdk#readme",
+  "homepage": "https://github.com/lerna-labs/hydra-sdk#readme",
   "bugs": {
-    "url": "https://github.com/Lerna-Labs/hydra-sdk/issues"
+    "url": "https://github.com/lerna-labs/hydra-sdk/issues"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Lerna-Labs/hydra-sdk",
+    "url": "https://github.com/lerna-labs/hydra-sdk",
     "directory": "packages/core"
   }
 }