React SDK (@miden-sdk/react)

The React SDK is a thin layer on top of the Web SDK. It wraps the underlying WASM WebClient with a React context (MidenProvider), a family of hooks (useMiden, useAccount, useSend, …), automatic sync polling, and a concurrency lock so multiple components never trip over the same WASM instance.

When to use it

Reach for the React SDK when your application is already a React app (Next.js, Vite + React, React Native, Electron + React, etc.). The hooks:

• own lifecycle management (the WASM worker, signer wiring, auto-sync loop),
• expose per-hook result interfaces with a domain-named action (send, mint, createWallet, …) plus isLoading / isCreating / isImporting, error, and reset,
• serialize mutations so concurrent component interactions don't corrupt the WASM state.

If you are building a non-React app — a service worker, a Node backend, a vanilla-TS dApp — use the imperative Web SDK directly.

You can always reach the underlying WASM client from any hook via useMidenClient() when a hook doesn't cover what you need — it returns the low-level WebClient, not the imperative MidenClient wrapper.

What's in the package

Surface	Purpose
MidenProvider	Root React context; loads WASM, wires the client, runs auto-sync
useMiden()	Raw lifecycle hook (isReady, sync, runExclusive)
useMidenClient()	Shortcut for the ready WASM WebClient
Query hooks	useAccount(s), useNotes, useNoteStream, useTransactionHistory, useSyncState, useAssetMetadata
Mutation hooks	useCreateWallet, useCreateFaucet, useImportAccount, useSend, useMultiSend, useMint, useConsume, useSwap
Advanced hooks	useTransaction, useExecuteProgram, useCompile, useSessionAccount, useExportStore, useImportStore, useImportNote, useExportNote, useSyncControl, useWaitForCommit, useWaitForNotes
External signers	MultiSignerProvider, SignerContext, useSigner, useMultiSigner — pluggable wallet integrations (Para, Turnkey, MidenFi, custom)
Utilities	formatAssetAmount, parseAssetAmount, getNoteSummary, toBech32AccountId, createNoteAttachment / readNoteAttachment, …

Each hook exports its own result interface — not a generic { data, isLoading, error } wrapper. Data lives in named fields (e.g. accounts, wallets, records, wallet, faucet). Transaction-producing mutations additionally expose a stage field that advances through idle → executing → proving → submitting → complete. See setup for per-family details.

Where to go next

• Setup — install the package, wrap your app in MidenProvider, configure the network.
• Query hooks — read accounts, notes, sync state, and asset metadata.
• Mutation hooks — create wallets and faucets, send, mint, consume, swap.
• Advanced — custom scripts, MASM compilation, session accounts, note import/export.
• Signers — external wallets (Para, Turnkey, MidenFi) and custom signer providers.
• Recipes — end-to-end patterns and a pointer to Philipp's full wallet tutorial.