@unlink-xyz/node 0.1.0

package/dist/index.cjs

@@ -0,0 +1,320 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_POLL_INTERVAL_MS: () => DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  FAILED_TX_STATES: () => FAILED_TX_STATES,
+  TERMINAL_TX_STATES: () => TERMINAL_TX_STATES,
+  TimeoutError: () => TimeoutError,
+  TransactionFailedError: () => TransactionFailedError,
+  UnlinkWallet: () => import_core3.UnlinkWallet,
+  createMemoryStorage: () => import_core3.createMemoryStorage,
+  createSqliteStorage: () => createSqliteStorage,
+  createWalletEmitter: () => createWalletEmitter,
+  initWallet: () => initWallet,
+  pollRelayStatus: () => pollRelayStatus,
+  waitForConfirmation: () => waitForConfirmation
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/init.ts
+var import_node_crypto = __toESM(require("crypto"), 1);
+var import_core = require("@unlink-xyz/core");
+var nodeRng = (n) => new Uint8Array(import_node_crypto.default.randomBytes(n));
+async function initWallet(config) {
+  const { setup, sync, ...coreConfig } = config;
+  void setup;
+  void sync;
+  const wallet = await import_core.UnlinkWallet.create({
+    ...coreConfig,
+    storage: config.storage ?? (0, import_core.createMemoryStorage)(),
+    rng: config.rng ?? nodeRng,
+    autoSync: config.autoSync ?? false,
+    fetch: config.fetch ?? globalThis.fetch
+  });
+  if (config.setup !== false) {
+    const hasSeed = await wallet.seed.exists();
+    if (!hasSeed) {
+      await wallet.seed.create();
+    }
+    const accounts = await wallet.accounts.list();
+    if (accounts.length === 0) {
+      await wallet.accounts.create();
+    }
+  }
+  if (config.sync !== false) {
+    await wallet.sync();
+  }
+  return wallet;
+}
+
+// src/errors.ts
+var TERMINAL_TX_STATES = [
+  "succeeded",
+  "reverted",
+  "failed",
+  "dead"
+];
+var FAILED_TX_STATES = [
+  "reverted",
+  "failed",
+  "dead"
+];
+var DEFAULT_TIMEOUT_MS = 5 * 60 * 1e3;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var MAX_POLL_INTERVAL_MS = 3e4;
+var BACKOFF_FACTOR = 1.5;
+var TimeoutError = class extends Error {
+  txId;
+  timeout;
+  constructor(txId, timeout) {
+    super(`Transaction ${txId} did not confirm within ${timeout}ms`);
+    this.name = "TimeoutError";
+    this.txId = txId;
+    this.timeout = timeout;
+  }
+};
+var TransactionFailedError = class extends Error {
+  txId;
+  state;
+  reason;
+  constructor(txId, state, reason) {
+    super(
+      `Transaction ${txId} failed with state: ${state}${reason ? ` \u2014 ${reason}` : ""}`
+    );
+    this.name = "TransactionFailedError";
+    this.txId = txId;
+    this.state = state;
+    this.reason = reason;
+  }
+};
+
+// src/confirmation.ts
+function toTxStatus(txId, raw) {
+  return {
+    txId,
+    state: raw.state,
+    txHash: raw.txHash ?? void 0,
+    blockNumber: raw.receipt?.blockNumber ?? void 0,
+    error: raw.error ?? void 0
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForConfirmation(wallet, txId, opts) {
+  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+  let interval = opts?.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const raw = await wallet.getTxStatus(txId);
+    const status = toTxStatus(txId, raw);
+    if (status.state === "succeeded") {
+      return status;
+    }
+    if (FAILED_TX_STATES.includes(status.state)) {
+      throw new TransactionFailedError(txId, status.state, status.error);
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await sleep(Math.min(interval, remaining));
+    interval = Math.min(interval * BACKOFF_FACTOR, MAX_POLL_INTERVAL_MS);
+  }
+  throw new TimeoutError(txId, timeout);
+}
+async function* pollRelayStatus(wallet, txId, opts) {
+  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+  let interval = opts?.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const raw = await wallet.getTxStatus(txId);
+    const status = toTxStatus(txId, raw);
+    yield status;
+    if (TERMINAL_TX_STATES.includes(status.state)) {
+      return;
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return;
+    await sleep(Math.min(interval, remaining));
+    interval = Math.min(interval * BACKOFF_FACTOR, MAX_POLL_INTERVAL_MS);
+  }
+}
+
+// src/events.ts
+var import_node_events = require("events");
+function createWalletEmitter(wallet) {
+  const emitter = new import_node_events.EventEmitter();
+  const unsubscribe = wallet.on((event) => {
+    emitter.emit(event.type, event);
+    emitter.emit("*", event);
+  });
+  return { emitter, unsubscribe };
+}
+
+// src/storage/sqlite.ts
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_core2 = require("@unlink-xyz/core");
+var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+function createSqliteStorage(opts) {
+  let db = null;
+  let stmtGet;
+  let stmtPut;
+  let stmtDel;
+  let stmtGetSchema;
+  let stmtUpsertSchema;
+  return {
+    async open() {
+      const dir = import_node_path.default.dirname(opts.path);
+      import_node_fs.default.mkdirSync(dir, { recursive: true });
+      db = new import_better_sqlite3.default(opts.path);
+      db.pragma("journal_mode = WAL");
+      db.pragma("busy_timeout = 5000");
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value BLOB NOT NULL);
+        CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);
+      `);
+      stmtGet = db.prepare("SELECT value FROM kv WHERE key = ?");
+      stmtPut = db.prepare(
+        "INSERT OR REPLACE INTO kv (key, value) VALUES (?, ?)"
+      );
+      stmtDel = db.prepare("DELETE FROM kv WHERE key = ?");
+      stmtGetSchema = db.prepare(
+        "SELECT value FROM meta WHERE key = 'schema_version'"
+      );
+      stmtUpsertSchema = db.prepare(
+        "INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)"
+      );
+    },
+    async get(key) {
+      (0, import_core2.validateKey)(key);
+      const row = stmtGet.get(key);
+      return row ? new Uint8Array(row.value) : null;
+    },
+    async put(key, value) {
+      (0, import_core2.validateKey)(key);
+      stmtPut.run(key, Buffer.from(value));
+    },
+    async delete(key) {
+      (0, import_core2.validateKey)(key);
+      stmtDel.run(key);
+    },
+    async batch(ops) {
+      const runBatch = db.transaction(() => {
+        for (const op of ops) {
+          if (op.put) {
+            const [k, v] = op.put;
+            (0, import_core2.validateKey)(k);
+            stmtPut.run(k, Buffer.from(v));
+          }
+          if (op.del) {
+            (0, import_core2.validateKey)(op.del);
+            stmtDel.run(op.del);
+          }
+        }
+      });
+      runBatch();
+    },
+    async iter(o = {}) {
+      if (o.start && o.end && o.start > o.end) {
+        throw new Error("iter start bound must not exceed end bound");
+      }
+      const conditions = [];
+      const params = [];
+      if (o.prefix) {
+        const escaped = o.prefix.replace(/[%_\\]/g, "\\$&");
+        conditions.push("key LIKE ? ESCAPE '\\'");
+        params.push(escaped + "%");
+      }
+      if (o.start) {
+        conditions.push("key >= ?");
+        params.push(o.start);
+      }
+      if (o.end) {
+        conditions.push("key <= ?");
+        params.push(o.end);
+      }
+      let sql = "SELECT key, value FROM kv";
+      if (conditions.length > 0) {
+        sql += " WHERE " + conditions.join(" AND ");
+      }
+      sql += o.reverse ? " ORDER BY key DESC" : " ORDER BY key ASC";
+      if (o.limit != null) {
+        sql += " LIMIT ?";
+        params.push(o.limit);
+      }
+      const rows = db.prepare(sql).all(...params);
+      return rows.map((row) => ({
+        key: row.key,
+        value: new Uint8Array(row.value)
+      }));
+    },
+    async count(prefix) {
+      let sql = "SELECT COUNT(*) as cnt FROM kv";
+      const params = [];
+      if (prefix) {
+        const escaped = prefix.replace(/[%_\\]/g, "\\$&");
+        sql += " WHERE key LIKE ? ESCAPE '\\'";
+        params.push(escaped + "%");
+      }
+      const row = db.prepare(sql).get(...params);
+      return row.cnt;
+    },
+    async getSchemaVersion() {
+      const row = stmtGetSchema.get();
+      return row?.value ?? 0;
+    },
+    async setSchemaVersion(v) {
+      stmtUpsertSchema.run(v);
+    }
+  };
+}
+
+// src/index.ts
+var import_core3 = require("@unlink-xyz/core");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_TIMEOUT_MS,
+  FAILED_TX_STATES,
+  TERMINAL_TX_STATES,
+  TimeoutError,
+  TransactionFailedError,
+  UnlinkWallet,
+  createMemoryStorage,
+  createSqliteStorage,
+  createWalletEmitter,
+  initWallet,
+  pollRelayStatus,
+  waitForConfirmation
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/init.ts","../src/errors.ts","../src/confirmation.ts","../src/events.ts","../src/storage/sqlite.ts"],"sourcesContent":["// Init\nexport { initWallet } from \"./init.js\";\n\n// Confirmation\nexport { waitForConfirmation, pollRelayStatus } from \"./confirmation.js\";\n\n// Events\nexport { createWalletEmitter } from \"./events.js\";\n\n// Storage\nexport {\n  createSqliteStorage,\n  type SqliteStorageOptions,\n} from \"./storage/sqlite.js\";\n\n// Errors\nexport {\n  TimeoutError,\n  TransactionFailedError,\n  TERMINAL_TX_STATES,\n  FAILED_TX_STATES,\n  DEFAULT_TIMEOUT_MS,\n  DEFAULT_POLL_INTERVAL_MS,\n} from \"./errors.js\";\n\n// Types\nexport type {\n  NodeWalletConfig,\n  TxStatus,\n  WaitOptions,\n  PollOptions,\n} from \"./types.js\";\n\n// Re-export commonly needed core types so consumers don't need @unlink-xyz/core\nexport { UnlinkWallet, createMemoryStorage } from \"@unlink-xyz/core\";\n\nexport type {\n  Account,\n  AccountInfo,\n  AccountView,\n  DepositRelayResult,\n  Environment,\n  HistoryEntry,\n  NoteRecord,\n  RelayState,\n  RelayStatusResponse,\n  Storage,\n  TransactRelayResult,\n  TransferPlanResult,\n  TransferResult,\n  WalletSDKEvent,\n  WithdrawPlanResult,\n  WithdrawResult,\n} from \"@unlink-xyz/core\";\n","import crypto from \"node:crypto\";\nimport { createMemoryStorage, UnlinkWallet } from \"@unlink-xyz/core\";\n\nimport type { NodeWalletConfig } from \"./types.js\";\n\nconst nodeRng = (n: number): Uint8Array =>\n  new Uint8Array(crypto.randomBytes(n));\n\n/**\n * Initialize an Unlink wallet with Node.js-friendly defaults.\n *\n * Compared to `UnlinkWallet.create()`, this:\n * - Defaults storage to in-memory (no IndexedDB required)\n * - Defaults RNG to `node:crypto`\n * - Defaults autoSync to `false`\n * - Optionally creates seed + first account automatically\n * - Optionally syncs notes from blockchain\n *\n * @example\n * ```ts\n * // Minimal — ready to use in one call:\n * const wallet = await initWallet({\n *   chainId: 11155111,\n *   environment: \"testnet\",\n * });\n *\n * // Skip auto-setup (e.g., to import an existing mnemonic):\n * const wallet = await initWallet({\n *   chainId: 11155111,\n *   environment: \"testnet\",\n *   setup: false,\n *   sync: false,\n * });\n * await wallet.seed.importMnemonic(\"your mnemonic ...\");\n * await wallet.accounts.create();\n * await wallet.sync();\n * ```\n */\nexport async function initWallet(\n  config: NodeWalletConfig,\n): Promise<UnlinkWallet> {\n  // Strip node-specific fields before passing to core\n  const { setup, sync, ...coreConfig } = config;\n  void setup;\n  void sync;\n\n  const wallet = await UnlinkWallet.create({\n    ...coreConfig,\n    storage: config.storage ?? createMemoryStorage(),\n    rng: config.rng ?? nodeRng,\n    autoSync: config.autoSync ?? false,\n    fetch: config.fetch ?? globalThis.fetch,\n  });\n\n  if (config.setup !== false) {\n    const hasSeed = await wallet.seed.exists();\n    if (!hasSeed) {\n      await wallet.seed.create();\n    }\n\n    const accounts = await wallet.accounts.list();\n    if (accounts.length === 0) {\n      await wallet.accounts.create();\n    }\n  }\n\n  if (config.sync !== false) {\n    await wallet.sync();\n  }\n\n  return wallet;\n}\n","import type { RelayState } from \"@unlink-xyz/core\";\n\n/** Terminal relay states — the transaction has finished processing. */\nexport const TERMINAL_TX_STATES: readonly RelayState[] = [\n  \"succeeded\",\n  \"reverted\",\n  \"failed\",\n  \"dead\",\n] as const;\n\n/** Failed relay states — the transaction did not succeed. */\nexport const FAILED_TX_STATES: readonly RelayState[] = [\n  \"reverted\",\n  \"failed\",\n  \"dead\",\n] as const;\n\n/** Default timeout for `waitForConfirmation` (5 minutes). */\nexport const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;\n\n/** Default initial poll interval (2 seconds). */\nexport const DEFAULT_POLL_INTERVAL_MS = 2_000;\n\n/** Maximum poll interval after backoff (30 seconds). */\nexport const MAX_POLL_INTERVAL_MS = 30_000;\n\n/** Backoff multiplier for exponential polling. */\nexport const BACKOFF_FACTOR = 1.5;\n\n/** Thrown when relay polling exceeds the configured timeout. */\nexport class TimeoutError extends Error {\n  readonly txId: string;\n  readonly timeout: number;\n\n  constructor(txId: string, timeout: number) {\n    super(`Transaction ${txId} did not confirm within ${timeout}ms`);\n    this.name = \"TimeoutError\";\n    this.txId = txId;\n    this.timeout = timeout;\n  }\n}\n\n/** Thrown when a transaction reaches a failed terminal state. */\nexport class TransactionFailedError extends Error {\n  readonly txId: string;\n  readonly state: RelayState;\n  readonly reason?: string;\n\n  constructor(txId: string, state: RelayState, reason?: string) {\n    super(\n      `Transaction ${txId} failed with state: ${state}${reason ? ` — ${reason}` : \"\"}`,\n    );\n    this.name = \"TransactionFailedError\";\n    this.txId = txId;\n    this.state = state;\n    this.reason = reason;\n  }\n}\n","import type { UnlinkWallet } from \"@unlink-xyz/core\";\n\nimport {\n  BACKOFF_FACTOR,\n  DEFAULT_POLL_INTERVAL_MS,\n  DEFAULT_TIMEOUT_MS,\n  FAILED_TX_STATES,\n  MAX_POLL_INTERVAL_MS,\n  TERMINAL_TX_STATES,\n  TimeoutError,\n  TransactionFailedError,\n} from \"./errors.js\";\nimport type { PollOptions, TxStatus, WaitOptions } from \"./types.js\";\n\nfunction toTxStatus(\n  txId: string,\n  raw: Awaited<ReturnType<UnlinkWallet[\"getTxStatus\"]>>,\n): TxStatus {\n  return {\n    txId,\n    state: raw.state,\n    txHash: raw.txHash ?? undefined,\n    blockNumber: raw.receipt?.blockNumber ?? undefined,\n    error: raw.error ?? undefined,\n  };\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Poll relay status until the transaction reaches a terminal state.\n *\n * Resolves with `TxStatus` on success (`\"succeeded\"`).\n * Throws `TransactionFailedError` on failure (`\"reverted\"`, `\"failed\"`, `\"dead\"`).\n * Throws `TimeoutError` if the timeout is exceeded.\n *\n * Uses exponential backoff: 2s → 3s → 4.5s → ... capped at 30s.\n *\n * @example\n * ```ts\n * const result = await wallet.transfer({ transfers: [{ token, recipient, amount }] });\n * const status = await waitForConfirmation(wallet, result.relayId);\n * console.log(status.state); // \"succeeded\"\n * ```\n */\nexport async function waitForConfirmation(\n  wallet: UnlinkWallet,\n  txId: string,\n  opts?: WaitOptions,\n): Promise<TxStatus> {\n  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;\n  let interval = opts?.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;\n  const deadline = Date.now() + timeout;\n\n  while (Date.now() < deadline) {\n    const raw = await wallet.getTxStatus(txId);\n    const status = toTxStatus(txId, raw);\n\n    if (status.state === \"succeeded\") {\n      return status;\n    }\n\n    if (FAILED_TX_STATES.includes(status.state)) {\n      throw new TransactionFailedError(txId, status.state, status.error);\n    }\n\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) break;\n\n    await sleep(Math.min(interval, remaining));\n    interval = Math.min(interval * BACKOFF_FACTOR, MAX_POLL_INTERVAL_MS);\n  }\n\n  throw new TimeoutError(txId, timeout);\n}\n\n/**\n * Async generator that yields `TxStatus` on each poll until a terminal state.\n *\n * Useful for streaming status updates (e.g., logging, progress bars).\n *\n * @example\n * ```ts\n * for await (const status of pollRelayStatus(wallet, relayId)) {\n *   console.log(status.state); // \"pending\" → \"broadcasting\" → \"submitted\" → \"succeeded\"\n * }\n * ```\n */\nexport async function* pollRelayStatus(\n  wallet: UnlinkWallet,\n  txId: string,\n  opts?: PollOptions,\n): AsyncGenerator<TxStatus, void, unknown> {\n  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;\n  let interval = opts?.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;\n  const deadline = Date.now() + timeout;\n\n  while (Date.now() < deadline) {\n    const raw = await wallet.getTxStatus(txId);\n    const status = toTxStatus(txId, raw);\n\n    yield status;\n\n    if (TERMINAL_TX_STATES.includes(status.state)) {\n      return;\n    }\n\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) return;\n\n    await sleep(Math.min(interval, remaining));\n    interval = Math.min(interval * BACKOFF_FACTOR, MAX_POLL_INTERVAL_MS);\n  }\n}\n","import { EventEmitter } from \"node:events\";\nimport type { UnlinkWallet, WalletSDKEvent } from \"@unlink-xyz/core\";\n\n/**\n * Wrap an UnlinkWallet's event system with a Node.js `EventEmitter`.\n *\n * Events are emitted by their `type` field (e.g., `\"notes-updated\"`,\n * `\"tx-status-changed\"`). A wildcard `\"*\"` event is also emitted for\n * every event.\n *\n * @returns An `EventEmitter` and an `unsubscribe` function to detach from the wallet.\n *\n * @example\n * ```ts\n * const { emitter, unsubscribe } = createWalletEmitter(wallet);\n *\n * emitter.on(\"notes-updated\", (event) => {\n *   console.log(\"Notes updated on chain\", event.chainId);\n * });\n *\n * emitter.on(\"tx-status-changed\", (event) => {\n *   console.log(`TX ${event.txId}: ${event.state}`);\n * });\n *\n * // Listen to all events\n * emitter.on(\"*\", (event) => console.log(event));\n *\n * // Cleanup when done\n * unsubscribe();\n * ```\n */\nexport function createWalletEmitter(wallet: UnlinkWallet): {\n  emitter: EventEmitter;\n  unsubscribe: () => void;\n} {\n  const emitter = new EventEmitter();\n\n  const unsubscribe = wallet.on((event: WalletSDKEvent) => {\n    emitter.emit(event.type, event);\n    emitter.emit(\"*\", event);\n  });\n\n  return { emitter, unsubscribe };\n}\n","import fs from \"node:fs\";\nimport path from \"node:path\";\nimport type {\n  BatchOp,\n  Bytes,\n  IterOptions,\n  KvPair,\n  Storage,\n} from \"@unlink-xyz/core\";\nimport { validateKey } from \"@unlink-xyz/core\";\nimport Database from \"better-sqlite3\";\n\nexport type SqliteStorageOptions = {\n  /** Full path to the .db file */\n  path: string;\n};\n\nexport function createSqliteStorage(opts: SqliteStorageOptions): Storage {\n  let db: Database.Database | null = null;\n  let stmtGet: Database.Statement;\n  let stmtPut: Database.Statement;\n  let stmtDel: Database.Statement;\n  let stmtGetSchema: Database.Statement;\n  let stmtUpsertSchema: Database.Statement;\n\n  return {\n    async open() {\n      const dir = path.dirname(opts.path);\n      fs.mkdirSync(dir, { recursive: true });\n\n      db = new Database(opts.path);\n      db.pragma(\"journal_mode = WAL\");\n      db.pragma(\"busy_timeout = 5000\");\n      db.exec(`\n        CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value BLOB NOT NULL);\n        CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);\n      `);\n\n      stmtGet = db.prepare(\"SELECT value FROM kv WHERE key = ?\");\n      stmtPut = db.prepare(\n        \"INSERT OR REPLACE INTO kv (key, value) VALUES (?, ?)\",\n      );\n      stmtDel = db.prepare(\"DELETE FROM kv WHERE key = ?\");\n      stmtGetSchema = db.prepare(\n        \"SELECT value FROM meta WHERE key = 'schema_version'\",\n      );\n      stmtUpsertSchema = db.prepare(\n        \"INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)\",\n      );\n    },\n\n    async get(key: string): Promise<Bytes | null> {\n      validateKey(key);\n      const row = stmtGet.get(key) as { value: Buffer } | undefined;\n      return row ? new Uint8Array(row.value) : null;\n    },\n\n    async put(key: string, value: Bytes): Promise<void> {\n      validateKey(key);\n      stmtPut.run(key, Buffer.from(value));\n    },\n\n    async delete(key: string): Promise<void> {\n      validateKey(key);\n      stmtDel.run(key);\n    },\n\n    async batch(ops: BatchOp[]): Promise<void> {\n      const runBatch = db!.transaction(() => {\n        for (const op of ops) {\n          if (op.put) {\n            const [k, v] = op.put;\n            validateKey(k);\n            stmtPut.run(k, Buffer.from(v));\n          }\n          if (op.del) {\n            validateKey(op.del);\n            stmtDel.run(op.del);\n          }\n        }\n      });\n      runBatch();\n    },\n\n    async iter(o: IterOptions = {}): Promise<KvPair[]> {\n      if (o.start && o.end && o.start > o.end) {\n        throw new Error(\"iter start bound must not exceed end bound\");\n      }\n\n      const conditions: string[] = [];\n      const params: (string | number)[] = [];\n\n      if (o.prefix) {\n        // Escape SQL LIKE wildcards in the prefix\n        const escaped = o.prefix.replace(/[%_\\\\]/g, \"\\\\$&\");\n        conditions.push(\"key LIKE ? ESCAPE '\\\\'\");\n        params.push(escaped + \"%\");\n      }\n      if (o.start) {\n        conditions.push(\"key >= ?\");\n        params.push(o.start);\n      }\n      if (o.end) {\n        conditions.push(\"key <= ?\");\n        params.push(o.end);\n      }\n\n      let sql = \"SELECT key, value FROM kv\";\n      if (conditions.length > 0) {\n        sql += \" WHERE \" + conditions.join(\" AND \");\n      }\n      sql += o.reverse ? \" ORDER BY key DESC\" : \" ORDER BY key ASC\";\n      if (o.limit != null) {\n        sql += \" LIMIT ?\";\n        params.push(o.limit);\n      }\n\n      const rows = db!.prepare(sql).all(...params) as Array<{\n        key: string;\n        value: Buffer;\n      }>;\n\n      return rows.map((row) => ({\n        key: row.key,\n        value: new Uint8Array(row.value),\n      }));\n    },\n\n    async count(prefix?: string): Promise<number> {\n      let sql = \"SELECT COUNT(*) as cnt FROM kv\";\n      const params: string[] = [];\n      if (prefix) {\n        const escaped = prefix.replace(/[%_\\\\]/g, \"\\\\$&\");\n        sql += \" WHERE key LIKE ? ESCAPE '\\\\'\";\n        params.push(escaped + \"%\");\n      }\n      const row = db!.prepare(sql).get(...params) as { cnt: number };\n      return row.cnt;\n    },\n\n    async getSchemaVersion(): Promise<number> {\n      const row = stmtGetSchema.get() as { value: number } | undefined;\n      return row?.value ?? 0;\n    },\n\n    async setSchemaVersion(v: number): Promise<void> {\n      stmtUpsertSchema.run(v);\n    },\n  };\n}\n"],"mappings":"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","names":["crypto","import_core","path","fs","Database","import_core"]}

package/dist/index.d.cts

@@ -0,0 +1,201 @@
+import { Storage, Environment, RelayState, UnlinkWallet } from '@unlink-xyz/core';
+export { Account, AccountInfo, AccountView, DepositRelayResult, Environment, HistoryEntry, NoteRecord, RelayState, RelayStatusResponse, Storage, TransactRelayResult, TransferPlanResult, TransferResult, UnlinkWallet, WalletSDKEvent, WithdrawPlanResult, WithdrawResult, createMemoryStorage } from '@unlink-xyz/core';
+import { EventEmitter } from 'node:events';
+
+/**
+ * Configuration for `initWallet()`.
+ *
+ * Extends core wallet config with Node.js-friendly defaults:
+ * - `storage` defaults to in-memory
+ * - `rng` defaults to `node:crypto`
+ * - `autoSync` defaults to `false`
+ */
+type NodeWalletConfig = {
+    chainId: number;
+    /** Storage backend. Defaults to `createMemoryStorage()`. */
+    storage?: Storage;
+    /** Random number generator. Defaults to `node:crypto.randomBytes`. */
+    rng?: (n: number) => Uint8Array;
+    /** Whether to auto-sync on an interval. Defaults to `false`. */
+    autoSync?: boolean;
+    /** Custom fetch implementation. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Chain RPC URL for burner EOA transactions. */
+    chainRpcUrl?: string;
+    /** Prover artifact configuration. */
+    prover?: {
+        artifactSource?: {
+            version?: string;
+            baseUrl?: string;
+            preferLocalFiles?: boolean;
+        };
+    };
+    /**
+     * Auto-create seed + first account on init. Defaults to `true`.
+     * Set to `false` if you want to import an existing mnemonic.
+     */
+    setup?: boolean;
+    /**
+     * Sync notes from blockchain after init. Defaults to `true`.
+     * Set to `false` for offline/local operations.
+     */
+    sync?: boolean;
+} & ({
+    /** Environment to auto-resolve gateway URL and pool address. */
+    environment: Environment;
+    /** Override pool address (defaults to environment config). */
+    poolAddress?: string;
+} | {
+    /** Explicit gateway URL. */
+    gatewayUrl: string;
+    /** Pool contract address (required with explicit gatewayUrl). */
+    poolAddress: string;
+});
+/** Status of a relayed transaction. */
+type TxStatus = {
+    txId: string;
+    state: RelayState;
+    txHash?: string;
+    blockNumber?: number;
+    error?: string;
+};
+/** Options for `waitForConfirmation()`. */
+type WaitOptions = {
+    /** Timeout in milliseconds. Defaults to 5 minutes. */
+    timeout?: number;
+    /** Initial poll interval in milliseconds. Defaults to 2000. */
+    pollInterval?: number;
+};
+/** Options for `pollRelayStatus()`. */
+type PollOptions = {
+    /** Initial poll interval in milliseconds. Defaults to 2000. */
+    pollInterval?: number;
+    /** Timeout in milliseconds. Defaults to 5 minutes. */
+    timeout?: number;
+};
+
+/**
+ * Initialize an Unlink wallet with Node.js-friendly defaults.
+ *
+ * Compared to `UnlinkWallet.create()`, this:
+ * - Defaults storage to in-memory (no IndexedDB required)
+ * - Defaults RNG to `node:crypto`
+ * - Defaults autoSync to `false`
+ * - Optionally creates seed + first account automatically
+ * - Optionally syncs notes from blockchain
+ *
+ * @example
+ * ```ts
+ * // Minimal — ready to use in one call:
+ * const wallet = await initWallet({
+ *   chainId: 11155111,
+ *   environment: "testnet",
+ * });
+ *
+ * // Skip auto-setup (e.g., to import an existing mnemonic):
+ * const wallet = await initWallet({
+ *   chainId: 11155111,
+ *   environment: "testnet",
+ *   setup: false,
+ *   sync: false,
+ * });
+ * await wallet.seed.importMnemonic("your mnemonic ...");
+ * await wallet.accounts.create();
+ * await wallet.sync();
+ * ```
+ */
+declare function initWallet(config: NodeWalletConfig): Promise<UnlinkWallet>;
+
+/**
+ * Poll relay status until the transaction reaches a terminal state.
+ *
+ * Resolves with `TxStatus` on success (`"succeeded"`).
+ * Throws `TransactionFailedError` on failure (`"reverted"`, `"failed"`, `"dead"`).
+ * Throws `TimeoutError` if the timeout is exceeded.
+ *
+ * Uses exponential backoff: 2s → 3s → 4.5s → ... capped at 30s.
+ *
+ * @example
+ * ```ts
+ * const result = await wallet.transfer({ transfers: [{ token, recipient, amount }] });
+ * const status = await waitForConfirmation(wallet, result.relayId);
+ * console.log(status.state); // "succeeded"
+ * ```
+ */
+declare function waitForConfirmation(wallet: UnlinkWallet, txId: string, opts?: WaitOptions): Promise<TxStatus>;
+/**
+ * Async generator that yields `TxStatus` on each poll until a terminal state.
+ *
+ * Useful for streaming status updates (e.g., logging, progress bars).
+ *
+ * @example
+ * ```ts
+ * for await (const status of pollRelayStatus(wallet, relayId)) {
+ *   console.log(status.state); // "pending" → "broadcasting" → "submitted" → "succeeded"
+ * }
+ * ```
+ */
+declare function pollRelayStatus(wallet: UnlinkWallet, txId: string, opts?: PollOptions): AsyncGenerator<TxStatus, void, unknown>;
+
+/**
+ * Wrap an UnlinkWallet's event system with a Node.js `EventEmitter`.
+ *
+ * Events are emitted by their `type` field (e.g., `"notes-updated"`,
+ * `"tx-status-changed"`). A wildcard `"*"` event is also emitted for
+ * every event.
+ *
+ * @returns An `EventEmitter` and an `unsubscribe` function to detach from the wallet.
+ *
+ * @example
+ * ```ts
+ * const { emitter, unsubscribe } = createWalletEmitter(wallet);
+ *
+ * emitter.on("notes-updated", (event) => {
+ *   console.log("Notes updated on chain", event.chainId);
+ * });
+ *
+ * emitter.on("tx-status-changed", (event) => {
+ *   console.log(`TX ${event.txId}: ${event.state}`);
+ * });
+ *
+ * // Listen to all events
+ * emitter.on("*", (event) => console.log(event));
+ *
+ * // Cleanup when done
+ * unsubscribe();
+ * ```
+ */
+declare function createWalletEmitter(wallet: UnlinkWallet): {
+    emitter: EventEmitter;
+    unsubscribe: () => void;
+};
+
+type SqliteStorageOptions = {
+    /** Full path to the .db file */
+    path: string;
+};
+declare function createSqliteStorage(opts: SqliteStorageOptions): Storage;
+
+/** Terminal relay states — the transaction has finished processing. */
+declare const TERMINAL_TX_STATES: readonly RelayState[];
+/** Failed relay states — the transaction did not succeed. */
+declare const FAILED_TX_STATES: readonly RelayState[];
+/** Default timeout for `waitForConfirmation` (5 minutes). */
+declare const DEFAULT_TIMEOUT_MS: number;
+/** Default initial poll interval (2 seconds). */
+declare const DEFAULT_POLL_INTERVAL_MS = 2000;
+/** Thrown when relay polling exceeds the configured timeout. */
+declare class TimeoutError extends Error {
+    readonly txId: string;
+    readonly timeout: number;
+    constructor(txId: string, timeout: number);
+}
+/** Thrown when a transaction reaches a failed terminal state. */
+declare class TransactionFailedError extends Error {
+    readonly txId: string;
+    readonly state: RelayState;
+    readonly reason?: string;
+    constructor(txId: string, state: RelayState, reason?: string);
+}
+
+export { DEFAULT_POLL_INTERVAL_MS, DEFAULT_TIMEOUT_MS, FAILED_TX_STATES, type NodeWalletConfig, type PollOptions, type SqliteStorageOptions, TERMINAL_TX_STATES, TimeoutError, TransactionFailedError, type TxStatus, type WaitOptions, createSqliteStorage, createWalletEmitter, initWallet, pollRelayStatus, waitForConfirmation };

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+import { Storage, Environment, RelayState, UnlinkWallet } from '@unlink-xyz/core';
+export { Account, AccountInfo, AccountView, DepositRelayResult, Environment, HistoryEntry, NoteRecord, RelayState, RelayStatusResponse, Storage, TransactRelayResult, TransferPlanResult, TransferResult, UnlinkWallet, WalletSDKEvent, WithdrawPlanResult, WithdrawResult, createMemoryStorage } from '@unlink-xyz/core';
+import { EventEmitter } from 'node:events';
+
+/**
+ * Configuration for `initWallet()`.
+ *
+ * Extends core wallet config with Node.js-friendly defaults:
+ * - `storage` defaults to in-memory
+ * - `rng` defaults to `node:crypto`
+ * - `autoSync` defaults to `false`
+ */
+type NodeWalletConfig = {
+    chainId: number;
+    /** Storage backend. Defaults to `createMemoryStorage()`. */
+    storage?: Storage;
+    /** Random number generator. Defaults to `node:crypto.randomBytes`. */
+    rng?: (n: number) => Uint8Array;
+    /** Whether to auto-sync on an interval. Defaults to `false`. */
+    autoSync?: boolean;
+    /** Custom fetch implementation. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Chain RPC URL for burner EOA transactions. */
+    chainRpcUrl?: string;
+    /** Prover artifact configuration. */
+    prover?: {
+        artifactSource?: {
+            version?: string;
+            baseUrl?: string;
+            preferLocalFiles?: boolean;
+        };
+    };
+    /**
+     * Auto-create seed + first account on init. Defaults to `true`.
+     * Set to `false` if you want to import an existing mnemonic.
+     */
+    setup?: boolean;
+    /**
+     * Sync notes from blockchain after init. Defaults to `true`.
+     * Set to `false` for offline/local operations.
+     */
+    sync?: boolean;
+} & ({
+    /** Environment to auto-resolve gateway URL and pool address. */
+    environment: Environment;
+    /** Override pool address (defaults to environment config). */
+    poolAddress?: string;
+} | {
+    /** Explicit gateway URL. */
+    gatewayUrl: string;
+    /** Pool contract address (required with explicit gatewayUrl). */
+    poolAddress: string;
+});
+/** Status of a relayed transaction. */
+type TxStatus = {
+    txId: string;
+    state: RelayState;
+    txHash?: string;
+    blockNumber?: number;
+    error?: string;
+};
+/** Options for `waitForConfirmation()`. */
+type WaitOptions = {
+    /** Timeout in milliseconds. Defaults to 5 minutes. */
+    timeout?: number;
+    /** Initial poll interval in milliseconds. Defaults to 2000. */
+    pollInterval?: number;
+};
+/** Options for `pollRelayStatus()`. */
+type PollOptions = {
+    /** Initial poll interval in milliseconds. Defaults to 2000. */
+    pollInterval?: number;
+    /** Timeout in milliseconds. Defaults to 5 minutes. */
+    timeout?: number;
+};
+
+/**
+ * Initialize an Unlink wallet with Node.js-friendly defaults.
+ *
+ * Compared to `UnlinkWallet.create()`, this:
+ * - Defaults storage to in-memory (no IndexedDB required)
+ * - Defaults RNG to `node:crypto`
+ * - Defaults autoSync to `false`
+ * - Optionally creates seed + first account automatically
+ * - Optionally syncs notes from blockchain
+ *
+ * @example
+ * ```ts
+ * // Minimal — ready to use in one call:
+ * const wallet = await initWallet({
+ *   chainId: 11155111,
+ *   environment: "testnet",
+ * });
+ *
+ * // Skip auto-setup (e.g., to import an existing mnemonic):
+ * const wallet = await initWallet({
+ *   chainId: 11155111,
+ *   environment: "testnet",
+ *   setup: false,
+ *   sync: false,
+ * });
+ * await wallet.seed.importMnemonic("your mnemonic ...");
+ * await wallet.accounts.create();
+ * await wallet.sync();
+ * ```
+ */
+declare function initWallet(config: NodeWalletConfig): Promise<UnlinkWallet>;
+
+/**
+ * Poll relay status until the transaction reaches a terminal state.
+ *
+ * Resolves with `TxStatus` on success (`"succeeded"`).
+ * Throws `TransactionFailedError` on failure (`"reverted"`, `"failed"`, `"dead"`).
+ * Throws `TimeoutError` if the timeout is exceeded.
+ *
+ * Uses exponential backoff: 2s → 3s → 4.5s → ... capped at 30s.
+ *
+ * @example
+ * ```ts
+ * const result = await wallet.transfer({ transfers: [{ token, recipient, amount }] });
+ * const status = await waitForConfirmation(wallet, result.relayId);
+ * console.log(status.state); // "succeeded"
+ * ```
+ */
+declare function waitForConfirmation(wallet: UnlinkWallet, txId: string, opts?: WaitOptions): Promise<TxStatus>;
+/**
+ * Async generator that yields `TxStatus` on each poll until a terminal state.
+ *
+ * Useful for streaming status updates (e.g., logging, progress bars).
+ *
+ * @example
+ * ```ts
+ * for await (const status of pollRelayStatus(wallet, relayId)) {
+ *   console.log(status.state); // "pending" → "broadcasting" → "submitted" → "succeeded"
+ * }
+ * ```
+ */
+declare function pollRelayStatus(wallet: UnlinkWallet, txId: string, opts?: PollOptions): AsyncGenerator<TxStatus, void, unknown>;
+
+/**
+ * Wrap an UnlinkWallet's event system with a Node.js `EventEmitter`.
+ *
+ * Events are emitted by their `type` field (e.g., `"notes-updated"`,
+ * `"tx-status-changed"`). A wildcard `"*"` event is also emitted for
+ * every event.
+ *
+ * @returns An `EventEmitter` and an `unsubscribe` function to detach from the wallet.
+ *
+ * @example
+ * ```ts
+ * const { emitter, unsubscribe } = createWalletEmitter(wallet);
+ *
+ * emitter.on("notes-updated", (event) => {
+ *   console.log("Notes updated on chain", event.chainId);
+ * });
+ *
+ * emitter.on("tx-status-changed", (event) => {
+ *   console.log(`TX ${event.txId}: ${event.state}`);
+ * });
+ *
+ * // Listen to all events
+ * emitter.on("*", (event) => console.log(event));
+ *
+ * // Cleanup when done
+ * unsubscribe();
+ * ```
+ */
+declare function createWalletEmitter(wallet: UnlinkWallet): {
+    emitter: EventEmitter;
+    unsubscribe: () => void;
+};
+
+type SqliteStorageOptions = {
+    /** Full path to the .db file */
+    path: string;
+};
+declare function createSqliteStorage(opts: SqliteStorageOptions): Storage;
+
+/** Terminal relay states — the transaction has finished processing. */
+declare const TERMINAL_TX_STATES: readonly RelayState[];
+/** Failed relay states — the transaction did not succeed. */
+declare const FAILED_TX_STATES: readonly RelayState[];
+/** Default timeout for `waitForConfirmation` (5 minutes). */
+declare const DEFAULT_TIMEOUT_MS: number;
+/** Default initial poll interval (2 seconds). */
+declare const DEFAULT_POLL_INTERVAL_MS = 2000;
+/** Thrown when relay polling exceeds the configured timeout. */
+declare class TimeoutError extends Error {
+    readonly txId: string;
+    readonly timeout: number;
+    constructor(txId: string, timeout: number);
+}
+/** Thrown when a transaction reaches a failed terminal state. */
+declare class TransactionFailedError extends Error {
+    readonly txId: string;
+    readonly state: RelayState;
+    readonly reason?: string;
+    constructor(txId: string, state: RelayState, reason?: string);
+}
+
+export { DEFAULT_POLL_INTERVAL_MS, DEFAULT_TIMEOUT_MS, FAILED_TX_STATES, type NodeWalletConfig, type PollOptions, type SqliteStorageOptions, TERMINAL_TX_STATES, TimeoutError, TransactionFailedError, type TxStatus, type WaitOptions, createSqliteStorage, createWalletEmitter, initWallet, pollRelayStatus, waitForConfirmation };

package/dist/index.js

@@ -0,0 +1,271 @@
+// src/init.ts
+import crypto from "crypto";
+import { createMemoryStorage, UnlinkWallet } from "@unlink-xyz/core";
+var nodeRng = (n) => new Uint8Array(crypto.randomBytes(n));
+async function initWallet(config) {
+  const { setup, sync, ...coreConfig } = config;
+  void setup;
+  void sync;
+  const wallet = await UnlinkWallet.create({
+    ...coreConfig,
+    storage: config.storage ?? createMemoryStorage(),
+    rng: config.rng ?? nodeRng,
+    autoSync: config.autoSync ?? false,
+    fetch: config.fetch ?? globalThis.fetch
+  });
+  if (config.setup !== false) {
+    const hasSeed = await wallet.seed.exists();
+    if (!hasSeed) {
+      await wallet.seed.create();
+    }
+    const accounts = await wallet.accounts.list();
+    if (accounts.length === 0) {
+      await wallet.accounts.create();
+    }
+  }
+  if (config.sync !== false) {
+    await wallet.sync();
+  }
+  return wallet;
+}
+
+// src/errors.ts
+var TERMINAL_TX_STATES = [
+  "succeeded",
+  "reverted",
+  "failed",
+  "dead"
+];
+var FAILED_TX_STATES = [
+  "reverted",
+  "failed",
+  "dead"
+];
+var DEFAULT_TIMEOUT_MS = 5 * 60 * 1e3;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var MAX_POLL_INTERVAL_MS = 3e4;
+var BACKOFF_FACTOR = 1.5;
+var TimeoutError = class extends Error {
+  txId;
+  timeout;
+  constructor(txId, timeout) {
+    super(`Transaction ${txId} did not confirm within ${timeout}ms`);
+    this.name = "TimeoutError";
+    this.txId = txId;
+    this.timeout = timeout;
+  }
+};
+var TransactionFailedError = class extends Error {
+  txId;
+  state;
+  reason;
+  constructor(txId, state, reason) {
+    super(
+      `Transaction ${txId} failed with state: ${state}${reason ? ` \u2014 ${reason}` : ""}`
+    );
+    this.name = "TransactionFailedError";
+    this.txId = txId;
+    this.state = state;
+    this.reason = reason;
+  }
+};
+
+// src/confirmation.ts
+function toTxStatus(txId, raw) {
+  return {
+    txId,
+    state: raw.state,
+    txHash: raw.txHash ?? void 0,
+    blockNumber: raw.receipt?.blockNumber ?? void 0,
+    error: raw.error ?? void 0
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForConfirmation(wallet, txId, opts) {
+  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+  let interval = opts?.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const raw = await wallet.getTxStatus(txId);
+    const status = toTxStatus(txId, raw);
+    if (status.state === "succeeded") {
+      return status;
+    }
+    if (FAILED_TX_STATES.includes(status.state)) {
+      throw new TransactionFailedError(txId, status.state, status.error);
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await sleep(Math.min(interval, remaining));
+    interval = Math.min(interval * BACKOFF_FACTOR, MAX_POLL_INTERVAL_MS);
+  }
+  throw new TimeoutError(txId, timeout);
+}
+async function* pollRelayStatus(wallet, txId, opts) {
+  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+  let interval = opts?.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const raw = await wallet.getTxStatus(txId);
+    const status = toTxStatus(txId, raw);
+    yield status;
+    if (TERMINAL_TX_STATES.includes(status.state)) {
+      return;
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return;
+    await sleep(Math.min(interval, remaining));
+    interval = Math.min(interval * BACKOFF_FACTOR, MAX_POLL_INTERVAL_MS);
+  }
+}
+
+// src/events.ts
+import { EventEmitter } from "events";
+function createWalletEmitter(wallet) {
+  const emitter = new EventEmitter();
+  const unsubscribe = wallet.on((event) => {
+    emitter.emit(event.type, event);
+    emitter.emit("*", event);
+  });
+  return { emitter, unsubscribe };
+}
+
+// src/storage/sqlite.ts
+import fs from "fs";
+import path from "path";
+import { validateKey } from "@unlink-xyz/core";
+import Database from "better-sqlite3";
+function createSqliteStorage(opts) {
+  let db = null;
+  let stmtGet;
+  let stmtPut;
+  let stmtDel;
+  let stmtGetSchema;
+  let stmtUpsertSchema;
+  return {
+    async open() {
+      const dir = path.dirname(opts.path);
+      fs.mkdirSync(dir, { recursive: true });
+      db = new Database(opts.path);
+      db.pragma("journal_mode = WAL");
+      db.pragma("busy_timeout = 5000");
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value BLOB NOT NULL);
+        CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);
+      `);
+      stmtGet = db.prepare("SELECT value FROM kv WHERE key = ?");
+      stmtPut = db.prepare(
+        "INSERT OR REPLACE INTO kv (key, value) VALUES (?, ?)"
+      );
+      stmtDel = db.prepare("DELETE FROM kv WHERE key = ?");
+      stmtGetSchema = db.prepare(
+        "SELECT value FROM meta WHERE key = 'schema_version'"
+      );
+      stmtUpsertSchema = db.prepare(
+        "INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)"
+      );
+    },
+    async get(key) {
+      validateKey(key);
+      const row = stmtGet.get(key);
+      return row ? new Uint8Array(row.value) : null;
+    },
+    async put(key, value) {
+      validateKey(key);
+      stmtPut.run(key, Buffer.from(value));
+    },
+    async delete(key) {
+      validateKey(key);
+      stmtDel.run(key);
+    },
+    async batch(ops) {
+      const runBatch = db.transaction(() => {
+        for (const op of ops) {
+          if (op.put) {
+            const [k, v] = op.put;
+            validateKey(k);
+            stmtPut.run(k, Buffer.from(v));
+          }
+          if (op.del) {
+            validateKey(op.del);
+            stmtDel.run(op.del);
+          }
+        }
+      });
+      runBatch();
+    },
+    async iter(o = {}) {
+      if (o.start && o.end && o.start > o.end) {
+        throw new Error("iter start bound must not exceed end bound");
+      }
+      const conditions = [];
+      const params = [];
+      if (o.prefix) {
+        const escaped = o.prefix.replace(/[%_\\]/g, "\\$&");
+        conditions.push("key LIKE ? ESCAPE '\\'");
+        params.push(escaped + "%");
+      }
+      if (o.start) {
+        conditions.push("key >= ?");
+        params.push(o.start);
+      }
+      if (o.end) {
+        conditions.push("key <= ?");
+        params.push(o.end);
+      }
+      let sql = "SELECT key, value FROM kv";
+      if (conditions.length > 0) {
+        sql += " WHERE " + conditions.join(" AND ");
+      }
+      sql += o.reverse ? " ORDER BY key DESC" : " ORDER BY key ASC";
+      if (o.limit != null) {
+        sql += " LIMIT ?";
+        params.push(o.limit);
+      }
+      const rows = db.prepare(sql).all(...params);
+      return rows.map((row) => ({
+        key: row.key,
+        value: new Uint8Array(row.value)
+      }));
+    },
+    async count(prefix) {
+      let sql = "SELECT COUNT(*) as cnt FROM kv";
+      const params = [];
+      if (prefix) {
+        const escaped = prefix.replace(/[%_\\]/g, "\\$&");
+        sql += " WHERE key LIKE ? ESCAPE '\\'";
+        params.push(escaped + "%");
+      }
+      const row = db.prepare(sql).get(...params);
+      return row.cnt;
+    },
+    async getSchemaVersion() {
+      const row = stmtGetSchema.get();
+      return row?.value ?? 0;
+    },
+    async setSchemaVersion(v) {
+      stmtUpsertSchema.run(v);
+    }
+  };
+}
+
+// src/index.ts
+import { UnlinkWallet as UnlinkWallet2, createMemoryStorage as createMemoryStorage2 } from "@unlink-xyz/core";
+export {
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_TIMEOUT_MS,
+  FAILED_TX_STATES,
+  TERMINAL_TX_STATES,
+  TimeoutError,
+  TransactionFailedError,
+  UnlinkWallet2 as UnlinkWallet,
+  createMemoryStorage2 as createMemoryStorage,
+  createSqliteStorage,
+  createWalletEmitter,
+  initWallet,
+  pollRelayStatus,
+  waitForConfirmation
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/init.ts","../src/errors.ts","../src/confirmation.ts","../src/events.ts","../src/storage/sqlite.ts","../src/index.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport { createMemoryStorage, UnlinkWallet } from \"@unlink-xyz/core\";\n\nimport type { NodeWalletConfig } from \"./types.js\";\n\nconst nodeRng = (n: number): Uint8Array =>\n  new Uint8Array(crypto.randomBytes(n));\n\n/**\n * Initialize an Unlink wallet with Node.js-friendly defaults.\n *\n * Compared to `UnlinkWallet.create()`, this:\n * - Defaults storage to in-memory (no IndexedDB required)\n * - Defaults RNG to `node:crypto`\n * - Defaults autoSync to `false`\n * - Optionally creates seed + first account automatically\n * - Optionally syncs notes from blockchain\n *\n * @example\n * ```ts\n * // Minimal — ready to use in one call:\n * const wallet = await initWallet({\n *   chainId: 11155111,\n *   environment: \"testnet\",\n * });\n *\n * // Skip auto-setup (e.g., to import an existing mnemonic):\n * const wallet = await initWallet({\n *   chainId: 11155111,\n *   environment: \"testnet\",\n *   setup: false,\n *   sync: false,\n * });\n * await wallet.seed.importMnemonic(\"your mnemonic ...\");\n * await wallet.accounts.create();\n * await wallet.sync();\n * ```\n */\nexport async function initWallet(\n  config: NodeWalletConfig,\n): Promise<UnlinkWallet> {\n  // Strip node-specific fields before passing to core\n  const { setup, sync, ...coreConfig } = config;\n  void setup;\n  void sync;\n\n  const wallet = await UnlinkWallet.create({\n    ...coreConfig,\n    storage: config.storage ?? createMemoryStorage(),\n    rng: config.rng ?? nodeRng,\n    autoSync: config.autoSync ?? false,\n    fetch: config.fetch ?? globalThis.fetch,\n  });\n\n  if (config.setup !== false) {\n    const hasSeed = await wallet.seed.exists();\n    if (!hasSeed) {\n      await wallet.seed.create();\n    }\n\n    const accounts = await wallet.accounts.list();\n    if (accounts.length === 0) {\n      await wallet.accounts.create();\n    }\n  }\n\n  if (config.sync !== false) {\n    await wallet.sync();\n  }\n\n  return wallet;\n}\n","import type { RelayState } from \"@unlink-xyz/core\";\n\n/** Terminal relay states — the transaction has finished processing. */\nexport const TERMINAL_TX_STATES: readonly RelayState[] = [\n  \"succeeded\",\n  \"reverted\",\n  \"failed\",\n  \"dead\",\n] as const;\n\n/** Failed relay states — the transaction did not succeed. */\nexport const FAILED_TX_STATES: readonly RelayState[] = [\n  \"reverted\",\n  \"failed\",\n  \"dead\",\n] as const;\n\n/** Default timeout for `waitForConfirmation` (5 minutes). */\nexport const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;\n\n/** Default initial poll interval (2 seconds). */\nexport const DEFAULT_POLL_INTERVAL_MS = 2_000;\n\n/** Maximum poll interval after backoff (30 seconds). */\nexport const MAX_POLL_INTERVAL_MS = 30_000;\n\n/** Backoff multiplier for exponential polling. */\nexport const BACKOFF_FACTOR = 1.5;\n\n/** Thrown when relay polling exceeds the configured timeout. */\nexport class TimeoutError extends Error {\n  readonly txId: string;\n  readonly timeout: number;\n\n  constructor(txId: string, timeout: number) {\n    super(`Transaction ${txId} did not confirm within ${timeout}ms`);\n    this.name = \"TimeoutError\";\n    this.txId = txId;\n    this.timeout = timeout;\n  }\n}\n\n/** Thrown when a transaction reaches a failed terminal state. */\nexport class TransactionFailedError extends Error {\n  readonly txId: string;\n  readonly state: RelayState;\n  readonly reason?: string;\n\n  constructor(txId: string, state: RelayState, reason?: string) {\n    super(\n      `Transaction ${txId} failed with state: ${state}${reason ? ` — ${reason}` : \"\"}`,\n    );\n    this.name = \"TransactionFailedError\";\n    this.txId = txId;\n    this.state = state;\n    this.reason = reason;\n  }\n}\n","import type { UnlinkWallet } from \"@unlink-xyz/core\";\n\nimport {\n  BACKOFF_FACTOR,\n  DEFAULT_POLL_INTERVAL_MS,\n  DEFAULT_TIMEOUT_MS,\n  FAILED_TX_STATES,\n  MAX_POLL_INTERVAL_MS,\n  TERMINAL_TX_STATES,\n  TimeoutError,\n  TransactionFailedError,\n} from \"./errors.js\";\nimport type { PollOptions, TxStatus, WaitOptions } from \"./types.js\";\n\nfunction toTxStatus(\n  txId: string,\n  raw: Awaited<ReturnType<UnlinkWallet[\"getTxStatus\"]>>,\n): TxStatus {\n  return {\n    txId,\n    state: raw.state,\n    txHash: raw.txHash ?? undefined,\n    blockNumber: raw.receipt?.blockNumber ?? undefined,\n    error: raw.error ?? undefined,\n  };\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Poll relay status until the transaction reaches a terminal state.\n *\n * Resolves with `TxStatus` on success (`\"succeeded\"`).\n * Throws `TransactionFailedError` on failure (`\"reverted\"`, `\"failed\"`, `\"dead\"`).\n * Throws `TimeoutError` if the timeout is exceeded.\n *\n * Uses exponential backoff: 2s → 3s → 4.5s → ... capped at 30s.\n *\n * @example\n * ```ts\n * const result = await wallet.transfer({ transfers: [{ token, recipient, amount }] });\n * const status = await waitForConfirmation(wallet, result.relayId);\n * console.log(status.state); // \"succeeded\"\n * ```\n */\nexport async function waitForConfirmation(\n  wallet: UnlinkWallet,\n  txId: string,\n  opts?: WaitOptions,\n): Promise<TxStatus> {\n  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;\n  let interval = opts?.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;\n  const deadline = Date.now() + timeout;\n\n  while (Date.now() < deadline) {\n    const raw = await wallet.getTxStatus(txId);\n    const status = toTxStatus(txId, raw);\n\n    if (status.state === \"succeeded\") {\n      return status;\n    }\n\n    if (FAILED_TX_STATES.includes(status.state)) {\n      throw new TransactionFailedError(txId, status.state, status.error);\n    }\n\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) break;\n\n    await sleep(Math.min(interval, remaining));\n    interval = Math.min(interval * BACKOFF_FACTOR, MAX_POLL_INTERVAL_MS);\n  }\n\n  throw new TimeoutError(txId, timeout);\n}\n\n/**\n * Async generator that yields `TxStatus` on each poll until a terminal state.\n *\n * Useful for streaming status updates (e.g., logging, progress bars).\n *\n * @example\n * ```ts\n * for await (const status of pollRelayStatus(wallet, relayId)) {\n *   console.log(status.state); // \"pending\" → \"broadcasting\" → \"submitted\" → \"succeeded\"\n * }\n * ```\n */\nexport async function* pollRelayStatus(\n  wallet: UnlinkWallet,\n  txId: string,\n  opts?: PollOptions,\n): AsyncGenerator<TxStatus, void, unknown> {\n  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;\n  let interval = opts?.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;\n  const deadline = Date.now() + timeout;\n\n  while (Date.now() < deadline) {\n    const raw = await wallet.getTxStatus(txId);\n    const status = toTxStatus(txId, raw);\n\n    yield status;\n\n    if (TERMINAL_TX_STATES.includes(status.state)) {\n      return;\n    }\n\n    const remaining = deadline - Date.now();\n    if (remaining <= 0) return;\n\n    await sleep(Math.min(interval, remaining));\n    interval = Math.min(interval * BACKOFF_FACTOR, MAX_POLL_INTERVAL_MS);\n  }\n}\n","import { EventEmitter } from \"node:events\";\nimport type { UnlinkWallet, WalletSDKEvent } from \"@unlink-xyz/core\";\n\n/**\n * Wrap an UnlinkWallet's event system with a Node.js `EventEmitter`.\n *\n * Events are emitted by their `type` field (e.g., `\"notes-updated\"`,\n * `\"tx-status-changed\"`). A wildcard `\"*\"` event is also emitted for\n * every event.\n *\n * @returns An `EventEmitter` and an `unsubscribe` function to detach from the wallet.\n *\n * @example\n * ```ts\n * const { emitter, unsubscribe } = createWalletEmitter(wallet);\n *\n * emitter.on(\"notes-updated\", (event) => {\n *   console.log(\"Notes updated on chain\", event.chainId);\n * });\n *\n * emitter.on(\"tx-status-changed\", (event) => {\n *   console.log(`TX ${event.txId}: ${event.state}`);\n * });\n *\n * // Listen to all events\n * emitter.on(\"*\", (event) => console.log(event));\n *\n * // Cleanup when done\n * unsubscribe();\n * ```\n */\nexport function createWalletEmitter(wallet: UnlinkWallet): {\n  emitter: EventEmitter;\n  unsubscribe: () => void;\n} {\n  const emitter = new EventEmitter();\n\n  const unsubscribe = wallet.on((event: WalletSDKEvent) => {\n    emitter.emit(event.type, event);\n    emitter.emit(\"*\", event);\n  });\n\n  return { emitter, unsubscribe };\n}\n","import fs from \"node:fs\";\nimport path from \"node:path\";\nimport type {\n  BatchOp,\n  Bytes,\n  IterOptions,\n  KvPair,\n  Storage,\n} from \"@unlink-xyz/core\";\nimport { validateKey } from \"@unlink-xyz/core\";\nimport Database from \"better-sqlite3\";\n\nexport type SqliteStorageOptions = {\n  /** Full path to the .db file */\n  path: string;\n};\n\nexport function createSqliteStorage(opts: SqliteStorageOptions): Storage {\n  let db: Database.Database | null = null;\n  let stmtGet: Database.Statement;\n  let stmtPut: Database.Statement;\n  let stmtDel: Database.Statement;\n  let stmtGetSchema: Database.Statement;\n  let stmtUpsertSchema: Database.Statement;\n\n  return {\n    async open() {\n      const dir = path.dirname(opts.path);\n      fs.mkdirSync(dir, { recursive: true });\n\n      db = new Database(opts.path);\n      db.pragma(\"journal_mode = WAL\");\n      db.pragma(\"busy_timeout = 5000\");\n      db.exec(`\n        CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value BLOB NOT NULL);\n        CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value INTEGER NOT NULL);\n      `);\n\n      stmtGet = db.prepare(\"SELECT value FROM kv WHERE key = ?\");\n      stmtPut = db.prepare(\n        \"INSERT OR REPLACE INTO kv (key, value) VALUES (?, ?)\",\n      );\n      stmtDel = db.prepare(\"DELETE FROM kv WHERE key = ?\");\n      stmtGetSchema = db.prepare(\n        \"SELECT value FROM meta WHERE key = 'schema_version'\",\n      );\n      stmtUpsertSchema = db.prepare(\n        \"INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)\",\n      );\n    },\n\n    async get(key: string): Promise<Bytes | null> {\n      validateKey(key);\n      const row = stmtGet.get(key) as { value: Buffer } | undefined;\n      return row ? new Uint8Array(row.value) : null;\n    },\n\n    async put(key: string, value: Bytes): Promise<void> {\n      validateKey(key);\n      stmtPut.run(key, Buffer.from(value));\n    },\n\n    async delete(key: string): Promise<void> {\n      validateKey(key);\n      stmtDel.run(key);\n    },\n\n    async batch(ops: BatchOp[]): Promise<void> {\n      const runBatch = db!.transaction(() => {\n        for (const op of ops) {\n          if (op.put) {\n            const [k, v] = op.put;\n            validateKey(k);\n            stmtPut.run(k, Buffer.from(v));\n          }\n          if (op.del) {\n            validateKey(op.del);\n            stmtDel.run(op.del);\n          }\n        }\n      });\n      runBatch();\n    },\n\n    async iter(o: IterOptions = {}): Promise<KvPair[]> {\n      if (o.start && o.end && o.start > o.end) {\n        throw new Error(\"iter start bound must not exceed end bound\");\n      }\n\n      const conditions: string[] = [];\n      const params: (string | number)[] = [];\n\n      if (o.prefix) {\n        // Escape SQL LIKE wildcards in the prefix\n        const escaped = o.prefix.replace(/[%_\\\\]/g, \"\\\\$&\");\n        conditions.push(\"key LIKE ? ESCAPE '\\\\'\");\n        params.push(escaped + \"%\");\n      }\n      if (o.start) {\n        conditions.push(\"key >= ?\");\n        params.push(o.start);\n      }\n      if (o.end) {\n        conditions.push(\"key <= ?\");\n        params.push(o.end);\n      }\n\n      let sql = \"SELECT key, value FROM kv\";\n      if (conditions.length > 0) {\n        sql += \" WHERE \" + conditions.join(\" AND \");\n      }\n      sql += o.reverse ? \" ORDER BY key DESC\" : \" ORDER BY key ASC\";\n      if (o.limit != null) {\n        sql += \" LIMIT ?\";\n        params.push(o.limit);\n      }\n\n      const rows = db!.prepare(sql).all(...params) as Array<{\n        key: string;\n        value: Buffer;\n      }>;\n\n      return rows.map((row) => ({\n        key: row.key,\n        value: new Uint8Array(row.value),\n      }));\n    },\n\n    async count(prefix?: string): Promise<number> {\n      let sql = \"SELECT COUNT(*) as cnt FROM kv\";\n      const params: string[] = [];\n      if (prefix) {\n        const escaped = prefix.replace(/[%_\\\\]/g, \"\\\\$&\");\n        sql += \" WHERE key LIKE ? ESCAPE '\\\\'\";\n        params.push(escaped + \"%\");\n      }\n      const row = db!.prepare(sql).get(...params) as { cnt: number };\n      return row.cnt;\n    },\n\n    async getSchemaVersion(): Promise<number> {\n      const row = stmtGetSchema.get() as { value: number } | undefined;\n      return row?.value ?? 0;\n    },\n\n    async setSchemaVersion(v: number): Promise<void> {\n      stmtUpsertSchema.run(v);\n    },\n  };\n}\n","// Init\nexport { initWallet } from \"./init.js\";\n\n// Confirmation\nexport { waitForConfirmation, pollRelayStatus } from \"./confirmation.js\";\n\n// Events\nexport { createWalletEmitter } from \"./events.js\";\n\n// Storage\nexport {\n  createSqliteStorage,\n  type SqliteStorageOptions,\n} from \"./storage/sqlite.js\";\n\n// Errors\nexport {\n  TimeoutError,\n  TransactionFailedError,\n  TERMINAL_TX_STATES,\n  FAILED_TX_STATES,\n  DEFAULT_TIMEOUT_MS,\n  DEFAULT_POLL_INTERVAL_MS,\n} from \"./errors.js\";\n\n// Types\nexport type {\n  NodeWalletConfig,\n  TxStatus,\n  WaitOptions,\n  PollOptions,\n} from \"./types.js\";\n\n// Re-export commonly needed core types so consumers don't need @unlink-xyz/core\nexport { UnlinkWallet, createMemoryStorage } from \"@unlink-xyz/core\";\n\nexport type {\n  Account,\n  AccountInfo,\n  AccountView,\n  DepositRelayResult,\n  Environment,\n  HistoryEntry,\n  NoteRecord,\n  RelayState,\n  RelayStatusResponse,\n  Storage,\n  TransactRelayResult,\n  TransferPlanResult,\n  TransferResult,\n  WalletSDKEvent,\n  WithdrawPlanResult,\n  WithdrawResult,\n} from \"@unlink-xyz/core\";\n"],"mappings":"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","names":["UnlinkWallet","createMemoryStorage"]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@unlink-xyz/node",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "pnpm --filter @unlink-xyz/core build && tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@unlink-xyz/core": "0.1.3",
+    "better-sqlite3": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.19.0",
+    "globals": "^15.14.0",
+    "prettier": "^3.5.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.2",
+    "vitest": "4.0.1"
+  }
+}