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

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>;
};

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;
};

The buffered runtime log tail and a clear action.

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

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;
};

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;
};

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;
};

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;
};

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;
};

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;
};

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;
};

Re-fetches info, balance, and activity.

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

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;
};

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;
};

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;
};

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;
};

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>;
};

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;
};

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;
};

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;
};

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>;
};