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

package/README.md

@@ -0,0 +1,159 @@
+# @lerna-labs/hydra-sdk
+
+Core TypeScript SDK for managing [Cardano Hydra](https://hydra.family/) Heads — connect, open, transact, and close Hydra Heads with a high-level API.
+
+> **Beta** — APIs may change between releases. Currently at `1.0.0-beta.x`.
+
+## Installation
+
+```bash
+npm install @lerna-labs/hydra-sdk
+```
+
+## Environment Variables
+
+The SDK reads configuration from environment variables at the point of use (never at import time):
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BLOCKFROST_API_KEY` | Yes (Wrangler) | Blockfrost project ID for L1 chain queries |
+| `HYDRA_API_URL` | Yes (UTxO queries) | Hydra node HTTP API endpoint (e.g. `http://localhost:4001`) |
+| `HYDRA_WS_URL` | Yes (Wrangler) | Hydra node WebSocket endpoint (e.g. `ws://localhost:4001`) |
+| `HYDRA_ADMIN_KEY_FILE` | One required | Path to a Cardano `.sk` signing key file |
+| `HYDRA_ADMIN_CARDANO_PK` | One required | Cardano private key hex string (fallback if no key file) |
+
+## Usage
+
+### Wrangler — Head Lifecycle Management
+
+The `Wrangler` class manages the full Hydra Head lifecycle: connecting, opening, monitoring, and closing.
+
+```typescript
+import { Wrangler } from "@lerna-labs/hydra-sdk";
+
+const wrangler = new Wrangler();
+
+// Connect to the Hydra node with automatic retry
+await wrangler.connect();
+
+// Open the Head (commits UTxO from L1 tx)
+await wrangler.waitForHeadOpen({ txHash: "abc123...", txIndex: 0 });
+
+// Monitor status
+const status = await wrangler.getHeadStatus();
+wrangler.onStatusChange((status) => console.log("Status:", status));
+
+// Close and finalize
+await wrangler.waitForHeadClose();
+
+// Disconnect when done
+await wrangler.disconnect();
+```
+
+### UTxO Queries
+
+```typescript
+import { getUtxoSet, queryUtxoByAddress } from "@lerna-labs/hydra-sdk";
+
+// Get all UTxOs in the Hydra Head
+const utxos = await getUtxoSet();
+
+// Query UTxOs for a specific address
+const myUtxos = await queryUtxoByAddress("addr_test1...");
+```
+
+### Wallet & Admin
+
+```typescript
+import { getAdmin, createMultisigAddress } from "@lerna-labs/hydra-sdk";
+
+// Get a MeshWallet instance from env-configured signing key
+const adminWallet = await getAdmin();
+
+// Create a multisig address from two participant addresses
+const { address, scriptCbor, scriptHash } = createMultisigAddress(
+  "addr_test1...",
+  "addr_test2...",
+);
+```
+
+### Signature Verification
+
+```typescript
+import { verifySignature } from "@lerna-labs/hydra-sdk";
+
+const { isValid, sigMeta, pubKeyHex } = verifySignature(
+  signature,
+  message,
+  signingAddress,
+  signatureKey,
+);
+```
+
+### Transaction Submission
+
+```typescript
+import { submitTx } from "@lerna-labs/hydra-sdk";
+
+const response = await submitTx(submitEndpoint, cborPayload, txId);
+```
+
+### Config Helpers
+
+```typescript
+import { requireEnv, optionalEnv } from "@lerna-labs/hydra-sdk";
+
+// Throws with a clear message if missing
+const apiKey = requireEnv("BLOCKFROST_API_KEY");
+
+// Returns fallback if not set
+const url = optionalEnv("HYDRA_API_URL", "http://localhost:4001");
+```
+
+### Utilities
+
+```typescript
+import { chunkString, bufferToHex, bufferToAscii } from "@lerna-labs/hydra-sdk";
+
+const chunks = chunkString("abcdef", 2); // ["ab", "cd", "ef"]
+```
+
+## API Reference
+
+### Functions
+
+| Export | Description |
+|--------|-------------|
+| `getAdmin()` | Create a `MeshWallet` from env-configured signing key |
+| `createMultisigAddress(addr1, addr2, networkId?, scriptType?)` | Build a multisig address from two participant addresses |
+| `createNativeScript(addr, opts?)` | Build a native script policy — bare `sig` by default, or time-bound `all:[sig, before]` when `opts.invalidHereafter` is set |
+| `getUtxoSet()` | Fetch all UTxOs in the Hydra Head |
+| `queryUtxoByAddress(address)` | Fetch UTxOs for a specific address |
+| `submitTx(endpoint, payload, id)` | Submit a signed transaction to the Hydra node |
+| `verifySignature(signature, message, address, key)` | Verify a CIP-8 message signature |
+| `requireEnv(name)` | Read a required environment variable (throws if missing) |
+| `optionalEnv(name, fallback)` | Read an optional environment variable with fallback |
+| `chunkString(str, size)` | Split a string into fixed-size chunks |
+| `bufferToHex(buffer)` | Convert a buffer to a hex string |
+| `bufferToAscii(buffer)` | Convert a buffer to an ASCII string |
+
+### Classes
+
+| Export | Description |
+|--------|-------------|
+| `Wrangler` | Hydra Head lifecycle manager — connect, open, monitor, close |
+
+### Types
+
+| Export | Description |
+|--------|-------------|
+| `CommitArgs` | Arguments for committing UTxOs when opening a Head |
+| `HeadStatus` | Hydra Head status identifier |
+| `HydraMessage` | Typed Hydra protocol message |
+| `HydraWsMessage` | Raw WebSocket message from Hydra node |
+| `ParsedUtxo` | Parsed UTxO with address, value, and datum |
+| `ServerOutput` | Hydra node server output message type |
+
+## License
+
+[Apache-2.0](../../LICENSE)

package/dist/cache/disk-cache.d.ts

@@ -0,0 +1,37 @@
+export interface DiskCacheConfig {
+    /** Root directory for all cache storage (e.g. "/ipfs-staging"). */
+    stagingDir: string;
+    /**
+     * Subdirectory name for the full document payloads.
+     * @default "documents"
+     */
+    documentsSubdir?: string;
+    /**
+     * Subdirectory name for the latest-entry lookup files.
+     * @default "latest"
+     */
+    latestSubdir?: string;
+}
+/**
+ * A generic disk-backed in-memory cache keyed by a string identifier.
+ *
+ * Each entry is persisted to disk in two places:
+ * - `documents/` — the full payload (intended for IPFS pinning)
+ * - `latest/`    — a lightweight lookup file keyed by id (for fast rehydration)
+ *
+ * On startup, call {@link rehydrate} to rebuild the in-memory `Map` from the
+ * `latest/` directory so the cache survives service restarts.
+ *
+ * @typeParam E - The shape of a cache entry (must include a string `id` field
+ *               used as the Map key and the latest/ filename).
+ */
+export declare function createDiskCache<E extends object>(config: DiskCacheConfig, 
+/** Extract the cache key from an entry. */
+keyFn: (entry: E) => string): {
+    rehydrate: () => Promise<number>;
+    put: (entry: E, filename: string, fullPayload: unknown) => Promise<string>;
+    get: (key: string) => E | undefined;
+    getAll: () => E[];
+    getDocumentsDir: () => string;
+};
+export type DiskCache<E extends object> = ReturnType<typeof createDiskCache<E>>;

package/dist/cache/disk-cache.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * A generic disk-backed in-memory cache keyed by a string identifier.
+ *
+ * Each entry is persisted to disk in two places:
+ * - `documents/` — the full payload (intended for IPFS pinning)
+ * - `latest/`    — a lightweight lookup file keyed by id (for fast rehydration)
+ *
+ * On startup, call {@link rehydrate} to rebuild the in-memory `Map` from the
+ * `latest/` directory so the cache survives service restarts.
+ *
+ * @typeParam E - The shape of a cache entry (must include a string `id` field
+ *               used as the Map key and the latest/ filename).
+ */
+export function createDiskCache(config, 
+/** Extract the cache key from an entry. */
+keyFn) {
+    const docsDir = path.join(config.stagingDir, config.documentsSubdir ?? 'documents');
+    const latestDir = path.join(config.stagingDir, config.latestSubdir ?? 'latest');
+    const cache = new Map();
+    /** Ensure the storage directories exist. */
+    async function ensureDirs() {
+        await fs.mkdir(docsDir, { recursive: true });
+        await fs.mkdir(latestDir, { recursive: true });
+    }
+    /**
+     * Rebuild the in-memory cache from the `latest/` directory on disk.
+     * Call once before the service starts accepting requests.
+     *
+     * @returns The number of entries loaded.
+     */
+    async function rehydrate() {
+        await ensureDirs();
+        const files = await fs.readdir(latestDir);
+        let count = 0;
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const raw = await fs.readFile(path.join(latestDir, file), 'utf-8');
+                const entry = JSON.parse(raw);
+                cache.set(keyFn(entry), entry);
+                count++;
+            }
+            catch {
+                // Skip corrupt / unparseable files
+            }
+        }
+        return count;
+    }
+    /**
+     * Store an entry in both the in-memory cache and on disk.
+     *
+     * @param entry       - The cache entry.
+     * @param filename    - Filename for the full payload in `documents/`.
+     * @param fullPayload - The complete payload to persist (may differ from
+     *                      the lightweight entry stored in `latest/`).
+     * @returns Absolute path to the written document file.
+     */
+    async function put(entry, filename, fullPayload) {
+        await ensureDirs();
+        const key = keyFn(entry);
+        cache.set(key, entry);
+        const docPath = path.join(docsDir, filename);
+        await fs.writeFile(docPath, JSON.stringify(fullPayload, null, 2));
+        const latestPath = path.join(latestDir, `${key}.json`);
+        await fs.writeFile(latestPath, JSON.stringify(entry));
+        return docPath;
+    }
+    /** Retrieve an entry by key from the in-memory cache. */
+    function get(key) {
+        return cache.get(key);
+    }
+    /** Return all cached entries. */
+    function getAll() {
+        return Array.from(cache.values());
+    }
+    /** Return the absolute path to the documents directory (for IPFS pinning). */
+    function getDocumentsDir() {
+        return docsDir;
+    }
+    return { rehydrate, put, get, getAll, getDocumentsDir };
+}

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+/** Read a required environment variable or throw with a clear message. */
+export declare function requireEnv(name: string): string;
+/** Read an optional environment variable with a fallback default. */
+export declare function optionalEnv(name: string, fallback: string): string;

package/dist/config.js

@@ -0,0 +1,12 @@
+/** Read a required environment variable or throw with a clear message. */
+export function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+/** Read an optional environment variable with a fallback default. */
+export function optionalEnv(name, fallback) {
+    return process.env[name] || fallback;
+}

package/dist/hydra/hydra-http-client.d.ts

@@ -0,0 +1,36 @@
+import type { CommitBlueprintPayload, HydraTransaction, HydraUTxOEntry, HydraUTxOs } from './types.js';
+/**
+ * HTTP client for the Hydra node REST API.
+ *
+ * Uses native `fetch` (Node 18+). Accepts 200 and 202 as success responses.
+ */
+export declare class HydraHttpClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    /**
+     * Build a commit transaction.
+     *
+     * `POST /commit` — returns the unsigned L1 transaction CBOR hex.
+     */
+    buildCommit(payload: HydraUTxOs | CommitBlueprintPayload | Record<string, never>): Promise<string>;
+    /**
+     * Publish a decommit transaction.
+     *
+     * `POST /decommit` — submits the decommit request to the Hydra node.
+     */
+    publishDecommit(transaction: HydraTransaction): Promise<unknown>;
+    /** Fetch the current UTxO snapshot. `GET /snapshot/utxo` */
+    getSnapshotUtxo(): Promise<Record<string, HydraUTxOEntry>>;
+    /**
+     * List the transaction ids of deposits that are pending (observed but not yet
+     * incremented into the head). `GET /commits`
+     *
+     * A deposit can linger here if an L1 rollback cancelled its increment — see
+     * {@link recoverable deposits}. Used to detect a stuck deposit and retry.
+     */
+    getPendingCommits(): Promise<string[]>;
+    /** Fetch protocol parameters. `GET /protocol-parameters` */
+    getProtocolParameters(): Promise<unknown>;
+    private post;
+    private get;
+}

package/dist/hydra/hydra-http-client.js

@@ -0,0 +1,66 @@
+/**
+ * HTTP client for the Hydra node REST API.
+ *
+ * Uses native `fetch` (Node 18+). Accepts 200 and 202 as success responses.
+ */
+export class HydraHttpClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/+$/, '');
+    }
+    /**
+     * Build a commit transaction.
+     *
+     * `POST /commit` — returns the unsigned L1 transaction CBOR hex.
+     */
+    async buildCommit(payload) {
+        const response = await this.post('/commit', payload);
+        return response.cborHex;
+    }
+    /**
+     * Publish a decommit transaction.
+     *
+     * `POST /decommit` — submits the decommit request to the Hydra node.
+     */
+    async publishDecommit(transaction) {
+        return this.post('/decommit', transaction);
+    }
+    /** Fetch the current UTxO snapshot. `GET /snapshot/utxo` */
+    async getSnapshotUtxo() {
+        return this.get('/snapshot/utxo');
+    }
+    /**
+     * List the transaction ids of deposits that are pending (observed but not yet
+     * incremented into the head). `GET /commits`
+     *
+     * A deposit can linger here if an L1 rollback cancelled its increment — see
+     * {@link recoverable deposits}. Used to detect a stuck deposit and retry.
+     */
+    async getPendingCommits() {
+        return this.get('/commits');
+    }
+    /** Fetch protocol parameters. `GET /protocol-parameters` */
+    async getProtocolParameters() {
+        return this.get('/protocol-parameters');
+    }
+    async post(path, payload) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok && response.status !== 202) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`Hydra HTTP ${response.status} on POST ${path}: ${body}`);
+        }
+        return response.json();
+    }
+    async get(path) {
+        const response = await fetch(`${this.baseUrl}${path}`);
+        if (!response.ok && response.status !== 202) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`Hydra HTTP ${response.status} on GET ${path}: ${body}`);
+        }
+        return response.json();
+    }
+}

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

@@ -0,0 +1,88 @@
+import { EventEmitter } from 'node:events';
+import { HydraWebSocket } from './hydra-websocket.js';
+import type { GreetingsMessage, HeadStatus, HydraHeadInfo, HydraMessage, HydraMonitorOptions, HydraStatus, ServerOutput, TimestampedEvent } from './types.js';
+/**
+ * Persistent WebSocket monitor for a Hydra head.
+ *
+ * Maintains a single long-lived WebSocket connection with auto-reconnect,
+ * real-time head state tracking, and proactive error surfacing.
+ *
+ * Events emitted:
+ * - `'message'`        — `(msg: HydraWsMessage)` for every incoming message
+ * - `'status'`         — `(status: HydraStatus, previous: HydraStatus)` on head-status changes
+ * - `'error:tx'`       — `(msg)` on PostTxOnChainFailed or TxInvalid
+ * - `'error:command'`  — `(msg)` on CommandFailed
+ * - `'error:decommit'` — `(msg)` on DecommitInvalid
+ * - `'connected'`      — `()` WebSocket open + Greetings received
+ * - `'disconnected'`   — `()` WebSocket closed (reconnect may follow)
+ * - `'reconnecting'`   — `(attempt: number, delayMs: number)`
+ * - `'reconnect_failed'` — `()` maxAttempts exhausted
+ *
+ * @example
+ * ```ts
+ * const monitor = new HydraMonitor({ wsUrl: 'ws://hydra-node:4102' });
+ * await monitor.start();
+ * console.log(monitor.headStatus); // 'IDLE'
+ * monitor.on('status', (s, prev) => console.log(`${prev} → ${s}`));
+ * ```
+ */
+export declare class HydraMonitor extends EventEmitter {
+    readonly ws: HydraWebSocket;
+    private _headStatus;
+    private _previousStatus;
+    private _headId;
+    private _events;
+    private _stopped;
+    private _reconnecting;
+    private readonly reconnectEnabled;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly maxAttempts;
+    private readonly eventBufferSize;
+    private readonly boundOnMessage;
+    private readonly boundOnClose;
+    constructor(options: HydraMonitorOptions);
+    /** Connect to the Hydra node. Resolves after Greetings received. */
+    start(): Promise<void>;
+    /** Disconnect and stop reconnecting. */
+    stop(): Promise<void>;
+    /** Whether the monitor is actively connected and listening. */
+    get connected(): boolean;
+    /** Current head status (uppercase). */
+    get headStatus(): HydraStatus;
+    /** Current head status (mixed-case, as reported in Greetings). */
+    get headStatusMixed(): HeadStatus;
+    /** The full Greetings message from the most recent connection. */
+    get greetings(): GreetingsMessage | null;
+    /**
+     * Summary of Hydra head info derived from live state plus the last Greetings.
+     *
+     * `headStatus` and `headId` reflect the current state tracked from transition
+     * messages (`HeadIsOpen`, `HeadIsClosed`, 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.
+     */
+    get headInfo(): HydraHeadInfo | null;
+    /** The last N events (configurable via eventBufferSize). Most recent last. */
+    get recentEvents(): readonly TimestampedEvent[];
+    /**
+     * Wait for headStatus to reach the target. Resolves immediately if already there.
+     * @param target - The HydraStatus to wait for.
+     * @param timeoutMs - Maximum wait time (default 60s).
+     */
+    waitForStatus(target: HydraStatus, timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for the next message matching the given tag.
+     * @param tag - The message tag to wait for.
+     * @param timeoutMs - Maximum wait time (default 60s).
+     */
+    waitForMessage<T extends ServerOutput['tag']>(tag: T, timeoutMs?: number): Promise<HydraMessage<T>>;
+    private onMessage;
+    private updateStatus;
+    private onClose;
+    private reconnectLoop;
+}