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

package/js/client.js

@@ -39,6 +39,80 @@ export class MidenClient {
     this.keystore = new KeystoreResource(inner, this);
   }
 
+  /**
+   * Escape hatch: runs `fn` with exclusive access to the proxied JS
+   * WebClient that backs this MidenClient.
+   *
+   * The proxy forwards missing properties to the underlying wasm-bindgen
+   * `WebClient`, so `fn` can reach lower-level methods like
+   * `executeTransaction`, `proveTransaction[WithProver]`,
+   * `submitProvenTransaction`, `applyTransaction`,
+   * `newSendTransactionRequest`, `newConsumeTransactionRequest`, etc.
+   *
+   * Intended for advanced consumers that need to split the bundled
+   * execute → prove → submit → apply pipeline across contexts — for example,
+   * a Chrome MV3 extension that runs `executeTransaction` in its service
+   * worker, dispatches the prove step to a `chrome.offscreen` document
+   * (where wasm-bindgen-rayon can spawn a real thread pool), then runs
+   * `submitProvenTransaction` + `applyTransaction` back in the SW.
+   *
+   * The callback runs inside `_serializeWasmCall`, so the WASM RefCell is
+   * held for the duration of `fn`. Concurrent SDK calls (sync, other
+   * transactions, etc.) queue on the same chain and run after `fn`
+   * settles. Without this serialization, raw inner-client access would
+   * race the proxy's chain and trip wasm-bindgen's "recursive use of an
+   * object detected" panic.
+   *
+   * Re-entrancy: while `fn` is running, the underlying client's
+   * `_withInnerLockDepth` counter is bumped so that `_serializeWasmCall`
+   * invocations made BY `fn` (or any proxy-dispatched method it calls)
+   * run inline rather than enqueuing on the chain. Without this, every
+   * `await inner.X(...)` inside `fn` would enqueue behind the outer
+   * `_withInnerWebClient` slot which is itself awaiting `fn` —
+   * a classic re-entrant-lock deadlock. The depth counter restores the
+   * intent of the docstring above: the lock is held for the duration
+   * of `fn`, and inner-client calls "borrow" that already-held lock
+   * instead of trying to re-acquire it.
+   *
+   * SAFETY CONTRACT for re-entrancy: callers MUST hold an external
+   * mutex preventing concurrent access to this same client instance
+   * via other code paths during `fn`. The chain still serializes
+   * against external callers — they queue behind the outer slot — but
+   * if an external task runs during one of `fn`'s awaits and calls
+   * into the SDK, it will see `_withInnerLockDepth > 0` and run
+   * inline, racing wasm-bindgen's borrow check. The wallet pattern
+   * (own outer mutex around `_withInnerWebClient`) satisfies this.
+   *
+   * Stability: marked `@internal`. The shape of the proxied client is
+   * intentionally not part of the documented public API and may change
+   * between SDK versions. If you depend on this method, pin the SDK
+   * version and test the lower-level surface carefully on each upgrade.
+   * If your use case is common enough to warrant a stable public API,
+   * file an issue.
+   *
+   * @internal
+   * @template T
+   * @param {(inner: object) => Promise<T>} fn - Async callback receiving
+   *   the proxied JS WebClient. Must not return references that escape
+   *   the callback's lifetime (the lock is released on settle).
+   * @returns {Promise<T>} The resolved value of `fn`.
+   */
+  _withInnerWebClient(fn) {
+    this.assertNotTerminated();
+    if (typeof fn !== "function") {
+      throw new TypeError("_withInnerWebClient: fn must be a function");
+    }
+    const inner = this.#inner;
+    return inner._serializeWasmCall(async () => {
+      inner._withInnerLockDepth = (inner._withInnerLockDepth || 0) + 1;
+      try {
+        return await fn(inner);
+      } finally {
+        inner._withInnerLockDepth--;
+      }
+    });
+  }
+
   /**
    * Creates and initializes a new MidenClient.
    *
@@ -67,6 +141,13 @@ export class MidenClient {
     const rpcUrl = resolveRpcUrl(options?.rpcUrl);
     const noteTransportUrl = resolveNoteTransportUrl(options?.noteTransportUrl);
 
+    // `useWorker: false` opts out of the Web Worker shim that wraps every
+    // WASM call. The shim exists to keep the main thread responsive in
+    // browser/extension contexts, but it serializes the prover via
+    // `TransactionProver.serialize()` — a format that has no encoding for
+    // `newCallbackProver(jsFn)` and silently downgrades it to `"local"`.
+    // Mobile/Tauri/native-prover consumers must pass `useWorker: false`.
+    const useWorker = options?.useWorker;
     let inner;
     if (options?.keystore) {
       inner = await WebClientClass.createClientWithExternalKeystore(
@@ -77,7 +158,8 @@ export class MidenClient {
         options.keystore.getKey,
         options.keystore.insertKey,
         options.keystore.sign,
-        options?.debugMode
+        options?.debugMode,
+        useWorker
       );
     } else {
       inner = await WebClientClass.createClient(
@@ -85,7 +167,8 @@ export class MidenClient {
         noteTransportUrl,
         seed,
         options?.storeName,
-        options?.debugMode
+        options?.debugMode,
+        useWorker
       );
     }
 
@@ -142,6 +225,32 @@ export class MidenClient {
     });
   }
 
+  /**
+   * Resolves once the WASM module is initialized and safe to use.
+   *
+   * Idempotent and shared across callers: the underlying loader memoizes the
+   * in-flight promise, so concurrent `ready()` calls await the same
+   * initialization and post-init callers resolve immediately from a cached
+   * module. Safe to call from `MidenProvider`, tutorial helpers, and any
+   * other consumer simultaneously.
+   *
+   * Useful on the `/lazy` entry (e.g. Next.js / Capacitor), where no
+   * top-level await runs at import time. On the default (eager) entry this
+   * is redundant — importing the module already awaits WASM — but calling it
+   * is still harmless.
+   *
+   * @returns {Promise<void>} Resolves when WASM is initialized.
+   */
+  static async ready() {
+    const getWasm = MidenClient._getWasmOrThrow;
+    if (!getWasm) {
+      throw new Error(
+        "MidenClient not initialized. Import from the SDK package entry point."
+      );
+    }
+    await getWasm();
+  }
+
   /**
    * Creates a mock client for testing.
    *
@@ -198,6 +307,61 @@ export class MidenClient {
     return await this.#inner.getSyncHeight();
   }
 
+  /**
+   * Resolves once every serialized WASM call that was already on the
+   * internal `_serializeWasmCall` chain when `waitForIdle()` was called
+   * (execute, submit, prove, apply, sync, or account creation) has
+   * settled. Use this from callers that need to perform a non-WASM-side
+   * action — e.g. clearing an in-memory auth key on wallet lock — after
+   * the kernel finishes, so its auth callback doesn't race with the key
+   * being cleared.
+   *
+   * Does NOT wait for calls enqueued after `waitForIdle()` returns —
+   * intentional, so a caller can drain and proceed without being blocked
+   * indefinitely by concurrent workload.
+   *
+   * Caveat for `syncState`: `syncStateWithTimeout` awaits the sync lock
+   * (`acquireSyncLock`, which uses Web Locks) BEFORE putting its WASM
+   * call onto the chain, so a `syncState` that is queued on the sync
+   * lock — but has not yet begun its WASM phase — is not visible to
+   * `waitForIdle` and will not be awaited. Other methods (`newWallet`,
+   * `executeTransaction`, etc.) route through the chain synchronously
+   * on call and are always observed.
+   *
+   * Safe to call at any time; returns immediately if nothing was in
+   * flight.
+   *
+   * @returns {Promise<void>}
+   */
+  async waitForIdle() {
+    this.assertNotTerminated();
+    await this.#inner.waitForIdle();
+  }
+
+  /**
+   * Returns the raw JS value that the most recent sign-callback invocation
+   * threw, or `null` if the last sign call succeeded (or no call has
+   * happened yet).
+   *
+   * Useful for recovering structured metadata (e.g. a `reason: 'locked'`
+   * property) that the kernel-level `auth::request` diagnostic would
+   * otherwise erase. Call immediately after catching a failed
+   * `transactions.submit` / `transactions.send` / `transactions.consume`.
+   *
+   * Meaningful only with `useWorker: false`: under the worker shim the
+   * sign callback fires against the worker's WASM keystore, while this
+   * accessor reads the main-thread instance — which never signed — so it
+   * returns `null`. Consumers that need this signal (e.g. external
+   * keystores with lock-aware sign callbacks) already require
+   * `useWorker: false` for the callback to be reachable at all.
+   *
+   * @returns {any} The raw thrown value, or `null`.
+   */
+  lastAuthError() {
+    this.assertNotTerminated();
+    return this.#inner.lastAuthError();
+  }
+
   /**
    * Terminates the underlying Web Worker. After this, all method calls will throw.
    */

package/js/node/napi-compat.js

@@ -91,6 +91,21 @@ export function wrapClient(rawClient, storeName) {
       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 =

package/js/node-index.js

@@ -77,7 +77,6 @@ export const NoteVisibility = Object.freeze({
 export const StorageMode = Object.freeze({
   Public: "public",
   Private: "private",
-  Network: "network",
 });
 
 // ── Re-exports ───────────────────────────────────────────────────────

package/js/resources/accounts.js

@@ -34,6 +34,7 @@ export class AccountsResource {
       return await this.#inner.newFaucet(
         storageMode,
         type === 1 || type === "NonFungibleFaucet",
+        opts.name ?? opts.symbol,
         opts.symbol,
         opts.decimals,
         BigInt(opts.maxSupply),
@@ -66,11 +67,9 @@ export class AccountsResource {
     if (!opts.auth)
       throw new Error("Contract creation requires an 'auth' (AuthSecretKey)");
 
-    // Default to immutable when type is omitted (safer for contracts)
-    const mutable = opts.type === "MutableContract" || opts.type === 3;
-    const accountTypeEnum = mutable
-      ? wasm.AccountType.RegularAccountUpdatableCode
-      : wasm.AccountType.RegularAccountImmutableCode;
+    // The 0.15 protocol has no code-mutability distinction, so the `type`
+    // ("ImmutableContract" / "MutableContract") only steers routing here; the
+    // account's on-chain visibility is set entirely by `storageMode`.
     const storageMode = resolveStorageMode(opts.storage ?? "public", wasm);
     const authComponent =
       wasm.AccountComponent.createAuthComponentFromSecretKey(opts.auth);
@@ -85,7 +84,6 @@ export class AccountsResource {
     }
 
     let builder = new wasm.AccountBuilder(opts.seed)
-      .accountType(accountTypeEnum)
       .storageMode(storageMode)
       .withAuthComponent(authComponent);
 

package/js/resources/transactions.js

@@ -177,6 +177,72 @@ export class TransactionsResource {
     return { txId, result };
   }
 
+  /** Create a partial-swap (PSWAP) note. See {@link PswapCreateOptions}. */
+  async pswapCreate(opts) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const { accountId, request } = await this.#buildPswapCreateRequest(
+      opts,
+      wasm
+    );
+
+    const { txId, result } = await this.#submitOrSubmitWithProver(
+      accountId,
+      request,
+      opts.prover
+    );
+
+    if (opts.waitForConfirmation) {
+      await this.waitFor(txId.toHex(), { timeout: opts.timeout });
+    }
+
+    return { txId, result };
+  }
+
+  /** Consume (fully or partially fill) a PSWAP note. See {@link PswapConsumeOptions}. */
+  async pswapConsume(opts) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const { accountId, request } = await this.#buildPswapConsumeRequest(
+      opts,
+      wasm
+    );
+
+    const { txId, result } = await this.#submitOrSubmitWithProver(
+      accountId,
+      request,
+      opts.prover
+    );
+
+    if (opts.waitForConfirmation) {
+      await this.waitFor(txId.toHex(), { timeout: opts.timeout });
+    }
+
+    return { txId, result };
+  }
+
+  /** Cancel a PSWAP note as its creator and reclaim the offered asset. See {@link PswapCancelOptions}. */
+  async pswapCancel(opts) {
+    this.#client.assertNotTerminated();
+    const wasm = await this.#getWasm();
+    const { accountId, request } = await this.#buildPswapCancelRequest(
+      opts,
+      wasm
+    );
+
+    const { txId, result } = await this.#submitOrSubmitWithProver(
+      accountId,
+      request,
+      opts.prover
+    );
+
+    if (opts.waitForConfirmation) {
+      await this.waitFor(txId.toHex(), { timeout: opts.timeout });
+    }
+
+    return { txId, result };
+  }
+
   async preview(opts) {
     this.#client.assertNotTerminated();
     const wasm = await this.#getWasm();
@@ -201,6 +267,27 @@ export class TransactionsResource {
         ({ accountId, request } = await this.#buildSwapRequest(opts, wasm));
         break;
       }
+      case "pswapCreate": {
+        ({ accountId, request } = await this.#buildPswapCreateRequest(
+          opts,
+          wasm
+        ));
+        break;
+      }
+      case "pswapConsume": {
+        ({ accountId, request } = await this.#buildPswapConsumeRequest(
+          opts,
+          wasm
+        ));
+        break;
+      }
+      case "pswapCancel": {
+        ({ accountId, request } = await this.#buildPswapCancelRequest(
+          opts,
+          wasm
+        ));
+        break;
+      }
       case "custom": {
         accountId = resolveAccountRef(opts.account, wasm);
         request = opts.request;
@@ -487,6 +574,53 @@ export class TransactionsResource {
     return { accountId, request };
   }
 
+  async #buildPswapCreateRequest(opts, wasm) {
+    const accountId = resolveAccountRef(opts.account, wasm);
+    const offeredFaucetId = resolveAccountRef(opts.offer.token, wasm);
+    const requestedFaucetId = resolveAccountRef(opts.request.token, wasm);
+    const noteType = resolveNoteType(opts.type, wasm);
+    const paybackNoteType = resolveNoteType(
+      opts.paybackType ?? opts.type,
+      wasm
+    );
+
+    const request = await this.#inner.newPswapCreateTransactionRequest(
+      accountId,
+      offeredFaucetId,
+      BigInt(opts.offer.amount),
+      requestedFaucetId,
+      BigInt(opts.request.amount),
+      noteType,
+      paybackNoteType
+    );
+    return { accountId, request };
+  }
+
+  async #buildPswapConsumeRequest(opts, wasm) {
+    const accountId = resolveAccountRef(opts.account, wasm);
+    const note = await this.#resolveNoteInput(opts.note);
+    const noteFillAmount = opts.noteFillAmount ?? 0n;
+
+    const request = await this.#inner.newPswapConsumeTransactionRequest(
+      note,
+      accountId,
+      BigInt(opts.fillAmount),
+      BigInt(noteFillAmount)
+    );
+    return { accountId, request };
+  }
+
+  async #buildPswapCancelRequest(opts, wasm) {
+    const accountId = resolveAccountRef(opts.account, wasm);
+    const note = await this.#resolveNoteInput(opts.note);
+
+    const request = await this.#inner.newPswapCancelTransactionRequest(
+      note,
+      accountId
+    );
+    return { accountId, request };
+  }
+
   async #resolveNoteInput(input) {
     if (typeof input === "string") {
       const record = await this.#inner.getInputNote(input);

package/lazy/package.json

@@ -1,4 +1,4 @@
 {
-  "main": "../dist/index.js",
-  "types": "../dist/index.d.ts"
+  "main": "../dist/st/index.js",
+  "types": "../dist/st/index.d.ts"
 }

package/mt/lazy/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../../dist/mt/index.js",
+  "types": "../../dist/mt/index.d.ts"
+}

package/mt/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../dist/mt/eager.js",
+  "types": "../dist/mt/index.d.ts"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miden-sdk/miden-sdk",
-  "version": "0.15.0-alpha.4",
+  "version": "0.15.0-alpha.5",
   "description": "Miden Wasm SDK",
   "license": "MIT",
   "repository": {
@@ -15,24 +15,36 @@
     "Miden"
   ],
   "type": "module",
-  "main": "./dist/eager.js",
-  "browser": "./dist/eager.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/st/eager.js",
+  "browser": "./dist/st/eager.js",
+  "types": "./dist/st/index.d.ts",
   "exports": {
     ".": {
       "node": {
-        "types": "./dist/index.d.ts",
+        "types": "./dist/st/index.d.ts",
         "default": "./js/node-index.js"
       },
       "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/eager.js"
+        "types": "./dist/st/index.d.ts",
+        "default": "./dist/st/eager.js"
       }
     },
     "./lazy": {
       "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
+        "types": "./dist/st/index.d.ts",
+        "default": "./dist/st/index.js"
+      }
+    },
+    "./mt": {
+      "import": {
+        "types": "./dist/mt/index.d.ts",
+        "default": "./dist/mt/eager.js"
+      }
+    },
+    "./mt/lazy": {
+      "import": {
+        "types": "./dist/mt/index.d.ts",
+        "default": "./dist/mt/index.js"
       }
     },
     "./package.json": "./package.json"
@@ -40,6 +52,7 @@
   "files": [
     "dist",
     "lazy",
+    "mt",
     "js/node-index.js",
     "js/node",
     "js/client.js",
@@ -56,7 +69,6 @@
     "@vitest/coverage-v8": "^3.0.0",
     "@wasm-tool/rollup-plugin-rust": "^3.0.3",
     "binaryen": "^129.0.0",
-    "cpr": "^3.0.1",
     "cross-env": "^7.0.3",
     "rimraf": "^6.0.1",
     "rollup": "^4.59.0",
@@ -71,14 +83,17 @@
     "glob": "^11.0.0"
   },
   "optionalDependencies": {
-    "@miden-sdk/node-darwin-arm64": "0.15.0-alpha.4",
-    "@miden-sdk/node-darwin-x64": "0.15.0-alpha.4",
-    "@miden-sdk/node-linux-x64-gnu": "0.15.0-alpha.4"
+    "@miden-sdk/node-darwin-arm64": "0.15.0-alpha.5",
+    "@miden-sdk/node-darwin-x64": "0.15.0-alpha.5",
+    "@miden-sdk/node-linux-x64-gnu": "0.15.0-alpha.5"
   },
   "scripts": {
     "build-rust-client-js": "pnpm --filter web_store run build",
-    "build": "rimraf dist && pnpm run build-rust-client-js && cross-env RUSTFLAGS=\"--cfg getrandom_backend=\\\"wasm_js\\\"\" rollup -c rollup.config.js && cpr js/types dist && node clean.js && node ./scripts/post-build.js",
-    "build-dev": "pnpm install && MIDEN_WEB_DEV=true pnpm run build",
+    "build": "rimraf dist && pnpm run build-rust-client-js && pnpm run build-st && pnpm run build-mt && pnpm run build-types && node ./scripts/post-build.js",
+    "build-st": "cross-env MIDEN_BUILD_VARIANT=st rollup -c rollup.config.js",
+    "build-mt": "cross-env MIDEN_BUILD_VARIANT=mt rollup -c rollup.config.js",
+    "build-types": "node ./scripts/build-types.js",
+    "build-dev": "pnpm install && cross-env MIDEN_WEB_DEV=true pnpm run build",
     "check:wasm-types": "node ./scripts/check-bindgen-types.js",
     "check:method-classification": "node ./scripts/check-method-classification.js",
     "check:standalone-types": "node ./scripts/check-standalone-types.js",