create-miden-app 1.0.3 → 1.0.6

package/template/create-miden-app/template/.claude/skills/frontend-source-guide/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: frontend-source-guide
+description: Guide for advanced Miden frontend development using source repo exploration. Covers AI development practices (Plan Mode, verification-driven development, context engineering, sub-agents) and maps the miden-client source repository for discovering advanced patterns. Use when building complex applications beyond basic hook usage, implementing custom signers, working with raw WebClient, or troubleshooting SDK internals.
+---
+
+# Advanced Miden Frontend Development: Source-Guided Context Engineering
+
+## Development Approach
+
+### 1. Plan Mode First
+
+For any non-trivial frontend application, start in Plan Mode before writing code.
+
+- Explore React SDK source and examples to understand available patterns
+- Design the component hierarchy, data flow, and which hooks to use
+- Identify which built-in hooks cover your needs vs what requires raw WebClient
+- Map out the user flow: account creation, token operations, note handling
+
+Rule of thumb: if the task involves custom transactions, external signers, or patterns not covered by the basic skills, plan first.
+
+### 2. Verification-Driven Development
+
+This is the single highest-leverage practice for AI-assisted frontend development.
+
+**Type check loop**: After every file edit, run `npx tsc -b --noEmit`. The project's type check hook does this automatically. If types fail:
+1. Read the error message
+2. Search the React SDK source for the correct type signature or hook usage
+3. Adapt the working pattern to your use case
+4. Recheck
+
+**Dev server loop**: Run `npm run dev` and check the browser. When something fails:
+1. Check the browser console for WASM errors, network errors, or React errors
+2. For WASM errors: check COOP/COEP headers and Vite config (see frontend-pitfalls skill)
+3. For unexpected behavior: compare your code against the example wallet in the React SDK
+
+Never submit code that doesn't type-check. The verification loop is your quality guarantee.
+
+### 3. Context Engineering with Source Repos
+
+The basic skills (react-sdk-patterns, frontend-pitfalls, vite-wasm-setup) cover standard patterns. For anything beyond those patterns, the miden-client source repository is the knowledge base.
+
+**How to use source repos effectively**:
+- Don't load entire repos into context. Use sub-agents to explore — they search, read relevant files, and summarize findings without filling the main conversation context.
+- Read source files only when you need a specific answer (progressive disclosure)
+- Look for working examples first, then adapt. The example wallet app is the most reliable reference.
+- When you find a useful pattern in source, extract just what you need — the exact hook call, the exact type, the exact provider setup.
+
+**Using sub-agents for exploration**:
+- Launch an explore sub-agent with a specific question: "Find how useSwap handles the payback note type in the React SDK"
+- The sub-agent searches, reads the relevant files, and returns a focused summary
+- Your main context stays clean for implementation
+
+### 4. Iterative Frontend Development
+
+Break complex applications into stages. Complete each before starting the next:
+
+1. **Design** (Plan Mode) — Component hierarchy, data flow, hook selection
+2. **Provider setup** — MidenProvider config, signer integration if needed
+3. **Query components** — Account display, balance rendering, note lists
+4. **Mutation components** — Send forms, mint buttons, consume flows
+5. **Transaction UX** — Stage progress, error handling, loading states
+6. **Polish** — Auto-sync tuning, memoization, edge cases
+
+When stuck at any stage: search the React SDK source for a similar working pattern. Adapt it, don't guess.
+
+---
+
+## Miden Source Repository Map
+
+Clone this repo alongside your project for reference. Claude will explore it when needed for advanced patterns.
+
+```bash
+# Contains React SDK source, WebClient WASM bindings, and working examples
+git clone --depth 1 https://github.com/0xMiden/miden-client.git ../miden-client
+```
+
+### `packages/react-sdk/` — React SDK Source
+
+The primary reference for all frontend development.
+
+- **`src/hooks/`** — All 18+ hook implementations. Each file is self-contained. Read these to understand exact parameters, error handling, and stage progression.
+- **`src/context/MidenProvider.tsx`** — Client initialization, sync loop, signer detection, runExclusive lock. Read this to understand initialization order.
+- **`src/context/SignerContext.ts`** — External signer interface. Read this when implementing custom signers.
+- **`src/store/MidenStore.ts`** — Zustand store structure. Read this to understand cached state and what triggers re-renders.
+- **`src/utils/`** — Utility implementations (amounts, notes, bech32, runExclusive, accountParsing).
+- **`src/types/index.ts`** — All TypeScript interfaces. The single source of truth for option types, result types, and configuration.
+- **`examples/wallet/`** — Complete working wallet app. The most reliable reference for how to set up MidenProvider, create accounts, display balances, claim notes, and send tokens.
+
+**Explore when**: Writing any new component, understanding exact hook behavior, finding how a specific feature works, debugging unexpected behavior.
+
+### `crates/web-client/` — WASM Client Bindings
+
+The Rust-to-WASM bridge that the React SDK wraps.
+
+- Contains the `WebClient` struct and all methods available via `useMidenClient()`
+- JavaScript bindings in `js/` directory
+
+**Explore when**: A hook doesn't exist for your operation, understanding what WebClient methods are available, debugging WASM-level errors.
+
+### `crates/idxdb-store/` — IndexedDB Persistence
+
+The browser storage layer for accounts, keys, notes, and transaction history.
+
+**Explore when**: Debugging data persistence issues, understanding what's stored in IndexedDB, investigating storage isolation for external signers.
+
+---
+
+## What to Explore for Each Pattern
+
+| Building This | Explore These Paths | What to Look For |
+|---|---|---|
+| Basic wallet UI | `examples/wallet/` | MidenProvider setup, useAccounts, useSend |
+| Custom transaction | `src/hooks/useTransaction.ts` | Request factory pattern, client methods |
+| External signer | `src/context/SignerContext.ts` | SignerContextValue interface, signCb |
+| Note consumption flow | `src/hooks/useConsume.ts` | NoteId parsing, filter construction |
+| Swap UI | `src/hooks/useSwap.ts` | Swap options, dual note types |
+| Token display | `src/utils/amounts.ts` | formatAssetAmount, parseAssetAmount |
+| Account ID formatting | `src/utils/accountBech32.ts` | toBech32AccountId |
+| State management | `src/store/MidenStore.ts` | Zustand selectors, cached state |
+| Direct WebClient usage | `src/context/MidenProvider.tsx` | useMidenClient(), runExclusive |
+| Multi-step workflow | `src/hooks/useWaitForCommit.ts`, `useWaitForNotes.ts` | Polling, timeout patterns |
+
+---
+
+## Common Advanced Patterns
+
+### Custom Hooks Wrapping WebClient
+For operations not covered by built-in hooks, create custom hooks that use useMidenClient() and runExclusive:
+```tsx
+function useBlockHeader(blockNumber: number) {
+  const client = useMidenClient();
+  const { runExclusive } = useMiden();
+  const [data, setData] = useState(null);
+  useEffect(() => {
+    // Note: runExclusive() may be simplified in a future SDK version.
+    // Check SDK changelog when upgrading.
+    runExclusive(async () => {
+      const header = await client.getBlockHeaderByNumber(blockNumber);
+      setData(header);
+    });
+  }, [blockNumber]);
+  return data;
+}
+```
+
+### Multi-Step Workflows
+Compose hooks for complex flows (mint → wait for commit → sync → consume):
+```tsx
+const { mutate: mint } = useMint();
+const { mutate: waitForCommit } = useWaitForCommit();
+const { mutate: waitForNotes } = useWaitForNotes();
+const { mutate: consume } = useConsume();
+
+const mintAndConsume = async () => {
+  const { transactionId } = await mint({ targetAccountId, faucetId, amount });
+  await waitForCommit({ transactionId });
+  await waitForNotes({ accountId: targetAccountId });
+  await consume({ accountId: targetAccountId, noteIds: [...] });
+};
+```
+
+### Custom Signer Implementation
+Implement the SignerContextValue interface, wrap MidenProvider in your provider. Reference `src/context/SignerContext.ts` for the exact interface contract. The `storeName` field must be unique per user to ensure IndexedDB isolation.

package/template/create-miden-app/template/.claude/skills/miden-concepts/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: miden-concepts
+description: Miden architecture and core concepts from a developer perspective. Covers the actor model, accounts, notes, transactions, assets, privacy model, and standard patterns. Use when designing Miden applications or understanding how Miden differs from traditional blockchains.
+---
+
+# Miden Architecture for Developers
+
+## What is Miden?
+
+Miden is a zero-knowledge rollup that uses an **actor model** where each account is an independent smart contract. It settles on Ethereum via validity proofs through Agglayer.
+
+Key properties:
+- **Privacy by default** — accounts, notes, and transactions are private; the network stores only cryptographic commitments
+- **Client-side execution** — transactions are executed and proven locally by the user's device
+- **Programmable everything** — accounts hold code and storage; notes carry scripts and assets
+
+## Mental Model Shifts from Traditional Blockchains
+
+| Traditional (Ethereum) | Miden |
+|------------------------|-------|
+| Transactions involve sender + receiver | Transactions involve **one account only** |
+| Public state by default | **Private by default** |
+| Validators execute transactions | **Client executes and proves** locally |
+| Gas metering | No gas (computational bounds exist) |
+| Synchronous contract calls | **Asynchronous** communication via notes |
+| Accounts are balances + storage | Accounts are **full smart contracts** with code, storage, and vault |
+
+## Core Concepts
+
+### Accounts
+Each account is an independent smart contract containing:
+- **Code** — Immutable logic compiled from Rust components
+- **Storage** — Up to 255 slots (Value or StorageMap)
+- **Vault** — Holds fungible and non-fungible assets
+- **Nonce** — Incremented with each state change
+- **ID** — Unique identifier (prefix + suffix, 2 Felts)
+
+Accounts are composed from **components** — reusable Rust modules annotated with `#[component]`.
+
+### Notes
+Notes are **UTXO-like messages** for asynchronous inter-account communication. A note contains:
+- **Script** — Logic that executes when the note is consumed
+- **Inputs** — Data passed to the script (Vec<Felt>)
+- **Assets** — Fungible/non-fungible tokens attached to the note
+- **Metadata** — Sender, tag, note type (public/private)
+
+Notes are created as **output notes** by one transaction and consumed as **input notes** by another.
+
+### Transactions
+A transaction is a **single-account state transition** with 4 phases:
+1. Consume input notes (execute their scripts against the account)
+2. Execute transaction script (optional, for one-off logic)
+3. Update account state (storage, vault, nonce)
+4. Produce output notes (for other accounts to consume later)
+
+**Important**: A two-party transfer (Alice sends Bob tokens) requires TWO transactions:
+1. Alice's transaction creates a P2ID note with tokens attached
+2. Bob's transaction consumes that note, receiving the tokens
+
+### Assets
+- **Fungible**: `[amount, 0, faucet_suffix, faucet_prefix]` (1 Word)
+- **Non-fungible**: Unique token tied to a faucet account
+- Assets live in account **vaults** and move between accounts via notes
+- Created by **faucet accounts** using `faucet::create_fungible_asset()` or `faucet::mint()`
+
+### Felt and Word
+- **Felt**: Field element in the Goldilocks prime field (p = 2^64 - 2^32 + 1). The fundamental data unit.
+- **Word**: Array of 4 Felts (32 bytes). Used for cryptographic hashes, storage keys, account IDs.
+
+**WARNING**: Felt arithmetic is **modular**. Subtraction wraps around the prime. Always validate with `.as_u64()` before subtracting. See the miden-pitfalls skill for details.
+
+## Standard Note Patterns
+
+| Pattern | Purpose | How It Works |
+|---------|---------|-------------|
+| **P2ID** | Send assets to a specific account | Note script checks consumer's ID matches target |
+| **P2IDE** | P2ID with expiration | Adds block-height timelock; sender can reclaim after expiry |
+| **SWAP** | Atomic asset exchange | Note offers asset A, requests asset B; consumer provides B |
+
+## Standard Components (miden-standards)
+
+| Component | Purpose |
+|-----------|---------|
+| `BasicWallet` | Standard wallet: `receive_asset()`, `move_asset_to_note()` |
+| `BasicFungibleFaucet` | Mint/burn fungible tokens |
+| `NoAuth` | No authentication (for testing) |
+| `AuthFalcon512Rpo` | Production signature authentication |
+
+## Development Model
+
+```
+Developer writes Rust → Compiler produces MASM → VM executes and proves
+```
+
+Three contract types:
+- `#[component]` — Account logic and storage (can have multiple per account)
+- `#[note]` — Note script (executes when consumed)
+- `#[tx_script]` — One-off transaction logic
+
+Contracts are tested locally with **MockChain** (no network needed) and deployed via **miden-client**.
+
+## Key Design Decisions for App Architects
+
+1. **One account per service** — Each bank, vault, or DEX pool is a separate account
+2. **Notes for communication** — Use deposit/withdraw/request notes instead of direct calls
+3. **Storage for state** — Use `Value` for flags, `StorageMap` for mappings
+4. **Privacy by default** — Choose `NoteType::Public` only when discoverability is needed
+5. **Components for reuse** — Standard wallet, auth, and faucet components compose into accounts

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

@@ -0,0 +1,294 @@
+---
+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
+
+All return `{ data, isLoading, error, refetch }`.
+
+### useAccounts()
+```tsx
+const { data: accounts } = useAccounts();
+// accounts.wallets — regular wallet accounts
+// accounts.faucets — token faucet accounts
+// accounts.all — everything (AccountHeader[])
+```
+
+### useAccount(accountId: string)
+```tsx
+const { data: account } = useAccount(accountId);
+// account.account — Account object (.id, .nonce, .bech32id())
+// account.assets — AssetBalance[] (assetId, amount, symbol?, decimals?)
+// account.getBalance(faucetId) — bigint balance for specific token
+```
+
+### useNotes(filter?)
+```tsx
+const { data: notes } = useNotes();
+// notes.notes — InputNoteRecord[]
+// notes.consumableNotes — ConsumableNoteRecord[]
+// notes.noteSummaries — NoteSummary[] (id, assets, sender)
+// notes.consumableNoteSummaries — NoteSummary[]
+
+// Filter by account:
+const { data } = useNotes({ accountId: "0x..." });
+// Filter by status:
+const { data } = useNotes({ status: "committed" });
+```
+
+### useSyncState()
+```tsx
+const { syncHeight, isSyncing, lastSyncTime, sync, error } = useSyncState();
+await sync(); // Manual sync
+```
+
+### useAssetMetadata(faucetId: string | string[])
+```tsx
+const { data: metadata } = useAssetMetadata(faucetId);
+// metadata.symbol — "TEST"
+// metadata.decimals — 8
+```
+
+### useTransactionHistory(options?)
+```tsx
+const { records, record, status, isLoading } = useTransactionHistory({ id: txId });
+// status: "pending" | "committed" | "discarded" | null
+```
+
+## Mutation Hooks
+
+All return `{ mutate, data, isLoading, stage, error, reset }`.
+
+**Transaction stages**: `"idle"` → `"executing"` → `"proving"` → `"submitting"` → `"complete"`
+
+### useCreateWallet()
+```tsx
+const { mutate: createWallet, isLoading } = 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 { mutate: createFaucet } = useCreateFaucet();
+const faucet = await createFaucet({
+  tokenSymbol: "TEST",
+  decimals: 8,             // Default: 8
+  maxSupply: 1000000n,     // bigint!
+  storageMode: "public",   // Default: "private"
+});
+```
+
+### useSend()
+```tsx
+const { mutate: send, stage } = 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 { mutate: multiSend } = useMultiSend();
+await multiSend({
+  from: senderAccountId,
+  assetId: faucetId,
+  recipients: [
+    { to: recipient1, amount: 500n },
+    { to: recipient2, amount: 300n },
+  ],
+  noteType: "private",
+});
+```
+
+### useMint()
+```tsx
+const { mutate: mint } = useMint();
+await mint({
+  targetAccountId: recipientId,
+  faucetId: myFaucetId,
+  amount: 10000n,         // bigint!
+  noteType: "public",
+});
+```
+
+### useConsume()
+```tsx
+const { mutate: consume } = useConsume();
+await consume({
+  accountId: myAccountId,
+  noteIds: [noteId1, noteId2],
+});
+```
+
+### useSwap()
+```tsx
+const { mutate: swap } = useSwap();
+await swap({
+  accountId: myAccountId,
+  offeredFaucetId: tokenA,
+  offeredAmount: 100n,
+  requestedFaucetId: tokenB,
+  requestedAmount: 50n,
+  noteType: "private",
+  paybackNoteType: "private",
+});
+```
+
+### useTransaction() — Escape Hatch
+```tsx
+const { mutate: execute } = 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 { mutate: waitForCommit } = useWaitForCommit();
+await waitForCommit({
+  transactionId: result.transactionId,
+  timeoutMs: 10000,   // Default: 10000
+  intervalMs: 1000,    // Default: 1000
+});
+```
+
+### useWaitForNotes()
+```tsx
+const { mutate: waitForNotes } = useWaitForNotes();
+await waitForNotes({
+  accountId: myAccountId,
+  minCount: 1,         // Default: 1
+  timeoutMs: 10000,
+});
+```
+
+## Transaction Progress UI
+
+```tsx
+function SendButton({ from, to, assetId, amount }) {
+  const { mutate: 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";
+```