create-miden-app 1.0.3 → 1.0.6

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

@@ -0,0 +1,296 @@
+---
+name: react-sdk-patterns
+description: Complete guide to building Miden frontends with @miden-sdk/react hooks. Covers MidenProvider setup, all query hooks (useAccounts, useAccount, useNotes, useSyncState, useAssetMetadata), all mutation hooks (useCreateWallet, useSend, useMultiSend, useMint, useConsume, useSwap, useTransaction, useCreateFaucet), transaction stages, signer integration, and utility functions. Use when writing, editing, or reviewing Miden React frontend code.
+---
+
+# Miden React SDK Patterns
+
+## 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.
+
+## MidenProvider Configuration
+
+```tsx
+import { MidenProvider } from "@miden-sdk/react";
+
+<MidenProvider
+  config={{
+    rpcUrl: "devnet",           // "devnet" | "testnet" | "localhost" | custom URL
+    prover: "devnet",           // "local" | "devnet" | "testnet" | custom URL
+    autoSyncInterval: 15000,    // ms, set to 0 to disable. Default: 15000
+    noteTransportUrl: "...",    // optional: for private note delivery
+  }}
+  loadingComponent={<Loading />}  // shown during WASM init
+  errorComponent={<Error />}      // shown on init failure (receives Error prop)
+>
+  <App />
+</MidenProvider>
+```
+
+| Network | rpcUrl | Use When |
+|---------|--------|----------|
+| Devnet | `"devnet"` | Development, testing with fake tokens |
+| Testnet | `"testnet"` | Pre-production testing |
+| Localhost | `"localhost"` | Local node at `http://localhost:57291` |
+
+## Query Hooks
+
+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)
+```
+
+### 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
+```
+
+### useNotes(filter?)
+```tsx
+const { notes, consumableNotes, noteSummaries, consumableNoteSummaries, isLoading, error, refetch } = useNotes();
+// 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" });
+```
+
+### useSyncState()
+```tsx
+const { syncHeight, isSyncing, lastSyncTime, sync, error } = useSyncState();
+await sync(); // Manual sync
+```
+
+### useAssetMetadata(faucetId: string | string[])
+```tsx
+const { assetMetadata } = useAssetMetadata(faucetId);
+// assetMetadata — Map<string, AssetMetadata>
+// Each entry: { assetId, symbol?, decimals? }
+const meta = assetMetadata.get(faucetId);
+// meta.symbol — "TEST"
+// meta.decimals — 8
+```
+
+### useTransactionHistory(options?)
+```tsx
+const { records, record, status, isLoading, error, refetch } = useTransactionHistory({ id: txId });
+// status: "pending" | "committed" | "discarded" | null
+```
+
+## Mutation Hooks
+
+Each returns its own action function plus `isLoading`, `stage`, `error`, `reset`.
+
+**Transaction stages**: `"idle"` → `"executing"` → `"proving"` → `"submitting"` → `"complete"`
+
+### useCreateWallet()
+```tsx
+const { createWallet, wallet, isCreating, error, reset } = useCreateWallet();
+const account = await createWallet({
+  storageMode: "private",  // "private" | "public" | "network". Default: "private"
+  mutable: true,           // Default: true
+  authScheme: 0,           // 0 = RpoFalcon512, 1 = EcdsaK256Keccak. Default: 0
+});
+```
+
+### useCreateFaucet()
+```tsx
+const { createFaucet, faucet, isCreating, error, reset } = useCreateFaucet();
+const account = await createFaucet({
+  tokenSymbol: "TEST",
+  decimals: 8,             // Default: 8
+  maxSupply: 1000000n,     // bigint!
+  storageMode: "public",   // Default: "private"
+});
+```
+
+### useSend()
+```tsx
+const { send, result, isLoading, stage, error, reset } = useSend();
+await send({
+  from: senderAccountId,
+  to: recipientAccountId,
+  assetId: faucetId,       // token faucet ID
+  amount: 1000n,           // bigint!
+  noteType: "private",     // "private" | "public". Default: "private"
+  recallHeight: 100,       // optional: sender can reclaim after this block
+  timelockHeight: 50,      // optional: recipient can consume after this block
+});
+```
+
+### useMultiSend()
+```tsx
+const { sendMany, result, isLoading, stage, error, reset } = useMultiSend();
+await sendMany({
+  from: senderAccountId,
+  assetId: faucetId,
+  recipients: [
+    { to: recipient1, amount: 500n },
+    { to: recipient2, amount: 300n },
+  ],
+  noteType: "private",
+});
+```
+
+### useMint()
+```tsx
+const { mint, result, isLoading, stage, error, reset } = useMint();
+await mint({
+  targetAccountId: recipientId,
+  faucetId: myFaucetId,
+  amount: 10000n,         // bigint!
+  noteType: "public",
+});
+```
+
+### useConsume()
+```tsx
+const { consume, result, isLoading, stage, error, reset } = useConsume();
+await consume({
+  accountId: myAccountId,
+  noteIds: [noteId1, noteId2],
+});
+```
+
+### useSwap()
+```tsx
+const { swap, result, isLoading, stage, error, reset } = useSwap();
+await swap({
+  accountId: myAccountId,
+  offeredFaucetId: tokenA,
+  offeredAmount: 100n,
+  requestedFaucetId: tokenB,
+  requestedAmount: 50n,
+  noteType: "private",
+  paybackNoteType: "private",
+});
+```
+
+### useTransaction() — Escape Hatch
+```tsx
+const { execute, result, isLoading, stage, error, reset } = useTransaction();
+
+// With pre-built TransactionRequest:
+await execute({ accountId, request: txRequest });
+
+// With factory function (gets access to client):
+await execute({
+  accountId,
+  request: (client) => client.newSwapTransactionRequest(/* ... */),
+});
+```
+
+### useWaitForCommit()
+```tsx
+const { waitForCommit } = useWaitForCommit();
+await waitForCommit(result.transactionId, {
+  timeoutMs: 10000,   // Default: 10000
+  intervalMs: 1000,    // Default: 1000
+});
+```
+
+### useWaitForNotes()
+```tsx
+const { waitForConsumableNotes } = useWaitForNotes();
+await waitForConsumableNotes({
+  accountId: myAccountId,
+  minCount: 1,         // Default: 1
+  timeoutMs: 10000,
+});
+```
+
+## Transaction Progress UI
+
+```tsx
+function SendButton({ from, to, assetId, amount }) {
+  const { send, stage, isLoading, error } = useSend();
+
+  return (
+    <div>
+      <button onClick={() => send({ from, to, assetId, amount })} disabled={isLoading}>
+        {isLoading ? `${stage}...` : "Send"}
+      </button>
+      {error && <p>Error: {error.message}</p>}
+    </div>
+  );
+}
+```
+
+## Signer Integration
+
+### Local Keystore (Default)
+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
+
+```tsx
+// Example: Para signer wrapping MidenProvider
+import { ParaSignerProvider } from "@miden-sdk/para";
+<ParaSignerProvider apiKey="..." environment="PRODUCTION">
+  <MidenProvider config={...}><App /></MidenProvider>
+</ParaSignerProvider>
+```
+
+### useSigner() — Unified Interface
+```tsx
+const { isConnected, connect, disconnect, name } = useSigner();
+```
+
+### Custom Signer
+Implement `SignerContextValue` interface via `SignerContext.Provider`. Requires: `name`, `storeName` (unique per user for DB isolation), `accountConfig`, `signCb`, `connect`, `disconnect`. See `frontend-source-guide` skill for source references.
+
+## Utility Functions
+
+```tsx
+import { formatAssetAmount, parseAssetAmount, getNoteSummary, formatNoteSummary, toBech32AccountId } from "@miden-sdk/react";
+
+formatAssetAmount(1000000n, 8)       // "0.01"
+parseAssetAmount("0.01", 8)           // 1000000n
+const summary = getNoteSummary(note); // { id, assets, sender }
+formatNoteSummary(summary);           // "1.5 TEST"
+toBech32AccountId("0x1234...");       // "miden1qy35..."
+```
+
+## Direct Client Access
+
+```tsx
+const client = useMidenClient(); // throws if not ready
+const { runExclusive } = useMiden();
+
+// For operations not covered by hooks:
+await runExclusive(async (client) => {
+  const header = await client.getBlockHeaderByNumber(100);
+});
+```
+
+## Type Imports
+
+```tsx
+import type {
+  MidenConfig, QueryResult, MutationResult, TransactionStage,
+  AccountsResult, AccountResult, AssetBalance, NotesResult, NoteSummary,
+  SendOptions, MultiSendOptions, MintOptions, ConsumeOptions, SwapOptions,
+  CreateWalletOptions, CreateFaucetOptions, ExecuteTransactionOptions,
+  TransactionResult, SyncState, WaitForCommitOptions, WaitForNotesOptions,
+  Account, AccountId, InputNoteRecord, ConsumableNoteRecord,
+  TransactionRecord, TransactionRequest, NoteType, AccountStorageMode,
+  SignerContextValue, SignCallback, SignerAccountConfig,
+} from "@miden-sdk/react";
+```

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

@@ -0,0 +1,158 @@
+---
+name: signer-integration
+description: Guide to integrating external signers (Para, Turnkey, MidenFi wallet adapter) and building custom signers for Miden React frontends. Covers provider setup, passkey authentication, unified signer interface, custom SignerContext implementation, and custom account components. Use when adding wallet connection, authentication, or external key management to a Miden frontend.
+---
+
+# Miden Signer Integration
+
+## Overview
+
+By default, MidenProvider uses a **local keystore** (keys in IndexedDB, no wallet connection needed). For production apps, wrap MidenProvider with a signer provider to use external key management.
+
+Signer providers must wrap MidenProvider (outer → inner):
+```
+<SignerProvider>      ← manages keys + auth
+  <MidenProvider>     ← manages Miden client
+    <App />
+  </MidenProvider>
+</SignerProvider>
+```
+
+## Pre-Built Signer Providers
+
+### Para (EVM Wallets)
+```tsx
+import { ParaSignerProvider } from "@miden-sdk/para";
+
+<ParaSignerProvider apiKey="your-api-key" environment="PRODUCTION">
+  <MidenProvider config={{ rpcUrl: "testnet" }}>
+    <App />
+  </MidenProvider>
+</ParaSignerProvider>
+
+const { para, wallet, isConnected } = useParaSigner();
+```
+
+### Turnkey (Passkey Authentication)
+```tsx
+import { TurnkeySignerProvider } from "@miden-sdk/miden-turnkey-react";
+
+// Config is optional — defaults to https://api.turnkey.com
+// and reads VITE_TURNKEY_ORG_ID from environment
+<TurnkeySignerProvider>
+  <MidenProvider config={{ rpcUrl: "testnet" }}>
+    <App />
+  </MidenProvider>
+</TurnkeySignerProvider>
+
+// Or with explicit config:
+<TurnkeySignerProvider config={{
+  apiBaseUrl: "https://api.turnkey.com",
+  defaultOrganizationId: "your-org-id",
+}}>
+  ...
+</TurnkeySignerProvider>
+```
+
+Connect via passkey:
+```tsx
+import { useSigner } from "@miden-sdk/react";
+import { useTurnkeySigner } from "@miden-sdk/miden-turnkey-react";
+
+const { isConnected, connect, disconnect } = useSigner();
+await connect();  // triggers passkey flow, auto-selects account
+
+// Turnkey-specific extras
+const { client, account, setAccount } = useTurnkeySigner();
+```
+
+### MidenFi Wallet Adapter (Browser Extension)
+```tsx
+import { MidenFiSignerProvider } from "@miden-sdk/wallet-adapter-react";
+
+<MidenFiSignerProvider network="Testnet">
+  <MidenProvider config={{ rpcUrl: "testnet" }}>
+    <App />
+  </MidenProvider>
+</MidenFiSignerProvider>
+```
+
+## Unified Signer Interface
+
+Works with any signer provider above:
+```tsx
+import { useSigner } from "@miden-sdk/react";
+
+const { isConnected, connect, disconnect, name } = useSigner();
+
+if (!isConnected) {
+  return <button onClick={connect}>Connect {name}</button>;
+}
+```
+
+## Building a Custom Signer
+
+Implement `SignerContextValue` via `SignerContext.Provider`:
+
+```tsx
+import { SignerContext } from "@miden-sdk/react";
+
+<SignerContext.Provider value={{
+  name: "MyWallet",
+  storeName: `mywallet_${userAddress}`,  // unique per user for DB isolation
+  isConnected: true,
+  accountConfig: {
+    publicKey: userPublicKeyCommitment,  // Uint8Array
+    storageMode: "private",
+  },
+  signCb: async (pubKey, signingInputs) => {
+    // Route to your signing service
+    return signature;  // Uint8Array
+  },
+  connect: async () => { /* trigger wallet connection */ },
+  disconnect: async () => { /* clear session */ },
+}}>
+  <MidenProvider config={{ rpcUrl: "testnet" }}>
+    <App />
+  </MidenProvider>
+</SignerContext.Provider>
+```
+
+**Required fields:**
+- `name` — Display name for the signer
+- `storeName` — Unique string per user (isolates IndexedDB data between users)
+- `accountConfig` — Public key commitment + storage mode
+- `signCb` — Callback that signs transaction data with your key management service
+- `connect` / `disconnect` — Session lifecycle handlers
+
+## Custom Account Components
+
+Attach application-specific `AccountComponent` instances (e.g., DEX logic from `.masp` packages) to accounts created by the signer:
+
+```tsx
+import { type SignerAccountConfig } from "@miden-sdk/react";
+import { AccountComponent } from "@miden-sdk/miden-sdk";
+
+const myDexComponent: AccountComponent = await loadCompiledComponent();
+
+const accountConfig: SignerAccountConfig = {
+  publicKeyCommitment: userPublicKeyCommitment,
+  accountType: "RegularAccountUpdatableCode",
+  storageMode: myStorageMode,
+  customComponents: [myDexComponent],
+};
+```
+
+Components are appended to the `AccountBuilder` after the default basic wallet component. The field is optional — omitting it preserves default behavior.
+
+## Which Signer to Choose
+
+| Signer | Auth Method | Keys Stored | Best For |
+|--------|-------------|-------------|----------|
+| Local keystore (default) | None | Browser IndexedDB | Development, demos |
+| Para | EVM wallet | Para servers | Apps with existing EVM users |
+| Turnkey | Passkey (biometric) | Turnkey servers | Consumer apps, no seed phrases |
+| MidenFi Wallet | Browser extension | Extension | Power users with MidenFi wallet |
+| Custom | Your choice | Your infrastructure | Enterprise, custom auth flows |
+
+**Key trade-off**: Local keystore requires no setup but keys are lost if the user clears browser data. External signers persist keys server-side but add a dependency.

package/template/.claude/skills/testing-patterns/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: testing-patterns
+description: Testing conventions, mock factory, fixtures, and TDD workflow for Miden frontend development. Covers Vitest + testing-library setup, @miden-sdk/react module mocking, realistic fixture data, test patterns for query and mutation hooks, and the automated verification pipeline. Use when writing, running, or debugging tests for Miden React components.
+---
+
+# Miden Frontend Testing Patterns
+
+## Test Stack
+
+- **Vitest** — Test runner (extends Vite config for consistent behavior)
+- **@testing-library/react** — Component rendering and queries
+- **@testing-library/user-event** — User interaction simulation
+- **@testing-library/jest-dom** — DOM assertion matchers (toBeInTheDocument, toBeDisabled, etc.)
+- **jsdom** — Browser environment for tests
+
+## Mock Factory: `@miden-sdk/react`
+
+All Miden SDK hooks are mocked via `src/__tests__/mocks/miden-sdk-react.ts`. This module exports mock implementations of every hook with realistic default return values.
+
+### Usage in test files
+
+```tsx
+// 1. Mock the entire module (hoisted to top by vitest)
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+
+// 2. Import hooks you want to override
+import { useAccounts, useSend } from "@miden-sdk/react";
+
+// 3. Override per-test
+it("shows empty state", () => {
+  vi.mocked(useAccounts).mockReturnValue({
+    accounts: [],
+    wallets: [],
+    faucets: [],
+    isLoading: false,
+    error: null,
+    refetch: vi.fn(),
+  });
+  render(<MyComponent />);
+});
+```
+
+### Default mock return values
+
+**Query hooks** return populated data by default:
+- `useAccounts()` — 2 wallets, 1 faucet
+- `useAccount()` — account with 10.0 TEST token balance
+- `useNotes()` — 1 input note, 1 consumable note
+- `useSyncState()` — syncHeight: 12345, not syncing
+- `useAssetMetadata()` — TEST token metadata (symbol, decimals: 8)
+- `useMiden()` — isReady: true
+
+**Mutation hooks** return idle state by default:
+- `useSend()` — `{ send: vi.fn(), stage: "idle", isLoading: false }`
+- `useMint()`, `useConsume()`, `useSwap()`, `useTransaction()` — similar pattern
+- `useCreateWallet()` — `{ createWallet: vi.fn(), isCreating: false }`
+
+### Simulating transaction stages
+
+```tsx
+// Show "proving" stage
+vi.mocked(useSend).mockReturnValue({
+  send: vi.fn(),
+  result: null,
+  isLoading: true,
+  stage: "proving",
+  error: null,
+  reset: vi.fn(),
+});
+
+// Show completed transaction
+vi.mocked(useSend).mockReturnValue({
+  send: vi.fn(),
+  result: { transactionId: "0xabc123" },
+  isLoading: false,
+  stage: "complete",
+  error: null,
+  reset: vi.fn(),
+});
+```
+
+## Fixtures
+
+Realistic test data in `src/__tests__/fixtures/`:
+
+```tsx
+import {
+  WALLET_ID_1,           // "mtst1qy35qfqdvpjx2e5zf9hkp4vr"
+  WALLET_ID_2,           // "mtst1qa7k9qjf8dp4x2e5zf9hkp5vr"
+  FAUCET_ID,             // "mtst1qx9y8zjf2dp4x2e5zf9hkp3vr"
+  COUNTER_ID,            // "mtst1aru8adnrqspgcsr3drk2n990lyc070ll"
+  MOCK_WALLET_HEADER,    // { id, nonce, storageCommitment }
+  MOCK_FAUCET_HEADER,    // { id, nonce, storageCommitment }
+  MOCK_ASSET_BALANCE,    // { assetId, amount: 1000000000n, symbol: "TEST", decimals: 8 }
+  MOCK_ACCOUNT,          // { id, nonce, bech32id() }
+  MOCK_TRANSACTION_RESULT, // { transactionId: "0x..." }
+  MOCK_NOTE_SUMMARY,    // { id, assets, sender }
+} from "@/__tests__/fixtures";
+```
+
+Key characteristics:
+- Account IDs use bech32 format (`mtst1...`)
+- Amounts are `bigint` (e.g., `1000000000n` = 10.0 with 8 decimals)
+- Asset metadata uses TEST token with 8 decimals
+
+## Test Patterns (copy-adaptable)
+
+Reference tests in `src/__tests__/patterns/`:
+
+| Pattern | File | Tests |
+|---------|------|-------|
+| Provider/context setup | `provider-setup.test.tsx` | ready, loading, error states |
+| Query hook component | `query-hook.test.tsx` | data, loading, error, empty states |
+| Mutation hook component | `mutation-hook.test.tsx` | idle, stages, success, error, argument verification |
+
+### Minimum test coverage per component
+
+Every component test should cover:
+1. **Success state** — renders correctly with data
+2. **Loading state** — shows loading indicator
+3. **Error state** — shows error message, recovery action
+4. **User interactions** — buttons, forms trigger correct handler calls
+
+## Mocking the wallet adapter
+
+The app uses `@miden-sdk/miden-wallet-adapter`. Mock it at the module level:
+
+```tsx
+vi.mock("@miden-sdk/miden-wallet-adapter", () => ({
+  WalletMultiButton: () => <button>Connect Wallet</button>,
+  useWallet: vi.fn(() => ({
+    address: "mtst1...",
+    connected: true,
+    requestTransaction: vi.fn(),
+  })),
+}));
+```
+
+Vitest config externalizes `@miden-sdk/miden-wallet-adapter*` sub-packages to prevent broken transitive resolution from the reactui sub-package.
+
+## Automated Verification Pipeline
+
+Hooks in `.claude/settings.json` enforce quality automatically:
+
+1. **PostToolUse: typecheck** — `npx tsc -b --noEmit` on every `.ts`/`.tsx` edit in `src/`
+2. **PostToolUse: affected tests** — `npx vitest --changed --run` on every `.ts`/`.tsx` edit in `src/`
+3. **Stop hook** — Full `vitest --run && tsc -b --noEmit && vite build` before task completion
+
+If any hook fails (exit code 2), the agent is blocked from proceeding until the issue is fixed.
+
+## TDD Flow
+
+```
+1. Write test (describe expected behavior)
+   ↓
+2. yarn test           → RED (test fails)
+   ↓
+3. Implement code
+   ↓
+4. Auto hooks fire     → typecheck + affected tests
+   ↓
+5. yarn test           → GREEN (all pass)
+   ↓
+6. Refactor if needed
+   ↓
+7. Task complete       → Stop hook: full suite + build
+```
+
+## Common Mistakes
+
+**Forgetting vi.clearAllMocks()**: Always call in `beforeEach` to prevent mock state leaking between tests.
+
+**Not mocking the SDK**: Components importing from `@miden-sdk/react` will fail without `vi.mock()` because the real SDK requires WASM initialization.
+
+**Using number instead of bigint**: Mock amounts must use `bigint` (`1000n`, not `1000`). The SDK enforces this at the type level.
+
+**Testing implementation details**: Test what the user sees (text, buttons, states), not internal hook calls. Use `screen.getByRole`, `screen.getByText`, not internal component state.