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.

import { createWebClient } from '@lightninglabs/wavelength-web';

const client = createWebClient({
  runtimeBaseUrl: 'https://your-host/wavewalletdk/<version>/',
});

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. 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:

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. Download the files for the pinned version.

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:

# Build the WASM runtime into wavelength/bin/wasm/
make -C /path/to/wavelength wasm-wallet

# Copy every runtime binary into a directory named after
# RUNTIME_MANIFEST_VERSION (example: Vite public/)
mkdir -p "./public/wavewalletdk/<version>"
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/<version>/"
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/<version>/, the versioned path the demo’s runtimeBaseUrl points at. After vite build, those files land in dist/ and are served from the app origin.

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/<version>/): 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 prefers wavewalletdk.wasm.gz when the browser supports DecompressionStream and falls back to the uncompressed wavewalletdk.wasm. Host both files so every supported browser can load the runtime.