create-miden-app 1.0.6 → 1.0.7

package/template/README.md

@@ -1,6 +1,6 @@
 # Miden Frontend Template
 
-Minimal Vite + React + TypeScript template for building Miden frontends. Includes a network counter demo that publishes an increment note via the MidenFi wallet adapter.
+Minimal Vite + React + TypeScript template for building Miden frontends. Includes a live Miden testnet network counter demo that publishes an increment note via the MidenFi wallet adapter and lets the network operator auto-execute it against the counter.
 
 ## Getting Started
 
@@ -9,7 +9,7 @@ yarn install
 yarn dev
 ```
 
-Open [http://localhost:5173](http://localhost:5173). Connect your MidenFi wallet and click the counter button to publish an increment note.
+Open [http://localhost:5173](http://localhost:5173). The app connects to Miden testnet out of the box and renders the current counter value. Install the [MidenFi wallet extension](https://chromewebstore.google.com/detail/midenfi), connect, and click the counter to submit an increment.
 
 ## Project Structure
 
@@ -20,42 +20,108 @@ src/
 ├── config.ts                       # Constants (counter address, explorer URL, SDK config)
 ├── components/
 │   ├── AppContent.tsx              # Page layout, logos, wallet button
-│   └── Counter.tsx                 # Counter UI
+│   ├── Counter.tsx                 # Counter UI (configured / unconfigured)
+│   └── ConfiguredCounter.tsx       # Counter UI when address is set
 ├── hooks/
-│   └── useIncrementCounter.ts      # Note construction, wallet submission, re-sync
+│   └── useIncrementCounter.ts      # Note construction, wallet submission, bounded poll
 └── lib/
     └── miden.ts                    # Shared Miden utilities
+
+public/packages/
+├── counter_account.masp            # Compiled counter contract (MASP format v4)
+└── increment_note.masp             # Compiled increment note script
 ```
 
 ## Network Counter Demo
 
-The template demonstrates the network note pattern on Miden testnet:
+The template demonstrates the Miden network-note pattern on testnet:
+
+1. A **counter account** is deployed as a network account (`AccountStorageMode::Network`) on testnet. This template ships with a live deployment at [`mtst1aqmx7qv6h3y92sqsmunh8uht4ujmfy4j`](https://testnet.midenscan.com/account/mtst1aqmx7qv6h3y92sqsmunh8uht4ujmfy4j).
+2. On button click, the frontend constructs a **public note** targeting the counter and submits it through the MidenFi wallet (the wallet signs and posts the transaction, not the in-browser client).
+3. The **network operator** picks up the note (tag + `NoteAttachment::newNetworkAccountTarget`) and executes it against the counter account, incrementing the on-chain count.
+4. The frontend polls `client.getAccount(counterAddress)` and re-reads the `StorageMap`; once the value changes it updates the UI. If the network is slow, polling falls back to a 30 s timeout.
+
+Pre-compiled `.masp` packages built with `cargo-miden 0.8.1` (matching `@miden-sdk/miden-sdk@0.14.x`) live in `public/packages/`.
+
+### Pointing at your own counter
+
+The counter address is resolved at runtime via the `VITE_MIDEN_COUNTER_ADDRESS` environment variable (`src/config.ts`):
 
-1. A **counter account** is deployed as a network account (`AccountStorageMode::Network`) at [`mtst1aru8adnrqspgcsr3drk2n990lyc070ll`](https://testnet.midenscan.com/account/mtst1aru8adnrqspgcsr3drk2n990lyc070ll)
-2. On button click, the frontend constructs a **public note** targeting the counter and submits it through the wallet adapter
-3. The **network operator** picks up the note and executes it against the counter account, incrementing the on-chain count
-4. The frontend re-syncs and reads the updated count from the counter's `StorageMap`
+| `VITE_MIDEN_COUNTER_ADDRESS` value | Effect |
+|---|---|
+| unset / commented out (default) | Use the live testnet counter shipped with the template (`mtst1aqmx7qv6h3y92sqsmunh8uht4ujmfy4j`). |
+| empty string (`VITE_MIDEN_COUNTER_ADDRESS=`) | Unconfigured — `<Counter>` renders the "address not configured" card and makes no network calls. |
+| any bech32 string (`mtst1...`) | Uses your own deployment. |
 
-Pre-compiled `.masp` packages for the counter account and increment note are in `public/packages/`.
+The slot-name constant is fixed in `src/config.ts` and must match the counter contract's storage map name.
+
+To redeploy (e.g. after modifying contract sources):
+
+1. In the [project-template](https://github.com/0xMiden/project-template) repo on the `migrate-clien-v014` branch, run the deployment binary:
+   ```bash
+   cargo install cargo-miden --version 0.8.1
+   cargo run -p integration --release --bin increment_count
+   ```
+   The binary builds `contracts/counter-account` + `contracts/increment-note`, creates the counter with `AccountStorageMode::Network`, and prints the bech32 address.
+2. Copy the freshly built artifacts into this template:
+   ```bash
+   cp contracts/counter-account/target/miden/release/counter_account.masp \
+      <frontend-template>/public/packages/
+   cp contracts/increment-note/target/miden/release/increment_note.masp \
+      <frontend-template>/public/packages/
+   ```
+3. Set `VITE_MIDEN_COUNTER_ADDRESS=<your bech32 address>` in `.env` (or your shell environment) — no source edit required.
+4. Verify with `.claude/hooks/check-artifacts.sh` (checks MASP format version).
 
 ## Key Dependencies
 
-| Package | Purpose |
-|---------|---------|
-| `@miden-sdk/react` | React hooks for Miden (useAccount, useSyncState, useImportAccount, etc.) |
-| `@miden-sdk/miden-sdk` | Core SDK types (Note, NoteScript, AccountId, Word, etc.) |
-| `@miden-sdk/vite-plugin` | Vite plugin handling WASM loading, top-level await, and COOP/COEP |
-| `@miden-sdk/miden-wallet-adapter` | MidenFi wallet adapter for transaction submission |
+| Package | Version pin | Purpose |
+|---------|-------------|---------|
+| `@miden-sdk/react` | `0.14.x` | React hooks for Miden (useAccount, useSyncState, useMiden, useMidenClient, useTransaction, …) |
+| `@miden-sdk/miden-sdk` | `0.14.x` | Core SDK types (Note, NoteScript, AccountId, Word, Felt, …) |
+| `@miden-sdk/vite-plugin` | `0.14.x` | Vite plugin that handles WASM loading, top-level await, and COOP/COEP |
+| `@miden-sdk/miden-wallet-adapter-react` | `0.14.x` | MidenFi wallet adapter React context + hooks |
+| `@miden-sdk/miden-wallet-adapter-base` | `0.14.x` | `Transaction.createCustomTransaction` helper used by the increment flow |
 
 ## Configuration
 
 SDK settings can be overridden via environment variables (see `.env.example`):
 
 ```bash
-VITE_MIDEN_RPC_URL=testnet    # "testnet" | "localhost" | custom URL
-VITE_MIDEN_PROVER=testnet     # "testnet" | "local"
+VITE_MIDEN_RPC_URL=testnet   # "devnet" | "testnet" | "localhost" | custom URL
+VITE_MIDEN_PROVER=testnet    # "devnet" | "testnet" | "local" | custom URL
 ```
 
+## Verification
+
+Automated gates that must all stay green:
+
+```bash
+npx tsc -b --noEmit       # type check
+npx vitest --run          # 36 unit tests (components, hook, patterns)
+npx vite build            # production build (emits dist/)
+npx eslint .              # lint
+```
+
+The PostToolUse hook runs typecheck + affected tests after every edit. The Stop hook runs the full suite when a task completes.
+
+Browser-level verification (render correctness, no console errors, wallet popup, E2E increment) can be done with either:
+- **Playwright MCP** for headless render / console checks
+- **Claude in Chrome** (via the `/chrome` command) to exercise the real MidenFi extension
+
+## Known Temporary Workarounds
+
+One active workaround remains after the 0.14.4 upgrade, covering an upstream feature gap. The inline comment in `src/hooks/useIncrementCounter.ts` describes the removal steps.
+
+### Fixed-interval network poll — waiting for Network-mode account updates ([miden-client#2111](https://github.com/0xMiden/miden-client/issues/2111))
+
+After `wallet.requestTransaction` returns, `src/hooks/useIncrementCounter.ts` bounded-polls the counter's storage map until the value changes or a 30 s timeout elapses. The React SDK's `useWaitForCommit` only watches *locally-submitted* transactions — our increment is wallet-submitted and consumed externally by the network operator, so it never reaches the local client's transaction log. [`#2111`](https://github.com/0xMiden/miden-client/issues/2111) tracks a React-SDK subscription primitive for account-state updates driven by external consumers (scoped narrowly from the broader event-system discussion in [`#467`](https://github.com/0xMiden/miden-client/issues/467)).
+
+**After #2111 lands a subscription primitive:**
+1. Replace the `while` poll loop in `useIncrementCounter.ts::increment` with the new subscription / waitFor API.
+2. Remove `NETWORK_POLL_INTERVAL_MS` + `NETWORK_POLL_TIMEOUT_MS` from `src/config.ts` if no other consumer depends on them.
+3. Remove the `#2111` TODO block.
+
 ## AI Developer Experience
 
-This template ships with `.claude/` skills for AI coding tools. Skills cover React SDK patterns, frontend pitfalls, Vite + WASM setup, signer integration, and Miden architecture. See `CLAUDE.md` for the full developer guide.
+This template ships with `.claude/` skills for AI coding tools. Skills cover React SDK patterns, frontend pitfalls, Vite + WASM setup, signer integration, testing patterns, and Miden architecture. See `CLAUDE.md` for the full developer guide.

package/template/package.json

@@ -13,15 +13,16 @@
     "test:coverage": "vitest --run --coverage"
   },
   "dependencies": {
-    "@miden-sdk/miden-wallet-adapter": "0.13.5",
-    "@miden-sdk/miden-sdk": "0.13.2",
-    "@miden-sdk/react": "0.13.3",
+    "@miden-sdk/miden-wallet-adapter-base": "0.14.3",
+    "@miden-sdk/miden-wallet-adapter-react": "0.14.3",
+    "@miden-sdk/miden-sdk": "0.14.4",
+    "@miden-sdk/react": "0.14.4",
     "react": "^19.1.1",
     "react-dom": "^19.1.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.36.0",
-    "@miden-sdk/vite-plugin": "0.13.4",
+    "@miden-sdk/vite-plugin": "0.14.4",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",

package/template/src/__tests__/fixtures/accounts.ts

@@ -1,12 +1,13 @@
 /**
- * Realistic account fixtures for Miden frontend tests.
- * Uses bech32 IDs and BigInt amounts matching real SDK shapes.
+ * Test fixtures for Miden frontend tests.
+ * Uses hex IDs (network-agnostic) and BigInt amounts matching real SDK shapes.
+ * These are mock values — never parsed by the real SDK at runtime.
  */
 
-export const WALLET_ID_1 = "mtst1qy35qfqdvpjx2e5zf9hkp4vr";
-export const WALLET_ID_2 = "mtst1qa7k9qjf8dp4x2e5zf9hkp5vr";
-export const FAUCET_ID = "mtst1qx9y8zjf2dp4x2e5zf9hkp3vr";
-export const COUNTER_ID = "mtst1aru8adnrqspgcsr3drk2n990lyc070ll";
+export const WALLET_ID_1 = "0x0a00000000000001";
+export const WALLET_ID_2 = "0x0a00000000000002";
+export const FAUCET_ID = "0x0a00000000000003";
+export const COUNTER_ID = "0x0a00000000000004";
 
 export const MOCK_WALLET_HEADER = {
   id: WALLET_ID_1,
@@ -52,6 +53,16 @@ export const MOCK_ASSET_METADATA = {
   decimals: 8,
 };
 
+// TransactionResult shape — matches @miden-sdk/react types for useMint / useConsume /
+// useSwap / useMultiSend / useTransaction result payloads.
 export const MOCK_TRANSACTION_RESULT = {
   transactionId: "0xabc123def456789012345678901234567890123456789012345678901234abcd",
 };
+
+// SendResult shape — distinct from TransactionResult. @miden-sdk/react's useSend
+// returns { txId, note }, not { transactionId }. Keep these fixtures separate so
+// mocks for useSend don't bleed into mocks for TransactionResult-typed hooks.
+export const MOCK_SEND_RESULT = {
+  txId: "0xabc123def456789012345678901234567890123456789012345678901234abcd",
+  note: null,
+};

package/template/src/__tests__/fixtures/index.ts

@@ -11,6 +11,7 @@ export {
   MOCK_ACCOUNT,
   MOCK_ASSET_METADATA,
   MOCK_TRANSACTION_RESULT,
+  MOCK_SEND_RESULT,
 } from "./accounts";
 
 export {

package/template/src/__tests__/mocks/miden-sdk-react.ts

@@ -23,6 +23,7 @@ import {
   MOCK_CONSUMABLE_NOTE_RECORD,
   MOCK_NOTE_SUMMARY,
   MOCK_TRANSACTION_RESULT,
+  MOCK_SEND_RESULT,
   FAUCET_ID,
 } from "../fixtures";
 
@@ -95,6 +96,8 @@ export const useNoteStream = vi.fn(() => ({
 // Mutation hooks
 // ---------------------------------------------------------------------------
 
+// Mutation hooks that resolve to TransactionResult { transactionId } —
+// useMint / useConsume / useSwap / useMultiSend / useTransaction.
 function createMutationMock(mutateKey: string) {
   return vi.fn(() => ({
     [mutateKey]: vi.fn(async () => MOCK_TRANSACTION_RESULT),
@@ -106,6 +109,19 @@ function createMutationMock(mutateKey: string) {
   }));
 }
 
+// useSend resolves to SendResult { txId, note } — not TransactionResult.
+// Keep this separate so tests that call `send()` get the correct shape.
+function createSendMock() {
+  return vi.fn(() => ({
+    send: vi.fn(async () => MOCK_SEND_RESULT),
+    result: null,
+    isLoading: false,
+    stage: "idle" as const,
+    error: null,
+    reset: vi.fn(),
+  }));
+}
+
 export const useCreateWallet = vi.fn(() => ({
   createWallet: vi.fn(async () => MOCK_ACCOUNT),
   wallet: null,
@@ -122,7 +138,7 @@ export const useCreateFaucet = vi.fn(() => ({
   reset: vi.fn(),
 }));
 
-export const useSend = createMutationMock("send");
+export const useSend = createSendMock();
 export const useMultiSend = createMutationMock("sendMany");
 export const useMint = createMutationMock("mint");
 export const useConsume = createMutationMock("consume");
@@ -181,6 +197,7 @@ export const useMiden = vi.fn(() => ({
   runExclusive: vi.fn(async <T>(fn: () => Promise<T>) => fn()),
   prover: null,
   signerAccountId: null,
+  signerConnected: null,
 }));
 
 export const useMidenClient = vi.fn(() => ({}));

package/template/src/__tests__/patterns/mutation-hook.test.tsx

@@ -85,7 +85,7 @@ describe("Mutation Hook Pattern", () => {
   it("shows success message after transaction completes", () => {
     vi.mocked(useSend).mockReturnValue({
       send: vi.fn(),
-      result: { transactionId: "0xabc123" },
+      result: { txId: "0xabc123", note: null },
       isLoading: false,
       stage: "complete" as const,
       error: null,
@@ -121,7 +121,7 @@ describe("Mutation Hook Pattern", () => {
 
   // Test the actual send call — verify correct arguments
   it("calls send with correct arguments on click", async () => {
-    const mockSend = vi.fn(async () => ({ transactionId: "0xtx" }));
+    const mockSend = vi.fn(async () => ({ txId: "0xtx", note: null }));
     vi.mocked(useSend).mockReturnValue({
       send: mockSend,
       result: null,

package/template/src/__tests__/patterns/provider-setup.test.tsx

@@ -50,6 +50,7 @@ describe("Provider Setup Pattern", () => {
       runExclusive: vi.fn(),
       prover: null,
       signerAccountId: null,
+      signerConnected: null,
     });
 
     render(<StatusIndicator />);
@@ -67,6 +68,7 @@ describe("Provider Setup Pattern", () => {
       runExclusive: vi.fn(),
       prover: null,
       signerAccountId: null,
+      signerConnected: null,
     });
 
     render(<StatusIndicator />);

package/template/src/components/AppContent.tsx

@@ -1,11 +1,41 @@
 import { useMiden, useSyncState } from "@miden-sdk/react";
-import { WalletMultiButton } from "@miden-sdk/miden-wallet-adapter";
+import { useMidenFiWallet } from "@miden-sdk/miden-wallet-adapter-react";
+import { WalletReadyState } from "@miden-sdk/miden-wallet-adapter-base";
 import reactLogo from "@/assets/react.svg";
 import midenLogo from "@/assets/miden.svg";
 import viteLogo from "/vite.svg";
 import { Counter } from "@/components/Counter";
 import "./AppContent.css";
 
+function WalletButton() {
+  // Use the MidenFi-specific hook (not the generic `useSigner()`) so we can
+  // gate on `wallet.readyState`. `useSigner().connect()` calls through to the
+  // same provider, but at the moment the user clicks the button the adapter
+  // may not yet have detected `window.midenWallet` — detection is polled, see
+  // `scopePollingDetectionStrategy` in @miden-sdk/miden-wallet-adapter-base.
+  // When readyState is NotDetected, MidenFiSignerProvider falls back to
+  // `window.open(adapter.url, "_blank")` — the Chrome Web Store URL — which
+  // on some platforms redirects to the Play Store. Disabling the button
+  // until the extension is detected prevents the fallback from firing.
+  const { wallet, connected, connecting, connect, disconnect } =
+    useMidenFiWallet();
+  const readyState = wallet?.readyState;
+  const walletReady =
+    readyState === WalletReadyState.Installed ||
+    readyState === WalletReadyState.Loadable;
+
+  if (!walletReady) {
+    return <button disabled>Install MidenFi Wallet</button>;
+  }
+  if (connected) {
+    return <button onClick={disconnect}>Disconnect Wallet</button>;
+  }
+  if (connecting) {
+    return <button disabled>Connecting...</button>;
+  }
+  return <button onClick={connect}>Connect Wallet</button>;
+}
+
 export function AppContent() {
   const { isReady, isInitializing, error } = useMiden();
   const { syncHeight } = useSyncState();
@@ -32,13 +62,13 @@ export function AppContent() {
         <a href="https://react.dev" target="_blank" rel="noreferrer">
           <img src={reactLogo} className="logo react" alt="React logo" />
         </a>
-        <a href="https://docs.miden.io" target="_blank" rel="noreferrer">
+        <a href="https://docs.miden.xyz" target="_blank" rel="noreferrer">
           <img src={midenLogo} className="logo miden" alt="Miden logo" />
         </a>
       </div>
       <h1>Vite + React + Miden</h1>
       <div className="wallet-section">
-        <WalletMultiButton />
+        <WalletButton />
       </div>
       <Counter />
       <p className="read-the-docs">

package/template/{create-miden-app/template/src/components/Counter.tsx → src/components/ConfiguredCounter.tsx}

@@ -1,8 +1,11 @@
 import { useIncrementCounter } from "@/hooks/useIncrementCounter";
-import { COUNTER_ADDRESS } from "@/config";
 import "./Counter.css";
 
-export function Counter() {
+export function ConfiguredCounter({
+  counterAddress,
+}: {
+  counterAddress: string;
+}) {
   const {
     increment,
     count,
@@ -11,7 +14,7 @@ export function Counter() {
     error,
     walletConnected,
     explorerUrl,
-  } = useIncrementCounter(COUNTER_ADDRESS);
+  } = useIncrementCounter(counterAddress);
 
   const busy = isSubmitting || isWaiting;
   const buttonLabel = isSubmitting
@@ -36,7 +39,7 @@ export function Counter() {
           rel="noreferrer"
           className="account-id"
         >
-          Counter: {COUNTER_ADDRESS}
+          Counter: {counterAddress}
         </a>
       </p>
       {error && <p className="error">{error}</p>}

package/template/src/components/Counter.tsx

@@ -1,45 +1,16 @@
-import { useIncrementCounter } from "@/hooks/useIncrementCounter";
 import { COUNTER_ADDRESS } from "@/config";
-import "./Counter.css";
+import { ConfiguredCounter } from "./ConfiguredCounter";
 
 export function Counter() {
-  const {
-    increment,
-    count,
-    isSubmitting,
-    isWaiting,
-    error,
-    walletConnected,
-    explorerUrl,
-  } = useIncrementCounter(COUNTER_ADDRESS);
-
-  const busy = isSubmitting || isWaiting;
-  const buttonLabel = isSubmitting
-    ? "Submitting..."
-    : isWaiting
-      ? "Waiting for network..."
-      : `count is ${count ?? "..."}`;
-
-  return (
-    <div className="card">
-      <button
-        className="counter-button"
-        onClick={increment}
-        disabled={busy || count === null || !walletConnected}
-      >
-        {buttonLabel}
-      </button>
-      <p>
-        <a
-          href={explorerUrl}
-          target="_blank"
-          rel="noreferrer"
-          className="account-id"
-        >
-          Counter: {COUNTER_ADDRESS}
-        </a>
-      </p>
-      {error && <p className="error">{error}</p>}
-    </div>
-  );
+  if (!COUNTER_ADDRESS) {
+    return (
+      <div className="card">
+        <p>
+          Counter address not configured — see README for deployment
+          instructions.
+        </p>
+      </div>
+    );
+  }
+  return <ConfiguredCounter counterAddress={COUNTER_ADDRESS} />;
 }