create-miden-app 1.0.3 → 1.0.6

package/cli.js

@@ -39,12 +39,12 @@ async function main() {
   }
 
   console.log(`
-    ✅ Done!
-    Next steps:
-    cd ${projectName}
-    npm install
-    npm run dev
-    `);
+Done! Next steps:
+
+  cd ${projectName}
+  yarn install
+  yarn dev
+`);
 }
 
 main();

package/package.json

@@ -1,16 +1,11 @@
 {
   "name": "create-miden-app",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "description": "A Miden Project Scaffold Template",
   "bin": {
     "create-miden-app": "cli.js"
   },
   "type": "module",
-  "scripts": {
-    "setup-v12": "./setup-v12.sh",
-    "update-v12": "./update-v12.sh",
-    "check-v12": "./check-v12-compatibility.sh"
-  },
   "files": [
     "cli.js",
     "template/"

package/template/.claude/hooks/check-artifacts.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Validates that required .masp contract artifacts exist in public/packages/.
+# Run before build or as a standalone check.
+
+cd "$CLAUDE_PROJECT_DIR" 2>/dev/null || cd "$(dirname "$0")/../.." || exit 1
+
+PACKAGES_DIR="public/packages"
+ERRORS=0
+
+if [ ! -d "$PACKAGES_DIR" ]; then
+  echo "ERROR: $PACKAGES_DIR directory does not exist"
+  exit 1
+fi
+
+# Check for .masp files
+MASP_FILES=$(find "$PACKAGES_DIR" -name "*.masp" 2>/dev/null)
+
+if [ -z "$MASP_FILES" ]; then
+  echo "ERROR: No .masp files found in $PACKAGES_DIR"
+  echo "Run 'cargo miden build' in the contract project and copy .masp files here."
+  exit 1
+fi
+
+echo "Contract artifacts in $PACKAGES_DIR:"
+while IFS= read -r file; do
+  SIZE=$(wc -c < "$file" | tr -d ' ')
+  if [ "$SIZE" -eq 0 ]; then
+    echo "  ERROR: $file is empty (0 bytes)"
+    ERRORS=$((ERRORS + 1))
+  elif [ "$SIZE" -lt 100 ]; then
+    echo "  WARN:  $file is suspiciously small ($SIZE bytes)"
+  else
+    echo "  OK:    $file ($SIZE bytes)"
+  fi
+done <<< "$MASP_FILES"
+
+if [ $ERRORS -gt 0 ]; then
+  echo ""
+  echo "$ERRORS artifact(s) have errors. Rebuild contracts with 'cargo miden build'."
+  exit 1
+fi
+
+echo ""
+echo "All artifacts valid."
+exit 0

package/template/.claude/hooks/run-affected-tests.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Post-edit hook: runs tests affected by changes since last commit.
+# Only triggers for .ts/.tsx files in src/. Uses vitest --changed for detection.
+
+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
+
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# Run tests affected by uncommitted changes (non-watch mode, no coverage)
+TEST_OUTPUT=$(npx vitest --changed --run 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 0 ]; then
+  echo '{"hookSpecificOutput": {"additionalContext": "Affected tests passed"}}'
+  exit 0
+else
+  # Show last 30 lines of test output for context
+  TRIMMED=$(echo "$TEST_OUTPUT" | tail -30)
+  echo "{\"hookSpecificOutput\": {\"additionalContext\": \"Affected tests FAILED. Fix failing tests before continuing.\n$TRIMMED\"}}"
+  exit 2
+fi

package/template/.claude/hooks/typecheck.sh

@@ -0,0 +1,27 @@
+#!/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/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/typecheck.sh",
+            "timeout": 60,
+            "statusMessage": "Type checking modified files..."
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-affected-tests.sh",
+            "timeout": 120,
+            "statusMessage": "Running affected tests..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && npx vitest --run && npx tsc -b --noEmit && npx vite build",
+            "timeout": 300,
+            "statusMessage": "Running full test suite + type check + build..."
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.claude/skills/frontend-pitfalls/SKILL.md

@@ -0,0 +1,189 @@
+---
+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/.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/.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