wavelength-web

Returns a ready-to-use RuntimeConfig for a network, preloaded with the canonical public REST gateway endpoints the web transport dials, merged with any overrides. This is a shallow merge of top-level RuntimeConfig fields. Pass overrides to set dataDir or point at your own infrastructure.

function defaultConfig(
  network: PresetNetwork,
  overrides?: Partial<RuntimeConfig>,
): RuntimeConfig

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

const config = defaultConfig('signet', { dataDir: 'my-wallet' });

'mainnet' and 'regtest' are not accepted: mainnet has no public deployment yet, and regtest’s local ports vary per development environment. Build their RuntimeConfig by hand, mainnet with your own gateway URLs and allowMainnet, regtest with local URLs and the insecure-transport flags. On web, arkServerAddress and swapServerAddress are REST URLs, and walletEsploraUrl is an HTTP Esplora endpoint. The web transport rejects arkServerTlsCertPath. It accepts swapServerTlsCertPath only when disableSwaps: true, which suppresses every swap field. The per-network endpoint values are on the wavelength-core reference.

Creates and returns a WavelengthClient that runs the embedded daemon in the browser. Call once at application startup, then wrap it with createWalletEngine from @lightninglabs/wavelength-core (or use createWebWalletEngine below to do both in one call) or call start(defaultConfig(network)) directly. Defaults to the Web Worker transport (WorkerWavelengthClient); pass runtimeThread: 'main' to run on the page’s main thread instead.

function createWebClient(
  options?: WebClientOptions,
): WavelengthClient

Browser-specific options for createWebClient. The config passed to client.start() is separate: use defaultConfig(network) from @lightninglabs/wavelength-web.

type WebClientOptions = {
  workerURL?: string;
  runtimeBaseUrl?: string;
  runtimeThread?: RuntimeThread;
  debug?: boolean;
};

Selects which thread the wasm runtime runs on: 'worker' (default) in a dedicated Web Worker that keeps the UI thread free, or 'main' on the page’s main thread as an escape hatch (for example, environments without Worker support).

type RuntimeThread = 'main' | 'worker';

Creates a WalletEngine over the browser/wasm transport: the one-call setup for a web app. It builds the client with createWebClient() internally, so you only need this one factory. Pass the result to WavelengthProvider from wavelength-react, or drive it directly without React.

function createWebWalletEngine(
  options?: WebWalletEngineOptions,
): WalletEngine

WebWalletEngineOptions

The browser-specific settings from WebClientOptions combined with WalletEngineOptions’s config/autoStart union (minus client, which this factory builds for you): the types require a config when autoStart is enabled, so autoStart: true without config is a compile error.

type WebWalletEngineOptions = WebClientOptions &
  (
    | { config: RuntimeConfig; autoStart: true }
    | { config?: RuntimeConfig; autoStart?: false }
  );

import { createWebWalletEngine, defaultConfig } from '@lightninglabs/wavelength-web';
import { WavelengthProvider } from '@lightninglabs/wavelength-react';

const engine = createWebWalletEngine({
  runtimeBaseUrl: 'https://your-host/wavewalletdk/',
  config: defaultConfig('signet'),
  autoStart: true,
});

export function Root() {
  return <WavelengthProvider engine={engine}>{/* your app */}</WavelengthProvider>;
}

Runs the wasm runtime on the page’s main thread. It implements WavelengthClient directly and is the escape hatch for environments without Web Worker support (or where main-thread execution is preferred for another reason). Unlike worker mode it blocks rendering while the runtime is busy.

class MainThreadWavelengthClient implements WavelengthClient {
  constructor(options?: WebClientOptions);
}

Prefer createWebClient({ runtimeThread: 'main' }) over constructing this class directly; only reach for the class import when you need to branch construction logic yourself (for example, feature-detecting Worker support at runtime).

The canonical set of daemon runtime binaries the wasm client loads at runtime, resolved against runtimeBaseUrl. RUNTIME_ASSET_FILES is just Object.values(RUNTIME_ASSETS). This set is built by wavelength (make wasm-wallet) and version-locked to the embedded wavelength daemon, so the files must be hosted side by side at one base URL.

const RUNTIME_ASSETS: {
  wasm: string;
  wasmGz: string;
  wasmExec: string;
  sqliteBridge: string;
  sqliteWorker: string;
  sqlite: string;
  sqliteWasm: string;
  sqliteOpfsProxy: string;
};

The values are fixed filenames, not just string-typed placeholders:

Flat list of every runtime binary that must be hosted together at runtimeBaseUrl: wavewalletdk.wasm, wavewalletdk.wasm.gz, wasm_exec.js, sqlite-bridge.js, sqlite-worker.js, sqlite3.js, sqlite3.wasm, sqlite3-opfs-async-proxy.js (that is, Object.values(RUNTIME_ASSETS)). Host these files and point runtimeBaseUrl at them before calling client.ready().

const RUNTIME_ASSET_FILES: readonly string[];

The daemon build this SDK release is paired with: the generated types, the client methods, and the runtime asset set all come from this one daemon revision. Hosted asset sets live in a directory named after this value, so a version bump changes every asset URL and browsers can never serve a stale cached runtime. Defined in (and re-exported from) @lightninglabs/wavelength-core.

const RUNTIME_MANIFEST_VERSION: string;

Browser (WebAuthn/PRF) implementation of the PasskeyCeremony contract. It is literally the three standalone functions below grouped into one object; pass it to useWalletPasskey from wavelength-react, or call the functions directly.

const webPasskeyCeremony: PasskeyCeremony;

const webPasskeyCeremony: PasskeyCeremony = {
  supportsPasskeyPrf,
  registerPasskeyWallet,
  assertPasskeyPrf,
};

Reports whether a user-verifying platform authenticator is available, which is a prerequisite for WebAuthn PRF.

function supportsPasskeyPrf(): Promise<boolean>;

Creates a new platform passkey and returns its PRF output and credential id. Some browsers do not surface the PRF result from create(), so this falls back to an assertion scoped to the just-created credential to read it reliably without prompting a chooser.

function registerPasskeyWallet(
  appName: string,
): Promise<PasskeyAssertion>;

Authenticates with a passkey and returns its PRF output plus the credential id used.

function assertPasskeyPrf(
  allowCredentialId?: string,
): Promise<PasskeyAssertion>;

Result of a passkey registration or assertion ceremony. Defined in @lightninglabs/wavelength-core and surfaced here through the re-export (see the callout at the top of this page); shown in full because it is the return type of the two functions above.

type PasskeyAssertion = {
  prfOutput: string;
  credentialId: string;
};

Reproducibility. Both functions evaluate the PRF extension against a fixed salt, SHA-256("wavewalletdk-passkey:v1"), a fixed namespace chosen client-side. Using the same fixed salt on every device/platform is what makes the derived wallet reproducible: asserting the same passkey anywhere yields the same prfOutput, and therefore the same derived wallet.

Discoverable vs. scoped assertions. assertPasskeyPrf() called with no argument performs a discoverable assertion (empty allowCredentials), letting the platform’s passkey chooser surface any matching synced passkey, including on a device that has never seen this wallet before. Passing allowCredentialId instead performs a scoped assertion limited to that one credential, which lets the OS unlock it directly without showing a chooser.

Parameters accepted by prepareSend() and send(). SendRequest is a discriminated union: provide invoice for a Lightning send, or onchainAddress for an on-chain send. The two branches are mutually exclusive; sweepAll exists only on the on-chain branch.

type SendRequest =
  | {
      invoice: string;
      amountSat?: number;
      note?: string;
      maxFeeSat?: number;
    }
  | {
      onchainAddress: string;
      amountSat?: number;
      sweepAll?: boolean;
      note?: string;
      maxFeeSat?: number;
    };

Parameters accepted by receive().

type ReceiveRequest = {
  amountSat: number;
  memo?: string;
};