@miden-sdk/react 0.14.4 → 0.14.8

package/CLAUDE.md

@@ -5,7 +5,7 @@
 ```bash
 npm install @miden-sdk/react @miden-sdk/miden-sdk
 # or
-yarn add @miden-sdk/react @miden-sdk/miden-sdk
+pnpm add @miden-sdk/react @miden-sdk/miden-sdk
 ```
 
 ## Getting Started
@@ -45,36 +45,37 @@ function App() {
 
 ## Reading Data (Query Hooks)
 
-All query hooks return `{ data, isLoading, error, refetch }`.
+Query hooks return `{ ...data, isLoading, error, refetch }` — the data fields are spread directly onto the result object, with hook-specific names (no generic `data` field).
 
 ### List Accounts
 ```tsx
-const { data: accounts, isLoading } = useAccounts();
+const { accounts, wallets, faucets, isLoading } = useAccounts();
 
-// accounts.wallets - regular accounts
-// accounts.faucets - token faucets
-// accounts.all - everything
+// wallets - regular accounts
+// faucets - token faucets
+// accounts - both, combined
 ```
 
 ### Get Account Details
 ```tsx
-const { data: account } = useAccount(accountId);
+const { account, isLoading } = useAccount(accountId);
 
-// account.id, account.nonce, account.bech32id()
-// account.balance(faucetId) - get token balance
+// account.id(), account.nonce(), account.bech32id()
+// account.vault().getBalance(assetId) - get token balance
 ```
 
 ### Get Notes
 ```tsx
-const { data: notes } = useNotes();
+const { notes, consumableNotes, noteSummaries, consumableNoteSummaries } = useNotes();
 
-// notes.input - incoming notes
-// notes.consumable - ready to claim
+// notes - all input notes for this account
+// consumableNotes - subset that's ready to claim
+// noteSummaries / consumableNoteSummaries - same lists, projected to UI-friendly summaries
 ```
 
 ### Check Sync Status
 ```tsx
-const { syncHeight, isSyncing, sync } = useSyncState();
+const { syncHeight, isSyncing, lastSyncTime, sync, error } = useSyncState();
 
 // Manual sync
 await sync();
@@ -82,19 +83,19 @@ await sync();
 
 ### Get Token Metadata
 ```tsx
-const { data: metadata } = useAssetMetadata(faucetId);
+const { metadata, isLoading } = useAssetMetadata(assetId);
 // metadata.symbol, metadata.decimals
 ```
 
 ## Writing Data (Mutation Hooks)
 
-All mutation hooks return `{ mutate, data, isLoading, stage, error, reset }`.
+Mutation hooks return `{ <action>, result, isLoading, stage, error, reset }` — the action callback is named after the hook (`send`, `consume`, `mint`, ...) and the resolved value is on `result`.
 
 **Transaction stages:** `idle` → `executing` → `proving` → `submitting` → `complete`
 
 ### Create Wallet
 ```tsx
-const { mutate: createWallet, isLoading } = useCreateWallet();
+const { createWallet, isLoading } = useCreateWallet();
 
 const account = await createWallet({
   storageMode: "private",  // "private" | "public" | "network"
@@ -103,12 +104,12 @@ const account = await createWallet({
 
 ### Send Tokens
 ```tsx
-const { mutate: send, stage } = useSend();
+const { send, stage } = useSend();
 
 await send({
   from: senderAccountId,
   to: recipientAccountId,
-  faucetId: tokenFaucetId,
+  assetId: tokenFaucetId,
   amount: 1000n,
   noteType: "private",  // "private" | "public"
 });
@@ -116,20 +117,20 @@ await send({
 
 ### Send to Multiple Recipients
 ```tsx
-const { mutate: multiSend } = useMultiSend();
+const { multiSend } = useMultiSend();
 
 await multiSend({
   from: senderAccountId,
-  outputs: [
-    { to: recipient1, faucetId, amount: 500n },
-    { to: recipient2, faucetId, amount: 300n },
+  recipients: [
+    { to: recipient1, assetId, amount: 500n },
+    { to: recipient2, assetId, amount: 300n },
   ],
 });
 ```
 
 ### Claim Notes
 ```tsx
-const { mutate: consume } = useConsume();
+const { consume } = useConsume();
 
 await consume({
   accountId: myAccountId,
@@ -139,7 +140,7 @@ await consume({
 
 ### Mint Tokens (Faucet Owner)
 ```tsx
-const { mutate: mint } = useMint();
+const { mint } = useMint();
 
 await mint({
   faucetId: myFaucetId,
@@ -150,7 +151,7 @@ await mint({
 
 ### Create Faucet
 ```tsx
-const { mutate: createFaucet } = useCreateFaucet();
+const { createFaucet } = useCreateFaucet();
 
 const faucet = await createFaucet({
   symbol: "TOKEN",
@@ -165,11 +166,11 @@ const faucet = await createFaucet({
 ### Show Transaction Progress
 ```tsx
 function SendButton() {
-  const { mutate: send, stage, isLoading, error } = useSend();
+  const { send, stage, isLoading, error } = useSend();
 
   const handleSend = async () => {
     try {
-      await send({ from, to, faucetId, amount });
+      await send({ from, to, assetId, amount });
     } catch (err) {
       console.error("Transaction failed:", err);
     }
@@ -207,11 +208,11 @@ const text = formatNoteSummary(summary);  // "1.5 TOKEN"
 
 ### Wait for Transaction Confirmation
 ```tsx
-const { mutate: waitForCommit } = useWaitForCommit();
+const { waitForCommit } = useWaitForCommit();
 
 // After sending
 const result = await send({ ... });
-await waitForCommit({ transactionId: result.transactionId });
+await waitForCommit({ txId: result.txId });
 ```
 
 ### Access Client Directly
@@ -316,7 +317,8 @@ import { SignerContext } from "@miden-sdk/react";
   storeName: `mywallet_${userAddress}`,  // unique per user for DB isolation
   isConnected: true,
   accountConfig: {
-    publicKey: userPublicKeyCommitment,  // Uint8Array
+    publicKeyCommitment: userPublicKeyCommitment,  // Uint8Array
+    accountType: "RegularAccountUpdatableCode",
     storageMode: "private",
   },
   signCb: async (pubKey, signingInputs) => {
@@ -377,23 +379,40 @@ account.bech32id();  // "miden1qy35..."
 
 ## Hook Reference
 
-| Hook | Returns | Purpose |
-|------|---------|---------|
-| `useAccounts()` | `{ wallets, faucets, all }` | List all accounts |
-| `useAccount(id)` | `Account` | Account details + balances |
-| `useNotes(filter?)` | `{ input, consumable }` | Available notes |
-| `useSyncState()` | `{ syncHeight, sync() }` | Sync status |
-| `useAssetMetadata(id)` | `{ symbol, decimals }` | Token info |
-| `useCreateWallet()` | `Account` | Create wallet |
-| `useCreateFaucet()` | `Account` | Create faucet |
-| `useImportAccount()` | `Account` | Import account |
-| `useSend()` | `TransactionResult` | Send tokens |
-| `useMultiSend()` | `TransactionResult` | Multi-recipient send |
-| `useMint()` | `TransactionResult` | Mint tokens |
-| `useConsume()` | `TransactionResult` | Claim notes |
-| `useSwap()` | `TransactionResult` | Atomic swap |
-| `useTransaction()` | `TransactionResult` | Custom transaction |
-| `useCompile()` | `{ component, txScript, noteScript }` | Compile MASM into `AccountComponent` / `TransactionScript` / `NoteScript` |
+Query hooks return `{ ...data, isLoading, error, refetch }`. Mutation hooks return `{ <action>, result, isLoading, stage, error, reset }`.
+
+### Query (read)
+| Hook | Data fields | Purpose |
+|------|-------------|---------|
+| `useAccounts()` | `accounts`, `wallets`, `faucets` | List local accounts |
+| `useAccount(id)` | `account` | Account details + balances |
+| `useNotes(filter?)` | `notes`, `consumableNotes`, `noteSummaries`, `consumableNoteSummaries` | Input notes + UI summaries |
+| `useNoteStream(filter?)` | streaming variant of `useNotes` | Auto-updates as notes arrive |
+| `useSyncState()` | `syncHeight`, `isSyncing`, `lastSyncTime`, `sync()` | Sync status + manual trigger |
+| `useSyncControl()` | `pause()`, `resume()`, `isPaused` | Pause/resume the auto-sync timer |
+| `useAssetMetadata(id)` | `metadata: { symbol, decimals }` | Token info |
+| `useTransactionHistory(...)` | `transactions` | Local transaction log |
+| `useSessionAccount()` | `account` | The signer's connected account |
+| `useWaitForNotes(...)` | resolves when matching notes appear | Pull-style note waiting |
+
+### Mutation (write)
+| Hook | Action | Returns on success |
+|------|--------|--------------------|
+| `useCreateWallet()` | `createWallet({ storageMode })` | `Account` |
+| `useCreateFaucet()` | `createFaucet({ symbol, decimals, ... })` | `Account` |
+| `useImportAccount()` | `importAccount(...)` | `Account` |
+| `useImportNote()` | `importNote(...)` | imported `InputNoteRecord` |
+| `useExportNote()` | `exportNote(...)` | serialized note bytes |
+| `useImportStore()` / `useExportStore()` | store import/export | bytes / `void` |
+| `useSend()` | `send({ from, to, assetId, amount, noteType })` | `SendResult` (with `txId`, `note`) |
+| `useMultiSend()` | `multiSend({ from, recipients })` | `TransactionResult` |
+| `useMint()` | `mint({ faucetId, to, amount })` | `TransactionResult` |
+| `useConsume()` | `consume({ accountId, notes })` | `TransactionResult` |
+| `useSwap()` | `swap({ ... })` | `TransactionResult` |
+| `useTransaction()` | `transact({ ... })` | `TransactionResult` (custom tx) |
+| `useExecuteProgram()` | `execute(...)` | program output |
+| `useCompile()` | `compile({ source })` | `{ component, txScript, noteScript }` |
+| `useWaitForCommit()` | `waitForCommit({ txId })` | resolves when committed on-chain |
 
 ## Type Imports
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -21,7 +21,7 @@ React hooks library for the Miden Web Client. Provides a simple, ergonomic inter
 ```bash
 npm install @miden-sdk/react @miden-sdk/miden-sdk
 # or
-yarn add @miden-sdk/react @miden-sdk/miden-sdk
+pnpm add @miden-sdk/react @miden-sdk/miden-sdk
 # or
 pnpm add @miden-sdk/react @miden-sdk/miden-sdk
 ```
@@ -32,14 +32,14 @@ From `packages/react-sdk`:
 
 ```bash
 # Unit tests
-yarn test:unit
+pnpm test:unit
 
 # Integration tests (Playwright) in test/
 # Build the web-client dist first:
-cd ../../crates/web-client && yarn build
+cd ../../crates/web-client && pnpm build
 cd ../../packages/react-sdk
-yarn playwright install --with-deps
-yarn test:integration
+pnpm exec playwright install --with-deps
+pnpm test:integration
 ```
 
 ## Quick Start
@@ -119,14 +119,25 @@ function App() {
 }
 ```
 
-## Next.js & SSR
+## Subpaths: Eager / Lazy × ST / MT
+
+The React SDK ships **four** bundle variants built from a single source tree. The two axes are independent:
+
+- **WASM init timing** — _eager_ awaits at SDK load (TLA); _lazy_ leaves init to `MidenClient.ready()` or first awaiting method.
+- **WASM threading model** — _ST_ (single-threaded) loads anywhere; _MT_ (multi-threaded via `wasm-bindgen-rayon`) parallelizes proving but **requires the page to be cross-origin-isolated**.
+
+| Subpath                            | SDK variant                       | When to use                                                |
+| ---------------------------------- | --------------------------------- | ---------------------------------------------------------- |
+| `@miden-sdk/react`                 | eager + ST                        | Plain browser apps, Vite, CRA, esbuild — no host control needed. |
+| `@miden-sdk/react/lazy`            | lazy + ST                         | Next.js / SSR, Capacitor (iOS/Android WKWebView).          |
+| `@miden-sdk/react/mt`              | eager + MT                        | dApps with COOP/COEP set; want fast proving and tolerate TLA. |
+| `@miden-sdk/react/mt/lazy`         | lazy + MT                         | dApps with COOP/COEP set, on Next.js or anywhere TLA can't run. |
 
-The React SDK is Next.js-compatible out of the box: it ships two bundle variants built from a single source tree, and both internally import `@miden-sdk/miden-sdk/lazy` — the lazy entry point that does **not** use a top-level `await`. Nothing initializes WASM at module evaluation, so server-side rendering never hangs.
+All four exports have identical APIs. The choice affects which `@miden-sdk/miden-sdk` variant your bundler resolves and therefore the underlying WASM behavior.
 
-- Default (`@miden-sdk/react`) — internally consumes the eager SDK. Use this in plain browser apps, Vite, CRA.
-- `@miden-sdk/react/lazy` — internally consumes the lazy SDK. Use this in Next.js (app router or pages), SSR, or inside a Capacitor iOS/Android WKWebView host (the wallet shell uses this).
+### Next.js / SSR
 
-Both exports have identical APIs. The choice only affects which `@miden-sdk/miden-sdk` variant your bundler ends up resolving.
+The lazy variants (`/lazy`, `/mt/lazy`) do not run a top-level `await` at module evaluation. Server-side rendering never hangs on WASM init. Use these in any Next.js app or Capacitor host:
 
 ```tsx
 // Next.js: app/providers.tsx
@@ -141,6 +152,50 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
 `MidenProvider` gates child rendering on `isReady`, so you don't have to await anything manually in components — hooks already fire only after WASM is initialized.
 
+### Multi-threaded proving (`/mt`, `/mt/lazy`)
+
+The MT variants enable `wasm-bindgen-rayon` for ~3–5× faster local proving on commodity laptops. Same API surface as the ST variants. Two extra requirements compared to ST:
+
+**1. The page must be cross-origin-isolated.** Set the host response headers:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+Without those, the browser refuses to construct `WebAssembly.Memory({ shared: true })` and the MT WASM fails to instantiate at SDK load. See the underlying [`@miden-sdk/miden-sdk` README](https://github.com/0xMiden/web-sdk/blob/main/crates/web-client/README.md#setting-cross-origin-isolation-headers) for snippets per host (Vite, Next.js, Express, browser-extension manifests). COEP also blocks cross-origin resources unless they carry CORP / proper CORS — opt in deliberately.
+
+**2. Bring up the rayon thread pool once at startup.** Re-exported as `initThreadPool(n)`. The React SDK does NOT call this for you — consumers must `await` it before the first transaction:
+
+```tsx
+"use client";
+import { useEffect } from "react";
+import { MidenProvider, useMiden } from "@miden-sdk/react/mt/lazy";
+import { initThreadPool } from "@miden-sdk/miden-sdk/mt/lazy";
+
+function ThreadPoolBoot() {
+  const { isReady } = useMiden();
+  useEffect(() => {
+    if (!isReady) return;
+    void initThreadPool(navigator.hardwareConcurrency);
+  }, [isReady]);
+  return null;
+}
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <MidenProvider config={{ rpcUrl: "testnet" }}>
+      <ThreadPoolBoot />
+      {children}
+    </MidenProvider>
+  );
+}
+```
+
+`initThreadPool` is idempotent — calling it multiple times resolves with the existing pool. Without this call, the rayon global thread pool spawns zero workers on `wasm32` and every `par_iter(...)` falls through to a sequential loop. You'd be shipping multi-threaded WASM that runs single-threaded.
+
+If you can't satisfy the COI requirement (third-party host, CDN that won't set headers), stay on the default `@miden-sdk/react` / `/lazy` subpaths — they ship the ST WASM and load anywhere.
+
 ### Constructing wasm-bindgen types directly in Next.js
 
 Hooks accept strings for account IDs, asset IDs, and note IDs (auto-detecting hex vs. bech32) and parse them internally inside async callbacks, so **most apps never touch wasm-bindgen types directly**. If you do need to (e.g. to inspect an ID's prefix/suffix, validate a pasted string, or use a low-level API like `new Felt(…)`), import from `@miden-sdk/miden-sdk/lazy` and gate the call on `isReady`:
@@ -1616,8 +1671,8 @@ One runnable Vite example lives in `examples/`:
 
 ```bash
 cd examples/wallet
-yarn install
-yarn dev
+pnpm install
+pnpm dev
 ```
 
 ## Requirements

package/dist/index.d.ts

@@ -259,7 +259,7 @@ interface CreateWalletOptions {
     storageMode?: StorageMode;
     /** Whether code can be updated. Default: true */
     mutable?: boolean;
-    /** Auth scheme. Default: AuthScheme.AuthRpoFalcon512 */
+    /** Auth scheme. Default: `AuthScheme.Falcon` */
     authScheme?: AuthScheme;
     /** Initial seed for deterministic account ID */
     initSeed?: Uint8Array;
@@ -273,7 +273,7 @@ interface CreateFaucetOptions {
     maxSupply: bigint | number;
     /** Storage mode. Default: private */
     storageMode?: StorageMode;
-    /** Auth scheme. Default: AuthScheme.AuthRpoFalcon512 */
+    /** Auth scheme. Default: `AuthScheme.Falcon` */
     authScheme?: AuthScheme;
 }
 type ImportAccountOptions = {
@@ -505,7 +505,7 @@ declare const DEFAULTS: {
     readonly AUTO_SYNC_INTERVAL: 15000;
     readonly STORAGE_MODE: "private";
     readonly WALLET_MUTABLE: true;
-    readonly AUTH_SCHEME: AuthScheme.AuthRpoFalcon512;
+    readonly AUTH_SCHEME: "falcon";
     readonly NOTE_TYPE: "private";
     readonly FAUCET_DECIMALS: 8;
 };