Demo app

The reference integration

The web-wallet-demo app in the Wavelength monorepo is a full React integration you can read, run, and copy patterns from. It is not a separate product; it exercises the same @lightninglabs/wavelength-web and @lightninglabs/wavelength-react packages your app would use.

What it demonstrates:

  • WavelengthProvider with an injected createWebWalletEngine() engine (self-hosted runtime assets, worker mode, optional RPC debug logging).
  • Multiple named wallets per origin, tracked in a localStorage registry (src/lib/walletRegistry.ts): a name, network, and unlock method per wallet, with sequential switching between them by stopping the running engine and starting the next entry.
  • Phase-based routing from useWallet(): create/unlock, backup, syncing, ready, stopped, and error screens driven by phase and useWalletInfo(), with a wallet list and a create/restore flow shown before any engine starts.
  • Password and passkey onboarding via useWalletCreate / useWalletUnlock and useWalletPasskey(...), with the credential id persisted on the wallet’s registry entry for scoped unlock (src/lib/walletRegistry.ts). The demo passes a ceremony built with createWebPasskeyCeremony so passkey timing lands on the same sink as its other performance samples; webPasskeyCeremony is the equivalent without instrumentation.
  • Core wallet flows: deposit address, Lightning receive, send (prepare and confirm), balance and activity, and settings.
  • Network presets for signet, testnet, and regtest, each wallet permanently bound to the network chosen at creation (endpointsForNetwork() in runtime-config.ts mirrors public gateway URLs and local arktest ports).
  • Production-like hosting concerns: COOP/COEP headers in vite.config.ts, self-hosted WASM binaries under public/runtime/<version>/, persistent storage request, and a local wipe path that clears OPFS and app markers (src/lib/wipeLocalData.ts).

Treat the demo as the source of truth for wiring details that docs summarize. Key entry points: src/main.tsx (engine bootstrap), src/App.tsx (orchestration), src/lib/walletRegistry.ts (the wallet list), and src/lib/runtime-config.ts (gateway defaults).

See also: createWebWalletEngine, useWallet, and useWalletPasskey in the API reference for details behind each of these bullets.

How to run it

Clone the monorepo, install dependencies, and start the demo dev server. Step-by-step commands (including wasm:local for a fresh WASM build and regtest/testnet overrides) live on the dedicated run page:

Run the demo app

Out of the box the demo’s create-wallet screen offers signet and testnet against Lightning Labs public gateways; no local backend is required for either. Regtest is a dev-only option, hidden unless you open the demo with ?regtest=1. For regtest, start arktest locally, pick regtest on the create screen, and enter the ports it prints in the collapsed “Advanced endpoints” section.

Runtime assets are staged (never committed) under public/runtime/<RUNTIME_MANIFEST_VERSION>/. Before the first dev:local run, and after upgrading the SDK or rebuilding WASM from wavelength, run pnpm --filter web-wallet-demo run wasm:local to stage fresh binaries; locally built assets cannot match the pinned release digests, so dev:local (not plain dev) is what disables verification for them. See Run the demo app for the full command.

React Native readers: see Run the demo app for the mobile counterpart, which mirrors this demo screen for screen.