Run the demo app

Clone and install

The reference integration lives in the Wavelength monorepo at apps/rn-wallet-demo. Clone the repository, install dependencies with pnpm, and build the workspace packages:

Terminal
git clone https://github.com/lightninglabs/wavelength-sdk.git
cd wavelength-sdk
pnpm install
pnpm build

The demo needs the native wallet runtime binaries staged before it can build. Run the package’s bindings:fetch script, which downloads them from the paired wavelength release:

Terminal
pnpm --filter @lightninglabs/wavelength-react-native run bindings:fetch

See Installation for why the binaries ship this way and what the script stages.

Run

Start Metro in its own terminal, then build and launch per platform:

Terminal
cd apps/rn-wallet-demo
npx expo start --dev-client --clear

This starts Metro, the dev server that serves the JS bundle to the app. Keep it running in its own terminal; --clear drops a possibly stale cache.

Terminal
pnpm run android

This generates the native android project if needed, compiles the dev build, installs it on the running emulator or a connected device, and launches it.

Terminal
pnpm run ios

This does the same for the iOS simulator: generates the native ios project if needed, compiles the dev build, installs it, and launches it. The script sets LANG=en_US.UTF-8 to satisfy pod install’s locale requirement.

The iOS build needs no code signing, so it works on a machine that has never set up an Apple developer account. The demo’s iOS passkey support is the one exception, and it is opt-in behind WAVELENGTH_IOS_PASSKEYS=1; see the demo README.

The first run generates the native android/ and ios/ projects (gitignored) and takes a while; later runs are incremental.

Networks

The start screen offers three presets:

  • regtest targets a local stack. Host addressing is automatic per platform: the Android emulator reaches your machine as 10.0.2.2, the iOS simulator as 127.0.0.1.
  • testnet and signet target the public test network deployments over TLS and also work on physical devices.

Every endpoint is editable under “Advanced endpoints” before starting, so a preset is a starting point, not a limit.

What the demo shows

The app exercises the full wallet flow: create, restore, or unlock (password or passkey), recovery-phrase backup, on-chain boarding and Lightning receive with scannable QRs, send, live activity, local-data wipe, and light/dark themes. It mirrors the web demo screen for screen, so the two SDK surfaces can be compared directly; see Demo app for the web counterpart.