create-miden-app 1.0.6 → 1.0.7

package/template/create-miden-app/template/.claude/hooks/typecheck.sh

@@ -1,27 +0,0 @@
-#!/bin/bash
-# Post-edit hook: runs TypeScript type checking when .ts/.tsx files in src/ are modified.
-# Reads JSON input from stdin (Claude Code hook protocol).
-
-INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
-
-# Only trigger for TypeScript/React files in src/
-if [[ -z "$FILE_PATH" ]] || [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.tsx ]]; then
-  exit 0
-fi
-
-if [[ "$FILE_PATH" != *"/src/"* ]]; then
-  exit 0
-fi
-
-# Run TypeScript type checking from project root
-cd "$CLAUDE_PROJECT_DIR" || exit 0
-
-if npx tsc -b --noEmit 2>&1; then
-  echo '{"hookSpecificOutput": {"additionalContext": "TypeScript type check passed"}}'
-  exit 0
-else
-  CHECK_OUTPUT=$(npx tsc -b --noEmit 2>&1 | tail -30)
-  echo "{\"hookSpecificOutput\": {\"additionalContext\": \"TypeScript type check FAILED. Fix type errors before continuing.\n$CHECK_OUTPUT\"}}"
-  exit 2
-fi

package/template/create-miden-app/template/.claude/settings.json

@@ -1,17 +0,0 @@
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/typecheck.sh",
-            "timeout": 60,
-            "statusMessage": "Type checking modified files..."
-          }
-        ]
-      }
-    ]
-  }
-}

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

@@ -1,189 +0,0 @@
----
-name: frontend-pitfalls
-description: Critical pitfalls and safety rules for Miden frontend development. Covers WASM initialization, concurrent access crashes, COOP/COEP headers, BigInt handling, Bech32 network mismatches, IndexedDB state loss, auto-sync side effects, Vite configuration, and React rendering race conditions. Use when reviewing, debugging, or writing Miden frontend code.
----
-
-# Miden Frontend Pitfalls
-
-## FP1: WASM Initialization Race (CRITICAL)
-
-Components that use Miden hooks before MidenProvider finishes WASM initialization will crash.
-
-```tsx
-// WRONG — crashes if WASM not ready
-function App() {
-  const { data } = useAccounts(); // throws before init
-  return <div>{data?.wallets.length}</div>;
-}
-
-// CORRECT — use loadingComponent or check isReady
-<MidenProvider
-  config={{ rpcUrl: "devnet" }}
-  loadingComponent={<p>Loading WASM...</p>}
->
-  <App />
-</MidenProvider>
-
-// CORRECT — guard with isReady
-function App() {
-  const { isReady } = useMiden();
-  if (!isReady) return <p>Loading...</p>;
-  return <WalletView />;
-}
-```
-
-## FP2: Recursive WASM Access Crash (CRITICAL)
-
-The WASM client is single-threaded. Concurrent calls crash with "recursive use of an object detected".
-
-```tsx
-// WRONG — two operations running simultaneously
-const handleClick = async () => {
-  sync();                    // fires async
-  await send({ ... });       // runs concurrently — CRASH
-};
-
-// CORRECT — use runExclusive for sequential execution
-const { runExclusive } = useMiden();
-await runExclusive(async (client) => {
-  await client.syncState();
-  // now safe to do next operation
-});
-```
-
-Built-in hooks (useSend, useConsume, etc.) already use runExclusive internally. This pitfall applies when using `useMidenClient()` directly or mixing manual client calls with hook mutations.
-
-## FP3: COOP/COEP Headers Missing (CRITICAL)
-
-WASM SharedArrayBuffer requires these headers. Without them, WASM init silently fails.
-
-```ts
-// REQUIRED in vite.config.ts
-server: {
-  headers: {
-    "Cross-Origin-Opener-Policy": "same-origin",
-    "Cross-Origin-Embedder-Policy": "require-corp",
-  },
-},
-
-// ALSO REQUIRED on production server (nginx, Vercel, Cloudflare)
-// See vite-wasm-setup skill for deployment configs
-```
-
-**Gotcha**: These headers break third-party iframes, external scripts without CORS, and OAuth popups. Use `credentialless` for COEP if cross-origin resources are needed.
-
-**Note**: `midenVitePlugin()` from `@miden-sdk/vite-plugin` handles COOP/COEP automatically via its `crossOriginIsolation` option (defaults to `false` to avoid breaking OAuth popups). Enable it instead of setting headers manually.
-
-## FP4: BigInt Type Mismatch (HIGH)
-
-All token amounts in the SDK are `bigint`. Passing `number` causes TypeScript errors or runtime failures.
-
-```tsx
-// WRONG
-await send({ from, to, assetId, amount: 1000 });        // number — fails
-await createFaucet({ maxSupply: 1000000, ... });          // number — fails
-
-// CORRECT
-await send({ from, to, assetId, amount: 1000n });        // bigint literal
-await createFaucet({ maxSupply: BigInt(1000000), ... });  // BigInt constructor
-
-// CORRECT — use parseAssetAmount for user input
-import { parseAssetAmount } from "@miden-sdk/react";
-const amount = parseAssetAmount(inputValue, 8);           // string → bigint
-```
-
-**Gotcha**: `JSON.stringify` cannot serialize `bigint`. Use a custom replacer or convert to string first.
-
-## FP5: Bech32 Network Mismatch (HIGH)
-
-Bech32-encoded account IDs include the network. A devnet address on testnet points to a different or nonexistent account.
-
-```tsx
-// WRONG — hardcoding a bech32 address used across networks
-const ADMIN = "miden1qy35..."; // this is network-specific!
-
-// CORRECT — use hex format for cross-network compatibility
-const ADMIN = "0x1234567890abcdef";
-
-// CORRECT — derive bech32 per network
-account.bech32id(); // returns correct bech32 for current network
-```
-
-Both hex and bech32 formats work in all hooks. Prefer hex for constants, bech32 for display.
-
-## FP6: Auto-Sync Side Effects (MEDIUM)
-
-Default `autoSyncInterval` is 15000ms (15 seconds). Each sync triggers re-renders in useAccounts, useAccount, useNotes, etc.
-
-```tsx
-// PROBLEM — form resets every 15 seconds because parent re-renders
-<MidenProvider config={{ rpcUrl: "devnet" }}>
-  <SendForm />  {/* re-renders on every sync */}
-</MidenProvider>
-
-// SOLUTION 1 — preferred: use stable keys and memoization
-const MemoizedForm = React.memo(SendForm);
-
-// SOLUTION 2 — disable auto-sync for manual control
-<MidenProvider config={{ rpcUrl: "devnet", autoSyncInterval: 0 }}>
-```
-
-## FP7: IndexedDB State Loss (MEDIUM)
-
-The client persists accounts, keys, and notes in IndexedDB. Browser "Clear site data", private browsing, or storage pressure can delete everything.
-
-- Warn users that clearing browser data deletes their wallet
-- Consider external signers (Para, Turnkey) for production — keys are server-side
-- Implement account export/backup for local keystore users
-
-## FP8: Vite Configuration Requirements (MEDIUM)
-
-The `@miden-sdk/vite-plugin` package handles all Miden-specific Vite config.
-The minimal setup is:
-
-```ts
-import { midenVitePlugin } from "@miden-sdk/vite-plugin";
-
-export default defineConfig({
-  plugins: [react(), midenVitePlugin()],
-});
-```
-
-`midenVitePlugin()` handles: WASM loading, top-level await, WASM pre-bundling exclusion,
-and optionally COOP/COEP headers (via the `crossOriginIsolation` option, defaults to `false`
-to avoid breaking OAuth popups).
-
-| Option | Default | Purpose |
-|--------|---------|---------|
-| `crossOriginIsolation` | `false` | Add COOP/COEP headers for SharedArrayBuffer |
-
-Enable `crossOriginIsolation: true` only if your app doesn't use OAuth or cross-origin iframes.
-For production COOP/COEP, set headers at the server level (see vite-wasm-setup skill).
-
-## FP9: React StrictMode Double-Init (LOW)
-
-React 19 StrictMode double-invokes effects in development. MidenProvider handles this via `isInitializedRef`, but direct `WebClient.createClient()` calls will initialize twice.
-
-```tsx
-// WRONG — manual client creation in useEffect
-useEffect(() => {
-  const client = await WebClient.createClient(url); // called twice in dev
-}, []);
-
-// CORRECT — always use MidenProvider
-<MidenProvider config={{ rpcUrl: "devnet" }}>
-```
-
-## Quick Reference
-
-| # | Pitfall | Severity | One-Line Rule |
-|---|---------|----------|---------------|
-| FP1 | WASM init race | CRITICAL | Use loadingComponent or check isReady |
-| FP2 | Recursive WASM | CRITICAL | Use runExclusive() for all direct client access |
-| FP3 | COOP/COEP | CRITICAL | Add headers in vite.config.ts AND production server |
-| FP4 | BigInt | HIGH | All amounts are bigint (1000n not 1000) |
-| FP5 | Bech32 mismatch | HIGH | Match network in rpcUrl and addresses |
-| FP6 | Auto-sync | MEDIUM | Set autoSyncInterval: 0 if UI stability matters |
-| FP7 | IndexedDB loss | MEDIUM | Warn users; use external signers for production |
-| FP8 | Vite config | MEDIUM | Use `midenVitePlugin()` — it handles all Miden Vite config |
-| FP9 | StrictMode | LOW | Use MidenProvider, not manual client creation |

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

@@ -1,163 +0,0 @@
----
-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

@@ -1,108 +0,0 @@
----
-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