--- title: "wavelength-react-native" description: "React Native transport factory, native passkey ceremony, and data-directory API." canonical: https://wavelength.lightning.engineering/reference/wavelength-react-native/ --- > Docs index: https://wavelength.lightning.engineering/llms.txt # 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`](/reference/wavelength-core/#WavelengthClient). [`createNativeWalletEngine()`](#createNativeWalletEngine) wraps that client in a [`WalletEngine`](/reference/wavelength-core/#WalletEngine) in one call, which is the entry point most apps want. It also ships the native (Android Credential Manager / iOS AuthenticationServices) passkey ceremony. > **One import for the client and every type** > > This package re-exports the entire [`@lightninglabs/wavelength-core`](/reference/wavelength-core/) public surface (`export * from '@lightninglabs/wavelength-core'`). You only need to import from `@lightninglabs/wavelength-react-native` to get the client factory, every request/result and nested response type, every core-exported generated string-enum constant, and `defaultConfig()`. This includes `FacadeMethod`, `ActivityStreamOptions`, `EntryProgress`, `CreditPreview`, and the complete activity, list, send, and exit type families. There is no need to also depend on `@lightninglabs/wavelength-core` directly. ## Configuration ### defaultConfig function 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. ```ts function defaultConfig( network: PresetNetwork, overrides?: Partial, ): RuntimeConfig ``` - `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` Optional. Fields that override the network preset's defaults. Default: {}. Returns: [`RuntimeConfig`](/reference/wavelength-core/#RuntimeConfig): A complete configuration object for `client.start()` or the engine factory’s `config`. ```ts 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](/reference/wavelength-core/#Network). ## Creating a client ### createNativeClient function Creates and returns an [`ExternalSeedWalletClient`](/reference/wavelength-core/#ExternalSeedWalletClient) backed by the React Native transport: the daemon compiled into the app via the gomobile bindings. Takes no options in this release. Activity arrives as typed `activity` events, re-emitted here from native `wavelengthActivity` device events. ```ts function createNativeClient(): ExternalSeedWalletClient ``` Returns: [`ExternalSeedWalletClient`](/reference/wavelength-core/#ExternalSeedWalletClient): A live client instance. Call `ready()` (resolves immediately, since the runtime is already compiled in) then `start(config)` to boot the daemon. ### External-seed startup The native client forwards [`startExternalSeedWallet(config, req)`](/reference/wavelength-core/#startExternalSeedWallet) through the gomobile bridge. The integrating application owns seed derivation and folder selection: pass a final nonempty `config.dataDir` and exactly 16 bytes of derived entropy. Unlike ordinary `start()`, this lifecycle never fills in the platform default directory implicitly. ```ts const client = createNativeClient(); await client.ready(); await client.startExternalSeedWallet( { ...config, dataDir: finalProfileDataDir }, { seedEntropy: derivedEntropy16 }, ); ``` The root seed, derivation path, account index, and folder layout remain outside this package. Persist the returned `identityPubKey` and supply it as `expectedIdentityPubKey` on later opens if the app wants to bind a selected folder to the expected wallet identity. > **Requires local paired bindings** > > This source API depends on [lightninglabs/wavelength#1158](https://github.com/lightninglabs/wavelength/pull/1158) and is absent from the currently pinned v0.1.1 AAR and XCFramework. Until a newer Wavelength release is pinned, build bindings locally from the paired Wavelength branch. ### createNativeWalletEngine function Creates a [`WalletEngine`](/reference/wavelength-core/#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](/reference/wavelength-react/). ```ts function createNativeWalletEngine( options?: NativeWalletEngineOptions, ): WalletEngine ``` - `options` [`NativeWalletEngineOptions`](/reference/wavelength-react-native/#NativeWalletEngineOptions) Optional. The engine's config and autoStart; createNativeClient() itself takes no options today. Returns: [`WalletEngine`](/reference/wavelength-core/#WalletEngine): A live engine driving a freshly built native client. See [`WalletEngine`](/reference/wavelength-core/#WalletEngine) for its full behavior, including the background processes it runs automatically. **`NativeWalletEngineOptions`** [`WalletEngineOptions`](/reference/wavelength-core/#createWalletEngine)’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. ```ts type NativeWalletEngineOptions = { onPerformance?: WavelengthPerformanceListener } & ( | { config: RuntimeConfig; autoStart: true } | { config?: RuntimeConfig; autoStart?: false } ); ``` - `config` [`RuntimeConfig`](/reference/wavelength-core/#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. - `onPerformance` [`WavelengthPerformanceListener`](/reference/wavelength-core/#WavelengthPerformanceListener) Optional. Receives structured timing samples for runtime readiness, wallet create/open RPCs, post-operation info adoption, and sync polling. On this transport runtime readiness is the only runtime-stage sample, since the native runtime is compiled in rather than loaded. Instrumentation stays off unless this is supplied. Default: unset (disabled). ```tsx 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 {/* your app */}; } ``` ## Passkeys (native) ### createNativePasskeyCeremony function Creates the native implementation of the [`PasskeyCeremony`](/reference/wavelength-core/#PasskeyCeremony) contract (Android Credential Manager, iOS AuthenticationServices). Pass it to `useWalletPasskey` from wavelength-react, or call its methods directly. ```ts function createNativePasskeyCeremony( options: NativePasskeyCeremonyOptions, ): PasskeyCeremony ``` - `options` [`NativePasskeyCeremonyOptions`](/reference/wavelength-react-native/#NativePasskeyCeremonyOptions) Native-specific ceremony configuration. Returns: [`PasskeyCeremony`](/reference/wavelength-core/#PasskeyCeremony): 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](/react-native/get-started/passkey-setup/) for the full walkthrough. > **iOS support is experimental** > > iOS passkey support needs iOS 18 or newer at runtime and is experimental in this release. ### NativePasskeyCeremonyOptions type Options for `createNativePasskeyCeremony`. ```ts type NativePasskeyCeremonyOptions = { rpId: string; }; ``` - `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 ### getDefaultDataDir function 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). ```ts function getDefaultDataDir(): Promise; ``` Returns: `Promise`: A plain absolute filesystem path, with no URI scheme. Not guaranteed to exist until the runtime has started. ## See also - [wavelength-core reference](/reference/wavelength-core/) for `WavelengthClient`, `WalletEngine`, `RuntimeConfig`, `WalletInfo`, `Balance`, `Entry`, and every other re-exported type. - [wavelength-react reference](/reference/wavelength-react/) for `WavelengthProvider`, `useWalletPasskey`, and the other hooks that consume an engine created here. - [Passkey setup](/react-native/get-started/passkey-setup/) for the Android and iOS domain-association walkthrough required by `createNativePasskeyCeremony`.