/`. 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](/web/get-started/run-the-demo-app/) for the full command.
React Native readers: see [Run the demo app](/react-native/get-started/run-the-demo-app/) for the mobile counterpart, which mirrors this demo screen for screen.
---
Source: https://wavelength.lightning.engineering/web/get-started/installation.md
# Installation
## The packages
For web apps, the Wavelength SDK ships as three npm packages. You install one or two of them depending on your stack:
| Package | What it is |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `@lightninglabs/wavelength-core` | Types, the `WavelengthClient` interface, errors, and enums. Pulled in transitively; you rarely install it directly. |
| `@lightninglabs/wavelength-web` | The browser WASM transport. Framework-agnostic: use it from vanilla JS, Vue, Svelte, or React. Re-exports everything from `core`. |
| `@lightninglabs/wavelength-react` | React provider and hooks. Transport-agnostic: it takes an injected engine and depends only on `core`. |
**React apps** need the web transport and the React bindings:
```bash
npm install @lightninglabs/wavelength-web @lightninglabs/wavelength-react
```
**Vanilla JS, Vue, Svelte, or other non-React frameworks** need only the web transport:
```bash
npm install @lightninglabs/wavelength-web
```
Before wiring up the code samples below, make sure the browser environment you’re deploying to meets the [requirements](/web/get-started/requirements/) and serves your app with the headers described in [Cross-origin isolation](/web/get-started/cross-origin-isolation/). The Wavelength SDK’s WebAssembly runtime will not start without them.
## Peer deps
`@lightninglabs/wavelength-react` declares `react` as a peer dependency, with an accepted range of `^18.0.0 || ^19.0.0`. Your app must also provide `react-dom` (or the equivalent for your React renderer). Either major version, 18 or 19, works:
```bash
npm install react react-dom
```
Build the wallet engine once near the root of your app. `createWebWalletEngine` accepts `WebWalletEngineOptions` (for example `runtimeBaseUrl` pointing at hosted WASM assets, see [Hosting runtime assets](/web/get-started/hosting-runtime-assets/)), plus `config` and `autoStart` to boot the embedded daemon as soon as the runtime is ready, no boot effect needed.
```tsx
import {
WavelengthProvider,
useWallet,
useWalletBalance,
} from '@lightninglabs/wavelength-react';
import {
createWebWalletEngine,
defaultConfig,
} from '@lightninglabs/wavelength-web';
// Configure transport options once. runtimeBaseUrl points at the hosted WASM
// asset folder.
const engine = createWebWalletEngine({
runtimeBaseUrl: 'https://your-host/wavewalletdk/',
config: defaultConfig('signet'),
autoStart: true,
});
export function App() {
return (
);
}
function Wallet() {
const { phase, error } = useWallet();
const balance = useWalletBalance();
if (phase !== 'ready') {
return Loading… ({phase})
;
}
return Spendable: {balance?.confirmedSat ?? 0} sats
;
}
```
`error` from `useWallet` holds the last fatal runtime-level error: set when the initial runtime load fails or when `start`/`stop` fails. Render it instead of dropping the failure on the floor.
For a non-React app, skip the provider and call `start` on the client directly after `ready()` resolves:
```ts
import { createWebClient, defaultConfig } from '@lightninglabs/wavelength-web';
const client = createWebClient({
runtimeBaseUrl: 'https://your-host/wavewalletdk/',
});
await client.ready();
await client.start(defaultConfig('signet'));
```
## Next steps
- [Requirements](/web/get-started/requirements/): confirm the browser support matrix and backend services the Wavelength SDK needs.
- [Hosting runtime assets](/web/get-started/hosting-runtime-assets/): obtain the WebAssembly runtime asset set and serve it from your own host.
- [Quickstart](/web/get-started/quickstart/): wire up the provider, create a wallet, and send your first payment.
---
Source: https://wavelength.lightning.engineering/web/get-started/requirements.md
# Requirements
## Browser support
Wavelength runs the full wallet daemon in the browser as WebAssembly. Target browsers with mature WASM, Web Worker, and storage APIs:
| Browser | Minimum version |
| ------------------------------------ | --------------- |
| Chrome (and Chromium-based browsers) | 100+ |
| Firefox | 110+ |
| Safari (macOS and iOS) | 16+ |
Node.js 20 or later is recommended for local development (Vite, Next.js, and similar bundlers). No special build plugins are required beyond serving the WASM runtime assets and, for worker mode, setting cross-origin isolation headers.
Passkey support (WebAuthn with PRF) is optional and depends on the browser and OS. Password-based wallets work everywhere in the matrix above.
## Cross-origin isolation
The default transport runs the daemon in a dedicated Web Worker and persists wallet state with OPFS-backed SQLite. Both paths rely on `SharedArrayBuffer`, which browsers only expose on **cross-origin isolated** pages.
Your app must send `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` response headers on every route that loads the wallet. See [Cross-origin isolation](/web/get-started/cross-origin-isolation/) for the exact values and a quick verification command.
If you cannot isolate the page (for example, because third-party embeds block `require-corp`), you can run the runtime on the main thread with `createWebClient({ runtimeThread: 'main' })`, but OPFS persistence will not be available and the UI thread will block while the daemon is busy. See [Data & persistence](/web/runtime/data-and-persistence/) for how storage behavior differs between main-thread and worker mode.
## Backends
Wavelength is self-custodial: the seed never leaves the browser. The embedded daemon still needs reachable **Ark**, **Esplora**, and (for Lightning swaps) **swap server** endpoints at runtime.
**Signet (recommended for development)** works out of the box with the public preset. Pass `defaultConfig('signet')` to `start()` and the client connects to Lightning Labs hosted gateways:
```ts
import { createWebClient, defaultConfig } from '@lightninglabs/wavelength-web';
const client = createWebClient();
await client.start(defaultConfig('signet'));
```
Presets also exist for `testnet`. No local backend is required for any hosted network.
**Regtest (local development)** targets services you run yourself, so there is no `defaultConfig` preset for it; local ports vary per machine, and the URLs are the whole point of a preset. Start [arktest](https://github.com/lightninglabs/wavelength), note the ports it prints, and build the config by hand, including the insecure-transport flags for plain-HTTP local gateways:
```ts
import type { RuntimeConfig } from '@lightninglabs/wavelength-web';
const config: RuntimeConfig = {
network: 'regtest',
arkServerAddress: 'http://127.0.0.1:7071',
walletEsploraUrl: 'http://127.0.0.1:8501',
swapServerAddress: 'http://127.0.0.1:10032',
arkServerInsecure: true,
swapServerInsecure: true,
};
await client.start(config);
```
**Mainnet** has no public preset yet, so like regtest there is no `defaultConfig` for it. Build the config by hand with your own gateway URLs and set `allowMainnet: true` before going live:
```ts
await client.start({
network: 'mainnet',
arkServerAddress: 'https://your-ark-server.example.com',
walletEsploraUrl: 'https://your-esplora.example.com/api',
swapServerAddress: 'https://your-swap-server.example.com',
allowMainnet: true,
});
```
On web, `arkServerAddress` and `swapServerAddress` must be REST URLs. `walletEsploraUrl` is an HTTP Esplora endpoint. The web transport always rejects `arkServerTlsCertPath`. It accepts `swapServerTlsCertPath` only when `disableSwaps: true`, which suppresses every swap field.
Mainnet access is gated to an approved allowlist. See [Mainnet access](/concepts/networks-and-config/#mainnet-access) for how to request it with your client’s `identity_pubkey`.
---
Source: https://wavelength.lightning.engineering/web/get-started/hosting-runtime-assets.md
# Hosting runtime assets
The web transport loads its WebAssembly runtime from a set of files that you host yourself and point `runtimeBaseUrl` at. You always provide the assets. The worker entry (`wavewalletdk-worker.js`) ships inside `@lightninglabs/wavelength-web` and is emitted by your bundler; only the daemon binaries below need to be hosted.
```ts
import { createWebClient } from '@lightninglabs/wavelength-web';
const client = createWebClient({
runtimeBaseUrl: 'https://your-host/wavewalletdk//',
});
```
If `runtimeBaseUrl` is unset, assets resolve relative to the page URL in both worker and main-thread mode, so you can also serve the runtime files alongside your app.
## The asset set
The runtime is a fixed set of files built from [wavelength](https://github.com/lightninglabs/wavelength). Import `RUNTIME_ASSET_FILES` to see every filename that must be served together at one base URL. `RUNTIME_MANIFEST_VERSION` identifies the daemon build the SDK is paired with:
```ts
import {
RUNTIME_ASSET_FILES,
RUNTIME_MANIFEST_VERSION,
} from '@lightninglabs/wavelength-web';
console.log(RUNTIME_ASSET_FILES);
// wavewalletdk.wasm, wavewalletdk.wasm.gz, wasm_exec.js, sqlite-bridge.js,
// sqlite-worker.js, sqlite3.js, sqlite3.wasm, sqlite3-opfs-async-proxy.js
```
## Get the asset set
There are two ways to obtain the files, both producing the set for the pinned `RUNTIME_MANIFEST_VERSION`:
**Download from the wavelength release.** The matching asset set is attached to the paired [wavelength release](https://github.com/lightninglabs/wavelength/releases) as `Wavewalletdk.wasm.tar.gz`. It holds every file above, flat with no enclosing directory, so it unpacks straight into the directory you serve them from:
```bash
BASE=https://github.com/lightninglabs/wavelength/releases/download
curl -fsSLO "$BASE//Wavewalletdk.wasm.tar.gz"
mkdir -p "./public/wavewalletdk/"
tar -xzf Wavewalletdk.wasm.tar.gz -C "./public/wavewalletdk/"
```
**Build from a wavelength checkout.** From a checkout of `wavelength`, build the WASM wallet target and copy the output into your app’s static folder:
```bash
make -C /path/to/wavelength wasm-wallet
mkdir -p "./public/wavewalletdk/"
for f in wavewalletdk.wasm wavewalletdk.wasm.gz wasm_exec.js sqlite-bridge.js \
sqlite-worker.js sqlite3.js sqlite3.wasm sqlite3-opfs-async-proxy.js; do
cp "/path/to/wavelength/bin/wasm/$f" "./public/wavewalletdk//"
done
```
The monorepo demo wraps the same build in `pnpm --filter web-wallet-demo run wasm:local`, which builds from a sibling `wavelength` checkout and stages files into `apps/web-wallet-demo/public/runtime//`, the versioned path the demo’s `runtimeBaseUrl` points at. After `vite build`, those files land in `dist/` and are served from the app origin.
A runtime built this way will not match the pinned digests described in [Integrity verification](#integrity-verification) below; point `createWebClient()` at it with `runtimeIntegrity: false` as covered there.
## Host the assets
Host all of them under a single path and set `runtimeBaseUrl` to that directory. Prefer a path that includes `RUNTIME_MANIFEST_VERSION` (for example `/wavewalletdk//`): every asset set then gets a unique URL, so browsers pick up new assets on an SDK upgrade instead of serving stale cached copies, and you can cache the files aggressively. Trailing slashes are optional; the client normalizes the base URL.
**Version lock.** Runtime assets are version-locked to the embedded daemon inside `@lightninglabs/wavelength-web`. When you upgrade the SDK, obtain and redeploy the matching WASM bundle. Mismatched versions can fail at load time or produce subtle runtime errors.
**Compression.** The client fetches `wavewalletdk.wasm.gz` first and falls back to the uncompressed `wavewalletdk.wasm` if it cannot be used (for example when the browser has no `DecompressionStream` to inflate it). Host both files so every supported browser can load the runtime.
No particular *compression* headers are required. The client reads the file’s first bytes and branches on the magic number rather than on `Content-Type` or `Content-Encoding`, so a body your host serves compressed, one it has already inflated, and one labelled `application/gzip` all load the same way. Compress it however your host makes easiest.
Other headers still matter: a cross-origin `runtimeBaseUrl` needs `Cross-Origin-Resource-Policy: cross-origin` on these assets, covered in [cross-origin isolation](/web/get-started/cross-origin-isolation/).
Do still set long-lived cache headers, but note that the browser will not keep a module this large in its HTTP cache regardless of what you send. The SDK therefore keeps its own copy in Cache Storage so returning visitors do not re-download it; see [Data & persistence](/web/runtime/data-and-persistence/#the-runtime-cache) for what that stores and when it is pruned. Cached bytes are re-verified against the pinned digest on every read, exactly like a fresh fetch, so a cache entry can never become a bypass for the checks below.
## Integrity verification
Before executing the wasm binary and the two bootstrap scripts the transport executes (`wasm_exec.js` and `sqlite-bridge.js`), the web transport verifies their fetched bytes against SHA-256 digests pinned in the npm package for the paired `RUNTIME_MANIFEST_VERSION`. Hosting a mismatched version’s assets fails loudly with `asset_integrity_failed` instead of silently running stale or tampered code. `wavewalletdk.wasm.gz` is covered too: the client verifies its decompressed bytes against the same digest entry as `wavewalletdk.wasm`, since decompressing it yields identical content.
The remaining files in the asset set (the sqlite worker chain: `sqlite-worker.js`, `sqlite3.js`, `sqlite3.wasm`, `sqlite3-opfs-async-proxy.js`) are not verified at runtime. Cover them by checking your deployed set at deploy time instead: `RUNTIME_ASSET_DIGESTS` exports the digest for every file in the set, keyed by filename in the same SRI format (`sha256-`) the client checks against.
```bash
f=./public/wavewalletdk//wavewalletdk.wasm
echo "sha256-$(openssl dgst -sha256 -binary "$f" | openssl base64 -A)"
```
**Escape hatch for source-built runtimes.** A runtime you build yourself from a `wavelength` checkout will not match the pinned digests, since those pin a specific published release. Set `runtimeIntegrity: false` on `createWebClient()` or `createWebWalletEngine()` to skip verification; doing so logs a one-time console warning so the switch is never silently left off in production.
**Hosting requirements.** Serve the runtime assets same-origin where possible. If your app sets a Content-Security-Policy, `script-src` must include `blob:` alongside `'self'`: the SDK executes its verified bootstrap scripts from blob URLs, and a policy without `blob:` breaks the SDK outright. Hosting the assets cross-origin additionally requires CORS headers on the asset host, since the client fetches them before verifying their bytes.
---
Source: https://wavelength.lightning.engineering/web/get-started/cross-origin-isolation.md
# Cross-origin isolation
## Why
The Wavelength SDK’s default transport runs the wallet daemon in a Web Worker and stores encrypted wallet data in OPFS-backed SQLite. Both the worker’s WASM module and the SQLite stack use `SharedArrayBuffer` for efficient memory sharing.
Browsers gate `SharedArrayBuffer` behind **cross-origin isolation**: the page must be served with headers that prevent other origins from reading its memory. Without isolation, `SharedArrayBuffer` is unavailable, OPFS persistence fails, and the worker transport cannot start.
Cross-origin isolation is a web-only concern. It applies to every route in your app that loads the Wavelength SDK. (The hosted demo app is served from its own origin with these headers for exactly this reason.)
## COOP/COEP headers
These are response headers on your own HTML document, so only the server that serves your app can set them. The Wavelength SDK cannot set them for you: they are not something the SDK, the worker, or the runtime assets can emit on their own. Send them on wallet routes (and on your dev server while testing locally):
```http
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```
`Cross-Origin-Opener-Policy: same-origin` keeps other browsing contexts from holding a reference to your page’s global object.
`Cross-Origin-Embedder-Policy: require-corp` requires every subresource (script, stylesheet, image, font, WASM) to either be same-origin or explicitly opt in with `Cross-Origin-Resource-Policy: cross-origin` (or be loaded with `crossorigin` where applicable). Same-origin assets need no extra attribute.
**Scope headers to wallet routes.** If only part of your site runs the wallet (for example a `/wallet/*` section), apply COOP/COEP on those paths rather than the entire domain. Hosts like Netlify and Cloudflare Pages read a `_headers` file:
```text
/wallet/*
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```
For Vite during local development, set the same headers on the dev and preview servers:
```ts
const crossOriginIsolation = {
'Cross-Origin-Opener-Policy': 'same-origin',
'Cross-Origin-Embedder-Policy': 'require-corp',
'Cross-Origin-Resource-Policy': 'same-origin',
};
export default defineConfig({
server: { headers: crossOriginIsolation },
preview: { headers: crossOriginIsolation },
});
```
**Self-host third-party assets.** Cross-origin Google Fonts, analytics scripts, and similar embeds are blocked under `require-corp`. Bundle fonts locally (for example with `@fontsource`) or serve them from the same origin as your app.
> **Note**
>
> If you set `runtimeBaseUrl` to point the daemon runtime binaries (`wavewalletdk.wasm.gz`, `wasm_exec.js`, `sqlite-*.js`) at a different origin, that origin must also send `Cross-Origin-Resource-Policy: cross-origin` on those asset responses. Otherwise `require-corp` blocks them from loading. The wasm binary and the bootstrap scripts (`wasm_exec.js`, `sqlite-bridge.js`) are always fetched directly rather than loaded via `