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

package/dist/{index.js → st/index.js}

@@ -1,9 +1,10 @@
 import loadWasm from './wasm.js';
-export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkId, NetworkNoteStatusInfo, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapEntryJs, StorageMapInfo, StorageMapUpdate, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, setupLogging } from './Cargo-CVlXCH_2.js';
+export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountProof, AccountReader, AccountStatus, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthSecretKey, BasicFungibleFaucetComponent, BlockHeader, CodeBuilder, CommittedNote, ConsumableNoteRecord, Endpoint, ExecutedTransaction, Felt, FeltArray, FetchedAccount, FetchedNote, FlattenedU8Vec, ForeignAccount, ForeignAccountArray, FungibleAsset, FungibleAssetDelta, FungibleAssetDeltaItem, GetProceduresResultItem, InputNote, InputNoteRecord, InputNoteState, InputNotes, IntoUnderlyingByteSource, IntoUnderlyingSink, IntoUnderlyingSource, JsAccountUpdate, JsStateSyncUpdate, JsStorageMapEntry, JsStorageSlot, JsVaultAsset, Library, MerklePath, NetworkId, NetworkNoteStatusInfo, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteArray, NoteAssets, NoteAttachment, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteExportFormat, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteStorage, NoteSyncBlock, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, Package, PartialNote, Poseidon2, ProcedureThreshold, Program, ProvenTransaction, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageMapEntry, StorageMapEntryJs, StorageMapInfo, StorageMapUpdate, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, WebClient, WebKeystoreApi, Word, createAuthFalcon512RpoMultisig, exportStore, importStore, initSync, sequentialSumBench, setupLogging } from './Cargo-CG4XszZo.js';
 
 const WorkerAction = Object.freeze({
   INIT: "init",
   INIT_MOCK: "initMock",
+  INIT_THREAD_POOL: "initThreadPool",
   CALL_METHOD: "callMethod",
   EXECUTE_CALLBACK: "executeCallback",
 });
@@ -504,6 +505,7 @@ class AccountsResource {
       return await this.#inner.newFaucet(
         storageMode,
         type === 1 || type === "NonFungibleFaucet",
+        opts.name ?? opts.symbol,
         opts.symbol,
         opts.decimals,
         BigInt(opts.maxSupply),
@@ -536,11 +538,9 @@ 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);
@@ -555,7 +555,6 @@ class AccountsResource {
     }
 
     let builder = new wasm.AccountBuilder(opts.seed)
-      .accountType(accountTypeEnum)
       .storageMode(storageMode)
       .withAuthComponent(authComponent);
 
@@ -866,6 +865,72 @@ 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();
@@ -890,6 +955,27 @@ 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;
@@ -1176,6 +1262,53 @@ 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);
@@ -1565,6 +1698,80 @@ 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.
    *
@@ -1593,6 +1800,13 @@ 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(
@@ -1603,7 +1817,8 @@ class MidenClient {
         options.keystore.getKey,
         options.keystore.insertKey,
         options.keystore.sign,
-        options?.debugMode
+        options?.debugMode,
+        useWorker
       );
     } else {
       inner = await WebClientClass.createClient(
@@ -1611,7 +1826,8 @@ class MidenClient {
         noteTransportUrl,
         seed,
         options?.storeName,
-        options?.debugMode
+        options?.debugMode,
+        useWorker
       );
     }
 
@@ -1668,6 +1884,32 @@ 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.
    *
@@ -1724,6 +1966,61 @@ 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.
    */
@@ -2319,7 +2616,6 @@ const NoteVisibility = Object.freeze({
 const StorageMode = Object.freeze({
   Public: "public",
   Private: "private",
-  Network: "network",
 });
 
 const Linking = Object.freeze({
@@ -2513,6 +2809,15 @@ class WebClient {
    * @param {string | undefined} [logLevel] - Optional log verbosity level
    *   ("error", "warn", "info", "debug", "trace", "off", or "none").
    *   When set, Rust tracing output is routed to the browser console.
+   * @param {boolean} [useWorker=true] - When `false`, skip the Web Worker shim
+   *   and call the wasm-bindgen `WebClient` directly on the current thread.
+   *   The worker exists to keep the main thread responsive during WASM work
+   *   in browser/extension contexts, but it serializes the prover argument
+   *   via `TransactionProver.serialize()` — a format that has no encoding
+   *   for `newCallbackProver(jsFn)` and silently downgrades it to `"local"`.
+   *   Consumers that hand a `CallbackProver` (e.g. native iOS/Android plug-in
+   *   provers in Capacitor apps, or any other JS-side prover bridge) need
+   *   `useWorker: false` so the prover handle reaches the WASM binding intact.
    */
   constructor(
     rpcUrl,
@@ -2522,7 +2827,8 @@ class WebClient {
     getKeyCb,
     insertKeyCb,
     signCb,
-    logLevel
+    logLevel,
+    useWorker = true
   ) {
     this.rpcUrl = rpcUrl;
     this.noteTransportUrl = noteTransportUrl;
@@ -2532,9 +2838,12 @@ class WebClient {
     this.insertKeyCb = insertKeyCb;
     this.signCb = signCb;
     this.logLevel = logLevel;
+    this.useWorker = useWorker !== false;
 
-    // Check if Web Workers are available.
-    if (typeof Worker !== "undefined") {
+    // Check if Web Workers are available AND the caller didn't opt out via
+    // `useWorker: false`. The opt-out is load-bearing for `CallbackProver`
+    // consumers — see the constructor doc above.
+    if (this.useWorker && typeof Worker !== "undefined") {
       console.log("WebClient: Web Workers are available.");
       // Pick between the module and classic worker variants at runtime — see
       // `WebClient.workerMode` below. Both branches keep the
@@ -2648,8 +2957,12 @@ class WebClient {
       // Once the worker script has loaded, initialize the worker.
       this.loaded.then(() => this.initializeWorker());
     } else {
-      console.log("WebClient: Web Workers are not available.");
-      // Worker not available; set up fallback values.
+      console.log(
+        this.useWorker
+          ? "WebClient: Web Workers are not available."
+          : "WebClient: Web Worker shim disabled by caller (useWorker=false)."
+      );
+      // Worker not available or explicitly disabled; set up fallback values.
       this.worker = null;
       this.pendingRequests = null;
       this.loaded = Promise.resolve();
@@ -2665,25 +2978,99 @@ class WebClient {
     // would panic with "recursive use of an object detected" due to
     // wasm-bindgen's internal RefCell.
     this._wasmCallChain = Promise.resolve();
+    // Depth counter for `_withInnerWebClient` re-entrancy. While > 0,
+    // `_serializeWasmCall` runs its callback inline instead of queueing
+    // it on the chain — see the comment on `_serializeWasmCall` for the
+    // safety contract.
+    this._withInnerLockDepth = 0;
   }
 
   /**
    * Serialize a WASM call that requires exclusive (&mut self) access.
    * Concurrent calls are queued and executed one at a time.
    *
+   * Wraps both the direct (in-thread) path and the worker-dispatched path.
+   * On the worker path this is redundant with the worker's own message queue,
+   * but harmless (the chain resolves immediately on the main thread once the
+   * worker's postMessage returns). On the direct path it is load-bearing —
+   * without it, concurrent main-thread callers would panic with
+   * "recursive use of an object detected" (wasm-bindgen's internal RefCell).
+   *
+   * Re-entrancy: when invoked from inside a `_withInnerWebClient(fn)`
+   * callback — detected via `_withInnerLockDepth > 0` — `fn` runs inline
+   * (no chain enqueue). The outer `_withInnerWebClient` invocation
+   * already holds the chain via its own wrapping `_serializeWasmCall`,
+   * so enqueueing the inner call would deadlock (the inner queues
+   * behind the outer; the outer awaits the inner). The inline run is
+   * safe because the chain still serializes against external callers
+   * — they queue behind the outer call's chain slot, which only resolves
+   * after `fn` (including all inline re-entries) settles. Callers of
+   * `_withInnerWebClient` MUST hold an external mutex preventing
+   * concurrent access via other code paths on this same instance during
+   * the callback; without that, an external task running between two
+   * awaits inside `fn` would race wasm-bindgen's borrow check.
+   *
    * @param {() => Promise<any>} fn - The async function to execute.
    * @returns {Promise<any>} The result of fn.
    */
   _serializeWasmCall(fn) {
+    if (this._withInnerLockDepth > 0) {
+      return Promise.resolve().then(fn);
+    }
     const result = this._wasmCallChain.catch(() => {}).then(fn);
     this._wasmCallChain = result.catch(() => {});
     return result;
   }
 
+  /**
+   * Returns a promise that resolves once every serialized WASM call that
+   * was already on `_wasmCallChain` when `waitForIdle()` was called has
+   * settled. Use this from callers that need to perform a non-WASM-side
+   * action (e.g. clear an in-memory auth key) AFTER any in-flight
+   * execute / submit / sync has completed, so the WASM kernel's auth
+   * callback doesn't race with the key being cleared.
+   *
+   * Does NOT wait for calls enqueued after `waitForIdle()` returns —
+   * this is intentional, so a caller can drain and then proceed without
+   * being blocked indefinitely by a concurrent workload.
+   *
+   * Caveat for `syncState`: `syncStateWithTimeout` awaits
+   * `acquireSyncLock` (Web Locks) BEFORE wrapping its WASM call in
+   * `_serializeWasmCall`, so a sync that is queued on the sync lock but
+   * has not yet reached its WASM phase is not on the chain and will not
+   * be awaited. Every other serialized method (`executeTransaction`,
+   * `newWallet`, `submitNewTransaction`, `proveTransaction`,
+   * `applyTransaction`, and the proxy-fallback reads) routes through
+   * the chain synchronously on call and is always observed.
+   *
+   * @returns {Promise<void>}
+   */
+  async waitForIdle() {
+    // Chain on `_wasmCallChain`; by the time this resolves, any in-flight
+    // serialized call has settled. Catch so the chain state doesn't leak.
+    await this._wasmCallChain.catch(() => {});
+  }
+
   // TODO: This will soon conflict with some changes in main.
   // More context here:
   // https://github.com/0xMiden/miden-client/pull/1645?notification_referrer_id=NT_kwHOA1yg7NoAJVJlcG9zaXRvcnk7NjU5MzQzNzAyO0lzc3VlOzM3OTY4OTU1Nzk&notifications_query=is%3Aunread#discussion_r2696075480
   initializeWorker() {
+    // Pass `numThreads` to the worker so it can call `wasm.initThreadPool(n)`
+    // inside its OWN WASM instance — the SDK worker's instance is separate
+    // from the main thread's, and rayon's global pool is per-instance.
+    // Default: navigator.hardwareConcurrency (or 1 if unavailable for any
+    // reason — e.g. the page isn't crossOriginIsolated, in which case the
+    // worker will skip pool init and parallelism falls back to sequential).
+    let numThreads = 1;
+    try {
+      if (
+        typeof self !== "undefined" &&
+        self.crossOriginIsolated &&
+        navigator?.hardwareConcurrency
+      ) {
+        numThreads = navigator.hardwareConcurrency;
+      }
+    } catch {}
     this.worker.postMessage({
       action: WorkerAction.INIT,
       args: [
@@ -2695,6 +3082,7 @@ class WebClient {
         !!this.insertKeyCb,
         !!this.signCb,
         this.logLevel,
+        numThreads,
       ],
     });
   }
@@ -2723,9 +3111,19 @@ class WebClient {
    * @param {string} seed - The seed for the account.
    * @param {string | undefined} network - Optional name for the store. Setting this allows multiple clients to be used in the same browser.
    * @param {string | undefined} logLevel - Optional log verbosity level ("error", "warn", "info", "debug", "trace", "off", or "none").
+   * @param {boolean} [useWorker=true] - When `false`, bypass the Web Worker shim
+   *   and run WASM calls on the current thread. Required for `CallbackProver`
+   *   consumers (the worker path serializes the prover and loses the callback).
    * @returns {Promise<WebClient>} The fully initialized WebClient.
    */
-  static async createClient(rpcUrl, noteTransportUrl, seed, network, logLevel) {
+  static async createClient(
+    rpcUrl,
+    noteTransportUrl,
+    seed,
+    network,
+    logLevel,
+    useWorker = true
+  ) {
     // Construct the instance (synchronously).
     const instance = new WebClient(
       rpcUrl,
@@ -2735,7 +3133,8 @@ class WebClient {
       undefined,
       undefined,
       undefined,
-      logLevel
+      logLevel,
+      useWorker
     );
 
     // Set up logging on the main thread before creating the client.
@@ -2766,6 +3165,9 @@ class WebClient {
    * @param {Function | undefined} insertKeyCb - The insert key callback.
    * @param {Function | undefined} signCb - The sign callback.
    * @param {string | undefined} logLevel - Optional log verbosity level ("error", "warn", "info", "debug", "trace", "off", or "none").
+   * @param {boolean} [useWorker=true] - When `false`, bypass the Web Worker shim
+   *   and run WASM calls on the current thread. Required for `CallbackProver`
+   *   consumers (the worker path serializes the prover and loses the callback).
    * @returns {Promise<WebClient>} The fully initialized WebClient.
    */
   static async createClientWithExternalKeystore(
@@ -2776,7 +3178,8 @@ class WebClient {
     getKeyCb,
     insertKeyCb,
     signCb,
-    logLevel
+    logLevel,
+    useWorker = true
   ) {
     // Construct the instance (synchronously).
     const instance = new WebClient(
@@ -2787,7 +3190,8 @@ class WebClient {
       getKeyCb,
       insertKeyCb,
       signCb,
-      logLevel
+      logLevel,
+      useWorker
     );
 
     // Set up logging on the main thread before creating the client.
@@ -2852,6 +3256,7 @@ class WebClient {
   async newFaucet(
     storageMode,
     nonFungible,
+    tokenName,
     tokenSymbol,
     decimals,
     maxSupply,
@@ -2862,6 +3267,7 @@ class WebClient {
       return await wasmWebClient.newFaucet(
         storageMode,
         nonFungible,
+        tokenName,
         tokenSymbol,
         decimals,
         maxSupply,