create-miden-app 1.0.6 → 1.0.7

package/template/.claude/skills/web-client-usage/SKILL.md

@@ -0,0 +1,454 @@
+---
+name: web-client-usage
+description: Conventions for writing JavaScript/TypeScript code that uses the Miden web SDK (`@miden-sdk/miden-sdk`). Use when building apps on Miden, writing integration tests, or calling MidenClient methods - covers initialization, the resource-based API (accounts, transactions, notes, keystore, compile), sync ordering, type conversions, transaction flows, custom contracts, private note transport, and pitfalls.
+---
+
+NOTE: In the frontend-template context, prefer @miden-sdk/react hooks for all
+operations they cover. Use the raw WebClient patterns documented here ONLY for
+operations not available through React hooks (e.g., custom TransactionRequests,
+direct store import/export, advanced sync control).
+
+# Web SDK Usage Patterns
+
+This skill targets the `@miden-sdk/miden-sdk` npm package shipped from
+[`0xMiden/miden-client`](https://github.com/0xMiden/miden-client). For
+React-hook usage, prefer the `react-sdk-patterns` skill - only fall through
+to the raw client when a hook does not cover what you need.
+
+## API Overview
+
+The SDK exposes a top-level `MidenClient` whose state is split across typed
+**resources**:
+
+| Resource | What it covers |
+|----------|----------------|
+| `client.accounts` | Wallets, faucets, custom contracts, listing, import/export |
+| `client.transactions` | `send` / `mint` / `consume` / `consumeAll` / `swap` / `execute` / `preview` / `waitFor` |
+| `client.notes` | Listing, fetching, importing/exporting, private-note transport |
+| `client.tags` | Note-tag subscriptions |
+| `client.settings` | Persistent client settings |
+| `client.compile` | Compiling MASM into account components, tx scripts, note scripts |
+| `client.keystore` | Inserting / fetching / removing secret keys |
+
+`MidenClient` is the public surface. The underlying WASM-bound class is still
+exported as `WasmWebClient` (alias for the legacy `WebClient`) for low-level
+operations the resource API does not yet wrap. To reach it, either use the
+React `useMidenClient()` hook or import `WasmWebClient` directly from
+`@miden-sdk/miden-sdk` (the class is `@internal` but exported). `MidenClient`
+keeps its wrapped client in a real JS private field (`#inner`), so external
+code cannot reach in directly.
+
+## Client Initialization
+
+### Convenience constructors (recommended)
+
+```typescript
+import { MidenClient } from "@miden-sdk/miden-sdk";
+
+// Testnet - autoSync on, testnet RPC + prover + note transport
+const client = await MidenClient.createTestnet();
+
+// Devnet equivalent
+const client = await MidenClient.createDevnet();
+```
+
+Both accept the same `ClientOptions` for overrides:
+
+```typescript
+const client = await MidenClient.createTestnet({
+  storeName: "my-app-tests",      // isolates the IndexedDB store
+  proverUrl: "local",             // prove locally instead of remote
+  autoSync: false,                // disable initial sync
+});
+```
+
+### Generic constructor
+
+```typescript
+const client = await MidenClient.create({
+  rpcUrl: "https://rpc.testnet.miden.io",  // string URL or "testnet"/"devnet"/"localhost"
+  noteTransportUrl: "https://ntx.testnet.miden.io",
+  storeName: "my-store",
+  seed: new Uint8Array(32),         // optional - deterministic key generation
+  proverUrl: "testnet",             // optional - sets a default prover
+  autoSync: true,                   // optional - call sync() after init
+  keystore: {                       // optional - external HSM/keystore
+    getKey: async (pubKey) => { /* return secretKey or null */ },
+    insertKey: async (pubKey, secretKey) => { /* persist */ },
+    sign: async (pubKey, signingInputs) => { /* return signature */ },
+  },
+});
+```
+
+If `rpcUrl` is omitted, `create()` delegates to `createTestnet()`.
+
+### Lazy / SSR-safe init
+
+Some bundles (Next.js, Capacitor, raw `/lazy` entry) cannot await WASM at
+import time. Use `MidenClient.ready()` to wait for WASM in-band - it is
+idempotent and shared across callers:
+
+```typescript
+await MidenClient.ready();
+const client = await MidenClient.createTestnet();
+```
+
+### Termination
+
+```typescript
+client.terminate();   // free WASM resources, close the store handle
+```
+
+After `terminate()`, every method throws - guard against late callbacks on
+unmount.
+
+## Sync - Always Sync First
+
+The client's view of the chain is only as fresh as its last sync. **Always
+call `sync()` before reading account state or building a transaction that
+depends on freshly received notes.**
+
+```typescript
+const summary = await client.sync();          // returns SyncSummary
+const height  = await client.getSyncHeight(); // current local block number
+```
+
+Common patterns:
+
+- Sync before consuming notes (notes must be committed on-chain)
+- Sync after submitting a transaction to observe the result
+- Pass `waitForConfirmation: true` to a `transactions.send/mint/consume/swap`
+  call to let the SDK wait for the tx commit instead of polling manually
+- Use `client.waitForIdle()` to flush all queued WASM calls before doing a
+  side-effect that must not race with a kernel callback (e.g. clearing an
+  in-memory unlock token after a wallet "lock")
+
+`autoSync: true` (default for `createTestnet`/`createDevnet`) only triggers a
+single sync at construction time - it is not a polling loop. Use the React
+SDK's `useSyncState` or `MidenProvider` `autoSyncInterval` for periodic sync.
+
+## Type Conversions
+
+Type confusion across the WASM boundary is the leading source of bugs.
+
+### `AccountId`
+
+```typescript
+const id = AccountId.fromHex("0xabc123...");          // throws on invalid hex
+const id = Address.fromBech32("mtst1abc...").accountId();
+const hex = id.toString(); // "0x..."
+```
+
+Pass `AccountId` (or any account ref the resource accepts: `string` hex,
+`Address`, `Account`, `AccountHeader`) to resource methods - never raw
+strings to methods that ask for `AccountId` directly.
+
+`AccountId.fromHex` throws on malformed input; wrap in `try/catch` when
+accepting user input.
+
+### Amounts - Always `BigInt`
+
+```typescript
+BigInt(1000)
+1000n           // numeric literal
+BigInt("1000")
+```
+
+All token amounts in the SDK are `bigint`. Mixing `number` causes silent
+precision loss above `Number.MAX_SAFE_INTEGER` and `TypeError` below.
+
+### Visibility & Account Types
+
+```typescript
+import { NoteVisibility, AccountType, AuthScheme, StorageMode } from "@miden-sdk/miden-sdk";
+
+NoteVisibility.Public  // "public"
+NoteVisibility.Private // "private"
+
+AccountType.MutableWallet
+AccountType.ImmutableWallet
+AccountType.FungibleFaucet
+AccountType.NonFungibleFaucet
+AccountType.MutableContract
+AccountType.ImmutableContract
+
+AuthScheme.Falcon      // default - Falcon-512 over Poseidon2
+AuthScheme.ECDSA       // EcdsaK256Keccak
+
+StorageMode.Public
+StorageMode.Private
+StorageMode.Network
+```
+
+Use `NoteVisibility` (not the legacy `NoteType` enum) and `AuthScheme.Falcon`
+for the Poseidon2-based Falcon-512 scheme.
+
+## Account Creation
+
+Type discriminator on `auth`: wallets and faucets take `auth: AuthSchemeType` (a `"falcon" | "ecdsa"` string-union, e.g. `AuthScheme.Falcon`); custom contracts take `auth: AuthSecretKey` (a concrete WASM instance).
+
+```typescript
+// Wallet - defaults: mutable, private, Falcon
+const wallet = await client.accounts.create();
+
+// Wallet with explicit options
+const wallet = await client.accounts.create({
+  type: AccountType.MutableWallet,
+  storage: "private",
+  auth: AuthScheme.Falcon,
+});
+
+// Faucet
+const faucet = await client.accounts.create({
+  type: AccountType.FungibleFaucet,
+  storage: "public",
+  symbol: "DAG",
+  decimals: 8,
+  maxSupply: 10_000_000n,
+});
+
+// Custom contract - requires seed and AuthSecretKey
+const component = await client.compile.component({ code: contractMasm, slots: [] });
+const contract = await client.accounts.create({
+  type: AccountType.MutableContract,
+  seed: new Uint8Array(32),
+  auth: secretKey,            // AuthSecretKey, not the AuthScheme enum
+  components: [component],
+});
+```
+
+## Transactions
+
+The transactions API is option-bag-based and accepts any account ref
+(`Account`, `AccountHeader`, hex string, `AccountId`).
+
+### Send
+
+```typescript
+const { txId } = await client.transactions.send({
+  account: wallet,                 // sender
+  to: "0xrecipient...",            // any account ref
+  token: faucet,                   // faucet account ref - identifies the asset
+  amount: 100n,
+  type: NoteVisibility.Public,     // optional, defaults to "public" (raw SDK; resolveNoteType in dist/index.js:307-316). React useSend defaults to "private".
+  reclaimAfter: 100,               // optional - sender can reclaim after this block
+  timelockUntil: 50,               // optional - recipient can consume after this block
+  waitForConfirmation: true,
+  timeout: 30_000,
+});
+```
+
+For private sends where you also need to deliver the note out-of-band, set
+`returnNote: true` and the call returns the constructed `Note` object -
+incompatible with `reclaimAfter`/`timelockUntil`.
+
+```typescript
+const { txId, note } = await client.transactions.send({
+  account: wallet,
+  to: recipientAddress,
+  token: faucet,
+  amount: 100n,
+  type: NoteVisibility.Private,
+  returnNote: true,
+});
+
+// Stream the note via the note-transport service
+await client.notes.sendPrivate({ note, to: Address.fromBech32("mtst1...") });
+```
+
+### Mint
+
+```typescript
+const { txId } = await client.transactions.mint({
+  account: faucet,                 // faucet executes the mint
+  to: targetAccountId,             // recipient
+  amount: 1000n,
+  type: NoteVisibility.Public,
+  waitForConfirmation: true,
+});
+```
+
+The transaction executes on the **faucet** - a frequent bug is passing the
+recipient as `account`.
+
+### Consume
+
+```typescript
+// Specific notes
+await client.transactions.consume({
+  account: wallet,
+  notes: [noteId1, noteRecord, "0xnote..."],   // any of: hex, NoteId, InputNoteRecord, Note
+  waitForConfirmation: true,
+});
+
+// Drain everything consumable for the account
+const { txId, consumed, remaining } = await client.transactions.consumeAll({
+  account: wallet,
+  maxNotes: 50,                    // optional cap
+});
+```
+
+### Swap
+
+```typescript
+await client.transactions.swap({
+  account: wallet,
+  offered: { token: tokenA, amount: 100n },
+  requested: { token: tokenB, amount: 50n },
+  type: NoteVisibility.Public,            // swap-note visibility
+  paybackType: NoteVisibility.Private,    // payback-note visibility
+});
+```
+
+### Execute (custom scripts)
+
+```typescript
+const script = await client.compile.txScript({
+  code: scriptMasm,
+  libraries: [{ namespace: "my::lib", code: libMasm, linking: "dynamic" }],
+});
+
+await client.transactions.execute({
+  account: contract,
+  script,
+  foreignAccounts: [
+    publicAccountId,                    // public - auto-fetched via RPC
+    { id: privateContractId, storage: storageRequirements },
+  ],
+  waitForConfirmation: true,
+});
+```
+
+**Public foreign accounts are auto-fetched** during execution - only private
+foreign accounts must be supplied with their storage requirements.
+
+### Preview (dry run)
+
+`transactions.preview({ operation: "send" | "mint" | "consume" | "swap" | "custom", ... })`
+runs the same kernel as the real call but without proving or submitting,
+returning a summary suitable for UI confirmation screens.
+
+## Notes
+
+```typescript
+await client.notes.list();                            // all input notes
+await client.notes.list({ status: "committed" });     // filter
+await client.notes.get(noteId);                       // single record
+await client.notes.listSent();                        // output notes
+await client.notes.listAvailable({ account: wallet });// consumable for an account
+
+// Import/export
+await client.notes.import(noteFile);
+const file = await client.notes.export(noteId);
+
+// Private-note transport
+await client.notes.fetchPrivate();                    // pulls anything addressed to tracked accounts
+await client.notes.sendPrivate({ note, to: addr });   // delivers via the transport service
+```
+
+## Accounts (querying)
+
+```typescript
+await client.accounts.list();                         // tracked accounts
+await client.accounts.get(ref);                       // single (returns null if not tracked)
+await client.accounts.getOrImport(ref);               // tries get(), falls back to import()
+await client.accounts.getDetails(ref);                // header + status + vault summary
+await client.accounts.insert({ account, overwrite }); // start tracking an existing account
+```
+
+For balance reads, use `getDetails` or - if you need a single asset balance
+without loading the full vault - drop into the underlying WASM client's
+`accountReader(id)` lazy reader.
+
+## Keystore
+
+```typescript
+await client.keystore.insert(accountId, secretKey);
+await client.keystore.get(pubKeyCommitment);
+await client.keystore.remove(pubKeyCommitment);
+await client.keystore.getCommitments(accountId);
+await client.keystore.getAccountId(pubKeyCommitment);
+```
+
+`keystore.insert` is the single call that both stores the key and registers
+its commitment with the account.
+
+## Compile
+
+```typescript
+await client.compile.component({ code, slots, supportAllTypes: true }); // supportAllTypes defaults to true (api-types.d.ts:784); set false if your component supplies its own auth-tx kernel invocation.
+await client.compile.txScript({ code, libraries });
+await client.compile.noteScript({ code, libraries });
+```
+
+Note scripts are **MASM libraries with a single `@note_script`-annotated
+procedure**, not begin/end programs - `client.compile.noteScript` builds the
+correct shape from a procedure body. The same applies to `@auth_script` for
+authentication scripts.
+
+## Common Workflows
+
+### Mint and consume (fund a fresh wallet)
+
+```typescript
+const wallet = await client.accounts.create();
+const faucet = await client.accounts.create({
+  type: AccountType.FungibleFaucet,
+  storage: "public",
+  symbol: "TEST",
+  decimals: 8,
+  maxSupply: 1_000_000n,
+});
+
+await client.transactions.mint({
+  account: faucet,
+  to: wallet,
+  amount: 10_000n,
+  type: NoteVisibility.Public,
+  waitForConfirmation: true,
+});
+
+await client.sync();
+await client.transactions.consumeAll({
+  account: wallet,
+  waitForConfirmation: true,
+});
+```
+
+### Wait for an external transfer
+
+```typescript
+await client.sync();
+const before = (await client.notes.listAvailable({ account: wallet })).length;
+
+while (true) {
+  await new Promise(r => setTimeout(r, 3000));
+  await client.sync();
+  const now = (await client.notes.listAvailable({ account: wallet })).length;
+  if (now > before) break;
+}
+```
+
+## Common Pitfalls
+
+1. **Forgetting to sync.** Notes won't appear, balances will be stale, foreign
+   accounts will be at the wrong block.
+2. **`number` instead of `BigInt`** for amounts - silent precision loss.
+3. **Passing strings where the SDK expects an account ref** - pre-parse with
+   `AccountId.fromHex()` (and catch its throw).
+4. **Consuming notes before they're committed** - sync first, check status.
+5. **Submitting `mint` with the recipient as `account`** - mint executes on
+   the faucet account, not the target.
+6. **Private notes without transport** - must call `notes.sendPrivate()` (or
+   pass `returnNote: true` to `transactions.send` and deliver out-of-band).
+7. **Holding WASM-owned objects across `terminate()`** - every `Account`,
+   `Note`, `AccountId`, `NoteAndArgsArray` etc. owns Rust memory through the
+   WASM ArrayBuffer. After `terminate()` they panic with "null pointer
+   passed to rust" - drop references on unmount.
+8. **Calling `accountReader(...)` in parallel with a write** (the method lives
+   on the raw `WasmWebClient`, accessed via React's `useMidenClient()` or a
+   direct `WasmWebClient` import; not on `MidenClient`) - the readers share
+   the WASM client. Wrap concurrent flows with `client.waitForIdle()` or rely
+   on the React SDK's `runExclusive`. For multiple browser clients or tabs,
+   give each isolated client a distinct `storeName`; see the initialization
+   examples above and `signer-integration` for per-user store isolation.

package/template/.env.example

@@ -1,5 +1,18 @@
-# Miden RPC endpoint (default: "testnet")
+# Miden SDK network configuration
+# Supported values: devnet | testnet | local | https://your-rpc-url
 VITE_MIDEN_RPC_URL=testnet
 
-# Miden prover (default: "testnet", alternative: "local")
+# Prover configuration
+# Supported values: devnet | testnet | local | https://your-prover-url
 VITE_MIDEN_PROVER=testnet
+
+# Counter contract address (bech32, e.g. mtst1...).
+#
+# Resolution rules:
+#   - Leave this line commented out / unset → app uses the live testnet
+#     default counter shipped with the template (recommended for first-run).
+#   - Set to "" (empty string) → unconfigured; <Counter> shows the
+#     "address not configured" card (useful when you've deployed nothing
+#     yet and don't want network calls).
+#   - Set to your own bech32 address → app reads from that counter.
+# VITE_MIDEN_COUNTER_ADDRESS=

package/template/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}

package/template/CLAUDE.md

@@ -30,20 +30,32 @@ Type checking alone:
 npx tsc -b --noEmit
 ```
 
-## SDK Choice: React SDK over Raw WebClient
+## SDK Choice: React SDK Hooks First
 
-ALWAYS prefer `@miden-sdk/react` hooks over raw `@miden-sdk/miden-sdk` WebClient methods.
-Only use WebClient directly via `useMidenClient()` for operations not covered by hooks.
+ALWAYS prefer `@miden-sdk/react` hooks over low-level `WasmWebClient` methods.
+Only use the WASM client directly via `useMidenClient()` for operations not covered by hooks.
 
-### Setup (main.tsx or App.tsx)
+### Setup — this template's actual providers (`src/providers.tsx`)
 ```tsx
 import { MidenProvider } from "@miden-sdk/react";
-
-<MidenProvider config={{ rpcUrl: "testnet", prover: "testnet" }}>
-  <App />
-</MidenProvider>
+import { MidenFiSignerProvider } from "@miden-sdk/miden-wallet-adapter-react";
+
+<MidenFiSignerProvider
+  appName={APP_NAME}
+  network={WalletAdapterNetwork.Testnet}
+  autoConnect
+>
+  <MidenProvider
+    config={{ rpcUrl: MIDEN_RPC_URL, prover: MIDEN_PROVER }}
+    loadingComponent={<div className="loading">Loading Miden WASM...</div>}
+  >
+    <App />
+  </MidenProvider>
+</MidenFiSignerProvider>
 ```
 
+> `MidenFiSignerProvider` must wrap `MidenProvider`. `MidenProvider` reads from `SignerContext` during initialization (to wire its external-keystore client), so the signer context has to exist before `MidenProvider` mounts.
+
 ### Query Hooks
 Each returns its own result shape plus `isLoading`, `error`, `refetch`:
 ```tsx
@@ -73,6 +85,8 @@ const display = formatAssetAmount(balance, 8);  // bigint → string
 const amount = parseAssetAmount("1.5", 8);       // string → bigint
 ```
 
+For exhaustive hook API reference, read `node_modules/@miden-sdk/react/CLAUDE.md` and `node_modules/@miden-sdk/react/README.md`.
+
 ## TDD Workflow
 
 When building features, follow this test-driven cycle:
@@ -110,15 +124,28 @@ Automated verification runs in layers (each catches different failure classes):
 
 1. **TypeScript type check** (auto, per-edit) — catches type errors immediately
 2. **Affected tests** (auto, per-edit) — catches logic regressions from changes
-3. **Full test suite + type check + build** (auto, on task completion via Stop hook) — catches integration issues
-4. **Browser verification** (manual/MCP) — catches "compiles but doesn't work" failures
+3. **Full test suite + type check + build** (auto, on each edit via PostToolUse) — catches integration issues
+4. **Browser verification** (Playwright MCP / Claude in Chrome) — catches "compiles but doesn't work" failures
 
 ### Browser verification (when needed)
-After completing a feature, verify in the browser:
+
+Two tools are available for browser verification. Use whichever is appropriate:
+
+#### Playwright MCP (visual verification, no wallet)
+Configured in `.mcp.json`. Use for checking that the UI renders correctly, no console errors, layout looks right. Cannot interact with the MidenFi wallet extension.
+
 1. Start dev server: `yarn dev`
-2. Navigate to `http://localhost:5173`
-3. Check for render errors and console messages
-4. If wallet-dependent features: ask the PM to verify with the MidenFi wallet extension
+2. Use Playwright MCP tools to navigate to `http://localhost:5173`
+3. Take a screenshot, check for render errors
+4. Check the browser console for errors
+
+#### Claude in Chrome (full verification, with wallet)
+Use for wallet-dependent features. Connects to the user's real browser where MidenFi is installed.
+
+1. Start Claude Code with `claude --chrome` (or run `/chrome` in session)
+2. Start dev server: `yarn dev`
+3. Navigate to `http://localhost:5173`
+4. Interact with wallet connect, transaction flows, etc.
 
 ## Contract Artifact Handoff
 
@@ -148,6 +175,12 @@ cargo miden build --release
 - **Stale artifacts**: Rebuild and re-copy after contract changes
 - **Deserialization failure at runtime**: Version mismatch — rebuild contracts with the SDK version matching `@miden-sdk/miden-sdk` in `package.json`
 
+## Known Temporary Workarounds
+
+One remaining upstream feature gap. The README has full rationale + removal steps; summary below.
+
+**Fixed-interval network poll** ([0xMiden/miden-client#2111](https://github.com/0xMiden/miden-client/issues/2111)): `useIncrementCounter.ts::increment` polls the counter's storage map every `NETWORK_POLL_INTERVAL_MS` (2.5 s) until the value changes or `NETWORK_POLL_TIMEOUT_MS` (30 s) elapses. `useWaitForCommit` doesn't apply because the increment is wallet-submitted and consumed externally by the network operator — the local client never sees the tx. #2111 tracks a React-SDK subscription primitive for this case (narrowed from the broader event-system discussion in #467).
+
 ## Critical Pitfalls
 
 **WASM init must complete first**: Always use MidenProvider's `loadingComponent` or check `useMiden().isReady`. Components rendering before WASM init will crash.
@@ -167,7 +200,7 @@ For non-developer users building with this template:
 3. Describe the app you want to build in natural language
 4. Claude will implement features using TDD — tests are written first, then code
 5. Automated hooks verify correctness at every step
-6. When Claude says "done", the Stop hook runs full tests + build automatically
+6. Automated hooks run full tests + build after each code edit
 7. Review the app in the browser: `yarn dev` → open `http://localhost:5173`
 8. If using wallet features, install the MidenFi browser extension to test
 
@@ -201,7 +234,7 @@ git clone https://github.com/vercel-labs/agent-skills.git
 
 ## Advanced Development
 
-For complex applications beyond basic hook usage (custom signers, raw WebClient, advanced note flows):
+For complex applications beyond basic hook usage (custom signers, direct WasmWebClient access, advanced note flows):
 
 1. Clone `miden-client` repo alongside this project (see `frontend-source-guide` skill)
 2. Use Plan Mode first — Claude explores React SDK source + examples before coding