wavelength-react

Context provider that hands a WalletEngine down to descendants. Wrap your application root (or any subtree) with this component so child hooks can access wallet state and operations.

function WavelengthProvider(props: WavelengthProviderProps): JSX.Element

engineWalletEngine

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.

childrenReactNode

The component subtree that can call Wavelength SDK hooks.

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.

type WavelengthProviderProps = {
  children: ReactNode;
  engine: WalletEngine;
};

Returns the 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.

function useWalletEngine(): WalletEngine

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.

function useWallet(): {
  phase: RuntimePhase;
  error: Error | null;
  start(config?: RuntimeConfig): Promise<WalletInfo>;
  stop(): Promise<void>;
};

phaseRuntimePhase

Current runtime/wallet lifecycle phase. See RuntimePhase on the wavelength-core reference; it includes 'restoring' while a background restore is bringing the wallet up.

errorError | 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<WalletInfo>

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<void>

Stops the runtime and clears the in-memory snapshot (info/balance/activity reset to null/null/[]); persisted wallet data is untouched.

The most recent complete wallet info, or null before the runtime reports it.

function useWalletInfo(): WalletInfo | null

The most recent wallet balance, or null before it is known.

function useWalletBalance(): Balance | null

The most recent activity entries, newest-first as returned by the daemon.

function useWalletActivity(): Entry[]

The background recovery status set by useWalletRestore and its acknowledge action.

function useWalletRecovery(): {
  recovery: RecoveryState;
  acknowledge(): void;
};

recoveryRecoveryState

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.

The buffered runtime log tail and a clear action.

function useWalletLogs(): {
  logs: WavelengthLogPayload[];
  clear(): void;
};

logsWavelengthLogPayload[]

Bounded tail (up to 200 entries) of 'log' events from the runtime, newest last.

clear()() => void

Clears the buffered log tail.

Creates a new wallet, with hook-local createPending/createError/createData state.

function useWalletCreate(): {
  create(req: CreateWalletRequest): Promise<CreateWalletResult>;
  createPending: boolean;
  createError: Error | null;
  createData: CreateWalletResult | null;
  resetCreate(): void;
};

create(req)(req: CreateWalletRequest) => Promise<CreateWalletResult>

Creates a new wallet, refetches info, and kicks a background refresh. See createWallet on the wavelength-core reference.

Restores a wallet from a mnemonic, with hook-local restorePending/restoreError/restoreData state.

function useWalletRestore(): {
  restore(req: RestoreWalletRequest): Promise<WalletInfo>;
  restorePending: boolean;
  restoreError: Error | null;
  restoreData: WalletInfo | null;
  resetRestore(): void;
};

restore(req)(req: RestoreWalletRequest) => Promise<WalletInfo>

Restores a wallet from req.mnemonic. See restoreWallet on the wavelength-core reference.

Unlocks an existing wallet, with hook-local unlockPending/unlockError/unlockData state.

function useWalletUnlock(): {
  unlock(req: UnlockWalletRequest): Promise<UnlockWalletResult>;
  unlockPending: boolean;
  unlockError: Error | null;
  unlockData: UnlockWalletResult | null;
  resetUnlock(): void;
};

unlock(req)(req: UnlockWalletRequest) => Promise<UnlockWalletResult>

Unlocks an existing wallet, refetches info, and kicks a background refresh. See unlockWallet on the wavelength-core reference.

Requests an on-chain deposit address, with hook-local depositPending/depositError/depositData state.

function useWalletDeposit(): {
  deposit(req?: DepositRequest): Promise<DepositResult>;
  depositPending: boolean;
  depositError: Error | null;
  depositData: DepositResult | null;
  resetDeposit(): void;
};

deposit(req?)(req?: DepositRequest) => Promise<DepositResult>

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.

Requests a Lightning receive invoice, with hook-local receivePending/receiveError/receiveData state.

function useWalletReceive(): {
  receive(req: ReceiveRequest): Promise<ReceiveResult>;
  receivePending: boolean;
  receiveError: Error | null;
  receiveData: ReceiveResult | null;
  resetReceive(): void;
};

receive(req)(req: ReceiveRequest) => Promise<ReceiveResult>

Requests a Lightning receive invoice and kicks a background refresh. See receive on the wavelength-core reference.

Quotes a payment without dispatching it, with hook-local preparePending/prepareError/prepareData state.

function useWalletPrepareSend(): {
  prepare(req: SendRequest): Promise<PrepareSendResult>;
  preparePending: boolean;
  prepareError: Error | null;
  prepareData: PrepareSendResult | null;
  resetPrepare(): void;
};

prepare(req)(req: SendRequest) => Promise<PrepareSendResult>

Quotes a payment without dispatching it; no refresh, since a quote moves no money. See prepareSend on the wavelength-core reference.

Dispatches a payment: send is the one-shot path, sendPrepared confirms a quote from useWalletPrepareSend. The two verbs are alternative dispatch paths for the same payment and share one sendPending/sendError/sendData slot.

function useWalletSend(): {
  send(req: SendRequest): Promise<SendResult>;
  sendPrepared(prepared: PrepareSendResult): Promise<SendResult>;
  sendPending: boolean;
  sendError: Error | null;
  sendData: SendResult | null;
  resetSend(): void;
};

send(req)(req: SendRequest) => Promise<SendResult>

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<SendResult>

Dispatches a quote returned by useWalletPrepareSend, then kicks a background refresh. See sendPrepared on the wavelength-core reference.

Re-fetches info, balance, and activity.

function useWalletRefresh(): {
  refresh(): Promise<void>;
  refreshPending: boolean;
  refreshError: Error | null;
  resetRefresh(): void;
};

refresh()() => Promise<void>

Re-fetches info, balance, and activity concurrently. See refresh on the wavelength-core reference.

Starts a single exit for one outpoint, with hook-local exitPending/exitError/exitData state. A 1:1 wrapper around WalletEngine.exit().

function useWalletExit(): {
  exit(req: ExitRequest): Promise<ExitResult>;
  exitPending: boolean;
  exitError: Error | null;
  exitData: ExitResult | null;
  resetExit(): void;
};

exit(req)(req: ExitRequest) => Promise<ExitResult>

Starts a single exit, cooperative or unilateral depending on req. Takes the full ExitRequest union; see exit on the wavelength-core reference.

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(). Pair it with 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.

function useWalletExitPlan(): {
  plan(req: GetExitPlanRequest): Promise<GetExitPlanResult>;
  planPending: boolean;
  planError: Error | null;
  planData: GetExitPlanResult | null;
  resetPlan(): void;
};

plan(req)(req: GetExitPlanRequest) => Promise<GetExitPlanResult>

Previews funding for the given outpoints without moving funds. See getExitPlan on the wavelength-core reference.

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(). 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.

function useWalletSweep(): {
  sweep(req: SweepWalletRequest): Promise<SweepWalletResult>;
  sweepPending: boolean;
  sweepError: Error | null;
  sweepData: SweepWalletResult | null;
  resetSweep(): void;
};

sweep(req)(req: SweepWalletRequest) => Promise<SweepWalletResult>

Previews or broadcasts the sweep, depending on req.broadcast. See sweepWallet on the wavelength-core reference.

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.

function useWalletExitBatch(): {
  exitBatch(opts: ExitBatchOptions): Promise<ExitBatchResult>;
  exitBatchPending: boolean;
  exitBatchError: Error | null;
  exitBatchData: ExitBatchResult | null;
  exitBatchEvents: ExitBatchEvent[];
  resetExitBatch(): void;
};

exitBatch(opts)(opts: ExitBatchOptions) => Promise<ExitBatchResult>

Starts the batch. See ExitBatchOptions on the wavelength-core reference for the cooperative/unilateral discriminated union.

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.

function useWalletExitStatus(
  outpoint: string,
  opts?: { detailed?: boolean; pollMs?: number },
): {
  status: ExitStatusResult | null;
  statusPending: boolean;
  statusError: Error | null;
  refreshStatus(): Promise<ExitStatusResult>;
};

outpointstring

The VTXO outpoint whose exit status is read.

opts.detailedboolean

Optional. Requests the detailed fields; leave it false for a coarse, cheaper status.

opts.pollMsnumber

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.

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.

function useWalletExits(): {
  summary: ExitSummaryResult | null;
  summaryPending: boolean;
  summaryError: Error | null;
  refreshSummary(): Promise<ExitSummaryResult>;
};

Lists wallet activity, VTXOs, or on-chain outputs on demand, with hook-local listPending/listError/listData state. A 1:1 wrapper around WalletEngine.list(). 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() without a manual fetch.

function useWalletList(): {
  list(req: ListRequest): Promise<ListResult>;
  listPending: boolean;
  listError: Error | null;
  listData: ListResult | null;
  resetList(): void;
};

list(req)(req: ListRequest) => Promise<ListResult>

Lists the requested view. See list on the wavelength-core reference.

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 from wavelength-web; the React Native transport supplies createNativePasskeyCeremony (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.

function useWalletPasskey(ceremony: PasskeyCeremony): {
  supported: boolean | null;
  create(appName: string): Promise<PasskeyWalletOutcome>;
  createPending: boolean;
  createError: Error | null;
  resetCreate(): void;
  open(credentialId?: string): Promise<PasskeyWalletOutcome>;
  openPending: boolean;
  openError: Error | null;
  resetOpen(): void;
};

ceremonyPasskeyCeremony

Platform ceremony implementation. In the browser, pass webPasskeyCeremony from wavelength-web.

supportedboolean | 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<PasskeyWalletOutcome>

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.

createPendingboolean

True while create() is in flight.

createErrorError | 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<PasskeyWalletOutcome>

Asserts a passkey (scoped to credentialId when provided, discoverable otherwise) and imports/unlocks the wallet.

openPendingboolean

True while open() is in flight.

openErrorError | null

The last error from open(), or null. A PasskeyCancelledError is never recorded here.

resetOpen()() => void

Clears openPending/openError back to idle.

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.

type PasskeyWalletOutcome = {
  result: OpenWalletFromPasskeyResult;
  credentialId: string;
};

resultOpenWalletFromPasskeyResult

The result returned by opening the wallet from the passkey. See OpenWalletFromPasskeyResult on the wavelength-core reference.

credentialIdstring

The credential id that produced the PRF output, for persistence and scoping future assertions.

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. The React Native transport supplies createNativePasskeyCeremony (wavelength-react-native) as its implementation of the same contract.

type WalletKind = 'passkey' | 'password';

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

type PasskeyCeremony = {
  supportsPasskeyPrf(): Promise<boolean>;
  registerPasskeyWallet(appName: string): Promise<PasskeyAssertion>;
  assertPasskeyPrf(allowCredentialId?: string): Promise<PasskeyAssertion>;
};

WalletKind'passkey' | 'password'

Labels how a local wallet is unlocked.

supportsPasskeyPrf()() => Promise<boolean>

Resolves true when the platform supports passkey PRF.

registerPasskeyWallet(appName)(appName: string) => Promise<PasskeyAssertion>

Registers a new passkey and returns its assertion. appName becomes the WebAuthn relying-party name in the web implementation.

assertPasskeyPrf(allowCredentialId?)(allowCredentialId?: string) => Promise<PasskeyAssertion>

Asserts an existing passkey, optionally scoped to a credential id (discoverable when omitted).

PasskeyAssertion.prfOutputstring

The PRF output (hex) shared with the Go SDK.

PasskeyAssertion.credentialIdstring

The credential id that produced the PRF output.