--- title: "wavelength-react" description: "React bindings for the Wavelength SDK - the WavelengthProvider component and hooks for balance, activity, and wallet operations." canonical: https://wavelength.lightning.engineering/reference/wavelength-react/ --- > Docs index: https://wavelength.lightning.engineering/llms.txt # wavelength-react React bindings for the Wavelength SDK - the WavelengthProvider component and hooks for balance, activity, and wallet operations. `@lightninglabs/wavelength-react` is the React binding for the Wavelength SDK: a context provider that hands a [`WalletEngine`](/reference/wavelength-core/#WalletEngine) down to a component subtree, plus hooks for reading its state and calling wallet operations. > **Note** > > This package re-exports the complete `wavelength-core` contract (`export * from '@lightninglabs/wavelength-core'`), including `WavelengthClient`, `WalletEngine`, `FacadeMethod`, `ActivityStreamOptions`, every request/result and nested response type, and every core-exported generated string-enum constant. You can import the core contract directly from `@lightninglabs/wavelength-react` instead of adding `@lightninglabs/wavelength-core` as a separate dependency. The engine itself is not built here: create one with `createWebWalletEngine` from [wavelength-web](/reference/wavelength-web/) or `createNativeWalletEngine` from [wavelength-react-native](/reference/wavelength-react-native/). Every hook on this page, including `useWalletPasskey`, must be called within a `WavelengthProvider` subtree; each throws if it is not. ## Provider ## WavelengthProvider class Context provider that hands a [`WalletEngine`](/reference/wavelength-core/#WalletEngine) down to descendants. Wrap your application root (or any subtree) with this component so child hooks can access wallet state and operations. ```ts function WavelengthProvider(props: WavelengthProviderProps): JSX.Element ``` | Parameter | Type | Description | | ---------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `engine` | [`WalletEngine`](/reference/wavelength-core/#WalletEngine) | A WalletEngine from any transport, e.g. createWebWalletEngine() from wavelength-web or createNativeWalletEngine() from wavelength-react-native. Required; the provider throws synchronously if it is missing. | | `children` | `ReactNode` | The component subtree that can call Wavelength SDK hooks. | > **Note** > > **The provider owns nothing.** `WavelengthProvider` does not build, start, poll, or dispose anything: it publishes the engine you hand it to `useSyncExternalStore` subscribers. Every lifecycle behavior described below (sync polling, activity-driven refresh, `autoStart`, the `stopped` transition on an unsolicited runtime stop) is owned by the `WalletEngine` itself, so it also applies to a vanilla (non-React) consumer that drives the same engine directly. See [`WalletEngine`](/reference/wavelength-core/#WalletEngine) on the wavelength-core reference for the full behavior list. > > The provider never calls `engine.dispose()` on unmount. The code that constructed the engine (typically module scope, outside any component) owns its lifetime and is responsible for disposing it when the app is truly done with it. ## WavelengthProviderProps type Props for the `WavelengthProvider` component. `WavelengthProviderProps` is not itself an exported name; the props type is declared inline on the component’s destructured parameter. It is named and documented separately here only for readability. ```ts type WavelengthProviderProps = { children: ReactNode; engine: WalletEngine; }; ``` ## useWalletEngine function Returns the [`WalletEngine`](/reference/wavelength-core/#WalletEngine) from the nearest `WavelengthProvider`: the escape hatch for anything the granular hooks below do not cover (for example calling `engine.client` directly, or a method with no dedicated hook). Throws outside a provider. ```ts function useWalletEngine(): WalletEngine ``` Returns[`WalletEngine`](/reference/wavelength-core/#WalletEngine) The provider’s engine instance. ## useWallet ## useWallet function The application-shell hook: the lifecycle phase to route your top-level UI on, the last fatal runtime error, and the start/stop actions. There are no `pending` flags here: `phase === 'starting'` / `'stopping'` already encode them. ```ts function useWallet(): { phase: RuntimePhase; error: Error | null; start(config?: RuntimeConfig): Promise; stop(): Promise; }; ``` | Parameter | Type | Description | | ---------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `phase` | [`RuntimePhase`](/reference/wavelength-core/#RuntimePhase) | Current runtime/wallet lifecycle phase. See RuntimePhase on the wavelength-core reference; note it now includes 'restoring'. | | `error` | `Error \| null` | The last fatal runtime-level error, or null. Set when the initial runtime load fails, when start()/stop() fails, or after the engine's background processes exhaust their failure budget (e.g. repeated sync-poll or background-refresh failures). | | `start(config?)` | `(config?: RuntimeConfig) => Promise` | Starts the runtime. Falls back to the engine's configured config (the one passed to createWebWalletEngine/createNativeWalletEngine) when called with no argument; throws if neither exists. Resolves with the WalletInfo from startup. | | `stop()` | `() => Promise` | Stops the runtime and clears the in-memory snapshot (info/balance/activity reset to null/null/\[]); persisted wallet data is untouched. | Returns`{ phase, error, start, stop }` The runtime lifecycle phase, last fatal error, and start/stop actions. ## Reading state The five hooks below each subscribe to one slice of the engine’s snapshot via `useSyncExternalStore`, so a component re-renders only when the slice it reads actually changes. `useWalletInfo`, `useWalletBalance`, and `useWalletActivity` are plain selectors; `useWalletRecovery` and `useWalletLogs` also return an action (`acknowledge()` and `clear()` respectively) alongside their slice. ## useWalletInfo function The most recent complete wallet info, or `null` before the runtime reports it. ```ts function useWalletInfo(): WalletInfo | null ``` Returns`WalletInfo | null` The current `WalletInfo`, or `null` before the runtime reports it. Always a complete object: the engine refetches full info whenever the wallet comes up (create, unlock, passkey open, restore). ## useWalletBalance function The most recent wallet balance, or `null` before it is known. ```ts function useWalletBalance(): Balance | null ``` Returns`Balance | null` The current Balance, or null before known. ## useWalletActivity function The most recent activity entries, newest-first as returned by the daemon. ```ts function useWalletActivity(): Entry[] ``` Returns`Entry[]` Always the result of `list({ view: 'activity', pendingOnly: false })`; it does not reflect the vtxos or onchain views. ## useWalletRecovery function The background recovery status set by [`useWalletRestore`](#useWalletRestore) and its acknowledge action. ```ts function useWalletRecovery(): { recovery: RecoveryState; acknowledge(): void; }; ``` | Parameter | Type | Description | | --------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `recovery` | [`RecoveryState`](/reference/wavelength-core/#RecoveryState) | The background recovery status, a discriminated union on status: { status: 'idle' } \| { status: 'restoring' } \| { status: 'done', result: CreateWalletResult } \| { status: 'failed', error: Error }. failed covers both a background scan that errored on an already-usable wallet and a restore that failed before the wallet came up at all, including an untracked restore; read phase from useWallet() alongside it to tell the two apart (ready vs. needsWallet). See RecoveryState on the wavelength-core reference. Drive a "restoring your balance and history" banner off the ready case, or a restore-failed message on the onboarding screen off the needsWallet case. | | `acknowledge()` | `() => void` | Resets recovery to { status: 'idle' }, e.g. after the user dismisses the banner. | ## useWalletLogs function The buffered runtime log tail and a clear action. ```ts function useWalletLogs(): { logs: WavelengthLogPayload[]; clear(): void; }; ``` | Parameter | Type | Description | | --------- | ------------------------ | ------------------------------------------------------------------------------- | | `logs` | `WavelengthLogPayload[]` | Bounded tail (up to 200 entries) of 'log' events from the runtime, newest last. | | `clear()` | `() => void` | Clears the buffered log tail. | ## Mutations The eight hooks below drive a wallet operation and carry hook-local, verb-prefixed `*Pending`/`*Error`/`*Data` state, all built on one shared convention: > **Mutation convention: throw-and-capture** > > Every mutation hook exposes the same shape, with its fields prefixed by the verb it performs: an action function (e.g. `create`), `Pending: boolean`, `Error: Error | null`, `Data` (the last successful result, or `null`), and `reset(): void`. Calling the action clears the previous error/data, sets pending to `true`, awaits the underlying engine call, and on completion **both** updates the hook’s state **and** settles the returned promise the normal way: it resolves with the result (and sets the data field) or rejects with the failure (and sets the error field to that same `Error` instance). This is throw-and-capture: read the `*Error`/`*Data` fields for a declarative render, or `await`/`try`/`catch` the action’s return value for imperative flow, whichever fits the call site. Error fields are always `Error | null`, never a string. `reset()` clears the pending/error/data trio back to idle without calling anything. > > The verb prefix is deliberate: a component composing several of these hooks (e.g. `create` and `deposit` side by side) never needs destructure aliases to avoid name collisions. [`useWalletPasskey`](#useWalletPasskey)’s `create`/`open` fields follow the same prefixing pattern, but this is one place the prefix does not save you: `useWalletCreate` and `useWalletPasskey` both expose a `create` verb, so destructuring both in the same component collides on all four of `create`, `createPending`, `createError`, and `resetCreate`. Keep one as a namespaced object (e.g. `const passkey = useWalletPasskey(...)`) instead of destructuring both. Each hook’s return type is also exported as `UseWalletResult` (`UseWalletCreateResult`, `UseWalletRestoreResult`, `UseWalletUnlockResult`, `UseWalletDepositResult`, `UseWalletReceiveResult`, `UseWalletPrepareSendResult`, `UseWalletSendResult`, `UseWalletRefreshResult`, and the exit-hook result types documented in [Exiting Ark](#exiting-ark) below), for typing wrapper components around a hook without re-deriving its shape. > > A `PasskeyCancelledError` (the user dismissed the OS prompt) is the one exception: it rethrows without being recorded into the error field, since a dismissed prompt is not a failure to display. ## useWalletCreate function Creates a new wallet, with hook-local createPending/createError/createData state. ```ts function useWalletCreate(): { create(req: CreateWalletRequest): Promise; createPending: boolean; createError: Error | null; createData: CreateWalletResult | null; resetCreate(): void; }; ``` | Parameter | Type | Description | | ------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `create(req)` | `(req: CreateWalletRequest) => Promise` | Creates a new wallet, refetches info, and kicks a background refresh. See createWallet on the wavelength-core reference. | Returns`{ create, createPending, createError, createData, resetCreate }` See the mutation convention above. ## useWalletRestore function Restores a wallet from a mnemonic, with hook-local restorePending/restoreError/restoreData state. ```ts function useWalletRestore(): { restore(req: RestoreWalletRequest): Promise; restorePending: boolean; restoreError: Error | null; restoreData: WalletInfo | null; resetRestore(): void; }; ``` | Parameter | Type | Description | | -------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `restore(req)` | `(req: RestoreWalletRequest) => Promise` | Restores a wallet from req.mnemonic. See restoreWallet on the wavelength-core reference. | Returns`{ restore, restorePending, restoreError, restoreData, resetRestore }` See the mutation convention above, with one twist: `restore`’s promise (and therefore `restorePending`/`restoreError`) only covers getting the wallet up; it resolves as soon as the restored wallet is usable, not when the optional server-assisted recovery scan finishes, and it never rejects for a scan failure. Observe the scan, and a restore that fails before the wallet came up, separately through [`useWalletRecovery`](#useWalletRecovery): even a fire-and-forget `restore()` call whose promise is not awaited still surfaces a pre-usability failure there once `phase` falls back to `'needsWallet'`. ## useWalletUnlock function Unlocks an existing wallet, with hook-local unlockPending/unlockError/unlockData state. ```ts function useWalletUnlock(): { unlock(req: UnlockWalletRequest): Promise; unlockPending: boolean; unlockError: Error | null; unlockData: UnlockWalletResult | null; resetUnlock(): void; }; ``` | Parameter | Type | Description | | ------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `unlock(req)` | `(req: UnlockWalletRequest) => Promise` | Unlocks an existing wallet, refetches info, and kicks a background refresh. See unlockWallet on the wavelength-core reference. | Returns`{ unlock, unlockPending, unlockError, unlockData, resetUnlock }` See the mutation convention above. ## useWalletDeposit function Requests an on-chain deposit address, with hook-local depositPending/depositError/depositData state. ```ts function useWalletDeposit(): { deposit(req?: DepositRequest): Promise; depositPending: boolean; depositError: Error | null; depositData: DepositResult | null; resetDeposit(): void; }; ``` | Parameter | Type | Description | | --------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deposit(req?)` | `(req?: DepositRequest) => Promise` | Requests an on-chain deposit address and kicks a background refresh. req is optional and defaults to {} when omitted. See deposit on the wavelength-core reference. | Returns`{ deposit, depositPending, depositError, depositData, resetDeposit }` See the mutation convention above. ## useWalletReceive function Requests a Lightning receive invoice, with hook-local receivePending/receiveError/receiveData state. ```ts function useWalletReceive(): { receive(req: ReceiveRequest): Promise; receivePending: boolean; receiveError: Error | null; receiveData: ReceiveResult | null; resetReceive(): void; }; ``` | Parameter | Type | Description | | -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `receive(req)` | `(req: ReceiveRequest) => Promise` | Requests a Lightning receive invoice and kicks a background refresh. See receive on the wavelength-core reference. | Returns`{ receive, receivePending, receiveError, receiveData, resetReceive }` See the mutation convention above. ## useWalletPrepareSend function Quotes a payment without dispatching it, with hook-local preparePending/prepareError/prepareData state. ```ts function useWalletPrepareSend(): { prepare(req: SendRequest): Promise; preparePending: boolean; prepareError: Error | null; prepareData: PrepareSendResult | null; resetPrepare(): void; }; ``` | Parameter | Type | Description | | -------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `prepare(req)` | `(req: SendRequest) => Promise` | Quotes a payment without dispatching it; no refresh, since a quote moves no money. See prepareSend on the wavelength-core reference. | Returns`{ prepare, preparePending, prepareError, prepareData, resetPrepare }` See the mutation convention above. `prepareData` holds the latest quote for a review screen; pair it with [`useWalletSend`](#useWalletSend)’s `sendPrepared` to dispatch it. ## useWalletSend function Dispatches a payment: `send` is the one-shot path, `sendPrepared` confirms a quote from [`useWalletPrepareSend`](#useWalletPrepareSend). The two verbs are alternative dispatch paths for the same payment and share one sendPending/sendError/sendData slot. ```ts function useWalletSend(): { send(req: SendRequest): Promise; sendPrepared(prepared: PrepareSendResult): Promise; sendPending: boolean; sendError: Error | null; sendData: SendResult | null; resetSend(): void; }; ``` | Parameter | Type | Description | | ------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `send(req)` | `(req: SendRequest) => Promise` | Quotes and dispatches a payment in one call, then kicks a background refresh. See send on the wavelength-core reference. | | `sendPrepared(prepared)` | `(prepared: PrepareSendResult) => Promise` | Dispatches a quote returned by useWalletPrepareSend, then kicks a background refresh. See sendPrepared on the wavelength-core reference. | Returns`{ send, sendPrepared, sendPending, sendError, sendData, resetSend }` See the mutation convention above. ## useWalletRefresh function Re-fetches info, balance, and activity. ```ts function useWalletRefresh(): { refresh(): Promise; refreshPending: boolean; refreshError: Error | null; resetRefresh(): void; }; ``` | Parameter | Type | Description | | ----------- | --------------------- | -------------------------------------------------------------------------------------------------- | | `refresh()` | `() => Promise` | Re-fetches info, balance, and activity concurrently. See refresh on the wavelength-core reference. | Returns`{ refresh, refreshPending, refreshError, resetRefresh }` The one mutation hook with no data field: `refresh()` resolves `void`, so there is nothing to hold. `refreshPending` tracks only this hook instance’s own calls, not the engine’s own background refreshes (the sync poll, the activity-driven settle reconcile, or the refresh kicked automatically after another mutation): those never flip it. Use it as what a pull-to-refresh spinner should show. ## Exiting Ark Seven hooks cover the exit surface. `useWalletExit`, `useWalletExitPlan`, `useWalletSweep`, and [`useWalletList`](#useWalletList) are 1:1 wrappers around one [`WalletEngine`](/reference/wavelength-core/#WalletEngine) verb each, following the same mutation convention as the hooks above. [`useWalletExitBatch`](#useWalletExitBatch) is the orchestrator: it drives a full multi-outpoint exit through the funding-contention guards documented on [`exitBatch`](/reference/wavelength-core/#exitBatch) in the wavelength-core reference, and additionally exposes the batch’s progress events. [`useWalletExitStatus`](#useWalletExitStatus) and [`useWalletExits`](#useWalletExits) are read hooks instead of mutations: they fetch on mount (and on relevant changes) and expose a `refresh*` action rather than a `reset*` one, since there is no pending/error/data trio to clear back to idle, only a cached read to force fresh. ## useWalletExit function Starts a single exit for one outpoint, with hook-local exitPending/exitError/exitData state. A 1:1 wrapper around [`WalletEngine.exit()`](/reference/wavelength-core/#WalletEngine). ```ts function useWalletExit(): { exit(req: ExitRequest): Promise; exitPending: boolean; exitError: Error | null; exitData: ExitResult | null; resetExit(): void; }; ``` | Parameter | Type | Description | | ----------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `exit(req)` | `(req: ExitRequest) => Promise` | Starts a single exit, cooperative or unilateral depending on req. Takes the full ExitRequest union; see exit on the wavelength-core reference. | Returns`{ exit, exitPending, exitError, exitData, resetExit }` See the mutation convention above. ## useWalletExitPlan function Previews unilateral-exit readiness and backing-wallet funding for a set of outpoints, with hook-local planPending/planError/planData state. A 1:1 wrapper around [`WalletEngine.getExitPlan()`](/reference/wavelength-core/#WalletEngine). Pair it with [`useWalletExitBatch`](#useWalletExitBatch) to act on a plan: `exitBatch` previews and re-plans internally, so this hook is for a standalone preview screen rather than a required prerequisite step before calling `exitBatch`. ```ts function useWalletExitPlan(): { plan(req: GetExitPlanRequest): Promise; planPending: boolean; planError: Error | null; planData: GetExitPlanResult | null; resetPlan(): void; }; ``` | Parameter | Type | Description | | ----------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `plan(req)` | `(req: GetExitPlanRequest) => Promise` | Previews funding for the given outpoints without moving funds. See getExitPlan on the wavelength-core reference. | Returns`{ plan, planPending, planError, planData, resetPlan }` See the mutation convention above. ## useWalletSweep function Previews (`broadcast: false`) or broadcasts (`broadcast: true`) a sweep of the backing on-chain wallet, with hook-local sweepPending/sweepError/sweepData state. A 1:1 wrapper around [`WalletEngine.sweepWallet()`](/reference/wavelength-core/#WalletEngine). Call it with `broadcast: false` first to preview the fee and net amount, then again with `broadcast: true` once the user confirms; only the broadcasting call moves funds and kicks a background refresh. ```ts function useWalletSweep(): { sweep(req: SweepWalletRequest): Promise; sweepPending: boolean; sweepError: Error | null; sweepData: SweepWalletResult | null; resetSweep(): void; }; ``` | Parameter | Type | Description | | ------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `sweep(req)` | `(req: SweepWalletRequest) => Promise` | Previews or broadcasts the sweep, depending on req.broadcast. See sweepWallet on the wavelength-core reference. | Returns`{ sweep, sweepPending, sweepError, sweepData, resetSweep }` See the mutation convention above. ## useWalletExitBatch function The orchestrator: starts a batch of exits across multiple outpoints, handling the funding-contention guards internally. Unlike the other mutation hooks, it also exposes `exitBatchEvents`, the batch’s progress events in order for the current or last run, so a UI can render a live per-outpoint timeline instead of waiting for the whole batch to settle. > **exitBatch starts exits and moves money** > > Read the hazard callout on [`exitBatch`](/reference/wavelength-core/#exitBatch) in the wavelength-core reference: this hook’s `exitBatch` action resolves once every exit is **started**, not completed, and a unilateral exit keeps running for hours or days afterward. ```ts function useWalletExitBatch(): { exitBatch(opts: ExitBatchOptions): Promise; exitBatchPending: boolean; exitBatchError: Error | null; exitBatchData: ExitBatchResult | null; exitBatchEvents: ExitBatchEvent[]; resetExitBatch(): void; }; ``` | Parameter | Type | Description | | ----------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | `exitBatch(opts)` | `(opts: ExitBatchOptions) => Promise` | Starts the batch. See ExitBatchOptions on the wavelength-core reference for the cooperative/unilateral discriminated union. | Returns`{ exitBatch, exitBatchPending, exitBatchError, exitBatchData, exitBatchEvents, resetExitBatch }` The mutation convention above, plus exitBatchEvents: the ExitBatchEvent list for the current or last run, reset to empty each time exitBatch() is called or resetExitBatch() runs. ## useWalletExitStatus function Reads one exit’s status. Defaults to the cheap, coarse phase-only call; pass `{ detailed: true }` for recovery-tree progress, the CSV maturity countdown, and a fee breakdown, at the cost of a live round-trip. Fetches on mount and whenever `outpoint` or the options change. ```ts function useWalletExitStatus( outpoint: string, opts?: { detailed?: boolean; pollMs?: number }, ): { status: ExitStatusResult | null; statusPending: boolean; statusError: Error | null; refreshStatus(): Promise; }; ``` | Parameter | Type | Description | | --------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `outpoint` | `string` | The VTXO outpoint whose exit status is read. | | `opts.detailed` | `boolean` | Optional. Requests the detailed fields; leave it false for a coarse, cheaper status. | | `opts.pollMs` | `number` | Optional. Polls at this interval, in milliseconds, while the component stays mounted. Polling is opt-in (omit it for a one-shot fetch); it keeps running with no visibility/focus gating (including in a backgrounded tab) and stops only on unmount, so there is no timer left running once the user navigates away. | Returns`{ status, statusPending, statusError, refreshStatus }` `status` is null before the first load resolves. Unlike the mutation hooks above, there is no reset action: refetch on demand with refreshStatus(), or change outpoint/opts to refetch automatically. ## useWalletExits function Reads the wallet-wide in-progress exit portfolio. Fetches on mount and whenever wallet activity changes, so a completed exit clears from the summary without a manual refresh. ```ts function useWalletExits(): { summary: ExitSummaryResult | null; summaryPending: boolean; summaryError: Error | null; refreshSummary(): Promise; }; ``` Returns`{ summary, summaryPending, summaryError, refreshSummary }` `summary` is null before the first load resolves. Like useWalletExitStatus, there is no reset action; call refreshSummary() to refetch on demand. ## useWalletList function Lists wallet activity, VTXOs, or on-chain outputs on demand, with hook-local listPending/listError/listData state. A 1:1 wrapper around [`WalletEngine.list()`](/reference/wavelength-core/#WalletEngine). Reach for it for an on-demand fetch, such as populating a VTXO picker before an exit; the always-fresh activity feed is already available from [`useWalletActivity()`](#useWalletActivity) without a manual fetch. ```ts function useWalletList(): { list(req: ListRequest): Promise; listPending: boolean; listError: Error | null; listData: ListResult | null; resetList(): void; }; ``` | Parameter | Type | Description | | ----------- | ------------------------------------------- | -------------------------------------------------------------------- | | `list(req)` | `(req: ListRequest) => Promise` | Lists the requested view. See list on the wavelength-core reference. | Returns`{ list, listPending, listError, listData, resetList }` See the mutation convention above. ## Passkeys ## useWalletPasskey function Drives a passkey ceremony and opens the wallet through the engine, refreshing engine state on success so `phase` advances automatically. The ceremony is injected, which keeps `wavelength-react` free of any transport dependency: in the browser, pass [`webPasskeyCeremony`](/reference/wavelength-web/#webPasskeyCeremony) from `wavelength-web`; the React Native transport supplies `createNativePasskeyCeremony` ([wavelength-react-native](/reference/wavelength-react-native/)). Creation and opening track separately (`create*`/`open*` fields below) because apps render them on different screens. Must be called within a `WavelengthProvider` subtree; throws otherwise. ```ts function useWalletPasskey(ceremony: PasskeyCeremony): { supported: boolean | null; create(appName: string): Promise; createPending: boolean; createError: Error | null; resetCreate(): void; open(credentialId?: string): Promise; openPending: boolean; openError: Error | null; resetOpen(): void; }; ``` | Parameter | Type | Description | | ---------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `ceremony` | [`PasskeyCeremony`](/reference/wavelength-core/#PasskeyCeremony) | Platform ceremony implementation. In the browser, pass webPasskeyCeremony from wavelength-web. | | Parameter | Type | Description | | --------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `supported` | `boolean \| null` | Whether the environment supports passkey PRF. Starts null while ceremony.supportsPasskeyPrf() is in flight, then settles to true or false once it resolves; if that probe rejects, supported settles to false rather than throwing. Treat null as still-checking and gate passkey UI on it accordingly, not as a falsy unsupported state. The probe is memoized per ceremony instance, so warming it once at app boot means supported is usually already settled by the time a screen reads it. | | `create(appName)` | `(appName: string) => Promise` | Registers a passkey and creates the wallet from it. Follows the same throw-and-capture convention as the mutation hooks above: it both resolves/rejects and updates createPending/createError/reset via resetCreate. | | `createPending` | `boolean` | True while create() is in flight. | | `createError` | `Error \| null` | The last error from create(), or null. A PasskeyCancelledError is never recorded here. | | `resetCreate()` | `() => void` | Clears createPending/createError back to idle. | | `open(credentialId?)` | `(credentialId?: string) => Promise` | Asserts a passkey (scoped to credentialId when provided, discoverable otherwise) and imports/unlocks the wallet. | | `openPending` | `boolean` | True while open() is in flight. | | `openError` | `Error \| null` | The last error from open(), or null. A PasskeyCancelledError is never recorded here. | | `resetOpen()` | `() => void` | Clears openPending/openError back to idle. | > **A cancelled ceremony still rejects** > > `create()` and `open()` reject with errors when they fail; a `PasskeyCancelledError` (user dismissed the OS prompt) is rethrown but never recorded into `createError`/`openError`. Always `await`/`catch` these calls, or read `createError`/`openError` for a declarative render. ## PasskeyWalletOutcome type Pairs the daemon-side open result with the credential id used in the ceremony, so the app can persist it and scope future unlocks to the same passkey. Returned by both `create` and `open`. ```ts type PasskeyWalletOutcome = { result: OpenWalletFromPasskeyResult; credentialId: string; }; ``` | Parameter | Type | Description | | -------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `result` | [`OpenWalletFromPasskeyResult`](/reference/wavelength-core/#OpenWalletFromPasskeyResult) | The result returned by opening the wallet from the passkey. See OpenWalletFromPasskeyResult on the wavelength-core reference. | | `credentialId` | `string` | The credential id that produced the PRF output, for persistence and scoping future assertions. | ## PasskeyCeremony type The per-platform contract `useWalletPasskey` drives. It is defined in `wavelength-core` but documented here since this package is its primary consumer; the browser implementation, `webPasskeyCeremony`, lives in [`wavelength-web`](/reference/wavelength-web/#webPasskeyCeremony). The React Native transport supplies `createNativePasskeyCeremony` ([wavelength-react-native](/reference/wavelength-react-native/)) as its implementation of the same contract. ```ts type WalletKind = 'passkey' | 'password'; type PasskeyAssertion = { prfOutput: string; credentialId: string; }; type PasskeyCeremony = { supportsPasskeyPrf(): Promise; registerPasskeyWallet(appName: string): Promise; assertPasskeyPrf(allowCredentialId?: string): Promise; }; ``` | Parameter | Type | Description | | -------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `WalletKind` | `'passkey' \| 'password'` | Labels how a local wallet is unlocked. | | `supportsPasskeyPrf()` | `() => Promise` | Resolves true when the platform supports passkey PRF. | | `registerPasskeyWallet(appName)` | `(appName: string) => Promise` | Registers a new passkey and returns its assertion. appName becomes the WebAuthn relying-party name in the web implementation. | | `assertPasskeyPrf(allowCredentialId?)` | `(allowCredentialId?: string) => Promise` | Asserts an existing passkey, optionally scoped to a credential id (discoverable when omitted). | | `PasskeyAssertion.prfOutput` | `string` | The PRF output (hex) shared with the Go SDK. | | `PasskeyAssertion.credentialId` | `string` | The credential id that produced the PRF output. | ## Re-exported from wavelength-core `@lightninglabs/wavelength-react` re-exports the complete `@lightninglabs/wavelength-core` surface. That includes `WavelengthClient`, `WalletEngine`, `createWalletEngine`, `FacadeMethod`, `ActivityStreamOptions`, `RuntimeConfig`, `WalletInfo`, `WalletStatus`, `Balance`, `Entry`, the complete activity/exit/send/list type families, all named nested response types, and all generated string-enum constants. `RuntimePhase`, `WalletState`, `RecoveryState`, `PasskeyCancelledError`, and `toError` are included too. `defaultConfig` comes from the transport packages (`@lightninglabs/wavelength-web` and `@lightninglabs/wavelength-react-native`). The core contract and enum constant families are listed on the [wavelength-core reference](/reference/wavelength-core/). ## See also - [wavelength-core reference](/reference/wavelength-core/) for `WalletEngine`, `WavelengthClient`, `RuntimeConfig`, `WalletInfo`, `Balance`, `Entry`, `RuntimePhase`, and `WalletState`. - [wavelength-web reference](/reference/wavelength-web/) for `createWebWalletEngine()` and `webPasskeyCeremony`, the browser transport and passkey ceremony used with this package. - [wavelength-react-native reference](/reference/wavelength-react-native/) for `createNativeWalletEngine()` and `createNativePasskeyCeremony()`, the React Native transport and passkey ceremony used with this package.