create-miden-app 1.0.4 → 1.0.7

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

@@ -0,0 +1,110 @@
+---
+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
+- **Storage** — Data accessible to the script during execution (`NoteStorage`, 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) |
+| `AuthSingleSig` | Production signature authentication — unified auth component covering both Falcon-512 and ECDSA-K256 key types |
+
+**v14 note**: `AuthSingleSig` unifies what were previously per-scheme auth components (one for Falcon-512, one for ECDSA-K256) into a single component that dispatches on the key type ([miden-client#1798](https://github.com/0xMiden/miden-client/pull/1798)). In the same release the underlying Falcon-512 signature scheme adopted Poseidon2 as its hash function, and is now named `Falcon512Poseidon2`. If you see the older per-scheme component names or the old signature-scheme name in examples or docs, the source predates 0.14 and needs updating.
+
+## 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/.claude/skills/react-sdk-patterns/SKILL.md

@@ -0,0 +1,562 @@
+---
+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 the raw `WasmWebClient` (exported as `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: "testnet",          // "devnet" | "testnet" | "localhost" | custom URL
+    prover: "testnet",          // "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 |
+|---------|--------|----------|
+| Testnet | `"testnet"` | Recommended for new projects - primary development network |
+| Devnet | `"devnet"` | Early-access testing (may lag feature parity with testnet) |
+| Localhost | `"localhost"` | Local node at `http://localhost:57291` |
+
+## Query Hooks
+
+Each returns its own result shape plus `isLoading`, `error`, `refetch`.
+
+### useAccounts()
+```tsx
+const { accounts, wallets, faucets, isLoading, error, refetch } = useAccounts();
+// wallets - AccountHeader[] (regular wallet accounts)
+// faucets - AccountHeader[] (token faucet accounts)
+// accounts - AccountHeader[] (everything)
+```
+
+### useAccount(accountId: string)
+```tsx
+const { account, assets, getBalance, isLoading, error, refetch } = useAccount(accountId);
+// account - Account object (.id, .nonce, .bech32id())
+// assets - AssetBalance[] (assetId, amount, symbol?, decimals?)
+// getBalance(faucetId) - bigint balance for specific token
+```
+
+### useNotes(filter?)
+```tsx
+const { notes, consumableNotes, noteSummaries, consumableNoteSummaries, isLoading, error, refetch } = useNotes();
+// notes - InputNoteRecord[]
+// consumableNotes - ConsumableNoteRecord[]
+// noteSummaries - NoteSummary[] (id, assets, sender)
+// consumableNoteSummaries - NoteSummary[]
+
+// Filter by account:
+const { notes } = useNotes({ accountId: "0x..." });
+// Filter by status:
+const { notes } = useNotes({ status: "committed" });
+// Filter by sender:
+const { notes } = useNotes({ sender: "0x..." });
+// Exclude specific notes:
+const { notes } = useNotes({ excludeIds: ["0xnote1", "0xnote2"] });
+```
+
+### useNoteStream(options?)
+```tsx
+const { notes, latest, markHandled, markAllHandled, snapshot, isLoading, error } = useNoteStream();
+// notes - StreamedNote[] (matching filter criteria)
+// latest - most recent StreamedNote (convenience)
+// markHandled(noteId) - exclude a note from future renders
+// markAllHandled() - exclude all current notes
+// snapshot() - capture { ids, timestamp } for cross-phase filtering
+
+// Options:
+const { notes } = useNoteStream({ status: "committed", sender: "0x..." });
+const { notes } = useNoteStream({ since: Date.now() - 60000 }); // last 60s
+const { notes } = useNoteStream({ excludeIds: new Set(["0xnote1"]) });
+const { notes } = useNoteStream({ amountFilter: (amount) => amount > 100n });
+```
+
+### useSyncState()
+```tsx
+const { syncHeight, isSyncing, lastSyncTime, sync, error } = useSyncState();
+await sync(); // Manual sync
+```
+
+### useAssetMetadata(faucetId: string | string[])
+```tsx
+const { assetMetadata } = useAssetMetadata(faucetId);
+// assetMetadata - Map<string, AssetMetadata>
+// Each entry: { assetId, symbol?, decimals? }
+const meta = assetMetadata.get(faucetId);
+// meta.symbol - "TEST"
+// meta.decimals - 8
+```
+
+### useTransactionHistory(options?)
+```tsx
+const { records, record, status, isLoading, error, refetch } = useTransactionHistory({ id: txId });
+// status: "pending" | "committed" | "discarded" | null
+```
+
+## Mutation Hooks
+
+Each returns its own action function plus `isLoading`, `stage`, `error`, `reset`.
+
+**Transaction stages**: `"idle"` → `"executing"` → `"proving"` → `"submitting"` → `"complete"`
+
+### useCreateWallet()
+```tsx
+const { createWallet, wallet, isCreating, error, reset } = useCreateWallet();
+const account = await createWallet({
+  storageMode: "private",  // "private" | "public" | "network". Default: "private"
+  mutable: true,           // Default: true
+  authScheme: 0,           // 0 = RpoFalcon512, 1 = EcdsaK256Keccak. Default: 0
+});
+```
+
+### useCreateFaucet()
+```tsx
+const { createFaucet, faucet, isCreating, error, reset } = useCreateFaucet();
+const account = await createFaucet({
+  tokenSymbol: "TEST",
+  decimals: 8,             // Default: 8
+  maxSupply: 1000000n,     // bigint!
+  storageMode: "public",   // Default: "private"
+});
+```
+
+### useImportAccount()
+```tsx
+const { importAccount, account, isImporting, error, reset } = useImportAccount();
+
+// Import by account ID (network lookup):
+const account = await importAccount({ type: "id", accountId: "0x..." });
+
+// Import from file:
+const account = await importAccount({ type: "file", file: accountFileOrBytes });
+
+// Import from seed:
+const account = await importAccount({ type: "seed", seed: seedBytes, mutable: true });
+```
+
+### useSend()
+```tsx
+const { send, result, isLoading, stage, error, reset } = useSend();
+await send({
+  from: senderAccountId,
+  to: recipientAccountId,
+  assetId: faucetId,       // token faucet ID
+  amount: 1000n,           // bigint!
+  noteType: "private",     // "private" | "public". Default: "private"
+  recallHeight: 100,       // optional: sender can reclaim after this block
+  timelockHeight: 50,      // optional: recipient can consume after this block
+  sendAll: true,           // optional: send entire balance (ignores amount)
+  attachment: [1n, 2n],    // optional: arbitrary data attached to the note
+});
+```
+
+### useMultiSend()
+```tsx
+const { sendMany, result, isLoading, stage, error, reset } = useMultiSend();
+await sendMany({
+  from: senderAccountId,
+  assetId: faucetId,
+  recipients: [
+    { to: recipient1, amount: 500n },
+    { to: recipient2, amount: 300n, noteType: "public" },          // per-recipient override
+    { to: recipient3, amount: 200n, attachment: [1n, 2n, 3n] },    // per-recipient attachment
+  ],
+  noteType: "private",     // default for all recipients
+});
+```
+
+### useMint()
+```tsx
+const { mint, result, isLoading, stage, error, reset } = useMint();
+await mint({
+  targetAccountId: recipientId,
+  faucetId: myFaucetId,
+  amount: 10000n,         // bigint!
+  noteType: "public",
+});
+```
+
+### useConsume()
+```tsx
+const { consume, result, isLoading, stage, error, reset } = useConsume();
+await consume({
+  accountId: myAccountId,
+  notes: [noteId1, noteId2],   // accepts: hex string IDs, NoteId, InputNoteRecord, or Note
+});
+```
+
+### useSwap()
+```tsx
+const { swap, result, isLoading, stage, error, reset } = useSwap();
+await swap({
+  accountId: myAccountId,
+  offeredFaucetId: tokenA,
+  offeredAmount: 100n,
+  requestedFaucetId: tokenB,
+  requestedAmount: 50n,
+  noteType: "private",
+  paybackNoteType: "private",
+});
+```
+
+### useTransaction() - Escape Hatch
+```tsx
+const { execute, result, isLoading, stage, error, reset } = useTransaction();
+
+// With pre-built TransactionRequest:
+await execute({ accountId, request: txRequest });
+
+// With factory function (gets access to client):
+await execute({
+  accountId,
+  request: (client) => client.newSwapTransactionRequest(/* ... */),
+});
+```
+
+### useWaitForCommit()
+```tsx
+const { waitForCommit } = useWaitForCommit();
+await waitForCommit(result.txId, {  // useSend returns { txId, note }; other hooks use { transactionId }
+  timeoutMs: 10000,   // Default: 10000
+  intervalMs: 1000,    // Default: 1000
+});
+```
+
+### useWaitForNotes()
+```tsx
+const { waitForConsumableNotes } = useWaitForNotes();
+await waitForConsumableNotes({
+  accountId: myAccountId,
+  minCount: 1,         // Default: 1
+  timeoutMs: 10000,
+});
+```
+
+### useSessionAccount(options)
+```tsx
+const { initialize, sessionAccountId, isReady, step, error, reset } = useSessionAccount({
+  fund: async (sessionId) => {
+    // Called after session wallet is created - fund it here
+    await send({ from: mainWallet, to: sessionId, assetId: faucetId, amount: 100n });
+  },
+  assetId: faucetId,              // optional: for note filtering
+  walletOptions: {                // optional: session wallet creation options
+    storageMode: "private",
+    mutable: true,
+    authScheme: 0,
+  },
+  pollIntervalMs: 3000,           // optional: funding detection interval. Default: 3000
+});
+// Steps: "idle" → "creating" → "funding" → "consuming" → "ready"
+// Call initialize() to start the flow. isReady becomes true when fully funded.
+```
+
+## Transaction Progress UI
+
+```tsx
+function SendButton({ from, to, assetId, amount }) {
+  const { send, stage, isLoading, error } = useSend();
+
+  return (
+    <div>
+      <button onClick={() => send({ from, to, assetId, amount })} disabled={isLoading}>
+        {isLoading ? `${stage}...` : "Send"}
+      </button>
+      {error && <p>Error: {error.message}</p>}
+    </div>
+  );
+}
+```
+
+## Signer Integration
+
+### Local Keystore (Default)
+No signer provider needed. Keys are managed in the browser via IndexedDB.
+
+### External Signers
+Wrap MidenProvider with a signer provider. Three pre-built options:
+- `ParaSignerProvider` from `@miden-sdk/para` - EVM wallets
+- `TurnkeySignerProvider` from `@miden-sdk/miden-turnkey-react` - passkey auth
+- `MidenFiSignerProvider` from `@miden-sdk/miden-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 () => {
+  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";
+```
+
+## Reading Account Storage
+
+For the high-level vault summary on a tracked account, the existing query hook is enough:
+
+```tsx
+const { account, assets, getBalance } = useAccount(accountId);
+// account.id, account.nonce, account.bech32id()
+// assets: AssetBalance[]; getBalance(faucetId): bigint
+```
+
+For lower-level reads (custom contract storage slots, map items), use `Account.storage()`. The React SDK serializes WASM access via `runExclusive`:
+
+```tsx
+const client = useMidenClient();
+const { runExclusive } = useMiden();
+
+await runExclusive(async () => {
+  const id = AccountId.fromBech32(addressBech32);
+  if (!(await client.getAccount(id))) {
+    await client.importAccountById(id);
+  }
+  await client.syncState();
+  const account = await client.getAccount(id);
+  if (!account) return;
+  // AccountStorage (miden_client_web.d.ts:639-660):
+  const value = account.storage().getItem("my_slot_name");
+  // For storage maps:
+  const mapValue = account.storage().getMapItem("my_map_slot", keyWord);
+});
+```
+
+`Account.storage()` returns an `AccountStorage`. Both `getItem(slot_name: string)` and `getMapItem(slot_name: string, key: Word)` return `Word | undefined`. Use slot-name strings (e.g. `COUNTER_SLOT_NAME` in `src/config.ts`), not numeric indices. See `src/hooks/useIncrementCounter.ts:73-83` for the live in-template `getMapItem` example.
+
+`useMidenClient()` returns the raw `WasmWebClient`. Its direct methods include `getAccount(accountId)`, `getAccountStorage(accountId)`, `importAccountById(accountId)`, `syncState()`, and the transaction-request factories (`newSendTransactionRequest`, `newConsumeTransactionRequest`, `newMintTransactionRequest`, `newSwapTransactionRequest`). For compile-from-source, call `client.createCodeBuilder()` and use the returned `CodeBuilder`'s `compileNoteScript(program: string)` / `compileTxScript(tx_script: string)` (`miden_client_web.d.ts`:1058-1115, factory at :4237). The higher-level `MidenClient.accounts.getOrImport` resource API lives on the standalone `MidenClient` (see `web-client-usage`).
+
+## Account Import then Sync then Read Storage Flow
+
+Hook-based pattern for the common "import a remote account, sync to current chain head, then read its state" workflow:
+
+```tsx
+function ImportAndInspect({ accountIdHex }: { accountIdHex: string }) {
+  const { importAccount, isImporting } = useImportAccount();
+  const { sync, isSyncing, syncHeight } = useSyncState();
+  const { account, assets, getBalance, refetch } = useAccount(accountIdHex);
+
+  async function load() {
+    await importAccount({ type: "id", accountId: accountIdHex });
+    await sync();
+    await refetch();
+  }
+  // Render account.id, syncHeight, balances...
+}
+```
+
+`useImportAccount` accepts `{ type: "id" | "file" | "seed", ... }`. After `sync()` resolves, the `useAccount(accountIdHex)` view reflects the latest chain state. For the raw `WasmWebClient` methods used by these hooks under the hood (`client.getAccount`, `client.importAccountById`, `client.syncState`), see `src/hooks/useIncrementCounter.ts` for a worked example. For the higher-level `MidenClient.accounts.*` resource API on a standalone `MidenClient` (outside React), see the `web-client-usage` skill.
+
+## Custom Notes and .masp Package Loading
+
+`.masp` package files (compiled MASM artifacts) are produced by `cargo miden build` in the `project-template/` workspace and copied into `frontend-template/public/packages/` during the contract handoff (see `CLAUDE.md` "Contract Artifact Handoff" section).
+
+The example below builds a custom transaction that emits two output notes carrying fungible assets. Each note has multi-felt input storage that the note script (compiled from MASM into `.masp`) reads and asserts on at consume time. The transaction is signed and submitted by the connected wallet via `useMidenFiWallet().requestTransaction(...)`.
+
+```tsx
+import { useMidenFiWallet } from "@miden-sdk/miden-wallet-adapter-react";
+import { Transaction } from "@miden-sdk/miden-wallet-adapter-base";
+import {
+  Package,
+  NoteScript,
+  Note,
+  NoteAssets,
+  NoteMetadata,
+  NoteRecipient,
+  NoteStorage,
+  NoteTag,
+  NoteType,
+  NoteAttachment,
+  NoteExecutionHint,
+  NoteArray,
+  AccountId,
+  Felt,
+  FeltArray,
+  FungibleAsset,
+  TransactionRequestBuilder,
+} from "@miden-sdk/miden-sdk";
+import { randomWord } from "@/lib/miden";
+
+const { requestTransaction } = useMidenFiWallet();
+
+async function submitMultiNoteTx(
+  senderBech32: string,
+  targetBech32: string,
+  faucetBech32: string,
+) {
+  // (a) .masp loading: fetch the pre-built artifact and decode the note script.
+  const buf = await fetch("/packages/my_note.masp").then((r) => r.arrayBuffer());
+  const pkg = Package.deserialize(new Uint8Array(buf));
+  const noteScript = NoteScript.fromPackage(pkg);
+
+  const sender = AccountId.fromBech32(senderBech32);
+  const target = AccountId.fromBech32(targetBech32);
+  const faucet = AccountId.fromBech32(faucetBech32);
+
+  // (b) Multi-input note storage: each output note carries multiple Felt
+  // inputs that the MASM script reads from its NoteStorage. Assertions on
+  // these felts (e.g. "the first felt must equal the expected nonce") live
+  // in the .masp script source under project-template/contracts/.
+  function makeRecipient(seedFelts: bigint[]): NoteRecipient {
+    const inputs = new FeltArray();
+    for (const v of seedFelts) inputs.push(new Felt(v));
+    return new NoteRecipient(randomWord(), noteScript, new NoteStorage(inputs));
+  }
+
+  // (c) Asset transfers: each note carries fungible assets that move to the
+  // recipient when the note is consumed. FungibleAsset is declared at
+  // miden_client_web.d.ts:1474 (constructor `(faucet_id, amount: bigint)` at :1492).
+  const assets1 = new NoteAssets([new FungibleAsset(faucet, 1000n)]);
+  const assets2 = new NoteAssets([new FungibleAsset(faucet, 500n)]);
+
+  const tag = NoteTag.withAccountTarget(target);
+  const attachment = NoteAttachment.newNetworkAccountTarget(
+    target,
+    NoteExecutionHint.always(),
+  );
+  const metadata = new NoteMetadata(sender, NoteType.Public, tag).withAttachment(
+    attachment,
+  );
+
+  // Two output notes with different felt inputs and asset amounts.
+  const note1 = new Note(assets1, metadata, makeRecipient([1n, 2n, 3n]));
+  const note2 = new Note(assets2, metadata, makeRecipient([4n, 5n, 6n]));
+
+  // (d) Multi-output transaction: emit both notes in one transaction.
+  // For transactions that consume multiple input notes simultaneously,
+  // TransactionRequestBuilder.withInputNotes(NoteAndArgsArray) is the
+  // counterpart (miden_client_web.d.ts:3963).
+  const txRequest = new TransactionRequestBuilder()
+    .withOwnOutputNotes(new NoteArray([note1, note2]))
+    .build();
+
+  // (f) Submission via the wallet adapter.
+  const tx = Transaction.createCustomTransaction(senderBech32, targetBech32, txRequest);
+  if (!requestTransaction) throw new Error("Wallet does not support requestTransaction");
+  await requestTransaction(tx);
+}
+```
+
+Notes on this pattern:
+
+- **Assertions live in MASM, not in TypeScript.** The note script compiled into `.masp` reads its `NoteStorage` felts at consume time and aborts the transaction if its assertions fail. The frontend's job is to construct and submit; MASM enforces. See `project-template/contracts/` for where to author MASM with assertion ops.
+- **Single-output reference for simpler flows.** For a simpler worked example using only one output note with empty assets and a single consume action, see `src/hooks/useIncrementCounter.ts`. That hook is intentionally simpler and does not exercise asset transfers or multi-output emission.
+- **Compile from source (no `.masp`) when needed.** When the note script is not pre-bundled as `.masp`, compile it through `CodeBuilder`. **`compileNoteScript`/`compileTxScript` are methods of `CodeBuilder`, not of `WasmWebClient`.** The pattern is:
+
+```tsx
+const client = useMidenClient();
+const builder = client.createCodeBuilder();
+// optionally: builder.linkStaticLibrary(myLib) or builder.linkDynamicLibrary(myLib)
+const noteScript = builder.compileNoteScript(noteSourceMasm);
+const txScript = builder.compileTxScript(txSourceMasm);
+```
+
+  See `miden_client_web.d.ts`:1058-1115 for `CodeBuilder` and :4237 for `createCodeBuilder()`. As the React-idiomatic alternative, `useCompile()` (`@miden-sdk/react/dist/index.d.ts`:1171-1196) wraps `CompilerResource` from the standalone `MidenClient` and exposes `noteScript`, `txScript`, `component`, `isReady` at the hook layer.
+- **Inside `useTransaction`'s `request` callback** the parameter is a `WasmWebClient` (`@miden-sdk/react/dist/index.d.ts`:393). Use `client.createCodeBuilder()` for compile, then build the `TransactionRequest` with `TransactionRequestBuilder` and return it. For the higher-level `MidenClient.compile.*` and `MidenClient.transactions.execute` resource API on a standalone `MidenClient`, see `web-client-usage`.
+
+## Cross-SDK Type Reference
+
+The runtime types come from `@miden-sdk/react` (re-exported from `@miden-sdk/miden-sdk` for the underlying `MidenClient` types). The `.d.ts` files are the source of truth. Look them up in:
+
+- the installed `.d.ts` for `@miden-sdk/react` (hook return types and option types)
+- the installed `.d.ts` for `@miden-sdk/miden-sdk` (`MidenClient`, `Account`, `AccountId`, `Note`, `Word`, etc.)
+
+Path layout differs across package managers (npm flat, pnpm nested, Yarn PnP virtual), so resolve them via your IDE's "Go to Definition" or the installed package surface rather than hard-coded paths.
+
+Common app-developer types:
+
+| Type | Source package | Notes |
+|------|----------------|-------|
+| `Account`, `AccountHeader` | `@miden-sdk/react` | `id`, `nonce`, `bech32id()` |
+| `AccountId` | `@miden-sdk/miden-sdk` | construct via `AccountId.fromHex(hex)`; throws on invalid hex |
+| `Address` | `@miden-sdk/miden-sdk` | bech32 wrapper; `Address.fromBech32(...)` |
+| `Note`, `InputNoteRecord`, `ConsumableNoteRecord` | `@miden-sdk/react` | re-exported from `@miden-sdk/miden-sdk`. Input notes are received; for output-note types and private-note flows see `web-client-usage`. |
+| `NoteVisibility` (constants + string-union) | `@miden-sdk/miden-sdk` | `const NoteVisibility = { Public: 'public', Private: 'private' }` plus `type NoteVisibility = 'public' \| 'private'` (`api-types.d.ts`:95-101). NOT an enum. Coexists with the raw WASM `NoteType` enum (`miden_client_web.d.ts`:2889) which the template uses directly when building notes via the WASM types (see `src/hooks/useIncrementCounter.ts`). |
+| `AccountType`, `AuthScheme`, `StorageMode` | `@miden-sdk/miden-sdk` | enums; see `web-client-usage` "Visibility & Account Types". |
+| `TransactionRequest` | `@miden-sdk/react` | client factory functions return this |
+| `Word` | `@miden-sdk/miden-sdk` | 32-byte (4 felts) value; `Word.toU64s()` returns `BigUint64Array` of length 4 (each lane is a `bigint` after subscript). See `miden_client_web.d.ts`:4535. |
+
+Do not hardcode this table for long-term reference. The `.d.ts` files stay in lockstep with the installed package version; this list will drift.
+
+## Rust to TypeScript Type Mapping
+
+The Rust (`miden-client`) and TypeScript (`@miden-sdk/miden-sdk`) SDKs share concepts but diverge on naming and primitive shapes. When porting between them:
+
+| Concept | Rust (`miden_objects` / `miden_client`) | TypeScript (`@miden-sdk/miden-sdk`) |
+|---------|------------------------------------------|--------------------------------------|
+| Token amount | `u64` | `bigint` |
+| Field element | `Felt` (Goldilocks `u64` mod p) | `Felt` (wraps `u64`) |
+| 32-byte word | `Word` (`[Felt; 4]`) | `Word`; `toU64s(): BigUint64Array` length 4 (each lane is `bigint` after subscript). |
+| Account identifier | `AccountId` | `AccountId`; construct via `AccountId.fromHex` |
+| Note visibility | `NoteType` enum | constants + string-union `NoteVisibility` (`'public' \| 'private'`) at the high-level `MidenClient` resource API; raw WASM `NoteType` enum (`Private = 2`, `Public = 1`) is also exported and used directly when constructing notes via the WASM types (see `src/hooks/useIncrementCounter.ts`). The two coexist; pick the layer your code lives in. |
+| Account type | `AccountType` | `AccountType` enum |
+| Authentication scheme | `AuthScheme` | `AuthScheme` enum |
+| Storage mode | `StorageMode` | `StorageMode` enum |
+
+Common gotchas:
+
+- The TS method is `FeltArray.push(element: Felt)` (`miden_client_web.d.ts`:1324); there is no `FeltArray.append`. To convert a `Felt` to a JS `bigint`, use `Felt.asInt()` (`miden_client_web.d.ts`:1296). When a Rust method appears missing in TS, consult `node_modules/@miden-sdk/miden-sdk/dist/index.d.ts` and `dist/crates/miden_client_web.d.ts` first instead of guessing the TS spelling.
+- TS amounts are always `bigint`. Mixing `number` causes silent precision loss above `Number.MAX_SAFE_INTEGER` and `TypeError` below.
+- `Word.toU64s()` returns `BigUint64Array` of length 4 (`miden_client_web.d.ts`:4535). Each lane is a `bigint` (e.g. `word.toU64s()[0]`). Use it when reading the four `u64` lanes from a Value storage slot or building assertions on `Word` outputs.
+
+For the canonical Rust types, see [`0xMiden/miden-client`](https://github.com/0xMiden/miden-client) and the `miden_objects` crate. For the canonical TS types, see `node_modules/@miden-sdk/miden-sdk/dist/index.d.ts`.