wavelength-react-native

React Native transport factory, native passkey ceremony, and data-directory API.

@lightninglabs/wavelength-react-native is the React Native transport for the Wavelength SDK: the daemon compiled into the app binary via gomobile bindings, exposed as a standard WavelengthClient. createNativeWalletEngine() wraps that client in a WalletEngine in one call, which is the entry point most apps want. It also ships the native (Android Credential Manager / iOS AuthenticationServices) passkey ceremony.

Configuration

Returns a ready-to-use RuntimeConfig for a network, preloaded with the canonical public gRPC host:port addresses the native 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

Parameter	Type	Description
`network`	`PresetNetwork`	The Bitcoin network to run against; mainnet and regtest are excluded because they have no preset. Use signet for development and testing.
`overrides`	`Partial<RuntimeConfig>`	Optional. Fields that override the network preset's defaults. Default: {}.

ReturnsRuntimeConfig

A complete configuration object for client.start() or the engine factory’s config.

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

const config = defaultConfig('signet', { dataDir: '/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 gRPC addresses and allowMainnet, regtest with local addresses and the insecure-transport flags. arkServerAddress and swapServerAddress are gRPC host:port values on native, while walletEsploraUrl remains an HTTP Esplora endpoint. The per-network endpoint values are on the wavelength-core reference.

Creating a client

Creates and returns a WavelengthClient backed by the React Native transport: the daemon compiled into the app via the gomobile bindings. Takes no options in this release; the signature reserves an options object for future use. Activity arrives as typed activity events, re-emitted here from native wavelengthActivity device events.

function createNativeClient(): WavelengthClient

ReturnsWavelengthClient

A live client instance. Call ready() (resolves immediately, since the runtime is already compiled in) then start(config) to boot the daemon.

Creates a WalletEngine over the React Native transport: the one-call setup for an RN app. It builds the client with createNativeClient() internally, so you only need this one factory. Pass the result to WavelengthProvider from wavelength-react.

function createNativeWalletEngine(
  options?: NativeWalletEngineOptions,
): WalletEngine

Parameter	Type	Description
`options`	`NativeWalletEngineOptions`	Optional. The engine's config and autoStart; createNativeClient() itself takes no options today.

ReturnsWalletEngine

A live engine driving a freshly built native client. See WalletEngine for its full behavior, including the background processes it runs automatically.

NativeWalletEngineOptions

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 NativeWalletEngineOptions =
  | { config: RuntimeConfig; autoStart: true }
  | { config?: RuntimeConfig; autoStart?: false };

Parameter	Type	Description
`config`	`RuntimeConfig`	Required when autoStart is true. Default runtime config used by autoStart and by the engine's start() when called with no argument.
`autoStart`	`true \| false`	Optional. Start the runtime automatically once it is ready. Setting it to true requires config.

import { createNativeWalletEngine, defaultConfig } from '@lightninglabs/wavelength-react-native';
import { WavelengthProvider } from '@lightninglabs/wavelength-react';

const engine = createNativeWalletEngine({
  config: defaultConfig('signet'),
  autoStart: true,
});

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

Passkeys (native)

Creates the native implementation of the PasskeyCeremony contract (Android Credential Manager, iOS AuthenticationServices). Pass it to useWalletPasskey from wavelength-react, or call its methods directly.

function createNativePasskeyCeremony(
  options: NativePasskeyCeremonyOptions,
): PasskeyCeremony

Parameter	Type	Description
`options`	`NativePasskeyCeremonyOptions`	Native-specific ceremony configuration.

ReturnsPasskeyCeremony

The native passkey ceremony. Its supportsPasskeyPrf() method is what backs useWalletPasskey’s supported flag.

Requires the relying-party domain to be associated with your app: assetlinks.json on Android, an Associated Domains entitlement plus apple-app-site-association on iOS. See the passkey setup guide for the full walkthrough.

Options for createNativePasskeyCeremony.

type NativePasskeyCeremonyOptions = {
  rpId: string;
};

Parameter	Type	Description
`rpId`	`string`	The WebAuthn relying-party id: the domain whose assetlinks.json (Android) and apple-app-site-association (iOS) vouch for this app. Native apps have no window.location, so the rpId is explicit configuration.

Data directory

Resolves the platform default wallet data directory: the same directory createNativeClient’s client uses when RuntimeConfig.dataDir is unset. Exposed for app-level data management (show the storage location, back it up, or wipe it).

function getDefaultDataDir(): Promise<string>;

ReturnsPromise<string>

A plain absolute filesystem path, with no URI scheme. Not guaranteed to exist until the runtime has started.