@miden-sdk/react 0.13.1 → 0.13.3

package/dist/index.mjs

@@ -29,6 +29,7 @@ var initialState = {
   notes: [],
   consumableNotes: [],
   assetMetadata: /* @__PURE__ */ new Map(),
+  noteFirstSeen: /* @__PURE__ */ new Map(),
   isLoadingAccounts: false,
   isLoadingNotes: false
 };
@@ -56,8 +57,74 @@ var useMidenStore = create()((set) => ({
     newMap.set(accountId, account);
     return { accountDetails: newMap };
   }),
-  setNotes: (notes) => set({ notes }),
+  setNotes: (notes) => set((state) => {
+    const now = Date.now();
+    const newFirstSeen = /* @__PURE__ */ new Map();
+    for (const note of notes) {
+      try {
+        const id = note.id().toString();
+        newFirstSeen.set(id, state.noteFirstSeen.get(id) ?? now);
+      } catch {
+      }
+    }
+    return { notes, noteFirstSeen: newFirstSeen };
+  }),
+  setNotesIfChanged: (notes) => set((state) => {
+    const safeId = (n) => {
+      try {
+        return n.id().toString();
+      } catch {
+        return null;
+      }
+    };
+    const prevIds = /* @__PURE__ */ new Set();
+    for (const n of state.notes) {
+      const id = safeId(n);
+      if (id) prevIds.add(id);
+    }
+    const newIds = /* @__PURE__ */ new Set();
+    for (const n of notes) {
+      const id = safeId(n);
+      if (id) newIds.add(id);
+    }
+    if (prevIds.size === newIds.size && [...prevIds].every((id) => newIds.has(id))) {
+      return {};
+    }
+    const now = Date.now();
+    const newFirstSeen = /* @__PURE__ */ new Map();
+    for (const note of notes) {
+      try {
+        const id = note.id().toString();
+        newFirstSeen.set(id, state.noteFirstSeen.get(id) ?? now);
+      } catch {
+      }
+    }
+    return { notes, noteFirstSeen: newFirstSeen };
+  }),
   setConsumableNotes: (consumableNotes) => set({ consumableNotes }),
+  setConsumableNotesIfChanged: (consumableNotes) => set((state) => {
+    const safeId = (n) => {
+      try {
+        return n.inputNoteRecord().id().toString();
+      } catch {
+        return null;
+      }
+    };
+    const prevIds = /* @__PURE__ */ new Set();
+    for (const n of state.consumableNotes) {
+      const id = safeId(n);
+      if (id) prevIds.add(id);
+    }
+    const newIds = /* @__PURE__ */ new Set();
+    for (const n of consumableNotes) {
+      const id = safeId(n);
+      if (id) newIds.add(id);
+    }
+    if (prevIds.size === newIds.size && [...prevIds].every((id) => newIds.has(id))) {
+      return {};
+    }
+    return { consumableNotes };
+  }),
   setAssetMetadata: (assetId, metadata) => set((state) => {
     const newMap = new Map(state.assetMetadata);
     newMap.set(assetId, metadata);
@@ -72,6 +139,7 @@ var useAccountsStore = () => useMidenStore((state) => state.accounts);
 var useNotesStore = () => useMidenStore((state) => state.notes);
 var useConsumableNotesStore = () => useMidenStore((state) => state.consumableNotes);
 var useAssetMetadataStore = () => useMidenStore((state) => state.assetMetadata);
+var useNoteFirstSeenStore = () => useMidenStore((state) => state.noteFirstSeen);
 
 // src/utils/accountParsing.ts
 import { AccountId, Address } from "@miden-sdk/miden-sdk";
@@ -95,6 +163,19 @@ var parseAccountId = (value) => {
   const normalized = normalizeAccountIdInput(value);
   return parseAccountIdFromString(normalized);
 };
+function isFaucetId(accountId) {
+  try {
+    let hex = typeof accountId.toHex === "function" ? accountId.toHex() : String(accountId);
+    if (hex.startsWith("0x") || hex.startsWith("0X")) {
+      hex = hex.slice(2);
+    }
+    const firstByte = parseInt(hex.slice(0, 2), 16);
+    const accountType = firstByte >> 4 & 3;
+    return accountType === 2 || accountType === 3;
+  } catch {
+    return false;
+  }
+}
 var parseAddress = (value, accountId) => {
   const normalized = normalizeAccountIdInput(value);
   if (isBech32Input(normalized)) {
@@ -339,19 +420,29 @@ function isPrivateStorageMode(storageMode) {
   return storageMode.toString() === "private";
 }
 async function initializeSignerAccount(client, config) {
-  const { AccountBuilder, AccountComponent, Word } = await import("@miden-sdk/miden-sdk");
+  const { AccountBuilder, AccountComponent, Word: Word2 } = await import("@miden-sdk/miden-sdk");
   await client.syncState();
-  const commitmentWord = Word.deserialize(config.publicKeyCommitment);
+  const commitmentWord = Word2.deserialize(config.publicKeyCommitment);
   const seed = config.accountSeed ?? crypto.getRandomValues(new Uint8Array(32));
   const accountType = await getAccountType(config.accountType);
-  const builder = new AccountBuilder(seed);
-  const buildResult = builder.withAuthComponent(
+  let builder = new AccountBuilder(seed).withAuthComponent(
     AccountComponent.createAuthComponentFromCommitment(
       commitmentWord,
       1
       // ECDSA auth scheme (K256/Keccak)
     )
-  ).accountType(accountType).storageMode(config.storageMode).withBasicWalletComponent().build();
+  ).accountType(accountType).storageMode(config.storageMode).withBasicWalletComponent();
+  if (config.customComponents?.length) {
+    for (const component of config.customComponents) {
+      if (component == null || typeof component.getProcedures !== "function") {
+        throw new Error(
+          "Each entry in customComponents must be an AccountComponent instance created via AccountComponent.compile(), AccountComponent.fromPackage(), or AccountComponent.fromLibrary()."
+        );
+      }
+      builder = builder.withComponent(component);
+    }
+  }
+  const buildResult = builder.build();
   const account = buildResult.account;
   const accountId = account.id();
   if (!isPrivateStorageMode(config.storageMode)) {
@@ -448,63 +539,91 @@ function MidenProvider({
   useEffect(() => {
     if (!signerContext && isInitializedRef.current) return;
     if (signerContext && !signerContext.isConnected) {
-      if (client) {
+      if (useMidenStore.getState().client) {
         useMidenStore.getState().reset();
         setClient(null);
         setSignerAccountId(null);
       }
       return;
     }
-    if (!signerContext) {
-      isInitializedRef.current = true;
-    }
+    let cancelled = false;
     const initClient = async () => {
-      setInitializing(true);
-      setConfig(resolvedConfig);
-      try {
-        let webClient;
-        if (signerContext && signerContext.isConnected) {
-          const storeName = `MidenClientDB_${signerContext.storeName}`;
-          webClient = await WebClient.createClientWithExternalKeystore(
-            resolvedConfig.rpcUrl,
-            resolvedConfig.noteTransportUrl,
-            resolvedConfig.seed,
-            storeName,
-            void 0,
-            // getKeyCb - not needed for public accounts
-            void 0,
-            // insertKeyCb - not needed for public accounts
-            signerContext.signCb
-          );
-          const accountId = await initializeSignerAccount(
-            webClient,
-            signerContext.accountConfig
-          );
-          setSignerAccountId(accountId);
-        } else {
-          const seed = resolvedConfig.seed;
-          webClient = await WebClient.createClient(
-            resolvedConfig.rpcUrl,
-            resolvedConfig.noteTransportUrl,
-            seed
-          );
-        }
-        setClient(webClient);
+      await runExclusive(async () => {
+        if (cancelled) return;
+        setInitializing(true);
+        setConfig(resolvedConfig);
         try {
-          const summary = await runExclusive(() => webClient.syncState());
-          setSyncState({
-            syncHeight: summary.blockNum(),
-            lastSyncTime: Date.now()
-          });
-          const accounts = await webClient.getAccounts();
-          useMidenStore.getState().setAccounts(accounts);
-        } catch {
+          let webClient;
+          let didSignerInit = false;
+          if (signerContext && signerContext.isConnected) {
+            const storeName = `MidenClientDB_${signerContext.storeName}`;
+            webClient = await WebClient.createClientWithExternalKeystore(
+              resolvedConfig.rpcUrl,
+              resolvedConfig.noteTransportUrl,
+              resolvedConfig.seed,
+              storeName,
+              void 0,
+              // getKeyCb - not needed for public accounts
+              void 0,
+              // insertKeyCb - not needed for public accounts
+              signerContext.signCb
+            );
+            if (cancelled) return;
+            const accountId = await initializeSignerAccount(
+              webClient,
+              signerContext.accountConfig
+            );
+            if (cancelled) return;
+            setSignerAccountId(accountId);
+            didSignerInit = true;
+          } else {
+            const seed = resolvedConfig.seed;
+            webClient = await WebClient.createClient(
+              resolvedConfig.rpcUrl,
+              resolvedConfig.noteTransportUrl,
+              seed
+            );
+            if (cancelled) return;
+          }
+          if (!didSignerInit) {
+            try {
+              const summary = await webClient.syncState();
+              if (cancelled) return;
+              setSyncState({
+                syncHeight: summary.blockNum(),
+                lastSyncTime: Date.now()
+              });
+            } catch {
+            }
+          }
+          if (!cancelled) {
+            try {
+              const accounts = await webClient.getAccounts();
+              if (cancelled) return;
+              useMidenStore.getState().setAccounts(accounts);
+            } catch {
+            }
+          }
+          if (!cancelled) {
+            if (!signerContext) {
+              isInitializedRef.current = true;
+            }
+            setClient(webClient);
+          }
+        } catch (error) {
+          if (!cancelled) {
+            setInitError(
+              error instanceof Error ? error : new Error(String(error))
+            );
+          }
         }
-      } catch (error) {
-        setInitError(error instanceof Error ? error : new Error(String(error)));
-      }
+      });
     };
     initClient();
+    return () => {
+      cancelled = true;
+      isInitializedRef.current = false;
+    };
   }, [
     runExclusive,
     resolvedConfig,
@@ -513,8 +632,7 @@ function MidenProvider({
     setInitError,
     setInitializing,
     setSyncState,
-    signerContext,
-    client
+    signerContext
   ]);
   useEffect(() => {
     if (!isReady || !client) return;
@@ -620,16 +738,6 @@ function useAccounts() {
     refetch
   };
 }
-function isFaucetId(accountId) {
-  try {
-    const hex = typeof accountId.toHex === "function" ? accountId.toHex() : String(accountId);
-    const firstByte = parseInt(hex.slice(0, 2), 16);
-    const accountType = firstByte >> 4 & 3;
-    return accountType === 2 || accountType === 3;
-  } catch {
-    return false;
-  }
-}
 
 // src/hooks/useAccount.ts
 import { useCallback as useCallback3, useEffect as useEffect4, useState as useState2, useMemo as useMemo3 } from "react";
@@ -656,17 +764,12 @@ var getRpcClient = (rpcUrl) => {
     return null;
   }
 };
-var fetchAssetMetadata = async (client, rpcClient, assetId) => {
+var fetchAssetMetadata = async (rpcClient, assetId) => {
   try {
     const accountId = parseAccountId(assetId);
-    let account = await client.getAccount(accountId);
-    if (!account && rpcClient) {
-      try {
-        const fetched = await rpcClient.getAccountDetails(accountId);
-        account = fetched.account?.();
-      } catch {
-      }
-    }
+    if (!isFaucetId(accountId)) return null;
+    const fetched = await rpcClient.getAccountDetails(accountId);
+    const account = fetched.account?.();
     if (!account) return null;
     const faucet = BasicFungibleFaucetComponent.fromAccount(account);
     const symbol = faucet.symbol().toString();
@@ -677,8 +780,6 @@ var fetchAssetMetadata = async (client, rpcClient, assetId) => {
   }
 };
 function useAssetMetadata(assetIds = []) {
-  const { client, isReady, runExclusive } = useMiden();
-  const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
   const assetMetadata = useAssetMetadataStore();
   const setAssetMetadata = useMidenStore((state) => state.setAssetMetadata);
   const rpcUrl = useMidenStore((state) => state.config.rpcUrl);
@@ -688,32 +789,19 @@ function useAssetMetadata(assetIds = []) {
     [assetIds]
   );
   useEffect3(() => {
-    if (!client || !isReady || uniqueAssetIds.length === 0) return;
+    if (!rpcClient || uniqueAssetIds.length === 0) return;
     uniqueAssetIds.forEach((assetId) => {
       const existing = assetMetadata.get(assetId);
       const hasMetadata = existing?.symbol !== void 0 || existing?.decimals !== void 0;
       if (hasMetadata || inflight.has(assetId)) return;
-      const promise = runExclusiveSafe(async () => {
-        const metadata = await fetchAssetMetadata(
-          client,
-          rpcClient,
-          assetId
-        );
+      const promise = fetchAssetMetadata(rpcClient, assetId).then((metadata) => {
         setAssetMetadata(assetId, metadata ?? { assetId });
       }).finally(() => {
         inflight.delete(assetId);
       });
       inflight.set(assetId, promise);
     });
-  }, [
-    client,
-    isReady,
-    uniqueAssetIds,
-    assetMetadata,
-    runExclusiveSafe,
-    setAssetMetadata,
-    rpcClient
-  ]);
+  }, [uniqueAssetIds, assetMetadata, setAssetMetadata, rpcClient]);
   return { assetMetadata };
 }
 
@@ -815,7 +903,7 @@ function useAccount(accountId) {
 
 // src/hooks/useNotes.ts
 import { useCallback as useCallback4, useEffect as useEffect5, useMemo as useMemo4, useState as useState3 } from "react";
-import { NoteFilter, NoteFilterTypes } from "@miden-sdk/miden-sdk";
+import { NoteFilter } from "@miden-sdk/miden-sdk";
 
 // src/utils/amounts.ts
 var formatAssetAmount = (amount, decimals) => {
@@ -899,6 +987,86 @@ var formatNoteSummary = (summary, formatAsset = (asset) => `${formatAssetAmount(
   return summary.sender ? `${assetsText} from ${summary.sender}` : assetsText;
 };
 
+// src/utils/accountId.ts
+function normalizeAccountId(id) {
+  return toBech32AccountId(id);
+}
+function accountIdsEqual(a, b) {
+  let idA;
+  let idB;
+  try {
+    idA = parseAccountId(a);
+    idB = parseAccountId(b);
+    return idA.toString() === idB.toString();
+  } catch {
+    return a === b;
+  } finally {
+    idA?.free?.();
+    idB?.free?.();
+  }
+}
+
+// src/utils/noteFilters.ts
+import {
+  NoteFilterTypes,
+  NoteType,
+  TransactionFilter
+} from "@miden-sdk/miden-sdk";
+function getNoteFilterType(status) {
+  switch (status) {
+    case "consumed":
+      return NoteFilterTypes.Consumed;
+    case "committed":
+      return NoteFilterTypes.Committed;
+    case "expected":
+      return NoteFilterTypes.Expected;
+    case "processing":
+      return NoteFilterTypes.Processing;
+    case "all":
+    default:
+      return NoteFilterTypes.All;
+  }
+}
+function getNoteType(type) {
+  switch (type) {
+    case "private":
+      return NoteType.Private;
+    case "public":
+      return NoteType.Public;
+    default:
+      return NoteType.Private;
+  }
+}
+async function waitForTransactionCommit(client, runExclusiveSafe, txIdHex, maxWaitMs = 1e4, delayMs = 1e3) {
+  const deadline = Date.now() + maxWaitMs;
+  const targetHex = normalizeHex(txIdHex);
+  while (Date.now() < deadline) {
+    await runExclusiveSafe(() => client.syncState());
+    const records = await runExclusiveSafe(
+      () => client.getTransactions(TransactionFilter.all())
+    );
+    const record = records.find(
+      (r) => normalizeHex(r.id().toHex()) === targetHex
+    );
+    if (record) {
+      const status = record.transactionStatus();
+      if (status.isCommitted()) {
+        return;
+      }
+      if (status.isDiscarded()) {
+        throw new Error("Transaction was discarded before commit");
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  throw new Error("Timeout waiting for transaction commit");
+}
+function normalizeHex(value) {
+  const trimmed = value.trim();
+  const normalized = trimmed.startsWith("0x") || trimmed.startsWith("0X") ? trimmed : `0x${trimmed}`;
+  return normalized.toLowerCase();
+}
+
 // src/hooks/useNotes.ts
 function useNotes(options) {
   const { client, isReady, runExclusive } = useMiden();
@@ -907,8 +1075,10 @@ function useNotes(options) {
   const consumableNotes = useConsumableNotesStore();
   const isLoadingNotes = useMidenStore((state) => state.isLoadingNotes);
   const setLoadingNotes = useMidenStore((state) => state.setLoadingNotes);
-  const setNotes = useMidenStore((state) => state.setNotes);
-  const setConsumableNotes = useMidenStore((state) => state.setConsumableNotes);
+  const setNotesIfChanged = useMidenStore((state) => state.setNotesIfChanged);
+  const setConsumableNotesIfChanged = useMidenStore(
+    (state) => state.setConsumableNotesIfChanged
+  );
   const { lastSyncTime } = useSyncStateStore();
   const [error, setError] = useState3(null);
   const refetch = useCallback4(async () => {
@@ -934,8 +1104,8 @@ function useNotes(options) {
           };
         }
       );
-      setNotes(fetchedNotes);
-      setConsumableNotes(fetchedConsumable);
+      setNotesIfChanged(fetchedNotes);
+      setConsumableNotesIfChanged(fetchedConsumable);
     } catch (err) {
       setError(err instanceof Error ? err : new Error(String(err)));
     } finally {
@@ -948,8 +1118,8 @@ function useNotes(options) {
     options?.status,
     options?.accountId,
     setLoadingNotes,
-    setNotes,
-    setConsumableNotes
+    setNotesIfChanged,
+    setConsumableNotesIfChanged
   ]);
   useEffect5(() => {
     if (isReady && notes.length === 0) {
@@ -976,14 +1146,65 @@ function useNotes(options) {
     (assetId) => assetMetadata.get(assetId),
     [assetMetadata]
   );
-  const noteSummaries = useMemo4(
-    () => notes.map((note) => getNoteSummary(note, getMetadata)).filter(Boolean),
-    [notes, getMetadata]
-  );
-  const consumableNoteSummaries = useMemo4(
-    () => consumableNotes.map((note) => getNoteSummary(note, getMetadata)).filter(Boolean),
-    [consumableNotes, getMetadata]
+  const normalizedSender = useMemo4(() => {
+    if (!options?.sender) return null;
+    try {
+      return normalizeAccountId(options.sender);
+    } catch {
+      return options.sender;
+    }
+  }, [options?.sender]);
+  const excludeIdsKey = useMemo4(() => {
+    if (!options?.excludeIds || options.excludeIds.length === 0) return "";
+    return [...options.excludeIds].sort().join("\0");
+  }, [options?.excludeIds]);
+  const filterBySender = useCallback4(
+    (summaries, target) => {
+      const cache = /* @__PURE__ */ new Map();
+      return summaries.filter((s) => {
+        if (!s.sender) return false;
+        let normalized = cache.get(s.sender);
+        if (normalized === void 0) {
+          try {
+            normalized = normalizeAccountId(s.sender);
+          } catch {
+            normalized = s.sender;
+          }
+          cache.set(s.sender, normalized);
+        }
+        return normalized === target;
+      });
+    },
+    []
   );
+  const noteSummaries = useMemo4(() => {
+    let summaries = notes.map((note) => getNoteSummary(note, getMetadata)).filter(Boolean);
+    if (normalizedSender) {
+      summaries = filterBySender(summaries, normalizedSender);
+    }
+    if (excludeIdsKey) {
+      const excludeSet = new Set(excludeIdsKey.split("\0"));
+      summaries = summaries.filter((s) => !excludeSet.has(s.id));
+    }
+    return summaries;
+  }, [notes, getMetadata, normalizedSender, excludeIdsKey, filterBySender]);
+  const consumableNoteSummaries = useMemo4(() => {
+    let summaries = consumableNotes.map((note) => getNoteSummary(note, getMetadata)).filter(Boolean);
+    if (normalizedSender) {
+      summaries = filterBySender(summaries, normalizedSender);
+    }
+    if (excludeIdsKey) {
+      const excludeSet = new Set(excludeIdsKey.split("\0"));
+      summaries = summaries.filter((s) => !excludeSet.has(s.id));
+    }
+    return summaries;
+  }, [
+    consumableNotes,
+    getMetadata,
+    normalizedSender,
+    excludeIdsKey,
+    filterBySender
+  ]);
   return {
     notes,
     consumableNotes,
@@ -994,46 +1215,251 @@ function useNotes(options) {
     refetch
   };
 }
-function getNoteFilterType(status) {
-  switch (status) {
-    case "consumed":
-      return NoteFilterTypes.Consumed;
-    case "committed":
-      return NoteFilterTypes.Committed;
-    case "expected":
-      return NoteFilterTypes.Expected;
-    case "processing":
-      return NoteFilterTypes.Processing;
-    case "all":
-    default:
-      return NoteFilterTypes.All;
+
+// src/hooks/useNoteStream.ts
+import { useCallback as useCallback5, useEffect as useEffect6, useMemo as useMemo5, useRef as useRef2, useState as useState4 } from "react";
+import { NoteFilter as NoteFilter2 } from "@miden-sdk/miden-sdk";
+
+// src/utils/noteAttachment.ts
+import {
+  NoteAttachment,
+  NoteAttachmentKind,
+  NoteAttachmentScheme,
+  Word
+} from "@miden-sdk/miden-sdk";
+function readNoteAttachment(note) {
+  try {
+    const metadata = note.metadata?.();
+    if (!metadata) return null;
+    const attachment = metadata.attachment?.();
+    if (!attachment) return null;
+    const kind = attachment.kind?.();
+    if (!kind) return null;
+    if (kind === NoteAttachmentKind.None) return null;
+    if (kind === NoteAttachmentKind.Word) {
+      const word = attachment.asWord?.();
+      if (!word) return null;
+      const u64s = word.toU64s();
+      const values = Array.from(u64s).map(
+        (v) => BigInt(v)
+      );
+      return { values, kind: "word" };
+    }
+    if (kind === NoteAttachmentKind.Array) {
+      const arr = attachment.asArray?.();
+      if (!arr) return null;
+      const u64s = arr.toU64s();
+      const values = Array.from(u64s).map(
+        (v) => BigInt(v)
+      );
+      return { values, kind: "array" };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function createNoteAttachment(values) {
+  const bigints = [];
+  for (let i = 0; i < values.length; i++) {
+    bigints.push(BigInt(values[i]));
+  }
+  if (bigints.length === 0) {
+    return new NoteAttachment();
+  }
+  const scheme = NoteAttachmentScheme.none();
+  if (bigints.length <= 4) {
+    while (bigints.length < 4) {
+      bigints.push(0n);
+    }
+    const word = new Word(BigUint64Array.from(bigints));
+    return NoteAttachment.newWord(scheme, word);
+  }
+  while (bigints.length % 4 !== 0) {
+    bigints.push(0n);
+  }
+  const words = [];
+  for (let i = 0; i < bigints.length; i += 4) {
+    words.push(new Word(BigUint64Array.from(bigints.slice(i, i + 4))));
+  }
+  const newArray = NoteAttachment["newArray"];
+  if (typeof newArray !== "function") {
+    throw new Error(
+      "NoteAttachment.newArray is not available. Ensure @miden-sdk/miden-sdk >= 0.13.1."
+    );
   }
+  return newArray.call(NoteAttachment, scheme, words);
 }
 
-// src/hooks/useTransactionHistory.ts
-import { useCallback as useCallback5, useEffect as useEffect6, useMemo as useMemo5, useState as useState4 } from "react";
-import { TransactionFilter } from "@miden-sdk/miden-sdk";
-function useTransactionHistory(options = {}) {
+// src/hooks/useNoteStream.ts
+function useNoteStream(options = {}) {
   const { client, isReady, runExclusive } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
+  const allNotes = useNotesStore();
+  const noteFirstSeen = useNoteFirstSeenStore();
   const { lastSyncTime } = useSyncStateStore();
-  const [records, setRecords] = useState4([]);
+  const setNotesIfChanged = useMidenStore((state) => state.setNotesIfChanged);
   const [isLoading, setIsLoading] = useState4(false);
   const [error, setError] = useState4(null);
-  const rawIds = useMemo5(() => {
+  const handledIdsRef = useRef2(/* @__PURE__ */ new Set());
+  const [handledVersion, setHandledVersion] = useState4(0);
+  const status = options.status ?? "committed";
+  const sender = options.sender ?? null;
+  const since = options.since;
+  const amountFilterRef = useRef2(options.amountFilter);
+  amountFilterRef.current = options.amountFilter;
+  const excludeIdsKey = useMemo5(() => {
+    if (!options.excludeIds) return "";
+    if (options.excludeIds instanceof Set)
+      return Array.from(options.excludeIds).sort().join("\0");
+    return [...options.excludeIds].sort().join("\0");
+  }, [options.excludeIds]);
+  const excludeIdSet = useMemo5(() => {
+    if (!excludeIdsKey) return null;
+    return new Set(excludeIdsKey.split("\0"));
+  }, [excludeIdsKey]);
+  const refetch = useCallback5(async () => {
+    if (!client || !isReady) return;
+    setIsLoading(true);
+    setError(null);
+    try {
+      const filterType = getNoteFilterType(status);
+      const filter = new NoteFilter2(filterType);
+      const fetched = await runExclusiveSafe(
+        () => client.getInputNotes(filter)
+      );
+      setNotesIfChanged(fetched);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client, isReady, runExclusiveSafe, status, setNotesIfChanged]);
+  useEffect6(() => {
+    if (isReady) {
+      refetch();
+    }
+  }, [isReady, lastSyncTime, refetch]);
+  const streamedNotes = useMemo5(() => {
+    void handledVersion;
+    const result = [];
+    let normalizedSender = null;
+    if (sender) {
+      try {
+        normalizedSender = normalizeAccountId(sender);
+      } catch {
+        normalizedSender = sender;
+      }
+    }
+    for (const record of allNotes) {
+      const note = buildStreamedNote(record, noteFirstSeen);
+      if (!note) continue;
+      if (handledIdsRef.current.has(note.id)) continue;
+      if (excludeIdSet && excludeIdSet.has(note.id)) continue;
+      if (normalizedSender && note.sender !== normalizedSender) continue;
+      if (since !== void 0 && note.firstSeenAt < since) continue;
+      if (amountFilterRef.current && !amountFilterRef.current(note.amount))
+        continue;
+      result.push(note);
+    }
+    result.sort((a, b) => a.firstSeenAt - b.firstSeenAt);
+    return result;
+  }, [allNotes, noteFirstSeen, excludeIdSet, sender, since, handledVersion]);
+  const latest = useMemo5(
+    () => streamedNotes.length > 0 ? streamedNotes[streamedNotes.length - 1] : null,
+    [streamedNotes]
+  );
+  const markHandled = useCallback5((noteId) => {
+    handledIdsRef.current = new Set(handledIdsRef.current).add(noteId);
+    setHandledVersion((v) => v + 1);
+  }, []);
+  const markAllHandled = useCallback5(() => {
+    const newSet = new Set(handledIdsRef.current);
+    for (const note of streamedNotes) {
+      newSet.add(note.id);
+    }
+    handledIdsRef.current = newSet;
+    setHandledVersion((v) => v + 1);
+  }, [streamedNotes]);
+  const snapshot = useCallback5(() => {
+    const ids = /* @__PURE__ */ new Set();
+    for (const note of streamedNotes) {
+      ids.add(note.id);
+    }
+    return { ids, timestamp: Date.now() };
+  }, [streamedNotes]);
+  return {
+    notes: streamedNotes,
+    latest,
+    markHandled,
+    markAllHandled,
+    snapshot,
+    isLoading,
+    error
+  };
+}
+function buildStreamedNote(record, noteFirstSeen) {
+  try {
+    const id = record.id().toString();
+    const metadata = record.metadata?.();
+    const senderHex = metadata?.sender?.()?.toString?.();
+    const sender = senderHex ? toBech32AccountId(senderHex) : "";
+    const assets = [];
+    let primaryAmount = 0n;
+    try {
+      const details = record.details();
+      const assetsList = details?.assets?.().fungibleAssets?.() ?? [];
+      for (const asset of assetsList) {
+        const assetId = asset.faucetId().toString();
+        const amount = BigInt(asset.amount());
+        assets.push({ assetId, amount });
+        if (primaryAmount === 0n) {
+          primaryAmount = amount;
+        }
+      }
+    } catch {
+    }
+    const attachmentData = readNoteAttachment(record);
+    const attachment = attachmentData ? attachmentData.values : null;
+    const firstSeenAt = noteFirstSeen.get(id) ?? Date.now();
+    return {
+      id,
+      sender,
+      amount: primaryAmount,
+      assets,
+      record,
+      firstSeenAt,
+      attachment
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/hooks/useTransactionHistory.ts
+import { useCallback as useCallback6, useEffect as useEffect7, useMemo as useMemo6, useState as useState5 } from "react";
+import { TransactionFilter as TransactionFilter2 } from "@miden-sdk/miden-sdk";
+function useTransactionHistory(options = {}) {
+  const { client, isReady, runExclusive } = useMiden();
+  const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
+  const { lastSyncTime } = useSyncStateStore();
+  const [records, setRecords] = useState5([]);
+  const [isLoading, setIsLoading] = useState5(false);
+  const [error, setError] = useState5(null);
+  const rawIds = useMemo6(() => {
     if (options.id) return [options.id];
     if (options.ids && options.ids.length > 0) return options.ids;
     return null;
   }, [options.id, options.ids]);
-  const idsHex = useMemo5(() => {
+  const idsHex = useMemo6(() => {
     if (!rawIds) return null;
     return rawIds.map(
-      (id) => normalizeHex(typeof id === "string" ? id : id.toHex())
+      (id) => normalizeHex2(typeof id === "string" ? id : id.toHex())
     );
   }, [rawIds]);
   const filter = options.filter;
   const refreshOnSync = options.refreshOnSync !== false;
-  const refetch = useCallback5(async () => {
+  const refetch = useCallback6(async () => {
     if (!client || !isReady) return;
     setIsLoading(true);
     setError(null);
@@ -1047,7 +1473,7 @@ function useTransactionHistory(options = {}) {
         () => client.getTransactions(resolvedFilter)
       );
       const filtered = localFilterHexes ? fetched.filter(
-        (record2) => localFilterHexes.includes(normalizeHex(record2.id().toHex()))
+        (record2) => localFilterHexes.includes(normalizeHex2(record2.id().toHex()))
       ) : fetched;
       setRecords(filtered);
     } catch (err) {
@@ -1056,19 +1482,19 @@ function useTransactionHistory(options = {}) {
       setIsLoading(false);
     }
   }, [client, isReady, runExclusiveSafe, filter, rawIds, idsHex]);
-  useEffect6(() => {
+  useEffect7(() => {
     if (!isReady) return;
     refetch();
   }, [isReady, refetch]);
-  useEffect6(() => {
+  useEffect7(() => {
     if (!isReady || !refreshOnSync || !lastSyncTime) return;
     refetch();
   }, [isReady, lastSyncTime, refreshOnSync, refetch]);
-  const record = useMemo5(() => {
+  const record = useMemo6(() => {
     if (!idsHex || idsHex.length !== 1) return null;
-    return records.find((item) => normalizeHex(item.id().toHex()) === idsHex[0]) ?? null;
+    return records.find((item) => normalizeHex2(item.id().toHex()) === idsHex[0]) ?? null;
   }, [records, idsHex]);
-  const status = useMemo5(() => {
+  const status = useMemo6(() => {
     if (!record) return null;
     const current = record.transactionStatus();
     if (current.isCommitted()) return "committed";
@@ -1090,29 +1516,29 @@ function buildFilter(filter, ids, idsHex) {
     return { filter };
   }
   if (!ids || ids.length === 0) {
-    return { filter: TransactionFilter.all() };
+    return { filter: TransactionFilter2.all() };
   }
   const allTransactionIds = ids.every((id) => typeof id !== "string");
   if (allTransactionIds) {
-    return { filter: TransactionFilter.ids(ids) };
+    return { filter: TransactionFilter2.ids(ids) };
   }
   return {
-    filter: TransactionFilter.all(),
+    filter: TransactionFilter2.all(),
     localFilterHexes: idsHex ?? []
   };
 }
-function normalizeHex(value) {
+function normalizeHex2(value) {
   const trimmed = value.trim();
   const normalized = trimmed.startsWith("0x") || trimmed.startsWith("0X") ? trimmed : `0x${trimmed}`;
   return normalized.toLowerCase();
 }
 
 // src/hooks/useSyncState.ts
-import { useCallback as useCallback6 } from "react";
+import { useCallback as useCallback7 } from "react";
 function useSyncState() {
   const { sync: triggerSync } = useMiden();
   const syncState = useSyncStateStore();
-  const sync = useCallback6(async () => {
+  const sync = useCallback7(async () => {
     await triggerSync();
   }, [triggerSync]);
   return {
@@ -1122,16 +1548,16 @@ function useSyncState() {
 }
 
 // src/hooks/useCreateWallet.ts
-import { useCallback as useCallback7, useState as useState5 } from "react";
+import { useCallback as useCallback8, useState as useState6 } from "react";
 import { AccountStorageMode } from "@miden-sdk/miden-sdk";
 function useCreateWallet() {
   const { client, isReady, sync, runExclusive } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
   const setAccounts = useMidenStore((state) => state.setAccounts);
-  const [wallet, setWallet] = useState5(null);
-  const [isCreating, setIsCreating] = useState5(false);
-  const [error, setError] = useState5(null);
-  const createWallet = useCallback7(
+  const [wallet, setWallet] = useState6(null);
+  const [isCreating, setIsCreating] = useState6(false);
+  const [error, setError] = useState6(null);
+  const createWallet = useCallback8(
     async (options = {}) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -1169,7 +1595,7 @@ function useCreateWallet() {
     },
     [client, isReady, runExclusive, setAccounts]
   );
-  const reset = useCallback7(() => {
+  const reset = useCallback8(() => {
     setWallet(null);
     setIsCreating(false);
     setError(null);
@@ -1196,16 +1622,16 @@ function getStorageMode(mode) {
 }
 
 // src/hooks/useCreateFaucet.ts
-import { useCallback as useCallback8, useState as useState6 } from "react";
+import { useCallback as useCallback9, useState as useState7 } from "react";
 import { AccountStorageMode as AccountStorageMode2 } from "@miden-sdk/miden-sdk";
 function useCreateFaucet() {
   const { client, isReady, runExclusive } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
   const setAccounts = useMidenStore((state) => state.setAccounts);
-  const [faucet, setFaucet] = useState6(null);
-  const [isCreating, setIsCreating] = useState6(false);
-  const [error, setError] = useState6(null);
-  const createFaucet = useCallback8(
+  const [faucet, setFaucet] = useState7(null);
+  const [isCreating, setIsCreating] = useState7(false);
+  const [error, setError] = useState7(null);
+  const createFaucet = useCallback9(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -1244,7 +1670,7 @@ function useCreateFaucet() {
     },
     [client, isReady, runExclusive, setAccounts]
   );
-  const reset = useCallback8(() => {
+  const reset = useCallback9(() => {
     setFaucet(null);
     setIsCreating(false);
     setError(null);
@@ -1271,16 +1697,16 @@ function getStorageMode2(mode) {
 }
 
 // src/hooks/useImportAccount.ts
-import { useCallback as useCallback9, useState as useState7 } from "react";
+import { useCallback as useCallback10, useState as useState8 } from "react";
 import { AccountFile } from "@miden-sdk/miden-sdk";
 function useImportAccount() {
   const { client, isReady, runExclusive } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
   const setAccounts = useMidenStore((state) => state.setAccounts);
-  const [account, setAccount] = useState7(null);
-  const [isImporting, setIsImporting] = useState7(false);
-  const [error, setError] = useState7(null);
-  const importAccount = useCallback9(
+  const [account, setAccount] = useState8(null);
+  const [isImporting, setIsImporting] = useState8(false);
+  const [error, setError] = useState8(null);
+  const importAccount = useCallback10(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -1375,7 +1801,7 @@ function useImportAccount() {
     },
     [client, isReady, runExclusive, setAccounts]
   );
-  const reset = useCallback9(() => {
+  const reset = useCallback10(() => {
     setAccount(null);
     setIsImporting(false);
     setError(null);
@@ -1425,43 +1851,154 @@ function bytesEqual(left, right) {
 }
 
 // src/hooks/useSend.ts
-import { useCallback as useCallback10, useState as useState8 } from "react";
-import { NoteType, TransactionFilter as TransactionFilter2 } from "@miden-sdk/miden-sdk";
+import { useCallback as useCallback11, useRef as useRef3, useState as useState9 } from "react";
+import {
+  FungibleAsset,
+  Note,
+  NoteAssets,
+  NoteType as NoteType2,
+  OutputNote,
+  OutputNoteArray,
+  TransactionRequestBuilder
+} from "@miden-sdk/miden-sdk";
+
+// src/utils/errors.ts
+var MidenError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "MidenError";
+    this.code = options?.code ?? "UNKNOWN";
+    if (options?.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+var ERROR_PATTERNS = [
+  {
+    test: (msg) => msg.includes("_assertClass") || msg.includes("expected instance of"),
+    code: "WASM_CLASS_MISMATCH",
+    message: "WASM class identity mismatch. This usually means multiple copies of @miden-sdk/miden-sdk are bundled. Ensure your bundler deduplicates the package. For Vite: add resolve.dedupe and optimizeDeps.exclude for @miden-sdk/miden-sdk."
+  },
+  {
+    test: (msg) => msg.includes("null pointer") || msg.includes("already been freed") || msg.includes("dereferencing a null"),
+    code: "WASM_POINTER_CONSUMED",
+    message: "WASM object was already consumed. Some WASM-bound objects can only be passed once \u2014 if you need to reuse a value, create a fresh instance before each call."
+  },
+  {
+    test: (msg) => msg.includes("not initialized") || msg.includes("Cannot read properties of null"),
+    code: "WASM_NOT_INITIALIZED",
+    message: "Miden client is not initialized. Ensure you are inside a <MidenProvider> and the client is ready before calling SDK methods."
+  },
+  {
+    test: (msg) => msg.includes("state commitment mismatch") || msg.includes("stale state"),
+    code: "WASM_SYNC_REQUIRED",
+    message: "Account state is stale. Call sync() before executing transactions, or ensure no concurrent transactions are running against the same account."
+  }
+];
+function wrapWasmError(e) {
+  if (e instanceof MidenError) return e;
+  const msg = e instanceof Error ? e.message : String(e);
+  for (const pattern of ERROR_PATTERNS) {
+    if (pattern.test(msg)) {
+      return new MidenError(pattern.message, { cause: e, code: pattern.code });
+    }
+  }
+  if (e instanceof Error) return e;
+  return new Error(msg);
+}
+
+// src/hooks/useSend.ts
 function useSend() {
   const { client, isReady, sync, runExclusive, prover } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
-  const [result, setResult] = useState8(null);
-  const [isLoading, setIsLoading] = useState8(false);
-  const [stage, setStage] = useState8("idle");
-  const [error, setError] = useState8(null);
-  const send = useCallback10(
+  const isBusyRef = useRef3(false);
+  const [result, setResult] = useState9(null);
+  const [isLoading, setIsLoading] = useState9(false);
+  const [stage, setStage] = useState9("idle");
+  const [error, setError] = useState9(null);
+  const send = useCallback11(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
       }
+      if (isBusyRef.current) {
+        throw new MidenError(
+          "A send is already in progress. Await the previous send before starting another.",
+          { code: "SEND_BUSY" }
+        );
+      }
+      isBusyRef.current = true;
       setIsLoading(true);
       setStage("executing");
       setError(null);
       try {
+        if (!options.skipSync) {
+          await sync();
+        }
         const noteType = getNoteType(options.noteType ?? DEFAULTS.NOTE_TYPE);
-        const fromAccountId = parseAccountId(options.from);
-        const toAccountId = parseAccountId(options.to);
+        let amount = options.amount;
+        if (options.sendAll) {
+          const resolvedAmount = await runExclusiveSafe(async () => {
+            const fromId = parseAccountId(options.from);
+            const account = await client.getAccount(fromId);
+            if (!account) throw new Error("Account not found");
+            const assetIdObj = parseAccountId(options.assetId);
+            const balance = account.vault?.()?.getBalance?.(assetIdObj);
+            if (balance === void 0 || balance === null) {
+              throw new Error("Could not query account balance");
+            }
+            const bal = BigInt(balance);
+            if (bal === 0n) {
+              throw new Error("Account has zero balance for this asset");
+            }
+            return bal;
+          });
+          amount = resolvedAmount;
+        }
+        if (amount === void 0 || amount === null) {
+          throw new Error("Amount is required (provide amount or sendAll)");
+        }
         const assetId = options.assetId ?? options.faucetId ?? null;
         if (!assetId) {
           throw new Error("Asset ID is required");
         }
-        const assetIdObj = parseAccountId(assetId);
-        const txResult = await runExclusiveSafe(async () => {
-          const txRequest = client.newSendTransactionRequest(
-            fromAccountId,
-            toAccountId,
-            assetIdObj,
-            noteType,
-            options.amount,
-            options.recallHeight ?? null,
-            options.timelockHeight ?? null
+        const hasAttachment = options.attachment !== void 0 && options.attachment !== null;
+        if (hasAttachment && (options.recallHeight != null || options.timelockHeight != null)) {
+          throw new Error(
+            "recallHeight and timelockHeight are not supported when attachment is provided"
           );
-          return await client.executeTransaction(fromAccountId, txRequest);
+        }
+        const txResult = await runExclusiveSafe(async () => {
+          const fromAccountId = parseAccountId(options.from);
+          const toAccountId = parseAccountId(options.to);
+          const assetIdObj = parseAccountId(assetId);
+          let txRequest;
+          if (hasAttachment) {
+            const attachment = createNoteAttachment(options.attachment);
+            const assets = new NoteAssets([
+              new FungibleAsset(assetIdObj, amount)
+            ]);
+            const note = Note.createP2IDNote(
+              fromAccountId,
+              toAccountId,
+              assets,
+              noteType,
+              attachment
+            );
+            txRequest = new TransactionRequestBuilder().withOwnOutputNotes(new OutputNoteArray([OutputNote.full(note)])).build();
+          } else {
+            txRequest = client.newSendTransactionRequest(
+              fromAccountId,
+              toAccountId,
+              assetIdObj,
+              noteType,
+              amount,
+              options.recallHeight ?? null,
+              options.timelockHeight ?? null
+            );
+          }
+          const execAccountId = parseAccountId(options.from);
+          return await client.executeTransaction(execAccountId, txRequest);
         });
         setStage("proving");
         const provenTransaction = await runExclusiveSafe(
@@ -1471,22 +2008,31 @@ function useSend() {
         const submissionHeight = await runExclusiveSafe(
           () => client.submitProvenTransaction(provenTransaction, txResult)
         );
+        const txIdHex = txResult.id().toHex();
+        const txIdString = txResult.id().toString();
+        let fullNote = null;
+        if (noteType === NoteType2.Private) {
+          fullNote = extractFullNote(txResult);
+        }
         await runExclusiveSafe(
           () => client.applyTransaction(txResult, submissionHeight)
         );
-        const txId = txResult.id();
-        await waitForTransactionCommit(client, runExclusiveSafe, txId);
-        if (noteType === NoteType.Private) {
-          const fullNote = extractFullNote(txResult);
+        if (noteType === NoteType2.Private) {
           if (!fullNote) {
             throw new Error("Missing full note for private send");
           }
-          const recipientAddress = parseAddress(options.to, toAccountId);
+          await waitForTransactionCommit(
+            client,
+            runExclusiveSafe,
+            txIdHex
+          );
+          const recipientAccountId = parseAccountId(options.to);
+          const recipientAddress = parseAddress(options.to, recipientAccountId);
           await runExclusiveSafe(
             () => client.sendPrivateNote(fullNote, recipientAddress)
           );
         }
-        const txSummary = { transactionId: txResult.id().toString() };
+        const txSummary = { transactionId: txIdString };
         setStage("complete");
         setResult(txSummary);
         await sync();
@@ -1498,11 +2044,12 @@ function useSend() {
         throw error2;
       } finally {
         setIsLoading(false);
+        isBusyRef.current = false;
       }
     },
     [client, isReady, prover, runExclusive, sync]
   );
-  const reset = useCallback10(() => {
+  const reset = useCallback11(() => {
     setResult(null);
     setIsLoading(false);
     setStage("idle");
@@ -1517,39 +2064,6 @@ function useSend() {
     reset
   };
 }
-function getNoteType(type) {
-  switch (type) {
-    case "private":
-      return NoteType.Private;
-    case "public":
-      return NoteType.Public;
-    case "encrypted":
-      return NoteType.Encrypted;
-    default:
-      return NoteType.Private;
-  }
-}
-async function waitForTransactionCommit(client, runExclusiveSafe, txId, maxWaitMs = 1e4, delayMs = 1e3) {
-  let waited = 0;
-  while (waited < maxWaitMs) {
-    await runExclusiveSafe(() => client.syncState());
-    const [record] = await runExclusiveSafe(
-      () => client.getTransactions(TransactionFilter2.ids([txId]))
-    );
-    if (record) {
-      const status = record.transactionStatus();
-      if (status.isCommitted()) {
-        return;
-      }
-      if (status.isDiscarded()) {
-        throw new Error("Transaction was discarded before commit");
-      }
-    }
-    await new Promise((resolve) => setTimeout(resolve, delayMs));
-    waited += delayMs;
-  }
-  throw new Error("Timeout waiting for transaction commit");
-}
 function extractFullNote(txResult) {
   try {
     const executedTx = txResult.executedTransaction?.();
@@ -1562,26 +2076,26 @@ function extractFullNote(txResult) {
 }
 
 // src/hooks/useMultiSend.ts
-import { useCallback as useCallback11, useState as useState9 } from "react";
+import { useCallback as useCallback12, useRef as useRef4, useState as useState10 } from "react";
 import {
-  FungibleAsset,
-  Note,
-  NoteAssets,
-  NoteAttachment,
-  NoteType as NoteType2,
-  OutputNote,
-  OutputNoteArray,
-  TransactionFilter as TransactionFilter3,
-  TransactionRequestBuilder
+  FungibleAsset as FungibleAsset2,
+  Note as Note2,
+  NoteAssets as NoteAssets2,
+  NoteAttachment as NoteAttachment2,
+  NoteType as NoteType3,
+  OutputNote as OutputNote2,
+  OutputNoteArray as OutputNoteArray2,
+  TransactionRequestBuilder as TransactionRequestBuilder2
 } from "@miden-sdk/miden-sdk";
 function useMultiSend() {
   const { client, isReady, sync, runExclusive, prover } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
-  const [result, setResult] = useState9(null);
-  const [isLoading, setIsLoading] = useState9(false);
-  const [stage, setStage] = useState9("idle");
-  const [error, setError] = useState9(null);
-  const sendMany = useCallback11(
+  const isBusyRef = useRef4(false);
+  const [result, setResult] = useState10(null);
+  const [isLoading, setIsLoading] = useState10(false);
+  const [stage, setStage] = useState10("idle");
+  const [error, setError] = useState10(null);
+  const sendMany = useCallback12(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -1589,35 +2103,53 @@ function useMultiSend() {
       if (options.recipients.length === 0) {
         throw new Error("No recipients provided");
       }
+      if (isBusyRef.current) {
+        throw new MidenError(
+          "A send is already in progress. Await the previous send before starting another.",
+          { code: "SEND_BUSY" }
+        );
+      }
+      isBusyRef.current = true;
       setIsLoading(true);
       setStage("executing");
       setError(null);
       try {
-        const noteType = getNoteType2(options.noteType ?? DEFAULTS.NOTE_TYPE);
-        const senderId = parseAccountId(options.from);
-        const assetId = parseAccountId(options.assetId);
-        const outputs = options.recipients.map(({ to, amount }) => {
-          const receiverId = parseAccountId(to);
-          const assets = new NoteAssets([new FungibleAsset(assetId, amount)]);
-          const note = Note.createP2IDNote(
-            senderId,
-            receiverId,
-            assets,
-            noteType,
-            new NoteAttachment()
-          );
-          const recipientAddress = parseAddress(to, receiverId);
-          return {
-            outputNote: OutputNote.full(note),
-            note,
-            recipientAddress
-          };
-        });
-        const txRequest = new TransactionRequestBuilder().withOwnOutputNotes(
-          new OutputNoteArray(outputs.map((o) => o.outputNote))
+        if (!options.skipSync) {
+          await sync();
+        }
+        const noteType = getNoteType(options.noteType ?? DEFAULTS.NOTE_TYPE);
+        const outputs = options.recipients.map(
+          ({ to, amount, attachment, noteType: recipientNoteType }) => {
+            const iterSenderId = parseAccountId(options.from);
+            const iterAssetId = parseAccountId(options.assetId);
+            const receiverId = parseAccountId(to);
+            const assets = new NoteAssets2([
+              new FungibleAsset2(iterAssetId, amount)
+            ]);
+            const resolvedNoteType = recipientNoteType ? getNoteType(recipientNoteType) : noteType;
+            const noteAttachment = attachment !== void 0 && attachment !== null ? createNoteAttachment(attachment) : new NoteAttachment2();
+            const note = Note2.createP2IDNote(
+              iterSenderId,
+              receiverId,
+              assets,
+              resolvedNoteType,
+              noteAttachment
+            );
+            const recipientAddress = parseAddress(to, receiverId);
+            return {
+              outputNote: OutputNote2.full(note),
+              note,
+              recipientAddress,
+              noteType: resolvedNoteType
+            };
+          }
+        );
+        const txRequest = new TransactionRequestBuilder2().withOwnOutputNotes(
+          new OutputNoteArray2(outputs.map((o) => o.outputNote))
         ).build();
+        const txSenderId = parseAccountId(options.from);
         const txResult = await runExclusiveSafe(
-          () => client.executeTransaction(senderId, txRequest)
+          () => client.executeTransaction(txSenderId, txRequest)
         );
         setStage("proving");
         const provenTransaction = await runExclusiveSafe(
@@ -1627,23 +2159,27 @@ function useMultiSend() {
         const submissionHeight = await runExclusiveSafe(
           () => client.submitProvenTransaction(provenTransaction, txResult)
         );
+        const txIdHex = txResult.id().toHex();
+        const txIdString = txResult.id().toString();
         await runExclusiveSafe(
           () => client.applyTransaction(txResult, submissionHeight)
         );
-        const txId = txResult.id();
-        if (noteType === NoteType2.Private) {
-          await waitForTransactionCommit2(
+        const hasPrivate = outputs.some((o) => o.noteType === NoteType3.Private);
+        if (hasPrivate) {
+          await waitForTransactionCommit(
             client,
             runExclusiveSafe,
-            txId
+            txIdHex
           );
           for (const output of outputs) {
-            await runExclusiveSafe(
-              () => client.sendPrivateNote(output.note, output.recipientAddress)
-            );
+            if (output.noteType === NoteType3.Private) {
+              await runExclusiveSafe(
+                () => client.sendPrivateNote(output.note, output.recipientAddress)
+              );
+            }
           }
         }
-        const txSummary = { transactionId: txId.toString() };
+        const txSummary = { transactionId: txIdString };
         setStage("complete");
         setResult(txSummary);
         await sync();
@@ -1655,11 +2191,12 @@ function useMultiSend() {
         throw error2;
       } finally {
         setIsLoading(false);
+        isBusyRef.current = false;
       }
     },
     [client, isReady, prover, runExclusive, sync]
   );
-  const reset = useCallback11(() => {
+  const reset = useCallback12(() => {
     setResult(null);
     setIsLoading(false);
     setStage("idle");
@@ -1674,82 +2211,48 @@ function useMultiSend() {
     reset
   };
 }
-function getNoteType2(type) {
-  switch (type) {
-    case "private":
-      return NoteType2.Private;
-    case "public":
-      return NoteType2.Public;
-    case "encrypted":
-      return NoteType2.Encrypted;
-    default:
-      return NoteType2.Private;
-  }
-}
-async function waitForTransactionCommit2(client, runExclusiveSafe, txId, maxWaitMs = 1e4, delayMs = 1e3) {
-  let waited = 0;
-  while (waited < maxWaitMs) {
-    await runExclusiveSafe(() => client.syncState());
-    const [record] = await runExclusiveSafe(
-      () => client.getTransactions(TransactionFilter3.ids([txId]))
-    );
-    if (record) {
-      const status = record.transactionStatus();
-      if (status.isCommitted()) {
-        return;
-      }
-      if (status.isDiscarded()) {
-        throw new Error("Transaction was discarded before commit");
-      }
-    }
-    await new Promise((resolve) => setTimeout(resolve, delayMs));
-    waited += delayMs;
-  }
-  throw new Error("Timeout waiting for transaction commit");
-}
 
 // src/hooks/useInternalTransfer.ts
-import { useCallback as useCallback12, useState as useState10 } from "react";
+import { useCallback as useCallback13, useState as useState11 } from "react";
 import {
-  FungibleAsset as FungibleAsset2,
-  Note as Note2,
+  FungibleAsset as FungibleAsset3,
+  Note as Note3,
   NoteAndArgs,
   NoteAndArgsArray,
-  NoteAssets as NoteAssets2,
-  NoteAttachment as NoteAttachment2,
-  NoteType as NoteType3,
-  OutputNote as OutputNote2,
-  OutputNoteArray as OutputNoteArray2,
-  TransactionRequestBuilder as TransactionRequestBuilder2
+  NoteAssets as NoteAssets3,
+  NoteAttachment as NoteAttachment3,
+  OutputNote as OutputNote3,
+  OutputNoteArray as OutputNoteArray3,
+  TransactionRequestBuilder as TransactionRequestBuilder3
 } from "@miden-sdk/miden-sdk";
 function useInternalTransfer() {
   const { client, isReady, sync, runExclusive, prover } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
-  const [result, setResult] = useState10(null);
-  const [isLoading, setIsLoading] = useState10(false);
-  const [stage, setStage] = useState10("idle");
-  const [error, setError] = useState10(null);
-  const transferOnce = useCallback12(
+  const [result, setResult] = useState11(null);
+  const [isLoading, setIsLoading] = useState11(false);
+  const [stage, setStage] = useState11("idle");
+  const [error, setError] = useState11(null);
+  const transferOnce = useCallback13(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
       }
-      const noteType = getNoteType3(options.noteType ?? DEFAULTS.NOTE_TYPE);
+      const noteType = getNoteType(options.noteType ?? DEFAULTS.NOTE_TYPE);
       const senderId = parseAccountId(options.from);
       const receiverId = parseAccountId(options.to);
       const assetId = parseAccountId(options.assetId);
-      const assets = new NoteAssets2([
-        new FungibleAsset2(assetId, options.amount)
+      const assets = new NoteAssets3([
+        new FungibleAsset3(assetId, options.amount)
       ]);
-      const note = Note2.createP2IDNote(
+      const note = Note3.createP2IDNote(
         senderId,
         receiverId,
         assets,
         noteType,
-        new NoteAttachment2()
+        new NoteAttachment3()
       );
       const noteId = note.id().toString();
-      const createRequest = new TransactionRequestBuilder2().withOwnOutputNotes(new OutputNoteArray2([OutputNote2.full(note)])).build();
+      const createRequest = new TransactionRequestBuilder3().withOwnOutputNotes(new OutputNoteArray3([OutputNote3.full(note)])).build();
       const createTxId = await runExclusiveSafe(
         () => prover ? client.submitNewTransactionWithProver(
           senderId,
@@ -1757,7 +2260,7 @@ function useInternalTransfer() {
           prover
         ) : client.submitNewTransaction(senderId, createRequest)
       );
-      const consumeRequest = new TransactionRequestBuilder2().withInputNotes(new NoteAndArgsArray([new NoteAndArgs(note, null)])).build();
+      const consumeRequest = new TransactionRequestBuilder3().withInputNotes(new NoteAndArgsArray([new NoteAndArgs(note, null)])).build();
       const consumeTxId = await runExclusiveSafe(
         () => prover ? client.submitNewTransactionWithProver(
           receiverId,
@@ -1773,7 +2276,7 @@ function useInternalTransfer() {
     },
     [client, isReady, prover, runExclusiveSafe]
   );
-  const transfer = useCallback12(
+  const transfer = useCallback13(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -1799,7 +2302,7 @@ function useInternalTransfer() {
     },
     [client, isReady, sync, transferOnce]
   );
-  const transferChain = useCallback12(
+  const transferChain = useCallback13(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -1840,7 +2343,7 @@ function useInternalTransfer() {
     },
     [client, isReady, sync, transferOnce]
   );
-  const reset = useCallback12(() => {
+  const reset = useCallback13(() => {
     setResult(null);
     setIsLoading(false);
     setStage("idle");
@@ -1856,47 +2359,35 @@ function useInternalTransfer() {
     reset
   };
 }
-function getNoteType3(type) {
-  switch (type) {
-    case "private":
-      return NoteType3.Private;
-    case "public":
-      return NoteType3.Public;
-    case "encrypted":
-      return NoteType3.Encrypted;
-    default:
-      return NoteType3.Private;
-  }
-}
 
 // src/hooks/useWaitForCommit.ts
-import { useCallback as useCallback13 } from "react";
-import { TransactionFilter as TransactionFilter4 } from "@miden-sdk/miden-sdk";
+import { useCallback as useCallback14 } from "react";
+import { TransactionFilter as TransactionFilter3 } from "@miden-sdk/miden-sdk";
 function useWaitForCommit() {
   const { client, isReady, runExclusive } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
-  const waitForCommit = useCallback13(
+  const waitForCommit = useCallback14(
     async (txId, options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
       }
       const timeoutMs = Math.max(0, options?.timeoutMs ?? 1e4);
       const intervalMs = Math.max(1, options?.intervalMs ?? 1e3);
-      const targetHex = normalizeHex2(
+      const targetHex = normalizeHex3(
         typeof txId === "string" ? txId : txId.toHex()
       );
-      let waited = 0;
-      while (waited < timeoutMs) {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
         await runExclusiveSafe(
           () => client.syncState()
         );
         const records = await runExclusiveSafe(
           () => client.getTransactions(
-            typeof txId === "string" ? TransactionFilter4.all() : TransactionFilter4.ids([txId])
+            typeof txId === "string" ? TransactionFilter3.all() : TransactionFilter3.ids([txId])
           )
         );
         const record = records.find(
-          (item) => normalizeHex2(item.id().toHex()) === targetHex
+          (item) => normalizeHex3(item.id().toHex()) === targetHex
         );
         if (record) {
           const status = record.transactionStatus();
@@ -1908,7 +2399,6 @@ function useWaitForCommit() {
           }
         }
         await new Promise((resolve) => setTimeout(resolve, intervalMs));
-        waited += intervalMs;
       }
       throw new Error("Timeout waiting for transaction commit");
     },
@@ -1916,18 +2406,18 @@ function useWaitForCommit() {
   );
   return { waitForCommit };
 }
-function normalizeHex2(value) {
+function normalizeHex3(value) {
   const trimmed = value.trim();
   const normalized = trimmed.startsWith("0x") || trimmed.startsWith("0X") ? trimmed : `0x${trimmed}`;
   return normalized.toLowerCase();
 }
 
 // src/hooks/useWaitForNotes.ts
-import { useCallback as useCallback14 } from "react";
+import { useCallback as useCallback15 } from "react";
 function useWaitForNotes() {
   const { client, isReady, runExclusive } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
-  const waitForConsumableNotes = useCallback14(
+  const waitForConsumableNotes = useCallback15(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -1938,7 +2428,9 @@ function useWaitForNotes() {
       const accountId = parseAccountId(options.accountId);
       let waited = 0;
       while (waited < timeoutMs) {
-        await runExclusiveSafe(() => client.syncState());
+        await runExclusiveSafe(
+          () => client.syncState()
+        );
         const notes = await runExclusiveSafe(
           () => client.getConsumableNotes(accountId)
         );
@@ -1956,16 +2448,15 @@ function useWaitForNotes() {
 }
 
 // src/hooks/useMint.ts
-import { useCallback as useCallback15, useState as useState11 } from "react";
-import { NoteType as NoteType4 } from "@miden-sdk/miden-sdk";
+import { useCallback as useCallback16, useState as useState12 } from "react";
 function useMint() {
   const { client, isReady, sync, runExclusive, prover } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
-  const [result, setResult] = useState11(null);
-  const [isLoading, setIsLoading] = useState11(false);
-  const [stage, setStage] = useState11("idle");
-  const [error, setError] = useState11(null);
-  const mint = useCallback15(
+  const [result, setResult] = useState12(null);
+  const [isLoading, setIsLoading] = useState12(false);
+  const [stage, setStage] = useState12("idle");
+  const [error, setError] = useState12(null);
+  const mint = useCallback16(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -1974,7 +2465,7 @@ function useMint() {
       setStage("executing");
       setError(null);
       try {
-        const noteType = getNoteType4(options.noteType ?? DEFAULTS.NOTE_TYPE);
+        const noteType = getNoteType(options.noteType ?? DEFAULTS.NOTE_TYPE);
         const targetAccountIdObj = parseAccountId(options.targetAccountId);
         const faucetIdObj = parseAccountId(options.faucetId);
         setStage("proving");
@@ -2007,7 +2498,7 @@ function useMint() {
     },
     [client, isReady, prover, runExclusive, sync]
   );
-  const reset = useCallback15(() => {
+  const reset = useCallback16(() => {
     setResult(null);
     setIsLoading(false);
     setStage("idle");
@@ -2022,30 +2513,18 @@ function useMint() {
     reset
   };
 }
-function getNoteType4(type) {
-  switch (type) {
-    case "private":
-      return NoteType4.Private;
-    case "public":
-      return NoteType4.Public;
-    case "encrypted":
-      return NoteType4.Encrypted;
-    default:
-      return NoteType4.Private;
-  }
-}
 
 // src/hooks/useConsume.ts
-import { useCallback as useCallback16, useState as useState12 } from "react";
-import { NoteFilter as NoteFilter2, NoteFilterTypes as NoteFilterTypes2, NoteId } from "@miden-sdk/miden-sdk";
+import { useCallback as useCallback17, useState as useState13 } from "react";
+import { NoteFilter as NoteFilter3, NoteFilterTypes as NoteFilterTypes2, NoteId } from "@miden-sdk/miden-sdk";
 function useConsume() {
   const { client, isReady, sync, runExclusive, prover } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
-  const [result, setResult] = useState12(null);
-  const [isLoading, setIsLoading] = useState12(false);
-  const [stage, setStage] = useState12("idle");
-  const [error, setError] = useState12(null);
-  const consume = useCallback16(
+  const [result, setResult] = useState13(null);
+  const [isLoading, setIsLoading] = useState13(false);
+  const [stage, setStage] = useState13("idle");
+  const [error, setError] = useState13(null);
+  const consume = useCallback17(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -2063,7 +2542,7 @@ function useConsume() {
           const noteIds = options.noteIds.map(
             (noteId) => NoteId.fromHex(noteId)
           );
-          const filter = new NoteFilter2(NoteFilterTypes2.List, noteIds);
+          const filter = new NoteFilter3(NoteFilterTypes2.List, noteIds);
           const noteRecords = await client.getInputNotes(filter);
           const notes = noteRecords.map((record) => record.toNote());
           if (notes.length === 0) {
@@ -2095,7 +2574,7 @@ function useConsume() {
     },
     [client, isReady, prover, runExclusive, sync]
   );
-  const reset = useCallback16(() => {
+  const reset = useCallback17(() => {
     setResult(null);
     setIsLoading(false);
     setStage("idle");
@@ -2112,16 +2591,15 @@ function useConsume() {
 }
 
 // src/hooks/useSwap.ts
-import { useCallback as useCallback17, useState as useState13 } from "react";
-import { NoteType as NoteType5 } from "@miden-sdk/miden-sdk";
+import { useCallback as useCallback18, useState as useState14 } from "react";
 function useSwap() {
   const { client, isReady, sync, runExclusive, prover } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
-  const [result, setResult] = useState13(null);
-  const [isLoading, setIsLoading] = useState13(false);
-  const [stage, setStage] = useState13("idle");
-  const [error, setError] = useState13(null);
-  const swap = useCallback17(
+  const [result, setResult] = useState14(null);
+  const [isLoading, setIsLoading] = useState14(false);
+  const [stage, setStage] = useState14("idle");
+  const [error, setError] = useState14(null);
+  const swap = useCallback18(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
@@ -2130,8 +2608,8 @@ function useSwap() {
       setStage("executing");
       setError(null);
       try {
-        const noteType = getNoteType5(options.noteType ?? DEFAULTS.NOTE_TYPE);
-        const paybackNoteType = getNoteType5(
+        const noteType = getNoteType(options.noteType ?? DEFAULTS.NOTE_TYPE);
+        const paybackNoteType = getNoteType(
           options.paybackNoteType ?? DEFAULTS.NOTE_TYPE
         );
         const accountIdObj = parseAccountId(options.accountId);
@@ -2170,7 +2648,7 @@ function useSwap() {
     },
     [client, isReady, prover, runExclusive, sync]
   );
-  const reset = useCallback17(() => {
+  const reset = useCallback18(() => {
     setResult(null);
     setIsLoading(false);
     setStage("idle");
@@ -2185,41 +2663,40 @@ function useSwap() {
     reset
   };
 }
-function getNoteType5(type) {
-  switch (type) {
-    case "private":
-      return NoteType5.Private;
-    case "public":
-      return NoteType5.Public;
-    case "encrypted":
-      return NoteType5.Encrypted;
-    default:
-      return NoteType5.Private;
-  }
-}
 
 // src/hooks/useTransaction.ts
-import { useCallback as useCallback18, useState as useState14 } from "react";
+import { useCallback as useCallback19, useRef as useRef5, useState as useState15 } from "react";
 function useTransaction() {
   const { client, isReady, sync, runExclusive, prover } = useMiden();
   const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
-  const [result, setResult] = useState14(null);
-  const [isLoading, setIsLoading] = useState14(false);
-  const [stage, setStage] = useState14("idle");
-  const [error, setError] = useState14(null);
-  const execute = useCallback18(
+  const isBusyRef = useRef5(false);
+  const [result, setResult] = useState15(null);
+  const [isLoading, setIsLoading] = useState15(false);
+  const [stage, setStage] = useState15("idle");
+  const [error, setError] = useState15(null);
+  const execute = useCallback19(
     async (options) => {
       if (!client || !isReady) {
         throw new Error("Miden client is not ready");
       }
+      if (isBusyRef.current) {
+        throw new MidenError(
+          "A transaction is already in progress. Await the previous transaction before starting another.",
+          { code: "SEND_BUSY" }
+        );
+      }
+      isBusyRef.current = true;
       setIsLoading(true);
       setStage("executing");
       setError(null);
       try {
+        if (!options.skipSync) {
+          await sync();
+        }
+        const txRequest = await resolveRequest(options.request, client);
         setStage("proving");
         const txResult = await runExclusiveSafe(async () => {
           const accountIdObj = resolveAccountId2(options.accountId);
-          const txRequest = await resolveRequest(options.request, client);
           const txId = prover ? await client.submitNewTransactionWithProver(
             accountIdObj,
             txRequest,
@@ -2238,11 +2715,12 @@ function useTransaction() {
         throw error2;
       } finally {
         setIsLoading(false);
+        isBusyRef.current = false;
       }
     },
     [client, isReady, prover, runExclusive, sync]
   );
-  const reset = useCallback18(() => {
+  const reset = useCallback19(() => {
     setResult(null);
     setIsLoading(false);
     setStage("idle");
@@ -2267,16 +2745,337 @@ async function resolveRequest(request, client) {
   return request;
 }
 
+// src/hooks/useSessionAccount.ts
+import { useCallback as useCallback20, useEffect as useEffect8, useRef as useRef6, useState as useState16 } from "react";
+import { AccountStorageMode as AccountStorageMode3 } from "@miden-sdk/miden-sdk";
+function useSessionAccount(options) {
+  const { client, isReady, sync, runExclusive } = useMiden();
+  const runExclusiveSafe = runExclusive ?? runExclusiveDirect;
+  const setAccounts = useMidenStore((state) => state.setAccounts);
+  const [sessionAccountId, setSessionAccountId] = useState16(null);
+  const [step, setStep] = useState16("idle");
+  const [error, setError] = useState16(null);
+  const cancelledRef = useRef6(false);
+  const isBusyRef = useRef6(false);
+  const storagePrefix = options.storagePrefix ?? "miden-session";
+  const pollIntervalMs = options.pollIntervalMs ?? 3e3;
+  const maxWaitMs = options.maxWaitMs ?? 6e4;
+  const storageMode = options.walletOptions?.storageMode ?? "public";
+  const mutable = options.walletOptions?.mutable ?? DEFAULTS.WALLET_MUTABLE;
+  const authScheme = options.walletOptions?.authScheme ?? DEFAULTS.AUTH_SCHEME;
+  const fundRef = useRef6(options.fund);
+  fundRef.current = options.fund;
+  useEffect8(() => {
+    try {
+      const stored = localStorage.getItem(`${storagePrefix}:accountId`);
+      const storedReady = localStorage.getItem(`${storagePrefix}:ready`);
+      if (stored && stored.length > 0) {
+        const validationId = parseAccountId(stored);
+        validationId?.free?.();
+        setSessionAccountId(stored);
+        if (storedReady === "true") {
+          setStep("ready");
+        }
+      }
+    } catch {
+      localStorage.removeItem(`${storagePrefix}:accountId`);
+      localStorage.removeItem(`${storagePrefix}:ready`);
+    }
+  }, [storagePrefix]);
+  const initialize = useCallback20(async () => {
+    if (!client || !isReady) {
+      throw new Error("Miden client is not ready");
+    }
+    if (isBusyRef.current) {
+      throw new MidenError(
+        "Session account initialization is already in progress.",
+        { code: "OPERATION_BUSY" }
+      );
+    }
+    isBusyRef.current = true;
+    cancelledRef.current = false;
+    setError(null);
+    try {
+      let walletId = sessionAccountId;
+      if (!walletId) {
+        setStep("creating");
+        const resolvedStorageMode = getStorageMode3(storageMode);
+        const wallet = await runExclusiveSafe(async () => {
+          const w = await client.newWallet(
+            resolvedStorageMode,
+            mutable,
+            authScheme
+          );
+          ensureAccountBech32(w);
+          const accounts = await client.getAccounts();
+          setAccounts(accounts);
+          return w;
+        });
+        if (cancelledRef.current) return;
+        walletId = wallet.id().toString();
+        setSessionAccountId(walletId);
+        localStorage.setItem(`${storagePrefix}:accountId`, walletId);
+      }
+      setStep("funding");
+      await fundRef.current(walletId);
+      if (cancelledRef.current) return;
+      setStep("consuming");
+      await waitAndConsume(
+        client,
+        runExclusiveSafe,
+        walletId,
+        pollIntervalMs,
+        maxWaitMs,
+        cancelledRef
+      );
+      if (cancelledRef.current) return;
+      setStep("ready");
+      localStorage.setItem(`${storagePrefix}:ready`, "true");
+      await sync();
+    } catch (err) {
+      if (!cancelledRef.current) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        setError(error2);
+        setStep("idle");
+        throw error2;
+      }
+    } finally {
+      isBusyRef.current = false;
+    }
+  }, [
+    client,
+    isReady,
+    sync,
+    runExclusiveSafe,
+    sessionAccountId,
+    storageMode,
+    mutable,
+    authScheme,
+    storagePrefix,
+    pollIntervalMs,
+    maxWaitMs,
+    setAccounts
+  ]);
+  const reset = useCallback20(() => {
+    cancelledRef.current = true;
+    isBusyRef.current = false;
+    setSessionAccountId(null);
+    setStep("idle");
+    setError(null);
+    localStorage.removeItem(`${storagePrefix}:accountId`);
+    localStorage.removeItem(`${storagePrefix}:ready`);
+  }, [storagePrefix]);
+  return {
+    initialize,
+    sessionAccountId,
+    isReady: step === "ready",
+    step,
+    error,
+    reset
+  };
+}
+function getStorageMode3(mode) {
+  switch (mode) {
+    case "private":
+      return AccountStorageMode3.private();
+    case "public":
+      return AccountStorageMode3.public();
+    default:
+      return AccountStorageMode3.public();
+  }
+}
+async function waitAndConsume(client, runExclusiveSafe, walletId, pollIntervalMs, maxWaitMs, cancelledRef) {
+  const deadline = Date.now() + maxWaitMs;
+  while (Date.now() < deadline) {
+    if (cancelledRef.current) return;
+    await runExclusiveSafe(
+      () => client.syncState()
+    );
+    if (cancelledRef.current) return;
+    const consumed = await runExclusiveSafe(async () => {
+      const accountIdObj = parseAccountId(walletId);
+      const consumable = await client.getConsumableNotes(accountIdObj);
+      if (consumable.length === 0) return false;
+      const notes = consumable.map((c) => c.inputNoteRecord().toNote());
+      const txRequest = client.newConsumeTransactionRequest(notes);
+      const freshAccountId = parseAccountId(walletId);
+      await client.submitNewTransaction(freshAccountId, txRequest);
+      return true;
+    });
+    if (consumed) return;
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+  throw new Error("Timeout waiting for session wallet funding");
+}
+
+// src/utils/bytes.ts
+function bytesToBigInt(bytes) {
+  let result = 0n;
+  for (let i = 0; i < bytes.length; i++) {
+    result = result << 8n | BigInt(bytes[i]);
+  }
+  return result;
+}
+function bigIntToBytes(value, length) {
+  if (value < 0n) {
+    throw new RangeError("bigIntToBytes: value must be non-negative");
+  }
+  const maxValue = (1n << BigInt(length * 8)) - 1n;
+  if (value > maxValue) {
+    throw new RangeError(
+      `bigIntToBytes: value ${value} does not fit in ${length} byte(s) (max ${maxValue})`
+    );
+  }
+  const bytes = new Uint8Array(length);
+  let remaining = value;
+  for (let i = length - 1; i >= 0; i--) {
+    bytes[i] = Number(remaining & 0xffn);
+    remaining >>= 8n;
+  }
+  return bytes;
+}
+function concatBytes(...arrays) {
+  const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}
+
+// src/utils/walletDetection.ts
+async function waitForWalletDetection(adapter, timeoutMs = 5e3) {
+  if (adapter.readyState === "Installed") return;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      adapter.off("readyStateChange", onReady);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      adapter.off("readyStateChange", onReady);
+      reject(
+        new Error(
+          `Wallet extension not detected within ${timeoutMs}ms. Is the browser extension installed and enabled?`
+        )
+      );
+    }, timeoutMs);
+    const onReady = (state) => {
+      if (state === "Installed") settle();
+    };
+    adapter.on("readyStateChange", onReady);
+    if (adapter.readyState === "Installed") settle();
+  });
+}
+
+// src/utils/storage.ts
+async function migrateStorage(options) {
+  if (typeof window === "undefined") return false;
+  const versionKey = options.versionKey ?? "miden:storageVersion";
+  const stored = localStorage.getItem(versionKey);
+  if (stored === options.version) return false;
+  if (options.onBeforeClear) {
+    await options.onBeforeClear();
+  }
+  await clearMidenStorage();
+  localStorage.setItem(versionKey, options.version);
+  if (options.reloadOnClear !== false) {
+    window.location.reload();
+  }
+  return true;
+}
+async function clearMidenStorage() {
+  if (typeof indexedDB === "undefined") return;
+  try {
+    const databases = await indexedDB.databases();
+    const midenDbs = databases.filter(
+      (db) => db.name?.toLowerCase().includes("miden")
+    );
+    await Promise.all(
+      midenDbs.map(
+        (db) => new Promise((resolve, reject) => {
+          if (!db.name) {
+            resolve();
+            return;
+          }
+          const req = indexedDB.deleteDatabase(db.name);
+          req.onsuccess = () => resolve();
+          req.onerror = () => reject(req.error);
+          req.onblocked = () => {
+            console.warn(
+              `IndexedDB "${db.name}" delete was blocked \u2014 close other tabs using this database.`
+            );
+            resolve();
+          };
+        })
+      )
+    );
+  } catch {
+  }
+}
+function createMidenStorage(prefix) {
+  const fullKey = (key) => `${prefix}:${key}`;
+  return {
+    get(key) {
+      try {
+        const raw = localStorage.getItem(fullKey(key));
+        if (raw === null) return null;
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    set(key, value) {
+      try {
+        localStorage.setItem(fullKey(key), JSON.stringify(value));
+      } catch (e) {
+        console.warn(`Failed to write localStorage key "${fullKey(key)}":`, e);
+      }
+    },
+    remove(key) {
+      localStorage.removeItem(fullKey(key));
+    },
+    clear() {
+      const keysToRemove = [];
+      for (let i = 0; i < localStorage.length; i++) {
+        const k = localStorage.key(i);
+        if (k?.startsWith(`${prefix}:`)) {
+          keysToRemove.push(k);
+        }
+      }
+      keysToRemove.forEach((k) => localStorage.removeItem(k));
+    }
+  };
+}
+
 // src/index.ts
 installAccountBech32();
 export {
   DEFAULTS,
+  MidenError,
   MidenProvider,
   SignerContext,
+  accountIdsEqual,
+  bigIntToBytes,
+  bytesToBigInt,
+  clearMidenStorage,
+  concatBytes,
+  createMidenStorage,
+  createNoteAttachment,
   formatAssetAmount,
   formatNoteSummary,
   getNoteSummary,
+  migrateStorage,
+  normalizeAccountId,
   parseAssetAmount,
+  readNoteAttachment,
   toBech32AccountId,
   useAccount,
   useAccounts,
@@ -2290,13 +3089,17 @@ export {
   useMidenClient,
   useMint,
   useMultiSend,
+  useNoteStream,
   useNotes,
   useSend,
+  useSessionAccount,
   useSigner,
   useSwap,
   useSyncState,
   useTransaction,
   useTransactionHistory,
   useWaitForCommit,
-  useWaitForNotes
+  useWaitForNotes,
+  waitForWalletDetection,
+  wrapWasmError
 };