create-miden-app 1.0.4 → 1.0.7

package/template/src/hooks/__tests__/useIncrementCounter.test.tsx

@@ -0,0 +1,257 @@
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { vi, describe, it, expect, beforeEach } from "vitest";
+
+// Stub fetch — `increment` fetches `/packages/increment_note.masp`. We never
+// reach Note construction in any test below (the path either short-circuits
+// on a missing wallet address or is short-circuited before `requestTransaction`
+// completes), but the fetch itself runs once and we don't want jsdom to error
+// out on an unhandled network request.
+const mockFetch = vi.fn(async () => ({
+  arrayBuffer: async () => new ArrayBuffer(0),
+}));
+vi.stubGlobal("fetch", mockFetch);
+
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+
+// `useIncrementCounter` reads `requestTransaction` and `address` directly from
+// the hook return per `WalletContextState`. We mock the wallet-adapter-react
+// package and provide a default disconnected stub. Individual tests override
+// via `vi.mocked(useMidenFiWallet).mockReturnValue(...)`.
+const defaultWallet = {
+  autoConnect: false,
+  wallets: [],
+  wallet: null,
+  address: null as string | null,
+  publicKey: null,
+  connected: false,
+  connecting: false,
+  disconnecting: false,
+  select: vi.fn(),
+  connect: vi.fn(async () => undefined),
+  disconnect: vi.fn(async () => undefined),
+  requestTransaction: vi.fn(async () => "0xtx"),
+  requestAssets: undefined,
+  requestPrivateNotes: undefined,
+  signBytes: undefined,
+  importPrivateNote: undefined,
+  requestConsumableNotes: undefined,
+  waitForTransaction: undefined,
+  requestSend: undefined,
+  requestConsume: undefined,
+  createAccount: undefined,
+};
+
+const mockGetAccount = vi.fn(async () => null);
+const mockImportAccountById = vi.fn(async () => undefined);
+const mockSyncState = vi.fn(async () => undefined);
+
+vi.mock("@miden-sdk/miden-wallet-adapter-react", () => ({
+  useMidenFiWallet: vi.fn(() => defaultWallet),
+}));
+
+// `useIncrementCounter` calls into many SDK constructors (Word/Felt/AccountId,
+// note builders, etc.) and chained builder methods like
+// `TransactionRequestBuilder().withOwnOutputNotes(...).build()`. We don't need
+// real values from these in unit tests — only that calls don't throw and the
+// hook can reach the poll loop. A Proxy-backed stub satisfies all chained
+// calls (`new X(...)`, `X.staticMethod(...)`, `instance.foo().bar(...)`) by
+// returning another callable+constructable stub for any property access.
+//
+// The one shape we DO need real data from is `Word.toU64s()` (the storage-map
+// value the hook reads to derive the count). The proxy intercepts that
+// specific access and returns a 4-tuple BigUint64Array-like value.
+vi.mock("@miden-sdk/miden-sdk", async () => {
+  const stub = (): object =>
+    new Proxy(function noop() {}, {
+      get: (_t, prop) => {
+        if (prop === "toU64s") return () => [0n, 0n, 0n, 0n];
+        // Avoid breaking Promise resolution / native Symbol checks
+        if (typeof prop === "symbol") return undefined;
+        return stub();
+      },
+      apply: () => stub(),
+      construct: () => stub(),
+    });
+  const exports: Record<string, unknown> = {};
+  for (const k of [
+    "TransactionRequestBuilder",
+    "Package",
+    "NoteScript",
+    "Note",
+    "NoteAssets",
+    "NoteMetadata",
+    "NoteRecipient",
+    "NoteStorage",
+    "NoteTag",
+    "NoteType",
+    "NoteAttachment",
+    "NoteExecutionHint",
+    "NoteArray",
+    "AccountId",
+    "Felt",
+    "FeltArray",
+    "Word",
+  ]) {
+    exports[k] = stub();
+  }
+  return exports;
+});
+
+vi.mock("@miden-sdk/miden-wallet-adapter-base", () => ({
+  Transaction: { createCustomTransaction: vi.fn(() => ({})) },
+}));
+
+vi.mock("@/lib/miden", () => ({ randomWord: () => ({}) }));
+
+import { useMiden, useMidenClient } from "@miden-sdk/react";
+import { useMidenFiWallet } from "@miden-sdk/miden-wallet-adapter-react";
+import { useIncrementCounter } from "../useIncrementCounter";
+import {
+  NETWORK_POLL_INTERVAL_MS,
+  NETWORK_POLL_TIMEOUT_MS,
+} from "@/config";
+
+const COUNTER_ADDRESS = "mtst1aqmx7qv6h3y92sqsmunh8uht4ujmfy4j";
+
+describe("useIncrementCounter", () => {
+  beforeEach(() => {
+    vi.useRealTimers();
+    vi.clearAllMocks();
+    mockGetAccount.mockReset();
+    mockImportAccountById.mockReset();
+    mockSyncState.mockReset();
+    mockFetch.mockClear();
+
+    vi.mocked(useMiden).mockReturnValue({
+      client: null,
+      isReady: true,
+      isInitializing: false,
+      error: null,
+      sync: vi.fn(),
+      runExclusive: <T,>(fn: () => Promise<T>) => fn(),
+      prover: null,
+      signerAccountId: null,
+      signerConnected: null,
+    });
+    vi.mocked(useMidenClient).mockReturnValue({
+      getAccount: mockGetAccount,
+      importAccountById: mockImportAccountById,
+      syncState: mockSyncState,
+    } as unknown as ReturnType<typeof useMidenClient>);
+    vi.mocked(useMidenFiWallet).mockReturnValue(defaultWallet);
+  });
+
+  it("surfaces an error when increment is called without a wallet address", async () => {
+    // Default stub has `address: null` (wallet not connected to an account).
+    // Make the mount-time loadCount succeed so its error path doesn't race
+    // with the one we're asserting against.
+    const fakeAccount = {
+      storage: () => ({ getMapItem: () => null }),
+    };
+    mockGetAccount.mockResolvedValue(fakeAccount as never);
+
+    const { result } = renderHook(() => useIncrementCounter(COUNTER_ADDRESS));
+    // Wait for mount-effect to finish (count resolves from null → 0).
+    await waitFor(() => expect(result.current.count).toBe(0));
+
+    await act(async () => {
+      await result.current.increment();
+    });
+
+    expect(result.current.error).toMatch(/no wallet account available/i);
+    expect(result.current.isSubmitting).toBe(false);
+    // requestTransaction must NOT have been called — we short-circuit before
+    // touching the wallet.
+    expect(defaultWallet.requestTransaction).not.toHaveBeenCalled();
+  });
+
+  it("surfaces an error when the counter account is unreachable on-chain", async () => {
+    // import + retry both return null → should setError, not stay silent.
+    mockGetAccount.mockResolvedValue(null);
+
+    const { result } = renderHook(() => useIncrementCounter(COUNTER_ADDRESS));
+
+    await waitFor(() => {
+      expect(result.current.error).toMatch(/counter account not found/i);
+    });
+    expect(result.current.count).toBeNull();
+  });
+
+  it("does not call useMiden().sync() during a poll iteration", async () => {
+    // Wallet must be connected so increment doesn't short-circuit before the
+    // poll loop. Provide a real address + a working `requestTransaction`.
+    const requestTransaction = vi.fn(async () => "0xtx");
+    vi.mocked(useMidenFiWallet).mockReturnValue({
+      ...defaultWallet,
+      address: "mtst1arwk88k8smzcq5p30upr6eerw5npmnyz",
+      connected: true,
+      requestTransaction,
+    });
+
+    // Spy on the hook-level `sync()`. The fix this test guards against would
+    // call this inside the poll loop; production code now does not.
+    const sync = vi.fn(async () => undefined);
+    vi.mocked(useMiden).mockReturnValue({
+      client: null,
+      isReady: true,
+      isInitializing: false,
+      error: null,
+      sync,
+      runExclusive: <T,>(fn: () => Promise<T>) => fn(),
+      prover: null,
+      signerAccountId: null,
+      signerConnected: null,
+    });
+
+    // Storage-map value drives `count`. `Word.toU64s()` already resolves to
+    // [0n, 0n, 0n, 0n] via the SDK proxy stub above, so `loadCount()` always
+    // returns 0 → `previousCount === latest`. The loop will keep ticking
+    // until the deadline; we only need ONE iteration to elapse, then stop.
+    mockGetAccount.mockResolvedValue({
+      storage: () => ({ getMapItem: () => ({ toU64s: () => [0n, 0n, 0n, 0n] }) }),
+    } as never);
+
+    vi.useFakeTimers();
+    try {
+      const { result } = renderHook(() => useIncrementCounter(COUNTER_ADDRESS));
+
+      // Wait for mount-effect's loadCount to settle.
+      await vi.waitFor(() => {
+        expect(result.current.count).toBe(0);
+      });
+
+      // Snapshot sync-call count before increment so we measure only what
+      // happens during the click + poll iteration.
+      expect(sync).not.toHaveBeenCalled();
+
+      // Trigger increment without awaiting; the call schedules the poll loop.
+      let incrementPromise: Promise<void> | undefined;
+      await act(async () => {
+        incrementPromise = result.current.increment();
+        // Let microtasks settle for the requestTransaction await.
+        await Promise.resolve();
+      });
+
+      // Advance past one poll interval (2.5s) — exactly one iteration runs.
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(NETWORK_POLL_INTERVAL_MS + 50);
+      });
+
+      // The redundant `await sync()` was removed from the poll loop. After
+      // one iteration, `useMiden().sync` must not have been called.
+      expect(sync).not.toHaveBeenCalled();
+
+      // requestTransaction was reached — proves the loop actually ran.
+      expect(requestTransaction).toHaveBeenCalledTimes(1);
+
+      // Drain the rest of the deadline so the increment promise resolves
+      // cleanly and React unmount can finish.
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(NETWORK_POLL_TIMEOUT_MS);
+        await incrementPromise;
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/template/src/hooks/useIncrementCounter.ts

@@ -0,0 +1,195 @@
+import { useEffect, useState, useCallback } from "react";
+import { useMiden, useMidenClient } from "@miden-sdk/react";
+// `useMidenFiWallet()` returns `WalletContextState` (see
+// `@miden-sdk/miden-wallet-adapter-react/dist/MidenFiSignerProvider.d.ts`),
+// which exposes `address`, `connected`, and `requestTransaction` directly
+// at the top level — distinct from the inner `wallet` field on the same
+// return (which is a `Wallet` adapter object, not the address).
+import { useMidenFiWallet } from "@miden-sdk/miden-wallet-adapter-react";
+import { Transaction } from "@miden-sdk/miden-wallet-adapter-base";
+import {
+  TransactionRequestBuilder,
+  Package,
+  NoteScript,
+  Note,
+  NoteAssets,
+  NoteMetadata,
+  NoteRecipient,
+  NoteStorage,
+  NoteTag,
+  NoteType,
+  NoteAttachment,
+  NoteExecutionHint,
+  NoteArray,
+  AccountId,
+  Felt,
+  FeltArray,
+  Word,
+} from "@miden-sdk/miden-sdk";
+import { randomWord } from "@/lib/miden";
+import {
+  COUNTER_SLOT_NAME,
+  EXPLORER_BASE_URL,
+  NETWORK_POLL_INTERVAL_MS,
+  NETWORK_POLL_TIMEOUT_MS,
+} from "@/config";
+
+export function useIncrementCounter(counterAddress: string) {
+  const [error, setError] = useState<string | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [isWaiting, setIsWaiting] = useState(false);
+  const [count, setCount] = useState<number | null>(null);
+
+  const { runExclusive, isReady } = useMiden();
+  const {
+    address: walletAddress,
+    connected: walletConnected,
+    requestTransaction,
+  } = useMidenFiWallet();
+  const client = useMidenClient();
+
+  // Fetch the on-chain counter value. Imports the counter account on first
+  // call, syncs from the network, and reads the storage map. All WASM calls
+  // are serialized via runExclusive to avoid "recursive use of an object"
+  // errors. Returns the fetched count (or null if the account is unreachable)
+  // and also updates component state.
+  const loadCount = useCallback(async (): Promise<number | null> => {
+    if (!isReady || !counterAddress) return null;
+    return await runExclusive(async () => {
+      const counterAccountId = AccountId.fromBech32(counterAddress);
+      if (!(await client.getAccount(counterAccountId))) {
+        await client.importAccountById(counterAccountId);
+      }
+      await client.syncState();
+
+      const account = await client.getAccount(counterAccountId);
+      if (!account) {
+        setCount(null);
+        setError(
+          `Counter account not found on-chain (${counterAddress}). Check VITE_MIDEN_COUNTER_ADDRESS / src/config.ts and confirm the counter is deployed on the configured network.`,
+        );
+        return null;
+      }
+      const countKey = Word.newFromFelts([
+        new Felt(0n),
+        new Felt(0n),
+        new Felt(0n),
+        new Felt(1n),
+      ]);
+      const value = account
+        .storage()
+        .getMapItem(COUNTER_SLOT_NAME, countKey);
+      // Storage map value is a Word whose first element holds the Felt count.
+      const newCount = value ? Number(value.toU64s()[0]) : 0;
+      setCount(newCount);
+      // Successful fetch — clear any prior unreachable/timeout error.
+      setError(null);
+      return newCount;
+    });
+  }, [isReady, client, runExclusive, counterAddress]);
+
+  useEffect(() => {
+    loadCount().catch((err) => {
+      setError(err instanceof Error ? err.message : String(err));
+    });
+  }, [loadCount]);
+
+  const increment = useCallback(async () => {
+    if (!walletAddress) {
+      setError(
+        "No wallet account available. Connect MidenFi to a testnet account before incrementing.",
+      );
+      return;
+    }
+    setError(null);
+    setIsSubmitting(true);
+    try {
+      const buf = await fetch("/packages/increment_note.masp").then((r) =>
+        r.arrayBuffer(),
+      );
+      const pkg = Package.deserialize(new Uint8Array(buf));
+      const noteScript = NoteScript.fromPackage(pkg);
+
+      const counterAccountId = AccountId.fromBech32(counterAddress);
+      const walletAccountId = AccountId.fromBech32(walletAddress);
+
+      const serialNum = randomWord();
+      const storage = new NoteStorage(new FeltArray());
+      const recipient = new NoteRecipient(serialNum, noteScript, storage);
+
+      const tag = NoteTag.withAccountTarget(counterAccountId);
+      const attachment = NoteAttachment.newNetworkAccountTarget(
+        counterAccountId,
+        NoteExecutionHint.always(),
+      );
+      const metadata = new NoteMetadata(
+        walletAccountId,
+        NoteType.Public,
+        tag,
+      ).withAttachment(attachment);
+
+      const note = new Note(new NoteAssets(), metadata, recipient);
+      const txRequest = new TransactionRequestBuilder()
+        .withOwnOutputNotes(new NoteArray([note]))
+        .build();
+
+      if (!requestTransaction) {
+        throw new Error("Wallet does not support requestTransaction");
+      }
+      const tx = Transaction.createCustomTransaction(
+        walletAddress,
+        counterAddress,
+        txRequest,
+      );
+      await requestTransaction(tx);
+      setIsSubmitting(false);
+
+      // Capture the pre-submission count so the poll loop knows what value
+      // to wait past. Not stale-safe because React batches state updates and
+      // `count` here is the closed-over value from the most recent render —
+      // which is exactly what we want: the value the user saw on the button.
+      const previousCount = count;
+
+      setIsWaiting(true);
+      // TODO(0xMiden/miden-client#2111): The React SDK exposes no hook to
+      // subscribe to account-state changes driven by the network operator
+      // (our counter is Network storage mode). `useWaitForCommit` only
+      // watches locally-submitted transactions, and this increment was
+      // submitted by the wallet. Until #2111 lands a subscription primitive,
+      // we poll the counter's storage map with a bounded timeout.
+      const deadline = Date.now() + NETWORK_POLL_TIMEOUT_MS;
+      let changed = false;
+      while (!changed && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, NETWORK_POLL_INTERVAL_MS));
+        // `loadCount()` calls `client.syncState()` internally inside
+        // `runExclusive`; no need for a second `sync()` here.
+        const latest = await loadCount();
+        changed = latest !== null && latest !== previousCount;
+      }
+      setIsWaiting(false);
+      if (!changed) {
+        // The tx was submitted successfully but the counter hadn't updated
+        // by the timeout. This can happen when testnet is slow or the
+        // network operator hasn't picked up the note yet. Surface a
+        // non-fatal message so the user knows to refresh or retry sync.
+        setError(
+          `Transaction submitted, but counter update was not observed within ${Math.round(NETWORK_POLL_TIMEOUT_MS / 1000)}s. Refresh or retry sync.`,
+        );
+      }
+    } catch (err) {
+      setIsSubmitting(false);
+      setIsWaiting(false);
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }, [walletAddress, requestTransaction, counterAddress, loadCount, count]);
+
+  return {
+    increment,
+    count,
+    isSubmitting,
+    isWaiting,
+    error,
+    walletConnected,
+    explorerUrl: `${EXPLORER_BASE_URL}/account/${counterAddress}`,
+  };
+}

package/template/src/index.css

@@ -54,6 +54,13 @@ button:focus-visible {
   outline: 4px auto -webkit-focus-ring-color;
 }
 
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
 @media (prefers-color-scheme: light) {
   :root {
     color: #213547;

package/template/src/lib/miden.ts

@@ -0,0 +1,9 @@
+import { Felt, Word } from "@miden-sdk/miden-sdk";
+
+/** Generate a random 4-felt Word (used as note serial number). */
+export function randomWord(): Word {
+  const felts = Array.from({ length: 4 }, () =>
+    new Felt(BigInt(Math.floor(Math.random() * 2 ** 32))),
+  );
+  return Word.newFromFelts(felts);
+}

package/template/src/main.tsx

@@ -1,10 +1,10 @@
-import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
-import './index.css'
-import App from './App.tsx'
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App.tsx";
 
-createRoot(document.getElementById('root')!).render(
+createRoot(document.getElementById("root")!).render(
   <StrictMode>
     <App />
   </StrictMode>,
-)
+);

package/template/src/providers.tsx

@@ -0,0 +1,27 @@
+import { type ReactNode } from "react";
+import { MidenProvider } from "@miden-sdk/react";
+import { MidenFiSignerProvider } from "@miden-sdk/miden-wallet-adapter-react";
+import { WalletAdapterNetwork } from "@miden-sdk/miden-wallet-adapter-base";
+import { APP_NAME, MIDEN_RPC_URL, MIDEN_PROVER } from "@/config";
+
+// MidenFiSignerProvider must wrap MidenProvider — MidenProvider reads
+// SignerContext during initialization (to wire its external-keystore client),
+// so the signer context has to exist before the provider mounts.
+export function AppProviders({ children }: { children: ReactNode }) {
+  return (
+    <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>
+        }
+      >
+        {children}
+      </MidenProvider>
+    </MidenFiSignerProvider>
+  );
+}

package/template/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/template/tsconfig.app.json

@@ -5,7 +5,7 @@
     "useDefineForClassFields": true,
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "module": "ESNext",
-    "types": ["vite/client"],
+    "types": ["vite/client", "vitest/globals", "@testing-library/jest-dom/vitest"],
     "skipLibCheck": true,
 
     /* Bundler mode */
@@ -16,13 +16,17 @@
     "noEmit": true,
     "jsx": "react-jsx",
 
+    /* Path aliases */
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+
     /* Linting */
     "strict": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
-    "erasableSyntaxOnly": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true
+    "noFallthroughCasesInSwitch": true
   },
   "include": ["src"]
 }

package/template/tsconfig.node.json

@@ -18,9 +18,7 @@
     "strict": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
-    "erasableSyntaxOnly": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true
+    "noFallthroughCasesInSwitch": true
   },
   "include": ["vite.config.ts"]
 }

package/template/vite.config.ts

@@ -1,26 +1,14 @@
+import path from "node:path";
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
-import wasm from "vite-plugin-wasm";
-import topLevelAwait from "vite-plugin-top-level-await";
-import path from "path";
+import { midenVitePlugin } from "@miden-sdk/vite-plugin";
 
-// https://vite.dev/config/
 export default defineConfig({
-  plugins: [react(), wasm(), topLevelAwait()],
+  plugins: [react(), midenVitePlugin({ crossOriginIsolation: true })],
   resolve: {
+    dedupe: ["react", "react-dom", "react/jsx-runtime"],
     alias: {
-      // Help resolve dexie when imported from linked packages
-      dexie: path.resolve(__dirname, "node_modules/dexie"),
-    },
-  },
-  optimizeDeps: {
-    exclude: ["@miden-sdk/miden-sdk"],
-    include: ["dexie"],
-  },
-  server: {
-    headers: {
-      "Cross-Origin-Opener-Policy": "same-origin",
-      "Cross-Origin-Embedder-Policy": "require-corp",
+      "@": path.resolve(__dirname, "./src"),
     },
   },
 });

package/template/vitest.config.ts

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  test: {
+    environment: "jsdom",
+    globals: true,
+    setupFiles: ["./vitest.setup.ts"],
+    include: ["src/**/*.{test,spec}.{ts,tsx}"],
+    passWithNoTests: true,
+    server: {
+      deps: {
+        // Tests mock the wallet adapter at the module level, so externalizing is safe.
+        external: [/@miden-sdk\/miden-wallet-adapter-react/],
+      },
+    },
+  },
+});

package/template/vitest.setup.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom/vitest";