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

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/messages.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Re-exported Hydra WebSocket message types from `@meshsdk/hydra`.
+ *
+ * `ServerOutput` is a discriminated union (on `.tag`) of all possible messages
+ * the Hydra node can send over its WebSocket API. Use `Extract` to narrow:
+ *
+ * @example
+ * ```ts
+ * function handleOpen(msg: HydraMessage<"HeadIsOpen">) {
+ *   console.log(msg.headId, msg.utxo);
+ * }
+ * ```
+ */
+export type { ClientInput, ClientMessage, ConnectionState, ServerOutput } from '@meshsdk/hydra';
+import type { ClientMessage, ServerOutput } from '@meshsdk/hydra';
+/** Any message received via the Hydra WebSocket (server output or client echo). */
+export type HydraWsMessage = ServerOutput | ClientMessage;
+/**
+ * Extract a specific message type from the `ServerOutput` union by its `tag`.
+ *
+ * @example
+ * ```ts
+ * type Greetings = HydraMessage<"Greetings">;
+ * // { tag: "Greetings"; me: { vkey: string }; headStatus: HeadStatus; ... }
+ * ```
+ */
+export type HydraMessage<T extends ServerOutput['tag']> = Extract<ServerOutput, {
+    tag: T;
+}>;
+/** Possible Hydra head states as reported in the `Greetings` message. */
+export type HeadStatus = 'Idle' | 'Initializing' | 'Open' | 'Closed' | 'FanoutPossible' | 'Final';

package/dist/hydra/messages.js

@@ -0,0 +1 @@
+export {};

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;
@@ -7,9 +8,18 @@ interface ParsedUtxo {
         quantity: string;
     }[];
 }
+/**
+ * Fetch the full UTxO set from the Hydra head snapshot.
+ *
+ * Reads `HYDRA_API_URL` from the environment.
+ *
+ * @returns All UTxOs currently held in the Hydra head.
+ */
 export declare function getUtxoSet(): 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 {};

package/dist/hydra/utxo.js

@@ -1,16 +1,21 @@
 import axios from 'axios';
+import { requireEnv } from '../config.js';
+/**
+ * Fetch the full UTxO set from the Hydra head snapshot.
+ *
+ * Reads `HYDRA_API_URL` from the environment.
+ *
+ * @returns All UTxOs currently held in the Hydra head.
+ */
 export async function getUtxoSet() {
-    const baseUrl = process.env.HYDRA_API_URL;
-    if (!baseUrl) {
-        throw new Error("HYDRA_API_URL is not defined in the environment variables!");
-    }
+    const baseUrl = requireEnv('HYDRA_API_URL');
     const url = `${baseUrl}/snapshot/utxo`;
     try {
         const response = await axios.get(url);
         const data = response.data;
         const UtxoSet = [];
         for (const [txKey, utxo] of Object.entries(data)) {
-            const [tx_hash, index_str] = txKey.split("#");
+            const [tx_hash, index_str] = txKey.split('#');
             const output_index = parseInt(index_str, 10);
             const amount = Object.entries(utxo.value).map(([unit, quantity]) => ({
                 unit,
@@ -26,27 +31,23 @@ export async function getUtxoSet() {
         return UtxoSet;
     }
     catch (error) {
-        console.error("Error fetching the Hydra Ledger?", error);
+        console.error('Error fetching the Hydra Ledger?', error);
         throw error;
     }
 }
 /**
- * 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 async function queryUtxoByAddress(address) {
-    console.log(`Querying UTxO by Address: ${address}`);
-    try {
-        const result = [];
-        const data = await getUtxoSet();
-        for (const utxo of data) {
-            if (utxo.address === address) {
-                result.push(utxo);
-            }
+    const result = [];
+    const data = await getUtxoSet();
+    for (const utxo of data) {
+        if (utxo.address === address) {
+            result.push(utxo);
         }
-        return result;
-    }
-    catch (error) {
-        console.error('Failed to fetch or parse UTxO snapshot:', error.message);
-        throw error;
     }
+    return result;
 }

package/dist/index.d.ts

@@ -1,7 +1,14 @@
+export type { DiskCache, DiskCacheConfig } from './cache/disk-cache.js';
+export { createDiskCache } from './cache/disk-cache.js';
+export { optionalEnv, requireEnv } from './config.js';
+export type { HeadStatus, HydraMessage, HydraWsMessage, ServerOutput } from './hydra/messages.js';
+export type { ParsedUtxo } from './hydra/utxo.js';
+export { getUtxoSet, queryUtxoByAddress } from './hydra/utxo.js';
+export type { IpfsClient, IpfsConfig, PinResult } from './ipfs/ipfs.js';
+export { createIpfsClient } from './ipfs/ipfs.js';
 export { getAdmin } from './mesh/get-admin.js';
 export { createMultisigAddress, createNativeScript } from './mesh/native-script.js';
-export { Wrangler } from './mesh/wrangler.js';
-export { getUtxoSet, queryUtxoByAddress } from './hydra/utxo.js';
+export { CommitArgs, UTxORef, Wrangler } from './mesh/wrangler.js';
 export { submitTx } from './tx3/submit-tx.js';
-export { bufferToHex, bufferToAscii, verifySignature } from './utils/verify-signature.js';
 export { chunkString } from './utils/chunk-string.js';
+export { bufferToAscii, bufferToHex, verifySignature } from './utils/verify-signature.js';

package/dist/index.js

@@ -1,7 +1,10 @@
+export { createDiskCache } from './cache/disk-cache.js';
+export { optionalEnv, requireEnv } from './config.js';
+export { getUtxoSet, queryUtxoByAddress } from './hydra/utxo.js';
+export { createIpfsClient } from './ipfs/ipfs.js';
 export { getAdmin } from './mesh/get-admin.js';
 export { createMultisigAddress, createNativeScript } from './mesh/native-script.js';
 export { Wrangler } from './mesh/wrangler.js';
-export { getUtxoSet, queryUtxoByAddress } from './hydra/utxo.js';
 export { submitTx } from './tx3/submit-tx.js';
-export { bufferToHex, bufferToAscii, verifySignature } from './utils/verify-signature.js';
 export { chunkString } from './utils/chunk-string.js';
+export { bufferToAscii, bufferToHex, verifySignature } from './utils/verify-signature.js';

package/dist/ipfs/ipfs.d.ts

@@ -0,0 +1,22 @@
+export interface IpfsConfig {
+    /** Base URL for the Kubo HTTP API (e.g. "http://localhost:5001"). */
+    apiUrl: string;
+}
+export interface PinResult {
+    /** The content-identifier returned by the IPFS node. */
+    cid: string;
+    /** Size in bytes as reported by the IPFS node. */
+    size: number;
+}
+/**
+ * Create an IPFS client bound to the given Kubo API endpoint.
+ *
+ * All operations go through the Kubo HTTP RPC, so the only requirement
+ * is a reachable Kubo node — no additional IPFS libraries are needed.
+ */
+export declare function createIpfsClient(config: IpfsConfig): {
+    pinJson: (filename: string, payload: unknown) => Promise<PinResult>;
+    pinDirectory: (dirPath: string) => Promise<PinResult>;
+    fetchJson: <T = unknown>(cid: string) => Promise<T>;
+};
+export type IpfsClient = ReturnType<typeof createIpfsClient>;

package/dist/ipfs/ipfs.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Create an IPFS client bound to the given Kubo API endpoint.
+ *
+ * All operations go through the Kubo HTTP RPC, so the only requirement
+ * is a reachable Kubo node — no additional IPFS libraries are needed.
+ */
+export function createIpfsClient(config) {
+    const { apiUrl } = config;
+    /**
+     * Pin a single JSON-serialisable payload and return its CID.
+     *
+     * @param filename - Filename used inside the IPFS object.
+     * @param payload  - Any JSON-serialisable value.
+     */
+    async function pinJson(filename, payload) {
+        const body = JSON.stringify(payload, null, 2);
+        const form = new FormData();
+        form.append('file', new Blob([body], { type: 'application/json' }), filename);
+        const res = await fetch(`${apiUrl}/api/v0/add?pin=true`, {
+            method: 'POST',
+            body: form,
+        });
+        if (!res.ok) {
+            throw new Error(`IPFS pin failed: ${res.status} ${await res.text()}`);
+        }
+        const json = (await res.json());
+        return { cid: json.Hash, size: Number.parseInt(json.Size, 10) };
+    }
+    /**
+     * Pin every file in a directory and wrap them in an IPFS directory object.
+     *
+     * @param dirPath - Absolute path to a local directory.
+     * @returns The CID of the wrapping IPFS directory.
+     */
+    async function pinDirectory(dirPath) {
+        const entries = await fs.readdir(dirPath);
+        const form = new FormData();
+        for (const entry of entries) {
+            const filePath = path.join(dirPath, entry);
+            const stat = await fs.stat(filePath);
+            if (!stat.isFile())
+                continue;
+            const content = await fs.readFile(filePath, 'utf-8');
+            form.append('file', new Blob([content]), entry);
+        }
+        const res = await fetch(`${apiUrl}/api/v0/add?pin=true&wrap-with-directory=true&recursive=true`, {
+            method: 'POST',
+            body: form,
+        });
+        if (!res.ok) {
+            throw new Error(`IPFS directory pin failed: ${res.status} ${await res.text()}`);
+        }
+        // Kubo returns one JSON object per line (ndjson). The last line is the
+        // wrapping directory entry.
+        const text = await res.text();
+        const lines = text.trim().split('\n');
+        const last = JSON.parse(lines[lines.length - 1]);
+        return { cid: last.Hash, size: Number.parseInt(last.Size, 10) };
+    }
+    /**
+     * Fetch a JSON payload from IPFS by CID.
+     *
+     * @param cid - The content identifier to retrieve.
+     */
+    async function fetchJson(cid) {
+        const res = await fetch(`${apiUrl}/api/v0/cat?arg=${cid}`, {
+            method: 'POST',
+        });
+        if (!res.ok) {
+            throw new Error(`IPFS fetch failed: ${res.status} ${await res.text()}`);
+        }
+        return (await res.json());
+    }
+    return { pinJson, pinDirectory, fetchJson };
+}

package/dist/mesh/get-admin.d.ts

@@ -1,2 +1,11 @@
 import { MeshWallet } from '@meshsdk/core';
+/**
+ * Create and initialize a MeshWallet for the Hydra head admin.
+ *
+ * Reads the Cardano signing key from `HYDRA_ADMIN_KEY_FILE` (preferred)
+ * or falls back to `HYDRA_ADMIN_CARDANO_PK`. Network is selected via `HYDRA_NETWORK`.
+ *
+ * @returns An initialized MeshWallet ready for signing transactions.
+ * @throws If no signing key is available or the wallet fails to initialize.
+ */
 export declare function getAdmin(): Promise<MeshWallet>;

package/dist/mesh/get-admin.js

@@ -1,10 +1,31 @@
-import { MeshWallet, } from '@meshsdk/core';
+import { readFileSync } from 'node:fs';
+import { MeshWallet } from '@meshsdk/core';
+import { optionalEnv } from '../config.js';
+/**
+ * Create and initialize a MeshWallet for the Hydra head admin.
+ *
+ * Reads the Cardano signing key from `HYDRA_ADMIN_KEY_FILE` (preferred)
+ * or falls back to `HYDRA_ADMIN_CARDANO_PK`. Network is selected via `HYDRA_NETWORK`.
+ *
+ * @returns An initialized MeshWallet ready for signing transactions.
+ * @throws If no signing key is available or the wallet fails to initialize.
+ */
 export async function getAdmin() {
-    const keyCborHex = process.env.HYDRA_ADMIN_CARDANO_PK || null;
+    let keyCborHex = null;
+    // Preferred: read the instance's cardano.sk file directly (no secrets in .env)
+    const keyFile = process.env.HYDRA_ADMIN_KEY_FILE;
+    if (keyFile) {
+        const content = JSON.parse(readFileSync(keyFile, 'utf-8'));
+        keyCborHex = content.cborHex ?? content.key?.cborHex ?? null;
+    }
+    // Fallback: cborHex passed via env var (backward compatible)
+    if (!keyCborHex) {
+        keyCborHex = process.env.HYDRA_ADMIN_CARDANO_PK || null;
+    }
     if (!keyCborHex) {
-        throw new Error('Admin signing key is not defined!');
+        throw new Error('Cardano signing key not found. Set HYDRA_ADMIN_KEY_FILE to the instance cardano.sk path, or HYDRA_ADMIN_CARDANO_PK to its cborHex.');
     }
-    let networkId = parseInt(process.env.HYDRA_NETWORK || '0', 10);
+    let networkId = parseInt(optionalEnv('HYDRA_NETWORK', '0'), 10);
     if (networkId < 0) {
         networkId = 0;
     }

package/dist/mesh/native-script.d.ts

@@ -1,9 +1,11 @@
 /**
- * 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 declare function createMultisigAddress(address1: string, address2: string, networkId?: number, scriptType?: 'any' | 'all'): {
     address: string;
@@ -11,9 +13,24 @@ export declare function createMultisigAddress(address1: string, address2: string
     scriptHash?: string;
 };
 /**
- * Create a Native Script policy for minting tokens
+ * Create a native script policy for minting tokens.
+ *
+ * Without options, produces a bare `sig(keyHash)` script suitable for
+ * in-head voter tokens that must remain burnable by the admin.
+ *
+ * When `invalidHereafter` is provided, produces a compound time-bound
+ * script: `all: [sig(keyHash), before(slot)]` — each ballot gets its
+ * own time-bound policy.
+ *
+ * @param address - Address (bech32) whose key hash is the required signer.
+ * @param opts.invalidHereafter - Slot after which minting is no longer possible.
+ * @param opts.networkId - `0` for testnet (default), `1` for mainnet.
+ * @returns The script address, serialized CBOR, and script hash.
  */
-export declare function createNativeScript(address1: string, networkId?: number, scriptType?: 'any' | 'all', invalidBefore?: number | null, invalidHereafter?: number | null): {
+export declare function createNativeScript(address: string, opts?: {
+    invalidHereafter?: number;
+    networkId?: number;
+}): {
     address: string;
     scriptCbor?: string;
     scriptHash?: string;