@miden-sdk/miden-sdk 0.14.11 → 0.15.0-alpha.5

package/js/node/loader.js

@@ -0,0 +1,138 @@
+/**
+ * Finds and loads the napi native module (.node binary).
+ *
+ * Search order:
+ * 1. MIDEN_MODULE_PATH environment variable (explicit override)
+ * 2. Platform-specific npm package (@miden-sdk/node-darwin-arm64, etc.)
+ * 3. Package prebuilds directory
+ * 4. Repo target directory (for local development)
+ */
+import { createRequire } from "module";
+import path from "path";
+import fs from "fs";
+import os from "os";
+
+const require = createRequire(import.meta.url);
+
+let _sdk = null;
+
+/**
+ * Loads the napi SDK module. Caches the result after first load.
+ *
+ * @param {object} [options]
+ * @param {string} [options.modulePath] - Explicit path to the .node file.
+ * @returns {object} The napi SDK module.
+ */
+export function loadNativeModule(options) {
+  if (_sdk) return _sdk;
+
+  // 1. Explicit path (option or env var)
+  const explicit = options?.modulePath || process.env.MIDEN_MODULE_PATH;
+  if (explicit) {
+    _sdk = require(explicit);
+    return _sdk;
+  }
+
+  // 2. Platform-specific npm package (installed via optionalDependencies)
+  const platformPackage = getPlatformPackageName();
+  if (platformPackage) {
+    try {
+      _sdk = require(platformPackage);
+      return _sdk;
+    } catch {
+      // Not installed -- fall through to other methods
+    }
+  }
+
+  const archMap = { arm64: "aarch64", x64: "x86_64" };
+  const arch = archMap[os.arch()] || os.arch();
+  const platform =
+    os.platform() === "darwin" ? "apple-darwin" : "unknown-linux-gnu";
+  const target = `${arch}-${platform}`;
+  const ext = os.platform() === "darwin" ? "dylib" : "so";
+  const libName = `libmiden_client_web.${ext}`;
+
+  // 3. Package prebuilds directory
+  const packageRoot = path.resolve(import.meta.dirname, "..");
+  const prebuildCandidates = [
+    path.join(
+      packageRoot,
+      "prebuilds",
+      `${os.platform()}-${os.arch()}`,
+      "miden_client_web.node"
+    ),
+    path.join(packageRoot, "prebuilds", "miden_client_web.node"),
+  ];
+
+  for (const p of prebuildCandidates) {
+    if (fs.existsSync(p)) {
+      _sdk = require(p);
+      return _sdk;
+    }
+  }
+
+  // 4. Repo target directory (development)
+  const repoRoot = findRepoRoot(packageRoot);
+  if (repoRoot) {
+    const targetCandidates = [
+      path.join(repoRoot, "target", target, "release", libName),
+      path.join(repoRoot, "target", "release", libName),
+      path.join(repoRoot, "target", target, "debug", libName),
+      path.join(repoRoot, "target", "debug", libName),
+    ];
+
+    for (const p of targetCandidates) {
+      if (fs.existsSync(p)) {
+        // napi requires a .node extension -- copy if needed
+        const nodeFile = path.join(path.dirname(p), "miden_client_web.node");
+        if (
+          !fs.existsSync(nodeFile) ||
+          fs.statSync(p).mtimeMs > fs.statSync(nodeFile).mtimeMs
+        ) {
+          fs.copyFileSync(p, nodeFile);
+        }
+        _sdk = require(nodeFile);
+        return _sdk;
+      }
+    }
+  }
+
+  throw new Error(
+    `Miden napi module not found.\n\n` +
+      `Build it with:\n` +
+      `  cargo build -p miden-client-web --no-default-features --features nodejs --release\n\n` +
+      `Or set MIDEN_MODULE_PATH to the .node file location.`
+  );
+}
+
+/**
+ * Returns the platform-specific npm package name for the current OS/arch,
+ * or null if the platform is not supported.
+ */
+function getPlatformPackageName() {
+  const platformMap = {
+    "darwin-arm64": "@miden-sdk/node-darwin-arm64",
+    "darwin-x64": "@miden-sdk/node-darwin-x64",
+    "linux-x64": "@miden-sdk/node-linux-x64-gnu",
+  };
+  return platformMap[`${os.platform()}-${os.arch()}`] || null;
+}
+
+/**
+ * Walks up from startDir looking for the repo root (has Cargo.toml + crates/).
+ */
+function findRepoRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    if (
+      fs.existsSync(path.join(dir, "Cargo.toml")) &&
+      fs.existsSync(path.join(dir, "crates"))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}

package/js/node/napi-compat.js

@@ -0,0 +1,253 @@
+/**
+ * NAPI compatibility layer.
+ *
+ * Normalizes differences between the napi (Node.js) and wasm-bindgen (browser)
+ * SDK surfaces so the shared MidenClient wrapper works on both platforms.
+ *
+ * Key normalizations:
+ * - Uint8Array/Buffer -> Array (napi's Vec<u8> expects plain arrays)
+ * - BigUint64Array/BigInt64Array -> Array (napi's Vec<u64>/Vec<BigInt> expects plain arrays)
+ * - null -> undefined (napi returns null for Option::None, wasm-bindgen returns undefined)
+ * - camelCase -> snake_case aliases (napi uses camelCase, wasm-bindgen uses snake_case)
+ * - Array type polyfills (browser has typed WASM arrays, napi accepts plain JS arrays)
+ */
+
+// ── Argument normalization ───────────────────────────────────────────
+
+/**
+ * Normalizes a single argument for napi compatibility.
+ *
+ * `BigInt` values are passed through untouched — napi-rs accepts JS `BigInt`
+ * for `u64` parameters (via `napi::bindgen_prelude::BigInt`), so no conversion
+ * is needed. Typed arrays of BigInts and bytes are converted to plain arrays.
+ */
+export function normalizeArg(val) {
+  if (val instanceof BigUint64Array) return Array.from(val);
+  if (val instanceof BigInt64Array) return Array.from(val);
+  if (val instanceof Uint8Array || Buffer.isBuffer(val)) return Array.from(val);
+  return val;
+}
+
+// ── Class wrapping ───────────────────────────────────────────────────
+
+/**
+ * Wraps a napi class so constructor and static method args are normalized.
+ */
+function wrapClass(Cls) {
+  if (!Cls) return Cls;
+  const Wrapper = function (...args) {
+    return new Cls(...args.map(normalizeArg));
+  };
+  Wrapper.prototype = Cls.prototype;
+  for (const key of Object.getOwnPropertyNames(Cls)) {
+    if (key === "prototype" || key === "length" || key === "name") continue;
+    const desc = Object.getOwnPropertyDescriptor(Cls, key);
+    if (desc && typeof desc.value === "function") {
+      Wrapper[key] = (...args) => desc.value.apply(Cls, args.map(normalizeArg));
+    } else if (desc) {
+      try {
+        Object.defineProperty(Wrapper, key, desc);
+      } catch {
+        /* skip non-configurable */
+      }
+    }
+  }
+  return Wrapper;
+}
+
+// ── Client wrapping ──────────────────────────────────────────────────
+
+/**
+ * Wraps a raw napi WebClient to normalize API differences with the browser SDK.
+ *
+ * - syncState() -> syncStateImpl() (no browser lock coordination needed)
+ * - syncStateWithTimeout() -> syncStateImpl() (timeout not applicable)
+ * - null -> undefined for Option<T> returns
+ * - BigInt/Uint8Array args normalized
+ */
+export function wrapClient(rawClient, storeName) {
+  return new Proxy(rawClient, {
+    get(target, prop) {
+      if (prop === "syncState") {
+        return (...args) => target.syncStateImpl(...args);
+      }
+      if (prop === "syncStateWithTimeout") {
+        return (_timeoutMs) => target.syncStateImpl();
+      }
+      if (prop === "storeName") {
+        return storeName || "default";
+      }
+      if (prop === "wasmWebClient") {
+        return target;
+      }
+      if (prop === "storeIdentifier") {
+        return () => target.storeIdentifier?.() ?? storeName ?? "unknown";
+      }
+      // terminate is a no-op on Node.js (no Web Worker to terminate)
+      if (prop === "terminate") {
+        return () => {};
+      }
+      // onStateChanged is browser-only (uses BroadcastChannel)
+      if (prop === "onStateChanged") {
+        return () => undefined;
+      }
+      // waitForIdle drains the browser SDK's detached `_serializeWasmCall`
+      // chain. The napi binding has no such chain — every call is awaited
+      // directly by its caller and serialized inside Rust — so there is
+      // nothing in flight by the time a caller could invoke this. Resolve
+      // immediately to keep the cross-platform MidenClient surface intact.
+      if (prop === "waitForIdle") {
+        return () => Promise.resolve();
+      }
+      // lastAuthError surfaces the raw value a JS sign callback threw.
+      // The Node binding signs with FilesystemKeyStore (no JS callback can
+      // ever run), so "no sign error" is the semantically correct answer,
+      // not a stub.
+      if (prop === "lastAuthError") {
+        return () => null;
+      }
+      if (prop === "newWallet") {
+        return (mode, mutable, authScheme, seed) => {
+          const normSeed =
+            seed instanceof Uint8Array || Buffer.isBuffer(seed)
+              ? Array.from(seed)
+              : seed;
+          return target
+            .newWallet(mode, mutable, authScheme, normSeed ?? null)
+            .then((v) => (v === null ? undefined : v));
+        };
+      }
+      const val = target[prop];
+      if (typeof val === "function") {
+        const bound = val.bind(target);
+        return (...args) => {
+          const result = bound(...args.map(normalizeArg));
+          if (result && typeof result.then === "function") {
+            return result.then((v) => (v === null ? undefined : v));
+          }
+          return result === null ? undefined : result;
+        };
+      }
+      return val;
+    },
+  });
+}
+
+// ── Prototype patching ───────────────────────────────────────────────
+
+/**
+ * Patches the raw SDK module:
+ * - Adds snake_case aliases for camelCase methods
+ * - Converts null -> undefined for Option<T> returns
+ * - Aliases static methods
+ */
+function patchSdkPrototypes(rawSdk) {
+  // snake_case aliases for instance methods
+  /* eslint-disable camelcase */
+  for (const [cls, aliases] of [
+    [rawSdk.Account, { to_commitment: "toCommitment" }],
+    [rawSdk.AccountHeader, { to_commitment: "toCommitment" }],
+  ]) {
+    if (!cls?.prototype) continue;
+    for (const [snake, camel] of Object.entries(aliases)) {
+      if (typeof cls.prototype[camel] === "function" && !cls.prototype[snake]) {
+        cls.prototype[snake] = cls.prototype[camel];
+      }
+    }
+  }
+  /* eslint-enable camelcase */
+
+  // null -> undefined for Option<T> return methods
+  for (const [cls, methods] of [
+    [rawSdk.AccountStorage, ["getItem", "getMapEntries", "getMapItem"]],
+    [rawSdk.NoteConsumability, ["consumableAfterBlock"]],
+  ]) {
+    if (!cls?.prototype) continue;
+    for (const method of methods) {
+      const original = cls.prototype[method];
+      if (typeof original === "function") {
+        cls.prototype[method] = function (...args) {
+          const result = original.apply(this, args);
+          return result === null ? undefined : result;
+        };
+      }
+    }
+  }
+
+  // snake_case aliases for static methods
+  if (rawSdk.NoteScript) {
+    if (!rawSdk.NoteScript.p2id && rawSdk.NoteScript.p2Id)
+      rawSdk.NoteScript.p2id = rawSdk.NoteScript.p2Id;
+    if (!rawSdk.NoteScript.p2ide && rawSdk.NoteScript.p2Ide)
+      rawSdk.NoteScript.p2ide = rawSdk.NoteScript.p2Ide;
+  }
+}
+
+// ── Array polyfills ──────────────────────────────────────────────────
+
+/**
+ * Creates polyfill constructors for WASM typed array types.
+ * napi accepts plain JS arrays directly, but the browser SDK requires
+ * typed wrappers (NoteAndArgsArray, FeltArray, etc.). These polyfills
+ * let `new sdk.FeltArray([a, b])` work on Node.js by returning a plain array.
+ */
+function makeArrayPolyfills() {
+  function polyfill(items) {
+    const arr =
+      items === undefined || items === null
+        ? []
+        : Array.isArray(items)
+          ? [...items]
+          : [items];
+    arr.get = (i) => arr[i];
+    arr.replaceAt = (i, val) => {
+      arr[i] = val;
+      return arr;
+    };
+    return arr;
+  }
+  const names = [
+    "AccountArray",
+    "AccountIdArray",
+    "FeltArray",
+    "ForeignAccountArray",
+    "NoteAndArgsArray",
+    "NoteArray",
+    "NoteDetailsAndTagArray",
+    "NoteIdAndArgsArray",
+    "NoteRecipientArray",
+    "OutputNoteArray",
+    "OutputNotesArray",
+    "StorageSlotArray",
+    "TransactionScriptInputPairArray",
+  ];
+  const result = {};
+  for (const name of names) {
+    result[name] = polyfill;
+  }
+  return result;
+}
+
+// ── SDK wrapper ──────────────────────────────────────────────────────
+
+/**
+ * Creates a wrapped SDK module suitable for use with the MidenClient wrapper.
+ * Applies all patches and returns an object that can be used as `getWasm()` return value.
+ */
+export function createSdkWrapper(rawSdk) {
+  patchSdkPrototypes(rawSdk);
+
+  return {
+    ...rawSdk,
+    // Wrap classes whose constructors/static methods accept BigInt or Uint8Array
+    AccountBuilder: wrapClass(rawSdk.AccountBuilder),
+    AccountComponent: wrapClass(rawSdk.AccountComponent),
+    AuthSecretKey: wrapClass(rawSdk.AuthSecretKey),
+    Felt: wrapClass(rawSdk.Felt),
+    FungibleAsset: wrapClass(rawSdk.FungibleAsset),
+    Word: wrapClass(rawSdk.Word),
+    NoteTag: wrapClass(rawSdk.NoteTag),
+    // Array type polyfills
+    ...makeArrayPolyfills(),
+  };
+}

package/js/node-index.js

@@ -0,0 +1,194 @@
+/**
+ * Node.js entry point for @miden-sdk/miden-sdk.
+ *
+ * Loaded automatically when Node.js resolves the package import
+ * (via the "node" condition in package.json exports).
+ *
+ * Provides the same API as the browser entry point (index.js),
+ * backed by a native napi addon with SQLite storage.
+ */
+
+import { loadNativeModule } from "./node/loader.js";
+import { createSdkWrapper } from "./node/napi-compat.js";
+import {
+  createWasmWebClient,
+  createMockWasmWebClient,
+} from "./node/client-factory.js";
+import { MidenClient } from "./client.js";
+import {
+  createP2IDNote,
+  createP2IDENote,
+  buildSwapTag,
+  _setWasm as _setStandaloneWasm,
+  _setWebClient as _setStandaloneWebClient,
+} from "./standalone.js";
+
+// ── Initialization ───────────────────────────────────────────────────
+
+let _initialized = false;
+let _rawSdk = null;
+let _wrappedSdk = null;
+let _WasmWebClient = null;
+let _MockWasmWebClient = null;
+
+function ensureInitialized() {
+  if (_initialized) return;
+
+  _rawSdk = loadNativeModule();
+  _wrappedSdk = createSdkWrapper(_rawSdk);
+  _WasmWebClient = createWasmWebClient(_rawSdk);
+  _MockWasmWebClient = createMockWasmWebClient(_rawSdk);
+
+  // Wire MidenClient statics
+  MidenClient._WasmWebClient = _WasmWebClient;
+  MidenClient._MockWasmWebClient = _MockWasmWebClient;
+  MidenClient._getWasmOrThrow = async () => _wrappedSdk;
+
+  // Wire standalone functions
+  _setStandaloneWasm(_wrappedSdk);
+  _setStandaloneWebClient(_WasmWebClient);
+
+  _initialized = true;
+}
+
+// Initialize on import
+ensureInitialized();
+
+// ── Enum constants (matching browser entry point) ────────────────────
+
+export const AccountType = Object.freeze({
+  MutableWallet: "MutableWallet",
+  ImmutableWallet: "ImmutableWallet",
+  FungibleFaucet: "FungibleFaucet",
+  ImmutableContract: "ImmutableContract",
+  MutableContract: "MutableContract",
+});
+
+export const AuthScheme = Object.freeze({
+  Falcon: "falcon",
+  ECDSA: "ecdsa",
+});
+
+export const NoteVisibility = Object.freeze({
+  Public: "public",
+  Private: "private",
+});
+
+export const StorageMode = Object.freeze({
+  Public: "public",
+  Private: "private",
+});
+
+// ── Re-exports ───────────────────────────────────────────────────────
+
+export { MidenClient };
+export { createP2IDNote, createP2IDENote, buildSwapTag };
+
+// Internal exports (matching browser entry point)
+export {
+  _WasmWebClient as WasmWebClient,
+  _MockWasmWebClient as MockWasmWebClient,
+  _MockWasmWebClient as MockWebClient,
+};
+
+// Re-export all napi SDK types (equivalent to browser's `export * from "../Cargo.toml"`).
+// Since we can't statically export dynamic napi bindings, we re-export common types explicitly
+// and provide getNativeModule()/getWrappedSdk() for anything else.
+
+export function getNativeModule() {
+  ensureInitialized();
+  return _rawSdk;
+}
+
+export function getWrappedSdk() {
+  ensureInitialized();
+  return _wrappedSdk;
+}
+
+// Re-export commonly used SDK types from the napi module.
+// Uses a lazy getter pattern so the module is loaded on first access.
+function _reexport(name) {
+  return {
+    get [name]() {
+      ensureInitialized();
+      return _wrappedSdk[name] ?? _rawSdk[name];
+    },
+  }[name];
+}
+
+// Account types
+export const Account = /* @__PURE__ */ _reexport("Account");
+export const AccountBuilder = /* @__PURE__ */ _reexport("AccountBuilder");
+export const AccountComponent = /* @__PURE__ */ _reexport("AccountComponent");
+export const AccountFile = /* @__PURE__ */ _reexport("AccountFile");
+export const AccountHeader = /* @__PURE__ */ _reexport("AccountHeader");
+export const AccountId = /* @__PURE__ */ _reexport("AccountId");
+export const AccountInterface = /* @__PURE__ */ _reexport("AccountInterface");
+export const AccountStorage = /* @__PURE__ */ _reexport("AccountStorage");
+export const AccountStorageMode =
+  /* @__PURE__ */ _reexport("AccountStorageMode");
+export const AccountStorageRequirements = /* @__PURE__ */ _reexport(
+  "AccountStorageRequirements"
+);
+export const Address = /* @__PURE__ */ _reexport("Address");
+
+// Auth types
+export const AuthSchemeNative = /* @__PURE__ */ _reexport("AuthScheme");
+export const AuthSecretKey = /* @__PURE__ */ _reexport("AuthSecretKey");
+
+// Crypto types
+export const Felt = /* @__PURE__ */ _reexport("Felt");
+export const Word = /* @__PURE__ */ _reexport("Word");
+export const Rpo = /* @__PURE__ */ _reexport("Rpo");
+export const Rpo256 = /* @__PURE__ */ _reexport("Rpo256");
+export const PublicKey = /* @__PURE__ */ _reexport("PublicKey");
+export const Signature = /* @__PURE__ */ _reexport("Signature");
+
+// Asset types
+export const FungibleAsset = /* @__PURE__ */ _reexport("FungibleAsset");
+
+// Note types
+export const Note = /* @__PURE__ */ _reexport("Note");
+export const NoteAssets = /* @__PURE__ */ _reexport("NoteAssets");
+export const NoteAttachment = /* @__PURE__ */ _reexport("NoteAttachment");
+export const NoteExportFormat = /* @__PURE__ */ _reexport("NoteExportFormat");
+export const NoteExecutionHint = /* @__PURE__ */ _reexport("NoteExecutionHint");
+export const NoteFile = /* @__PURE__ */ _reexport("NoteFile");
+export const NoteFilter = /* @__PURE__ */ _reexport("NoteFilter");
+export const NoteFilterTypes = /* @__PURE__ */ _reexport("NoteFilterTypes");
+export const NoteId = /* @__PURE__ */ _reexport("NoteId");
+export const NoteMetadata = /* @__PURE__ */ _reexport("NoteMetadata");
+export const NoteRecipient = /* @__PURE__ */ _reexport("NoteRecipient");
+export const NoteScript = /* @__PURE__ */ _reexport("NoteScript");
+export const NoteStorage = /* @__PURE__ */ _reexport("NoteStorage");
+export const NoteTag = /* @__PURE__ */ _reexport("NoteTag");
+export const NoteType = /* @__PURE__ */ _reexport("NoteType");
+export const OutputNote = /* @__PURE__ */ _reexport("OutputNote");
+
+// Transaction types
+export const TransactionFilter = /* @__PURE__ */ _reexport("TransactionFilter");
+export const TransactionProver = /* @__PURE__ */ _reexport("TransactionProver");
+export const TransactionRequestBuilder = /* @__PURE__ */ _reexport(
+  "TransactionRequestBuilder"
+);
+
+// Network types
+export const NetworkId = /* @__PURE__ */ _reexport("NetworkId");
+export const RpcClient = /* @__PURE__ */ _reexport("RpcClient");
+export const Endpoint = /* @__PURE__ */ _reexport("Endpoint");
+
+// Transaction result / sync types
+export const SyncSummary = /* @__PURE__ */ _reexport("SyncSummary");
+export const TransactionResult = /* @__PURE__ */ _reexport("TransactionResult");
+
+// Store import/export
+export const exportStore = /* @__PURE__ */ _reexport("exportStore");
+export const importStore = /* @__PURE__ */ _reexport("importStore");
+
+// Misc
+export const AdviceMap = /* @__PURE__ */ _reexport("AdviceMap");
+export const ForeignAccount = /* @__PURE__ */ _reexport("ForeignAccount");
+export const Package = /* @__PURE__*/ _reexport("Package");
+export const StorageMap = /* @__PURE__ */ _reexport("StorageMap");
+export const StorageSlot = /* @__PURE__ */ _reexport("StorageSlot");
+export const TokenSymbol = /* @__PURE__ */ _reexport("TokenSymbol");