@miden-sdk/miden-sdk 0.13.2 → 0.13.3

package/dist/index.js

@@ -1,5 +1,5 @@
 import loadWasm from './wasm.js';
-export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountType, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthScheme, 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, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteAssets, NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteInputs, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, OutputNotesArray, Package, PartialNote, ProcedureThreshold, Program, ProvenTransaction, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, Word, createAuthFalcon512RpoMultisig, initSync, setupLogging } from './Cargo-e77f9a02.js';
+export { Account, AccountArray, AccountBuilder, AccountBuilderResult, AccountCode, AccountComponent, AccountComponentCode, AccountDelta, AccountFile, AccountHeader, AccountId, AccountIdArray, AccountInterface, AccountStorage, AccountStorageDelta, AccountStorageMode, AccountStorageRequirements, AccountType, AccountVaultDelta, Address, AdviceInputs, AdviceMap, AssetVault, AuthFalcon512RpoMultisigConfig, AuthScheme, 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, NetworkType, Note, NoteAndArgs, NoteAndArgsArray, NoteAssets, NoteAttachment, NoteAttachmentKind, NoteAttachmentScheme, NoteConsumability, NoteConsumptionStatus, NoteDetails, NoteDetailsAndTag, NoteDetailsAndTagArray, NoteExecutionHint, NoteFile, NoteFilter, NoteFilterTypes, NoteHeader, NoteId, NoteIdAndArgs, NoteIdAndArgsArray, NoteInclusionProof, NoteInputs, NoteLocation, NoteMetadata, NoteRecipient, NoteRecipientArray, NoteScript, NoteSyncInfo, NoteTag, NoteType, OutputNote, OutputNoteArray, OutputNoteRecord, OutputNoteState, OutputNotes, OutputNotesArray, Package, PartialNote, ProcedureThreshold, Program, ProvenTransaction, PublicKey, RpcClient, Rpo256, SerializedInputNoteData, SerializedOutputNoteData, SerializedTransactionData, Signature, SigningInputs, SigningInputsType, SlotAndKeys, SparseMerklePath, StorageMap, StorageSlot, StorageSlotArray, SyncSummary, TestUtils, TokenSymbol, TransactionArgs, TransactionFilter, TransactionId, TransactionProver, TransactionRecord, TransactionRequest, TransactionRequestBuilder, TransactionResult, TransactionScript, TransactionScriptInputPair, TransactionScriptInputPairArray, TransactionStatus, TransactionStoreUpdate, TransactionSummary, Word, createAuthFalcon512RpoMultisig, initSync, setupLogging } from './Cargo-0ed69232.js';
 
 const WorkerAction = Object.freeze({
   INIT: "init",
@@ -239,6 +239,242 @@ function releaseSyncLockWithError(dbId, error) {
   }
 }
 
+/**
+ * A simple promise-chain mutex for serializing async operations.
+ *
+ * Ignores errors: if one operation throws, the next still runs (no deadlocks).
+ */
+class AsyncLock {
+  constructor() {
+    this._pending = Promise.resolve();
+  }
+
+  /**
+   * Queue `fn` so that it runs only after all previously queued operations
+   * have settled (resolved or rejected).
+   *
+   * @template T
+   * @param {() => Promise<T>} fn
+   * @returns {Promise<T>}
+   */
+  runExclusive(fn) {
+    const run = this._pending.then(
+      () => fn(),
+      () => fn()
+    );
+    // Swallow the result/error so the chain itself never rejects
+    this._pending = run.then(
+      () => undefined,
+      () => undefined
+    );
+    return run;
+  }
+}
+
+/**
+ * Cross-Tab Write Lock Module
+ *
+ * Provides an exclusive write lock using the Web Locks API so that mutating
+ * operations on the same IndexedDB database are serialized across browser tabs.
+ *
+ * When the Web Locks API is unavailable the lock is a no-op — the in-process
+ * AsyncLock still protects against concurrent WASM access within a single tab.
+ */
+
+
+/**
+ * Execute `fn` while holding an exclusive cross-tab write lock for the given
+ * store.  If the Web Locks API is not available, `fn` runs immediately.
+ *
+ * @param {string} storeName - Logical database / store name.
+ * @param {() => Promise<T>} fn - The async work to perform under the lock.
+ * @param {number} [timeoutMs=0] - Optional timeout in milliseconds for
+ *   acquiring the lock. 0 (default) means wait indefinitely. When the timeout
+ *   fires the lock request is aborted and the returned promise rejects with an
+ *   `AbortError`. Has no effect when the Web Locks API is unavailable.
+ * @returns {Promise<T>}
+ * @template T
+ */
+async function withWriteLock(storeName, fn, timeoutMs = 0) {
+  if (!hasWebLocks()) {
+    return fn();
+  }
+
+  const lockName = `miden-db-${storeName || "default"}`;
+
+  if (timeoutMs > 0) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      return await navigator.locks.request(
+        lockName,
+        { mode: "exclusive", signal: controller.signal },
+        async () => {
+          clearTimeout(timeoutId);
+          return fn();
+        }
+      );
+    } catch (err) {
+      clearTimeout(timeoutId);
+      throw err;
+    }
+  }
+
+  return navigator.locks.request(lockName, { mode: "exclusive" }, async () => {
+    return fn();
+  });
+}
+
+// WASM PROXY METHODS
+// ================================================================================================
+
+/**
+ * Set of method names that are synchronous (non-async) on the WASM object
+ * and should NOT be wrapped with the async WASM lock. Wrapping them would
+ * turn their return type from T into Promise<T>, breaking callers that
+ * expect a synchronous return value.
+ *
+ * These methods may still mutate internal client state (e.g. RNG), but they
+ * complete in a single synchronous call without yielding to the event loop.
+ * JavaScript's single-threaded execution guarantees they cannot interleave
+ * with an in-progress async WASM call.
+ *
+ * When updating this set, check the Rust source for any `pub fn` (non-async)
+ * method on `impl WebClient` with #[wasm_bindgen] that is NOT already handled
+ * by an explicit wrapper method on the JS WebClient class.
+ */
+const SYNC_METHODS = new Set([
+  "newMintTransactionRequest",
+  "newSendTransactionRequest",
+  "newConsumeTransactionRequest",
+  "newSwapTransactionRequest",
+  "createCodeBuilder",
+  "buildSwapTag",
+  "setDebugMode",
+  "usesMockChain",
+  "serializeMockChain",
+  "serializeMockNoteTransportNode",
+  "proveBlock",
+]);
+
+/**
+ * Set of method names that mutate state. These are wrapped with the cross-tab
+ * write lock (Layer 2) when accessed through the Proxy fallback.
+ */
+const WRITE_METHODS = new Set([
+  "newAccount",
+  "importAccountFile",
+  "importAccountById",
+  "importPublicAccountFromSeed",
+  "importNoteFile",
+  "forceImportStore",
+  "addTag",
+  "removeTag",
+  "setSetting",
+  "removeSetting",
+  "insertAccountAddress",
+  "removeAccountAddress",
+  "sendPrivateNote",
+  // fetch*PrivateNotes fetches from the note transport AND writes to IndexedDB
+  "fetchPrivateNotes",
+  "fetchAllPrivateNotes",
+  "addAccountSecretKeyToWebStore",
+  "executeForSummary",
+]);
+
+/**
+ * Set of method names that are read-only (no state mutation). These are
+ * wrapped with the in-process WASM lock only (Layer 1).
+ *
+ * This set exists purely for the CI lint check (`check-method-classification`)
+ * which ensures every WASM export is explicitly classified — preventing new
+ * write methods from silently defaulting to read-only.
+ *
+ * The Proxy behaviour is unchanged: methods not in SYNC_METHODS or
+ * WRITE_METHODS already get WASM-lock-only wrapping.
+ */
+const READ_METHODS = new Set([
+  "getAccounts",
+  "getAccount",
+  "getAccountAuthByPubKeyCommitment",
+  "getPublicKeyCommitmentsOfAccount",
+  "getInputNotes",
+  "getInputNote",
+  "getOutputNotes",
+  "getOutputNote",
+  "getConsumableNotes",
+  "getTransactions",
+  "getSyncHeight",
+  "exportNoteFile",
+  "exportStore",
+  "exportAccountFile",
+  "listTags",
+  "getSetting",
+  "listSettingKeys",
+]);
+
+/**
+ * Module-level map tracking whether the current tab already holds the
+ * cross-tab Web Lock for a given store name. Keyed by storeName so that
+ * two WebClient instances targeting the same store correctly detect
+ * re-entrancy and skip re-acquiring the lock (which would deadlock).
+ */
+const _writeLockHeldByStore = new Map();
+
+/**
+ * Create the Proxy that wraps a WebClient instance. The proxy:
+ * - Returns properties from the wrapper (instance) first.
+ * - Falls back to the underlying WASM WebClient, wrapping function calls
+ *   through the in-process WASM lock (Layer 1) and, for write methods,
+ *   the cross-tab write lock (Layer 2).
+ */
+function createClientProxy(instance) {
+  return new Proxy(instance, {
+    get(target, prop, receiver) {
+      // If the property exists on the wrapper, return it.
+      if (prop in target) {
+        return Reflect.get(target, prop, receiver);
+      }
+      // Otherwise, if the wasmWebClient has it, return that.
+      if (target.wasmWebClient && prop in target.wasmWebClient) {
+        const value = target.wasmWebClient[prop];
+        if (typeof value === "function") {
+          // Synchronous methods: call directly without async wrapping.
+          // These are pure-computation methods whose callers expect a
+          // synchronous return value.
+          if (SYNC_METHODS.has(prop)) {
+            return (...args) => value.apply(target.wasmWebClient, args);
+          } else if (WRITE_METHODS.has(prop)) {
+            // Write methods: cross-tab lock (outer) → WASM lock (inner)
+            return (...args) =>
+              target._withWrite(prop, () =>
+                target._wasmLock.runExclusive(() =>
+                  value.apply(target.wasmWebClient, args)
+                )
+              );
+          } else if (READ_METHODS.has(prop)) {
+            // Read methods: WASM lock only
+            return (...args) =>
+              target._wasmLock.runExclusive(() =>
+                value.apply(target.wasmWebClient, args)
+              );
+          } else {
+            throw new Error(
+              `Unclassified WASM method: "${prop}". Add it to SYNC_METHODS, WRITE_METHODS, or READ_METHODS.`
+            );
+          }
+        }
+        return value;
+      }
+      return undefined;
+    },
+  });
+}
+
+// WASM MODULE LOADING
+// ================================================================================================
+
 const buildTypedArraysExport = (exportObject) => {
   return Object.entries(exportObject).reduce(
     (exports, [exportName, _export]) => {
@@ -307,6 +543,10 @@ const getWasmOrThrow = async () => {
   }
   return module;
 };
+
+// WEB CLIENT
+// ================================================================================================
+
 /**
  * WebClient is a wrapper around the underlying WASM WebClient object.
  *
@@ -323,6 +563,18 @@ const getWasmOrThrow = async () => {
  * 3. It employs a Proxy to forward any calls not designated for web worker computation
  *    directly to the underlying WASM WebClient instance.
  *
+ * Concurrency safety is provided by three layers:
+ *
+ * - **Layer 1 (In-Process AsyncLock):** All main-thread WASM calls are serialized
+ *   through `_wasmLock` to prevent "recursive use of an object detected" panics.
+ *
+ * - **Layer 2 (Cross-Tab Write Lock):** Mutating operations acquire an exclusive
+ *   Web Lock (`miden-db-{storeName}`) so that writes from different tabs are
+ *   serialized against the same IndexedDB database.
+ *
+ * - **Layer 3 (BroadcastChannel):** After every write, a notification is sent
+ *   to all other tabs so they can refresh stale in-memory state.
+ *
  * Additionally, the wrapper provides a static createClient function. This static method
  * instantiates the WebClient object and ensures that the necessary createClient calls are
  * performed both in the main thread and within the worker thread. This dual initialization
@@ -376,6 +628,55 @@ class WebClient {
     this.signCb = signCb;
     this.logLevel = logLevel;
 
+    // Layer 1: In-process WASM lock — serializes all main-thread WASM calls.
+    this._wasmLock = new AsyncLock();
+
+    // Layer 2 timeout: how long to wait to acquire the cross-tab write lock
+    // before aborting. Set to 0 to wait indefinitely. Can be overridden on
+    // the instance, e.g. client._writeLockTimeoutMs = 0.
+    this._writeLockTimeoutMs = 60_000;
+
+    // Layer 3: BroadcastChannel for cross-tab state-change notifications.
+    // If construction fails (e.g. unsupported WebView), Layer 3 is disabled
+    // but correctness is preserved: the cross-tab write lock (Layer 2) still
+    // prevents concurrent writes, and the next explicit user action will
+    // trigger a sync. Tabs just won't receive proactive refresh signals.
+    const channelName = `miden-state-${storeName || "default"}`;
+    try {
+      this._stateChannel =
+        typeof BroadcastChannel !== "undefined"
+          ? new BroadcastChannel(channelName)
+          : null;
+    } catch {
+      this._stateChannel = null;
+    }
+    this._stateListeners = [];
+    if (this._stateChannel) {
+      this._stateChannel.onmessage = async (event) => {
+        // Ignore cross-tab messages until the client is fully initialized.
+        if (!this.wasmWebClient) return;
+
+        // Auto-sync: refresh in-memory Rust Client state from IndexedDB.
+        // Sync coalescing (in syncLock.js) ensures concurrent syncs share the
+        // same result, so rapid messages are handled without debouncing.
+        try {
+          await this.syncState();
+        } catch {
+          // Sync failure is non-fatal — the next explicit sync will retry.
+        }
+
+        // Invoke listeners AFTER syncState resolves so in-memory state
+        // is guaranteed fresh when callbacks run.
+        for (const listener of this._stateListeners) {
+          try {
+            listener(event.data);
+          } catch {
+            // Swallow listener errors.
+          }
+        }
+      };
+    }
+
     // Check if Web Workers are available.
     if (typeof Worker !== "undefined") {
       console.log("WebClient: Web Workers are available.");
@@ -479,6 +780,94 @@ class WebClient {
     this.wasmWebClientPromise = null;
   }
 
+  // CONCURRENCY HELPERS
+  // ================================================================================================
+
+  /**
+   * Execute `fn` under the cross-tab write lock and broadcast a state-change
+   * notification when it completes. Safe to call re-entrantly within the same
+   * tab (the inner call skips the cross-tab lock since the outer call holds it).
+   *
+   * @param {string} operation - Name of the operation (for the broadcast payload).
+   * @param {() => Promise<T>} fn - The async work.
+   * @returns {Promise<T>}
+   * @template T
+   */
+  async _withWrite(operation, fn) {
+    const storeName = this.storeName || "default";
+
+    if (_writeLockHeldByStore.get(storeName)) {
+      // This tab already holds the cross-tab Web Lock for this store —
+      // skip re-acquiring it to avoid deadlock. The outer call's lock
+      // still blocks other tabs. Works correctly even when two WebClient
+      // instances target the same store within the same tab.
+      return fn();
+    }
+
+    const result = await withWriteLock(
+      storeName,
+      async () => {
+        _writeLockHeldByStore.set(storeName, true);
+        try {
+          return await fn();
+        } finally {
+          _writeLockHeldByStore.set(storeName, false);
+        }
+      },
+      this._writeLockTimeoutMs
+    );
+
+    // Layer 3: notify other tabs. Skip for syncState — sync is not a
+    // user-facing mutation, and broadcasting it would cause a ping-pong
+    // loop (Tab A syncs → broadcasts → Tab B auto-syncs → broadcasts → …).
+    if (operation !== "syncState") {
+      this._broadcastStateChange(operation);
+    }
+
+    return result;
+  }
+
+  /**
+   * Send a state-change notification over the BroadcastChannel (Layer 3).
+   *
+   * @param {string} [operation] - Human-readable name of the operation.
+   */
+  _broadcastStateChange(operation) {
+    if (this._stateChannel) {
+      try {
+        this._stateChannel.postMessage({
+          type: "stateChanged",
+          operation,
+          storeName: this.storeName || "default",
+        });
+      } catch {
+        // BroadcastChannel may be closed — ignore.
+      }
+    }
+  }
+
+  /**
+   * Register a listener that is called when **another tab** mutates the same
+   * IndexedDB database (Layer 3). The WebClient automatically calls
+   * `syncState()` before invoking listeners, so the in-memory state is
+   * already refreshed when your callback runs. Use this for additional
+   * work like re-fetching accounts or updating UI.
+   *
+   * Returns an unsubscribe function.
+   *
+   * @param {(event: {type: string, operation?: string, storeName: string}) => void} callback
+   * @returns {() => void} Unsubscribe function.
+   */
+  onStateChanged(callback) {
+    this._stateListeners.push(callback);
+    return () => {
+      this._stateListeners = this._stateListeners.filter((l) => l !== callback);
+    };
+  }
+
+  // WORKER / WASM INITIALIZATION
+  // ================================================================================================
+
   // 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
@@ -513,6 +902,9 @@ class WebClient {
     return this.wasmWebClientPromise;
   }
 
+  // FACTORY METHODS
+  // ================================================================================================
+
   /**
    * Factory method to create and initialize a WebClient instance.
    * This method is async so you can await the asynchronous call to createClient().
@@ -550,24 +942,7 @@ class WebClient {
     // Wait for the worker to be ready
     await instance.ready;
 
-    // Return a proxy that forwards missing properties to wasmWebClient.
-    return new Proxy(instance, {
-      get(target, prop, receiver) {
-        // If the property exists on the wrapper, return it.
-        if (prop in target) {
-          return Reflect.get(target, prop, receiver);
-        }
-        // Otherwise, if the wasmWebClient has it, return that.
-        if (target.wasmWebClient && prop in target.wasmWebClient) {
-          const value = target.wasmWebClient[prop];
-          if (typeof value === "function") {
-            return value.bind(target.wasmWebClient);
-          }
-          return value;
-        }
-        return undefined;
-      },
-    });
+    return createClientProxy(instance);
   }
 
   /**
@@ -625,24 +1000,8 @@ class WebClient {
     );
 
     await instance.ready;
-    // Return a proxy that forwards missing properties to wasmWebClient.
-    return new Proxy(instance, {
-      get(target, prop, receiver) {
-        // If the property exists on the wrapper, return it.
-        if (prop in target) {
-          return Reflect.get(target, prop, receiver);
-        }
-        // Otherwise, if the wasmWebClient has it, return that.
-        if (target.wasmWebClient && prop in target.wasmWebClient) {
-          const value = target.wasmWebClient[prop];
-          if (typeof value === "function") {
-            return value.bind(target.wasmWebClient);
-          }
-          return value;
-        }
-        return undefined;
-      },
-    });
+
+    return createClientProxy(instance);
   }
 
   /**
@@ -668,33 +1027,38 @@ class WebClient {
     });
   }
 
-  // ----- Explicitly Wrapped Methods (Worker-Forwarded) -----
+  // EXPLICITLY WRAPPED METHODS (Worker-Forwarded + Concurrency-Safe)
+  // ================================================================================================
 
   async newWallet(storageMode, mutable, authSchemeId, seed) {
-    try {
-      if (!this.worker) {
-        const wasmWebClient = await this.getWasmWebClient();
-        return await wasmWebClient.newWallet(
-          storageMode,
+    return this._withWrite("newWallet", async () => {
+      try {
+        if (!this.worker) {
+          return await this._wasmLock.runExclusive(async () => {
+            const wasmWebClient = await this.getWasmWebClient();
+            return await wasmWebClient.newWallet(
+              storageMode,
+              mutable,
+              authSchemeId,
+              seed
+            );
+          });
+        }
+        const wasm = await getWasmOrThrow();
+        const serializedStorageMode = storageMode.asStr();
+        const serializedAccountBytes = await this.callMethodWithWorker(
+          MethodName.NEW_WALLET,
+          serializedStorageMode,
           mutable,
           authSchemeId,
           seed
         );
+        return wasm.Account.deserialize(new Uint8Array(serializedAccountBytes));
+      } catch (error) {
+        console.error("INDEX.JS: Error in newWallet:", error);
+        throw error;
       }
-      const wasm = await getWasmOrThrow();
-      const serializedStorageMode = storageMode.asStr();
-      const serializedAccountBytes = await this.callMethodWithWorker(
-        MethodName.NEW_WALLET,
-        serializedStorageMode,
-        mutable,
-        authSchemeId,
-        seed
-      );
-      return wasm.Account.deserialize(new Uint8Array(serializedAccountBytes));
-    } catch (error) {
-      console.error("INDEX.JS: Error in newWallet:", error);
-      throw error;
-    }
+    });
   }
 
   async newFaucet(
@@ -705,134 +1069,157 @@ class WebClient {
     maxSupply,
     authSchemeId
   ) {
-    try {
-      if (!this.worker) {
-        const wasmWebClient = await this.getWasmWebClient();
-        return await wasmWebClient.newFaucet(
-          storageMode,
+    return this._withWrite("newFaucet", async () => {
+      try {
+        if (!this.worker) {
+          return await this._wasmLock.runExclusive(async () => {
+            const wasmWebClient = await this.getWasmWebClient();
+            return await wasmWebClient.newFaucet(
+              storageMode,
+              nonFungible,
+              tokenSymbol,
+              decimals,
+              maxSupply,
+              authSchemeId
+            );
+          });
+        }
+        const wasm = await getWasmOrThrow();
+        const serializedStorageMode = storageMode.asStr();
+        const serializedMaxSupply = maxSupply.toString();
+        const serializedAccountBytes = await this.callMethodWithWorker(
+          MethodName.NEW_FAUCET,
+          serializedStorageMode,
           nonFungible,
           tokenSymbol,
           decimals,
-          maxSupply,
+          serializedMaxSupply,
           authSchemeId
         );
-      }
-      const wasm = await getWasmOrThrow();
-      const serializedStorageMode = storageMode.asStr();
-      const serializedMaxSupply = maxSupply.toString();
-      const serializedAccountBytes = await this.callMethodWithWorker(
-        MethodName.NEW_FAUCET,
-        serializedStorageMode,
-        nonFungible,
-        tokenSymbol,
-        decimals,
-        serializedMaxSupply,
-        authSchemeId
-      );
 
-      return wasm.Account.deserialize(new Uint8Array(serializedAccountBytes));
-    } catch (error) {
-      console.error("INDEX.JS: Error in newFaucet:", error);
-      throw error;
-    }
+        return wasm.Account.deserialize(new Uint8Array(serializedAccountBytes));
+      } catch (error) {
+        console.error("INDEX.JS: Error in newFaucet:", error);
+        throw error;
+      }
+    });
   }
 
   async submitNewTransaction(accountId, transactionRequest) {
-    try {
-      if (!this.worker) {
-        const wasmWebClient = await this.getWasmWebClient();
-        return await wasmWebClient.submitNewTransaction(
-          accountId,
-          transactionRequest
-        );
-      }
+    return this._withWrite("submitNewTransaction", async () => {
+      try {
+        if (!this.worker) {
+          return await this._wasmLock.runExclusive(async () => {
+            const wasmWebClient = await this.getWasmWebClient();
+            return await wasmWebClient.submitNewTransaction(
+              accountId,
+              transactionRequest
+            );
+          });
+        }
 
-      const wasm = await getWasmOrThrow();
-      const serializedTransactionRequest = transactionRequest.serialize();
-      const result = await this.callMethodWithWorker(
-        MethodName.SUBMIT_NEW_TRANSACTION,
-        accountId.toString(),
-        serializedTransactionRequest
-      );
+        const wasm = await getWasmOrThrow();
+        const serializedTransactionRequest = transactionRequest.serialize();
+        const result = await this.callMethodWithWorker(
+          MethodName.SUBMIT_NEW_TRANSACTION,
+          accountId.toString(),
+          serializedTransactionRequest
+        );
 
-      const transactionResult = wasm.TransactionResult.deserialize(
-        new Uint8Array(result.serializedTransactionResult)
-      );
+        const transactionResult = wasm.TransactionResult.deserialize(
+          new Uint8Array(result.serializedTransactionResult)
+        );
 
-      return transactionResult.id();
-    } catch (error) {
-      console.error("INDEX.JS: Error in submitNewTransaction:", error);
-      throw error;
-    }
+        return transactionResult.id();
+      } catch (error) {
+        console.error("INDEX.JS: Error in submitNewTransaction:", error);
+        throw error;
+      }
+    });
   }
 
   async submitNewTransactionWithProver(accountId, transactionRequest, prover) {
-    try {
-      if (!this.worker) {
-        const wasmWebClient = await this.getWasmWebClient();
-        return await wasmWebClient.submitNewTransactionWithProver(
-          accountId,
-          transactionRequest,
-          prover
-        );
-      }
+    return this._withWrite("submitNewTransactionWithProver", async () => {
+      try {
+        if (!this.worker) {
+          return await this._wasmLock.runExclusive(async () => {
+            const wasmWebClient = await this.getWasmWebClient();
+            return await wasmWebClient.submitNewTransactionWithProver(
+              accountId,
+              transactionRequest,
+              prover
+            );
+          });
+        }
 
-      const wasm = await getWasmOrThrow();
-      const serializedTransactionRequest = transactionRequest.serialize();
-      const proverPayload = prover.serialize();
-      const result = await this.callMethodWithWorker(
-        MethodName.SUBMIT_NEW_TRANSACTION_WITH_PROVER,
-        accountId.toString(),
-        serializedTransactionRequest,
-        proverPayload
-      );
+        const wasm = await getWasmOrThrow();
+        const serializedTransactionRequest = transactionRequest.serialize();
+        const proverPayload = prover.serialize();
+        const result = await this.callMethodWithWorker(
+          MethodName.SUBMIT_NEW_TRANSACTION_WITH_PROVER,
+          accountId.toString(),
+          serializedTransactionRequest,
+          proverPayload
+        );
 
-      const transactionResult = wasm.TransactionResult.deserialize(
-        new Uint8Array(result.serializedTransactionResult)
-      );
+        const transactionResult = wasm.TransactionResult.deserialize(
+          new Uint8Array(result.serializedTransactionResult)
+        );
 
-      return transactionResult.id();
-    } catch (error) {
-      console.error(
-        "INDEX.JS: Error in submitNewTransactionWithProver:",
-        error
-      );
-      throw error;
-    }
+        return transactionResult.id();
+      } catch (error) {
+        console.error(
+          "INDEX.JS: Error in submitNewTransactionWithProver:",
+          error
+        );
+        throw error;
+      }
+    });
   }
 
   async executeTransaction(accountId, transactionRequest) {
-    try {
-      if (!this.worker) {
-        const wasmWebClient = await this.getWasmWebClient();
-        return await wasmWebClient.executeTransaction(
-          accountId,
-          transactionRequest
-        );
-      }
+    return this._withWrite("executeTransaction", async () => {
+      try {
+        if (!this.worker) {
+          return await this._wasmLock.runExclusive(async () => {
+            const wasmWebClient = await this.getWasmWebClient();
+            return await wasmWebClient.executeTransaction(
+              accountId,
+              transactionRequest
+            );
+          });
+        }
 
-      const wasm = await getWasmOrThrow();
-      const serializedTransactionRequest = transactionRequest.serialize();
-      const serializedResultBytes = await this.callMethodWithWorker(
-        MethodName.EXECUTE_TRANSACTION,
-        accountId.toString(),
-        serializedTransactionRequest
-      );
+        const wasm = await getWasmOrThrow();
+        const serializedTransactionRequest = transactionRequest.serialize();
+        const serializedResultBytes = await this.callMethodWithWorker(
+          MethodName.EXECUTE_TRANSACTION,
+          accountId.toString(),
+          serializedTransactionRequest
+        );
 
-      return wasm.TransactionResult.deserialize(
-        new Uint8Array(serializedResultBytes)
-      );
-    } catch (error) {
-      console.error("INDEX.JS: Error in executeTransaction:", error);
-      throw error;
-    }
+        return wasm.TransactionResult.deserialize(
+          new Uint8Array(serializedResultBytes)
+        );
+      } catch (error) {
+        console.error("INDEX.JS: Error in executeTransaction:", error);
+        throw error;
+      }
+    });
   }
 
+  // proveTransaction is CPU-heavy but does NOT write to IndexedDB, so it only
+  // needs the in-process WASM lock (Layer 1), not the cross-tab write lock.
   async proveTransaction(transactionResult, prover) {
     try {
       if (!this.worker) {
-        const wasmWebClient = await this.getWasmWebClient();
-        return await wasmWebClient.proveTransaction(transactionResult, prover);
+        return await this._wasmLock.runExclusive(async () => {
+          const wasmWebClient = await this.getWasmWebClient();
+          return await wasmWebClient.proveTransaction(
+            transactionResult,
+            prover
+          );
+        });
       }
 
       const wasm = await getWasmOrThrow();
@@ -854,6 +1241,52 @@ class WebClient {
     }
   }
 
+  // submitProvenTransaction and applyTransaction sync state before the write
+  // to catch cross-tab writes that occurred between execute and submit.
+  // This ensures the local IndexedDB view is fresh before submission.
+
+  async submitProvenTransaction(provenTransaction, transactionResult) {
+    return this._withWrite("submitProvenTransaction", async () => {
+      // Sync state to catch cross-tab writes that occurred since execute.
+      // We call syncStateImpl directly (bypassing the sync lock) because we
+      // already hold the write lock — calling syncState() would attempt to
+      // acquire sync lock → write lock, which is the reverse of the normal
+      // sync lock → write lock order and could deadlock across tabs.
+      try {
+        await this._wasmLock.runExclusive(async () => {
+          const wasmWebClient = await this.getWasmWebClient();
+          await wasmWebClient.syncStateImpl();
+        });
+      } catch {
+        // Sync failure is non-fatal — proceed with submission.
+        // The node will reject truly invalid transactions.
+      }
+
+      return await this._wasmLock.runExclusive(async () => {
+        const wasmWebClient = await this.getWasmWebClient();
+        return await wasmWebClient.submitProvenTransaction(
+          provenTransaction,
+          transactionResult
+        );
+      });
+    });
+  }
+
+  async applyTransaction(provenTransaction, transactionResult) {
+    return this._withWrite("applyTransaction", async () => {
+      return await this._wasmLock.runExclusive(async () => {
+        const wasmWebClient = await this.getWasmWebClient();
+        return await wasmWebClient.applyTransaction(
+          provenTransaction,
+          transactionResult
+        );
+      });
+    });
+  }
+
+  // SYNC
+  // ================================================================================================
+
   /**
    * Syncs the client state with the node.
    *
@@ -861,6 +1294,9 @@ class WebClient {
    * with an in-process mutex fallback for older browsers. If a sync is already in progress,
    * subsequent callers will wait and receive the same result (coalescing behavior).
    *
+   * Sync also acquires the cross-tab write lock (Layer 2) so that it does not
+   * interleave with writes from other tabs.
+   *
    * @returns {Promise<SyncSummary>} The sync summary
    */
   async syncState() {
@@ -874,6 +1310,8 @@ class WebClient {
    * with an in-process mutex fallback for older browsers. If a sync is already in progress,
    * subsequent callers will wait and receive the same result (coalescing behavior).
    *
+   * Lock nesting order: Sync Lock (coalescing, outer) → Write Lock → WASM Lock (inner).
+   *
    * @param {number} timeoutMs - Timeout in milliseconds (0 = no timeout)
    * @returns {Promise<SyncSummary>} The sync summary
    */
@@ -882,7 +1320,7 @@ class WebClient {
     const dbId = this.storeName || "default";
 
     try {
-      // Acquire the sync lock (coordinates concurrent calls)
+      // Acquire the sync lock (coordinates concurrent calls via coalescing)
       const lockHandle = await acquireSyncLock(dbId, timeoutMs);
 
       if (!lockHandle.acquired) {
@@ -890,27 +1328,31 @@ class WebClient {
         return lockHandle.coalescedResult;
       }
 
-      // We acquired the lock - perform the sync
+      // We acquired the sync lock. Now acquire the write lock so that
+      // sync doesn't interleave with writes from other tabs.
       try {
-        let result;
-        if (!this.worker) {
-          const wasmWebClient = await this.getWasmWebClient();
-          result = await wasmWebClient.syncStateImpl();
-        } else {
-          const wasm = await getWasmOrThrow();
-          const serializedSyncSummaryBytes = await this.callMethodWithWorker(
-            MethodName.SYNC_STATE
-          );
-          result = wasm.SyncSummary.deserialize(
-            new Uint8Array(serializedSyncSummaryBytes)
-          );
-        }
+        const result = await this._withWrite("syncState", async () => {
+          if (!this.worker) {
+            return await this._wasmLock.runExclusive(async () => {
+              const wasmWebClient = await this.getWasmWebClient();
+              return await wasmWebClient.syncStateImpl();
+            });
+          } else {
+            const wasm = await getWasmOrThrow();
+            const serializedSyncSummaryBytes = await this.callMethodWithWorker(
+              MethodName.SYNC_STATE
+            );
+            return wasm.SyncSummary.deserialize(
+              new Uint8Array(serializedSyncSummaryBytes)
+            );
+          }
+        });
 
-        // Release the lock with the result
+        // Release the sync lock with the result
         releaseSyncLock(dbId, result);
         return result;
       } catch (error) {
-        // Release the lock with the error
+        // Release the sync lock with the error
         releaseSyncLockWithError(dbId, error);
         throw error;
       }
@@ -920,13 +1362,39 @@ class WebClient {
     }
   }
 
+  /**
+   * Replace the sign callback on a live client instance.
+   * This allows hot-swapping the signer without recreating the client.
+   *
+   * @param {(pubKey: Uint8Array, signingInputs: Uint8Array) => Promise<Uint8Array> | Uint8Array} signCb
+   *   - The new sign callback, or null/undefined to clear it.
+   */
+  setSignCb(signCb) {
+    this.signCb = signCb ?? null;
+  }
+
+  // LIFECYCLE
+  // ================================================================================================
+
   terminate() {
     if (this.worker) {
       this.worker.terminate();
     }
+    if (this._stateChannel) {
+      try {
+        this._stateChannel.close();
+      } catch {
+        // Already closed — ignore.
+      }
+      this._stateChannel = null;
+    }
+    this._stateListeners = [];
   }
 }
 
+// MOCK WEB CLIENT
+// ================================================================================================
+
 class MockWebClient extends WebClient {
   constructor(seed, logLevel) {
     super(null, null, seed, "mock", undefined, undefined, undefined, logLevel);
@@ -973,24 +1441,7 @@ class MockWebClient extends WebClient {
     // Wait for the worker to be ready
     await instance.ready;
 
-    // Return a proxy that forwards missing properties to wasmWebClient.
-    return new Proxy(instance, {
-      get(target, prop, receiver) {
-        // If the property exists on the wrapper, return it.
-        if (prop in target) {
-          return Reflect.get(target, prop, receiver);
-        }
-        // Otherwise, if the wasmWebClient has it, return that.
-        if (target.wasmWebClient && prop in target.wasmWebClient) {
-          const value = target.wasmWebClient[prop];
-          if (typeof value === "function") {
-            return value.bind(target.wasmWebClient);
-          }
-          return value;
-        }
-        return undefined;
-      },
-    });
+    return createClientProxy(instance);
   }
 
   /**
@@ -1023,15 +1474,23 @@ class MockWebClient extends WebClient {
       }
 
       try {
-        let result;
-        const wasmWebClient = await this.getWasmWebClient();
+        const result = await this._withWrite("syncState", async () => {
+          if (!this.worker) {
+            return await this._wasmLock.runExclusive(async () => {
+              const wasmWebClient = await this.getWasmWebClient();
+              return wasmWebClient.syncStateImpl();
+            });
+          }
 
-        if (!this.worker) {
-          result = await wasmWebClient.syncStateImpl();
-        } else {
-          let serializedMockChain = wasmWebClient.serializeMockChain().buffer;
-          let serializedMockNoteTransportNode =
-            wasmWebClient.serializeMockNoteTransportNode().buffer;
+          const { serializedMockChain, serializedMockNoteTransportNode } =
+            await this._wasmLock.runExclusive(async () => {
+              const wasmWebClient = await this.getWasmWebClient();
+              return {
+                serializedMockChain: wasmWebClient.serializeMockChain().buffer,
+                serializedMockNoteTransportNode:
+                  wasmWebClient.serializeMockNoteTransportNode().buffer,
+              };
+            });
 
           const wasm = await getWasmOrThrow();
 
@@ -1041,10 +1500,10 @@ class MockWebClient extends WebClient {
             serializedMockNoteTransportNode
           );
 
-          result = wasm.SyncSummary.deserialize(
+          return wasm.SyncSummary.deserialize(
             new Uint8Array(serializedSyncSummaryBytes)
           );
-        }
+        });
 
         releaseSyncLock(dbId, result);
         return result;
@@ -1059,113 +1518,139 @@ class MockWebClient extends WebClient {
   }
 
   async submitNewTransaction(accountId, transactionRequest) {
-    try {
-      if (!this.worker) {
-        return await super.submitNewTransaction(accountId, transactionRequest);
-      }
+    return this._withWrite("submitNewTransaction", async () => {
+      try {
+        if (!this.worker) {
+          return await this._wasmLock.runExclusive(async () => {
+            const wasmWebClient = await this.getWasmWebClient();
+            return await wasmWebClient.submitNewTransaction(
+              accountId,
+              transactionRequest
+            );
+          });
+        }
 
-      const wasmWebClient = await this.getWasmWebClient();
-      const wasm = await getWasmOrThrow();
-      const serializedTransactionRequest = transactionRequest.serialize();
-      const serializedMockChain = wasmWebClient.serializeMockChain().buffer;
-      const serializedMockNoteTransportNode =
-        wasmWebClient.serializeMockNoteTransportNode().buffer;
-
-      const result = await this.callMethodWithWorker(
-        MethodName.SUBMIT_NEW_TRANSACTION_MOCK,
-        accountId.toString(),
-        serializedTransactionRequest,
-        serializedMockChain,
-        serializedMockNoteTransportNode
-      );
+        const wasm = await getWasmOrThrow();
+        const serializedTransactionRequest = transactionRequest.serialize();
+        const { serializedMockChain, serializedMockNoteTransportNode } =
+          await this._wasmLock.runExclusive(async () => {
+            const wasmWebClient = await this.getWasmWebClient();
+            return {
+              serializedMockChain: wasmWebClient.serializeMockChain().buffer,
+              serializedMockNoteTransportNode:
+                wasmWebClient.serializeMockNoteTransportNode().buffer,
+            };
+          });
 
-      const newMockChain = new Uint8Array(result.serializedMockChain);
-      const newMockNoteTransportNode = result.serializedMockNoteTransportNode
-        ? new Uint8Array(result.serializedMockNoteTransportNode)
-        : undefined;
+        const result = await this.callMethodWithWorker(
+          MethodName.SUBMIT_NEW_TRANSACTION_MOCK,
+          accountId.toString(),
+          serializedTransactionRequest,
+          serializedMockChain,
+          serializedMockNoteTransportNode
+        );
 
-      const transactionResult = wasm.TransactionResult.deserialize(
-        new Uint8Array(result.serializedTransactionResult)
-      );
+        const newMockChain = new Uint8Array(result.serializedMockChain);
+        const newMockNoteTransportNode = result.serializedMockNoteTransportNode
+          ? new Uint8Array(result.serializedMockNoteTransportNode)
+          : undefined;
 
-      if (!(this instanceof MockWebClient)) {
-        return transactionResult.id();
-      }
+        const transactionResult = wasm.TransactionResult.deserialize(
+          new Uint8Array(result.serializedTransactionResult)
+        );
 
-      this.wasmWebClient = new wasm.WebClient();
-      this.wasmWebClientPromise = Promise.resolve(this.wasmWebClient);
-      await this.wasmWebClient.createMockClient(
-        this.seed,
-        newMockChain,
-        newMockNoteTransportNode
-      );
+        if (!(this instanceof MockWebClient)) {
+          return transactionResult.id();
+        }
 
-      return transactionResult.id();
-    } catch (error) {
-      console.error("INDEX.JS: Error in submitNewTransaction:", error);
-      throw error;
-    }
+        this.wasmWebClient = new wasm.WebClient();
+        this.wasmWebClientPromise = Promise.resolve(this.wasmWebClient);
+        await this.wasmWebClient.createMockClient(
+          this.seed,
+          newMockChain,
+          newMockNoteTransportNode
+        );
+
+        return transactionResult.id();
+      } catch (error) {
+        console.error("INDEX.JS: Error in submitNewTransaction:", error);
+        throw error;
+      }
+    });
   }
 
   async submitNewTransactionWithProver(accountId, transactionRequest, prover) {
-    try {
-      if (!this.worker) {
-        return await super.submitNewTransactionWithProver(
-          accountId,
-          transactionRequest,
-          prover
+    return this._withWrite("submitNewTransactionWithProver", async () => {
+      try {
+        if (!this.worker) {
+          return await this._wasmLock.runExclusive(async () => {
+            const wasmWebClient = await this.getWasmWebClient();
+            return await wasmWebClient.submitNewTransactionWithProver(
+              accountId,
+              transactionRequest,
+              prover
+            );
+          });
+        }
+
+        const wasm = await getWasmOrThrow();
+        const serializedTransactionRequest = transactionRequest.serialize();
+        const proverPayload = prover.serialize();
+        const { serializedMockChain, serializedMockNoteTransportNode } =
+          await this._wasmLock.runExclusive(async () => {
+            const wasmWebClient = await this.getWasmWebClient();
+            return {
+              serializedMockChain: wasmWebClient.serializeMockChain().buffer,
+              serializedMockNoteTransportNode:
+                wasmWebClient.serializeMockNoteTransportNode().buffer,
+            };
+          });
+
+        const result = await this.callMethodWithWorker(
+          MethodName.SUBMIT_NEW_TRANSACTION_WITH_PROVER_MOCK,
+          accountId.toString(),
+          serializedTransactionRequest,
+          proverPayload,
+          serializedMockChain,
+          serializedMockNoteTransportNode
         );
-      }
 
-      const wasmWebClient = await this.getWasmWebClient();
-      const wasm = await getWasmOrThrow();
-      const serializedTransactionRequest = transactionRequest.serialize();
-      const proverPayload = prover.serialize();
-      const serializedMockChain = wasmWebClient.serializeMockChain().buffer;
-      const serializedMockNoteTransportNode =
-        wasmWebClient.serializeMockNoteTransportNode().buffer;
-
-      const result = await this.callMethodWithWorker(
-        MethodName.SUBMIT_NEW_TRANSACTION_WITH_PROVER_MOCK,
-        accountId.toString(),
-        serializedTransactionRequest,
-        proverPayload,
-        serializedMockChain,
-        serializedMockNoteTransportNode
-      );
+        const newMockChain = new Uint8Array(result.serializedMockChain);
+        const newMockNoteTransportNode = result.serializedMockNoteTransportNode
+          ? new Uint8Array(result.serializedMockNoteTransportNode)
+          : undefined;
 
-      const newMockChain = new Uint8Array(result.serializedMockChain);
-      const newMockNoteTransportNode = result.serializedMockNoteTransportNode
-        ? new Uint8Array(result.serializedMockNoteTransportNode)
-        : undefined;
+        const transactionResult = wasm.TransactionResult.deserialize(
+          new Uint8Array(result.serializedTransactionResult)
+        );
 
-      const transactionResult = wasm.TransactionResult.deserialize(
-        new Uint8Array(result.serializedTransactionResult)
-      );
+        if (!(this instanceof MockWebClient)) {
+          return transactionResult.id();
+        }
+
+        this.wasmWebClient = new wasm.WebClient();
+        this.wasmWebClientPromise = Promise.resolve(this.wasmWebClient);
+        await this.wasmWebClient.createMockClient(
+          this.seed,
+          newMockChain,
+          newMockNoteTransportNode
+        );
 
-      if (!(this instanceof MockWebClient)) {
         return transactionResult.id();
+      } catch (error) {
+        console.error(
+          "INDEX.JS: Error in submitNewTransactionWithProver:",
+          error
+        );
+        throw error;
       }
-
-      this.wasmWebClient = new wasm.WebClient();
-      this.wasmWebClientPromise = Promise.resolve(this.wasmWebClient);
-      await this.wasmWebClient.createMockClient(
-        this.seed,
-        newMockChain,
-        newMockNoteTransportNode
-      );
-
-      return transactionResult.id();
-    } catch (error) {
-      console.error(
-        "INDEX.JS: Error in submitNewTransactionWithProver:",
-        error
-      );
-      throw error;
-    }
+    });
   }
 }
 
+// STATICS
+// ================================================================================================
+
 function copyWebClientStatics(WasmWebClient) {
   if (!WasmWebClient) {
     return;