create-miden-app 1.0.6 → 1.0.7

package/template/.claude/skills/react-sdk-patterns/SKILL.md

@@ -7,7 +7,7 @@ description: Complete guide to building Miden frontends with @miden-sdk/react ho
 
 ## SDK Choice
 
-ALWAYS use `@miden-sdk/react` hooks. Only fall back to raw `@miden-sdk/miden-sdk` WebClient via `useMidenClient()` for operations not covered by hooks. The React SDK handles WASM safety (runExclusive), state management (Zustand), auto-sync, and transaction stage tracking automatically.
+ALWAYS use `@miden-sdk/react` hooks. Only fall back to the raw `WasmWebClient` (exported as `WebClient`) via `useMidenClient()` for operations not covered by hooks. The React SDK handles WASM safety (runExclusive), state management (Zustand), auto-sync, and transaction stage tracking automatically.
 
 ## MidenProvider Configuration
 
@@ -16,8 +16,8 @@ import { MidenProvider } from "@miden-sdk/react";
 
 <MidenProvider
   config={{
-    rpcUrl: "devnet",           // "devnet" | "testnet" | "localhost" | custom URL
-    prover: "devnet",           // "local" | "devnet" | "testnet" | custom URL
+    rpcUrl: "testnet",          // "devnet" | "testnet" | "localhost" | custom URL
+    prover: "testnet",          // "local" | "devnet" | "testnet" | custom URL
     autoSyncInterval: 15000,    // ms, set to 0 to disable. Default: 15000
     noteTransportUrl: "...",    // optional: for private note delivery
   }}
@@ -30,8 +30,8 @@ import { MidenProvider } from "@miden-sdk/react";
 
 | Network | rpcUrl | Use When |
 |---------|--------|----------|
-| Devnet | `"devnet"` | Development, testing with fake tokens |
-| Testnet | `"testnet"` | Pre-production testing |
+| Testnet | `"testnet"` | Recommended for new projects - primary development network |
+| Devnet | `"devnet"` | Early-access testing (may lag feature parity with testnet) |
 | Localhost | `"localhost"` | Local node at `http://localhost:57291` |
 
 ## Query Hooks
@@ -41,31 +41,51 @@ Each returns its own result shape plus `isLoading`, `error`, `refetch`.
 ### useAccounts()
 ```tsx
 const { accounts, wallets, faucets, isLoading, error, refetch } = useAccounts();
-// wallets — AccountHeader[] (regular wallet accounts)
-// faucets — AccountHeader[] (token faucet accounts)
-// accounts — AccountHeader[] (everything)
+// wallets - AccountHeader[] (regular wallet accounts)
+// faucets - AccountHeader[] (token faucet accounts)
+// accounts - AccountHeader[] (everything)
 ```
 
 ### useAccount(accountId: string)
 ```tsx
 const { account, assets, getBalance, isLoading, error, refetch } = useAccount(accountId);
-// account — Account object (.id, .nonce, .bech32id())
-// assets — AssetBalance[] (assetId, amount, symbol?, decimals?)
-// getBalance(faucetId) — bigint balance for specific token
+// account - Account object (.id, .nonce, .bech32id())
+// assets - AssetBalance[] (assetId, amount, symbol?, decimals?)
+// getBalance(faucetId) - bigint balance for specific token
 ```
 
 ### useNotes(filter?)
 ```tsx
 const { notes, consumableNotes, noteSummaries, consumableNoteSummaries, isLoading, error, refetch } = useNotes();
-// notes — InputNoteRecord[]
-// consumableNotes — ConsumableNoteRecord[]
-// noteSummaries — NoteSummary[] (id, assets, sender)
-// consumableNoteSummaries — NoteSummary[]
+// notes - InputNoteRecord[]
+// consumableNotes - ConsumableNoteRecord[]
+// noteSummaries - NoteSummary[] (id, assets, sender)
+// consumableNoteSummaries - NoteSummary[]
 
 // Filter by account:
 const { notes } = useNotes({ accountId: "0x..." });
 // Filter by status:
 const { notes } = useNotes({ status: "committed" });
+// Filter by sender:
+const { notes } = useNotes({ sender: "0x..." });
+// Exclude specific notes:
+const { notes } = useNotes({ excludeIds: ["0xnote1", "0xnote2"] });
+```
+
+### useNoteStream(options?)
+```tsx
+const { notes, latest, markHandled, markAllHandled, snapshot, isLoading, error } = useNoteStream();
+// notes - StreamedNote[] (matching filter criteria)
+// latest - most recent StreamedNote (convenience)
+// markHandled(noteId) - exclude a note from future renders
+// markAllHandled() - exclude all current notes
+// snapshot() - capture { ids, timestamp } for cross-phase filtering
+
+// Options:
+const { notes } = useNoteStream({ status: "committed", sender: "0x..." });
+const { notes } = useNoteStream({ since: Date.now() - 60000 }); // last 60s
+const { notes } = useNoteStream({ excludeIds: new Set(["0xnote1"]) });
+const { notes } = useNoteStream({ amountFilter: (amount) => amount > 100n });
 ```
 
 ### useSyncState()
@@ -77,11 +97,11 @@ await sync(); // Manual sync
 ### useAssetMetadata(faucetId: string | string[])
 ```tsx
 const { assetMetadata } = useAssetMetadata(faucetId);
-// assetMetadata — Map<string, AssetMetadata>
+// assetMetadata - Map<string, AssetMetadata>
 // Each entry: { assetId, symbol?, decimals? }
 const meta = assetMetadata.get(faucetId);
-// meta.symbol — "TEST"
-// meta.decimals — 8
+// meta.symbol - "TEST"
+// meta.decimals - 8
 ```
 
 ### useTransactionHistory(options?)
@@ -117,6 +137,20 @@ const account = await createFaucet({
 });
 ```
 
+### useImportAccount()
+```tsx
+const { importAccount, account, isImporting, error, reset } = useImportAccount();
+
+// Import by account ID (network lookup):
+const account = await importAccount({ type: "id", accountId: "0x..." });
+
+// Import from file:
+const account = await importAccount({ type: "file", file: accountFileOrBytes });
+
+// Import from seed:
+const account = await importAccount({ type: "seed", seed: seedBytes, mutable: true });
+```
+
 ### useSend()
 ```tsx
 const { send, result, isLoading, stage, error, reset } = useSend();
@@ -128,6 +162,8 @@ await send({
   noteType: "private",     // "private" | "public". Default: "private"
   recallHeight: 100,       // optional: sender can reclaim after this block
   timelockHeight: 50,      // optional: recipient can consume after this block
+  sendAll: true,           // optional: send entire balance (ignores amount)
+  attachment: [1n, 2n],    // optional: arbitrary data attached to the note
 });
 ```
 
@@ -139,9 +175,10 @@ await sendMany({
   assetId: faucetId,
   recipients: [
     { to: recipient1, amount: 500n },
-    { to: recipient2, amount: 300n },
+    { to: recipient2, amount: 300n, noteType: "public" },          // per-recipient override
+    { to: recipient3, amount: 200n, attachment: [1n, 2n, 3n] },    // per-recipient attachment
   ],
-  noteType: "private",
+  noteType: "private",     // default for all recipients
 });
 ```
 
@@ -161,7 +198,7 @@ await mint({
 const { consume, result, isLoading, stage, error, reset } = useConsume();
 await consume({
   accountId: myAccountId,
-  noteIds: [noteId1, noteId2],
+  notes: [noteId1, noteId2],   // accepts: hex string IDs, NoteId, InputNoteRecord, or Note
 });
 ```
 
@@ -179,7 +216,7 @@ await swap({
 });
 ```
 
-### useTransaction() — Escape Hatch
+### useTransaction() - Escape Hatch
 ```tsx
 const { execute, result, isLoading, stage, error, reset } = useTransaction();
 
@@ -196,7 +233,7 @@ await execute({
 ### useWaitForCommit()
 ```tsx
 const { waitForCommit } = useWaitForCommit();
-await waitForCommit(result.transactionId, {
+await waitForCommit(result.txId, {  // useSend returns { txId, note }; other hooks use { transactionId }
   timeoutMs: 10000,   // Default: 10000
   intervalMs: 1000,    // Default: 1000
 });
@@ -212,6 +249,25 @@ await waitForConsumableNotes({
 });
 ```
 
+### useSessionAccount(options)
+```tsx
+const { initialize, sessionAccountId, isReady, step, error, reset } = useSessionAccount({
+  fund: async (sessionId) => {
+    // Called after session wallet is created - fund it here
+    await send({ from: mainWallet, to: sessionId, assetId: faucetId, amount: 100n });
+  },
+  assetId: faucetId,              // optional: for note filtering
+  walletOptions: {                // optional: session wallet creation options
+    storageMode: "private",
+    mutable: true,
+    authScheme: 0,
+  },
+  pollIntervalMs: 3000,           // optional: funding detection interval. Default: 3000
+});
+// Steps: "idle" → "creating" → "funding" → "consuming" → "ready"
+// Call initialize() to start the flow. isReady becomes true when fully funded.
+```
+
 ## Transaction Progress UI
 
 ```tsx
@@ -236,9 +292,9 @@ No signer provider needed. Keys are managed in the browser via IndexedDB.
 
 ### External Signers
 Wrap MidenProvider with a signer provider. Three pre-built options:
-- `ParaSignerProvider` from `@miden-sdk/para` — EVM wallets
-- `TurnkeySignerProvider` from `@miden-sdk/miden-turnkey-react` — passkey auth
-- `MidenFiSignerProvider` from `@miden-sdk/wallet-adapter-react` — MidenFi wallet
+- `ParaSignerProvider` from `@miden-sdk/para` - EVM wallets
+- `TurnkeySignerProvider` from `@miden-sdk/miden-turnkey-react` - passkey auth
+- `MidenFiSignerProvider` from `@miden-sdk/miden-wallet-adapter-react` - MidenFi wallet
 
 ```tsx
 // Example: Para signer wrapping MidenProvider
@@ -248,7 +304,7 @@ import { ParaSignerProvider } from "@miden-sdk/para";
 </ParaSignerProvider>
 ```
 
-### useSigner() — Unified Interface
+### useSigner() - Unified Interface
 ```tsx
 const { isConnected, connect, disconnect, name } = useSigner();
 ```
@@ -275,7 +331,7 @@ const client = useMidenClient(); // throws if not ready
 const { runExclusive } = useMiden();
 
 // For operations not covered by hooks:
-await runExclusive(async (client) => {
+await runExclusive(async () => {
   const header = await client.getBlockHeaderByNumber(100);
 });
 ```
@@ -294,3 +350,213 @@ import type {
   SignerContextValue, SignCallback, SignerAccountConfig,
 } from "@miden-sdk/react";
 ```
+
+## Reading Account Storage
+
+For the high-level vault summary on a tracked account, the existing query hook is enough:
+
+```tsx
+const { account, assets, getBalance } = useAccount(accountId);
+// account.id, account.nonce, account.bech32id()
+// assets: AssetBalance[]; getBalance(faucetId): bigint
+```
+
+For lower-level reads (custom contract storage slots, map items), use `Account.storage()`. The React SDK serializes WASM access via `runExclusive`:
+
+```tsx
+const client = useMidenClient();
+const { runExclusive } = useMiden();
+
+await runExclusive(async () => {
+  const id = AccountId.fromBech32(addressBech32);
+  if (!(await client.getAccount(id))) {
+    await client.importAccountById(id);
+  }
+  await client.syncState();
+  const account = await client.getAccount(id);
+  if (!account) return;
+  // AccountStorage (miden_client_web.d.ts:639-660):
+  const value = account.storage().getItem("my_slot_name");
+  // For storage maps:
+  const mapValue = account.storage().getMapItem("my_map_slot", keyWord);
+});
+```
+
+`Account.storage()` returns an `AccountStorage`. Both `getItem(slot_name: string)` and `getMapItem(slot_name: string, key: Word)` return `Word | undefined`. Use slot-name strings (e.g. `COUNTER_SLOT_NAME` in `src/config.ts`), not numeric indices. See `src/hooks/useIncrementCounter.ts:73-83` for the live in-template `getMapItem` example.
+
+`useMidenClient()` returns the raw `WasmWebClient`. Its direct methods include `getAccount(accountId)`, `getAccountStorage(accountId)`, `importAccountById(accountId)`, `syncState()`, and the transaction-request factories (`newSendTransactionRequest`, `newConsumeTransactionRequest`, `newMintTransactionRequest`, `newSwapTransactionRequest`). For compile-from-source, call `client.createCodeBuilder()` and use the returned `CodeBuilder`'s `compileNoteScript(program: string)` / `compileTxScript(tx_script: string)` (`miden_client_web.d.ts`:1058-1115, factory at :4237). The higher-level `MidenClient.accounts.getOrImport` resource API lives on the standalone `MidenClient` (see `web-client-usage`).
+
+## Account Import then Sync then Read Storage Flow
+
+Hook-based pattern for the common "import a remote account, sync to current chain head, then read its state" workflow:
+
+```tsx
+function ImportAndInspect({ accountIdHex }: { accountIdHex: string }) {
+  const { importAccount, isImporting } = useImportAccount();
+  const { sync, isSyncing, syncHeight } = useSyncState();
+  const { account, assets, getBalance, refetch } = useAccount(accountIdHex);
+
+  async function load() {
+    await importAccount({ type: "id", accountId: accountIdHex });
+    await sync();
+    await refetch();
+  }
+  // Render account.id, syncHeight, balances...
+}
+```
+
+`useImportAccount` accepts `{ type: "id" | "file" | "seed", ... }`. After `sync()` resolves, the `useAccount(accountIdHex)` view reflects the latest chain state. For the raw `WasmWebClient` methods used by these hooks under the hood (`client.getAccount`, `client.importAccountById`, `client.syncState`), see `src/hooks/useIncrementCounter.ts` for a worked example. For the higher-level `MidenClient.accounts.*` resource API on a standalone `MidenClient` (outside React), see the `web-client-usage` skill.
+
+## Custom Notes and .masp Package Loading
+
+`.masp` package files (compiled MASM artifacts) are produced by `cargo miden build` in the `project-template/` workspace and copied into `frontend-template/public/packages/` during the contract handoff (see `CLAUDE.md` "Contract Artifact Handoff" section).
+
+The example below builds a custom transaction that emits two output notes carrying fungible assets. Each note has multi-felt input storage that the note script (compiled from MASM into `.masp`) reads and asserts on at consume time. The transaction is signed and submitted by the connected wallet via `useMidenFiWallet().requestTransaction(...)`.
+
+```tsx
+import { useMidenFiWallet } from "@miden-sdk/miden-wallet-adapter-react";
+import { Transaction } from "@miden-sdk/miden-wallet-adapter-base";
+import {
+  Package,
+  NoteScript,
+  Note,
+  NoteAssets,
+  NoteMetadata,
+  NoteRecipient,
+  NoteStorage,
+  NoteTag,
+  NoteType,
+  NoteAttachment,
+  NoteExecutionHint,
+  NoteArray,
+  AccountId,
+  Felt,
+  FeltArray,
+  FungibleAsset,
+  TransactionRequestBuilder,
+} from "@miden-sdk/miden-sdk";
+import { randomWord } from "@/lib/miden";
+
+const { requestTransaction } = useMidenFiWallet();
+
+async function submitMultiNoteTx(
+  senderBech32: string,
+  targetBech32: string,
+  faucetBech32: string,
+) {
+  // (a) .masp loading: fetch the pre-built artifact and decode the note script.
+  const buf = await fetch("/packages/my_note.masp").then((r) => r.arrayBuffer());
+  const pkg = Package.deserialize(new Uint8Array(buf));
+  const noteScript = NoteScript.fromPackage(pkg);
+
+  const sender = AccountId.fromBech32(senderBech32);
+  const target = AccountId.fromBech32(targetBech32);
+  const faucet = AccountId.fromBech32(faucetBech32);
+
+  // (b) Multi-input note storage: each output note carries multiple Felt
+  // inputs that the MASM script reads from its NoteStorage. Assertions on
+  // these felts (e.g. "the first felt must equal the expected nonce") live
+  // in the .masp script source under project-template/contracts/.
+  function makeRecipient(seedFelts: bigint[]): NoteRecipient {
+    const inputs = new FeltArray();
+    for (const v of seedFelts) inputs.push(new Felt(v));
+    return new NoteRecipient(randomWord(), noteScript, new NoteStorage(inputs));
+  }
+
+  // (c) Asset transfers: each note carries fungible assets that move to the
+  // recipient when the note is consumed. FungibleAsset is declared at
+  // miden_client_web.d.ts:1474 (constructor `(faucet_id, amount: bigint)` at :1492).
+  const assets1 = new NoteAssets([new FungibleAsset(faucet, 1000n)]);
+  const assets2 = new NoteAssets([new FungibleAsset(faucet, 500n)]);
+
+  const tag = NoteTag.withAccountTarget(target);
+  const attachment = NoteAttachment.newNetworkAccountTarget(
+    target,
+    NoteExecutionHint.always(),
+  );
+  const metadata = new NoteMetadata(sender, NoteType.Public, tag).withAttachment(
+    attachment,
+  );
+
+  // Two output notes with different felt inputs and asset amounts.
+  const note1 = new Note(assets1, metadata, makeRecipient([1n, 2n, 3n]));
+  const note2 = new Note(assets2, metadata, makeRecipient([4n, 5n, 6n]));
+
+  // (d) Multi-output transaction: emit both notes in one transaction.
+  // For transactions that consume multiple input notes simultaneously,
+  // TransactionRequestBuilder.withInputNotes(NoteAndArgsArray) is the
+  // counterpart (miden_client_web.d.ts:3963).
+  const txRequest = new TransactionRequestBuilder()
+    .withOwnOutputNotes(new NoteArray([note1, note2]))
+    .build();
+
+  // (f) Submission via the wallet adapter.
+  const tx = Transaction.createCustomTransaction(senderBech32, targetBech32, txRequest);
+  if (!requestTransaction) throw new Error("Wallet does not support requestTransaction");
+  await requestTransaction(tx);
+}
+```
+
+Notes on this pattern:
+
+- **Assertions live in MASM, not in TypeScript.** The note script compiled into `.masp` reads its `NoteStorage` felts at consume time and aborts the transaction if its assertions fail. The frontend's job is to construct and submit; MASM enforces. See `project-template/contracts/` for where to author MASM with assertion ops.
+- **Single-output reference for simpler flows.** For a simpler worked example using only one output note with empty assets and a single consume action, see `src/hooks/useIncrementCounter.ts`. That hook is intentionally simpler and does not exercise asset transfers or multi-output emission.
+- **Compile from source (no `.masp`) when needed.** When the note script is not pre-bundled as `.masp`, compile it through `CodeBuilder`. **`compileNoteScript`/`compileTxScript` are methods of `CodeBuilder`, not of `WasmWebClient`.** The pattern is:
+
+```tsx
+const client = useMidenClient();
+const builder = client.createCodeBuilder();
+// optionally: builder.linkStaticLibrary(myLib) or builder.linkDynamicLibrary(myLib)
+const noteScript = builder.compileNoteScript(noteSourceMasm);
+const txScript = builder.compileTxScript(txSourceMasm);
+```
+
+  See `miden_client_web.d.ts`:1058-1115 for `CodeBuilder` and :4237 for `createCodeBuilder()`. As the React-idiomatic alternative, `useCompile()` (`@miden-sdk/react/dist/index.d.ts`:1171-1196) wraps `CompilerResource` from the standalone `MidenClient` and exposes `noteScript`, `txScript`, `component`, `isReady` at the hook layer.
+- **Inside `useTransaction`'s `request` callback** the parameter is a `WasmWebClient` (`@miden-sdk/react/dist/index.d.ts`:393). Use `client.createCodeBuilder()` for compile, then build the `TransactionRequest` with `TransactionRequestBuilder` and return it. For the higher-level `MidenClient.compile.*` and `MidenClient.transactions.execute` resource API on a standalone `MidenClient`, see `web-client-usage`.
+
+## Cross-SDK Type Reference
+
+The runtime types come from `@miden-sdk/react` (re-exported from `@miden-sdk/miden-sdk` for the underlying `MidenClient` types). The `.d.ts` files are the source of truth. Look them up in:
+
+- the installed `.d.ts` for `@miden-sdk/react` (hook return types and option types)
+- the installed `.d.ts` for `@miden-sdk/miden-sdk` (`MidenClient`, `Account`, `AccountId`, `Note`, `Word`, etc.)
+
+Path layout differs across package managers (npm flat, pnpm nested, Yarn PnP virtual), so resolve them via your IDE's "Go to Definition" or the installed package surface rather than hard-coded paths.
+
+Common app-developer types:
+
+| Type | Source package | Notes |
+|------|----------------|-------|
+| `Account`, `AccountHeader` | `@miden-sdk/react` | `id`, `nonce`, `bech32id()` |
+| `AccountId` | `@miden-sdk/miden-sdk` | construct via `AccountId.fromHex(hex)`; throws on invalid hex |
+| `Address` | `@miden-sdk/miden-sdk` | bech32 wrapper; `Address.fromBech32(...)` |
+| `Note`, `InputNoteRecord`, `ConsumableNoteRecord` | `@miden-sdk/react` | re-exported from `@miden-sdk/miden-sdk`. Input notes are received; for output-note types and private-note flows see `web-client-usage`. |
+| `NoteVisibility` (constants + string-union) | `@miden-sdk/miden-sdk` | `const NoteVisibility = { Public: 'public', Private: 'private' }` plus `type NoteVisibility = 'public' \| 'private'` (`api-types.d.ts`:95-101). NOT an enum. Coexists with the raw WASM `NoteType` enum (`miden_client_web.d.ts`:2889) which the template uses directly when building notes via the WASM types (see `src/hooks/useIncrementCounter.ts`). |
+| `AccountType`, `AuthScheme`, `StorageMode` | `@miden-sdk/miden-sdk` | enums; see `web-client-usage` "Visibility & Account Types". |
+| `TransactionRequest` | `@miden-sdk/react` | client factory functions return this |
+| `Word` | `@miden-sdk/miden-sdk` | 32-byte (4 felts) value; `Word.toU64s()` returns `BigUint64Array` of length 4 (each lane is a `bigint` after subscript). See `miden_client_web.d.ts`:4535. |
+
+Do not hardcode this table for long-term reference. The `.d.ts` files stay in lockstep with the installed package version; this list will drift.
+
+## Rust to TypeScript Type Mapping
+
+The Rust (`miden-client`) and TypeScript (`@miden-sdk/miden-sdk`) SDKs share concepts but diverge on naming and primitive shapes. When porting between them:
+
+| Concept | Rust (`miden_objects` / `miden_client`) | TypeScript (`@miden-sdk/miden-sdk`) |
+|---------|------------------------------------------|--------------------------------------|
+| Token amount | `u64` | `bigint` |
+| Field element | `Felt` (Goldilocks `u64` mod p) | `Felt` (wraps `u64`) |
+| 32-byte word | `Word` (`[Felt; 4]`) | `Word`; `toU64s(): BigUint64Array` length 4 (each lane is `bigint` after subscript). |
+| Account identifier | `AccountId` | `AccountId`; construct via `AccountId.fromHex` |
+| Note visibility | `NoteType` enum | constants + string-union `NoteVisibility` (`'public' \| 'private'`) at the high-level `MidenClient` resource API; raw WASM `NoteType` enum (`Private = 2`, `Public = 1`) is also exported and used directly when constructing notes via the WASM types (see `src/hooks/useIncrementCounter.ts`). The two coexist; pick the layer your code lives in. |
+| Account type | `AccountType` | `AccountType` enum |
+| Authentication scheme | `AuthScheme` | `AuthScheme` enum |
+| Storage mode | `StorageMode` | `StorageMode` enum |
+
+Common gotchas:
+
+- The TS method is `FeltArray.push(element: Felt)` (`miden_client_web.d.ts`:1324); there is no `FeltArray.append`. To convert a `Felt` to a JS `bigint`, use `Felt.asInt()` (`miden_client_web.d.ts`:1296). When a Rust method appears missing in TS, consult `node_modules/@miden-sdk/miden-sdk/dist/index.d.ts` and `dist/crates/miden_client_web.d.ts` first instead of guessing the TS spelling.
+- TS amounts are always `bigint`. Mixing `number` causes silent precision loss above `Number.MAX_SAFE_INTEGER` and `TypeError` below.
+- `Word.toU64s()` returns `BigUint64Array` of length 4 (`miden_client_web.d.ts`:4535). Each lane is a `bigint` (e.g. `word.toU64s()[0]`). Use it when reading the four `u64` lanes from a Value storage slot or building assertions on `Word` outputs.
+
+For the canonical Rust types, see [`0xMiden/miden-client`](https://github.com/0xMiden/miden-client) and the `miden_objects` crate. For the canonical TS types, see `node_modules/@miden-sdk/miden-sdk/dist/index.d.ts`.

package/template/.claude/skills/signer-integration/SKILL.md

@@ -68,15 +68,34 @@ const { client, account, setAccount } = useTurnkeySigner();
 
 ### MidenFi Wallet Adapter (Browser Extension)
 ```tsx
-import { MidenFiSignerProvider } from "@miden-sdk/wallet-adapter-react";
-
-<MidenFiSignerProvider network="Testnet">
+import { MidenFiSignerProvider } from "@miden-sdk/miden-wallet-adapter-react";
+import { WalletAdapterNetwork } from "@miden-sdk/miden-wallet-adapter-base";
+
+<MidenFiSignerProvider
+  appName="My App"                                        // optional: passed to MidenWalletAdapter
+  network={WalletAdapterNetwork.Testnet}                  // WalletAdapterNetwork enum: Devnet | Testnet | Localnet
+  autoConnect                                             // reconnect on mount. Default: false
+  accountType="RegularAccountImmutableCode"               // Default: "RegularAccountImmutableCode"
+  storageMode="public"                                    // "private" | "public" | "network". Default: "public"
+  customComponents={[myComponent]}                        // optional: custom AccountComponents
+  privateDataPermission={permission}                      // optional: private data access level
+  allowedPrivateData={allowedData}                        // optional: allowed private data types
+>
   <MidenProvider config={{ rpcUrl: "testnet" }}>
     <App />
   </MidenProvider>
 </MidenFiSignerProvider>
 ```
 
+With `MidenFiSignerProvider` in place, use `useSigner()` from the React SDK to manage connection state. The regular React SDK hooks (`useSend`, `useConsume`, etc.) automatically sign via the connected wallet — no additional wiring needed.
+
+### This template's MidenFi-specific pattern
+
+This template deviates from the generic `useSigner()` approach in two places — worth knowing because it's a pattern you'll likely want when the wallet extension is the primary signer:
+
+- **Wallet button uses `useMidenFiWallet()` + `WalletReadyState`** (`src/components/AppContent.tsx`). The button gates on `wallet.readyState` so it can render a disabled "Install MidenFi Wallet" state before the extension is detected. `useSigner().connect()` would silently fall through to the adapter's `window.open(adapter.url, ...)` install fallback (Chrome Web Store → Play Store redirect on some platforms); gating on `readyState` avoids that path entirely.
+- **Custom transaction flow calls `wallet.requestTransaction(...)` directly** (`src/hooks/useIncrementCounter.ts`). The counter increment builds a bespoke `TransactionRequest` (via `TransactionRequestBuilder`, a custom `Note` with `NoteAttachment.newNetworkAccountTarget`, etc.) and hands it to the wallet for signing + submission. The React SDK mutation hooks (`useSend`, `useConsume`, ...) don't cover this kind of custom note construction, and the tx is submitted by the wallet rather than the local client — so `useWaitForCommit` doesn't apply either.
+
 ## Unified Signer Interface
 
 Works with any signer provider above: