wavelength-core

Returns the canonical public endpoint preset for a network in one transport’s flavor: REST gateway URLs for 'rest' (the web transport), host:port gRPC addresses for 'grpc' (native transports). This is the building block the transport packages’ defaultConfig helpers compose over; app code normally calls wavelength-web’s or wavelength-react-native’s defaultConfig instead.

Only the preset networks are accepted. mainnet and regtest have no preset: a RuntimeConfig for either is built by hand.

function networkDefaults(
  network: PresetNetwork,
  transport: ServerTransport,
): Partial<RuntimeConfig>

networkPresetNetwork

The Bitcoin network to look up; mainnet and regtest are excluded because they have no preset.

transportServerTransport

The endpoint flavor the caller's transport dials: 'rest' or 'grpc'.

The standard daemon log verbosity levels, from most to least verbose. Exported for UIs that render a level picker; debugLevel itself stays a plain string because the daemon also accepts a per-subsystem list such as 'ROND=debug,info'.

const DEBUG_LEVELS = [
  'trace', 'debug', 'info', 'warn', 'error', 'critical', 'off',
] as const;

type DebugLevel = (typeof DEBUG_LEVELS)[number];

Configuration passed to WavelengthClient.start(). For the common case, start from your transport package’s defaultConfig(network) and override only the fields you need.

type RuntimeConfig = {
  network?: Network;
  allowMainnet?: boolean;
  dataDir?: string;
  debugLevel?: string;
  arkServerAddress?: string;
  arkServerTlsCertPath?: string;
  arkServerInsecure?: boolean;
  walletType?: 'lwwallet' | 'btcwallet';
  walletEsploraUrl?: string;
  walletPasswordFile?: string;
  walletPollIntervalSeconds?: number;
  walletRecoveryWindow?: number;
  walletFeeUrl?: string;
  walletBlockHeadersSource?: string;
  walletFilterHeadersSource?: string;
  swapServerAddress?: string;
  swapServerTlsCertPath?: string;
  swapServerInsecure?: boolean;
  swapDatabaseFileName?: string;
  disableSwaps?: boolean;
  maxOperatorFeeSat?: number;
  signingWorkers?: number;
  bufferSize?: number;
};

The fields stay flat even when they apply to one embedded backend. For example, this btcwallet configuration uses only top-level RuntimeConfig fields:

const config: RuntimeConfig = {
  network: 'signet',
  walletType: 'btcwallet',
  walletFeeUrl: 'https://fees.example.com',
  walletBlockHeadersSource: 'neutrino',
  walletFilterHeadersSource: 'neutrino',
  walletRecoveryWindow: 250,
  maxOperatorFeeSat: 100,
  signingWorkers: 4,
  bufferSize: 64,
};

networkNetwork

The Bitcoin network to run against. Use mainnet only together with allowMainnet.

allowMainnetboolean

Must be true to run on mainnet. The SDK rejects a mainnet config without it before startup.

dataDirstring

Storage root for daemon and wallet state (an OPFS path in the browser). A daemon default is used when unset.

debugLevelstring

Daemon log verbosity. Accepts a standard DebugLevel or a per-subsystem expression such as 'ROND=debug,info'. Distinct from the web client's RPC-payload debug option.

arkServerAddressstring

Ark operator and mailbox endpoint. Use a REST URL on web and a host:port gRPC address on React Native.

arkServerTlsCertPathstring

Optional filesystem TLS certificate path for native transports. The web transport rejects it.

arkServerInsecureboolean

Disables TLS for the Ark endpoint. Use only for local development.

walletType'lwwallet' | 'btcwallet'

Embedded wallet backend. Default: lwwallet.

walletEsploraUrlstring

HTTP Esplora endpoint for lwwallet only, on both platforms.

walletPasswordFilestring

Password file for lwwallet only.

walletPollIntervalSecondsnumber

Chain polling interval for lwwallet only. Must be a nonnegative safe integer.

walletRecoveryWindownumber

Wallet address look-ahead window for either supported embedded backend. Must fit in uint32.

walletFeeUrlstring

Fee estimator endpoint for btcwallet only.

walletBlockHeadersSourcestring

Block-header source for btcwallet only.

walletFilterHeadersSourcestring

Compact-filter-header source for btcwallet only.

swapServerAddressstring

Swap endpoint. Use a REST URL on web and a host:port gRPC address on React Native.

swapServerTlsCertPathstring

Optional filesystem TLS certificate path for native transports. The web transport rejects it unless swaps are disabled.

swapServerInsecureboolean

Disables TLS for the swap endpoint. Use only for local development.

swapDatabaseFileNamestring

Daemon-owned SQLite file for swap state.

disableSwapsboolean

Disables Lightning swaps and suppresses preset and override swap fields.

maxOperatorFeeSatnumber

Maximum operator fee in satoshis. Must be a nonnegative safe integer.

signingWorkersnumber

Signing worker count. Must be a nonnegative safe integer.

bufferSizenumber

Runtime buffer size. Must be a nonnegative safe integer.

The SDK validates RuntimeConfig before it starts the daemon. It rejects backend-only fields used with the wrong walletType, invalid numeric values, mainnet without allowMainnet: true, and arkServerTlsCertPath on web. Web accepts swapServerTlsCertPath only when disableSwaps: true, which suppresses every swap field. lwwallet fields are walletEsploraUrl, walletPasswordFile, and walletPollIntervalSeconds. btcwallet fields are walletFeeUrl, walletBlockHeadersSource, and walletFilterHeadersSource.

Some daemon-only options (such as the LND wallet backend) are deliberately not exposed through RuntimeConfig. Most apps should use defaultConfig() from their transport package and override only the fields they need.

Selects the Bitcoin network the embedded daemon runs against. PresetNetwork narrows the union to the networks that carry a public endpoint preset (the domain of networkDefaults and the transports’ defaultConfig). mainnet and regtest are excluded: mainnet has no public deployment yet, and regtest’s local ports vary per development environment. testnet4 is part of the union and carries a preset, but its deployment is not supported yet, so its endpoints are not listed below.

type Network = 'mainnet' | 'testnet' | 'testnet4' | 'signet' | 'regtest';

The transport packages’ defaultConfig() helpers draw from one canonical endpoint table per network, so the common case needs no URLs looked up. Toggle between the REST gateway URLs (web transport) and the gRPC host:port addresses (React Native transport):

The wire protocol used by a transport to connect to the Ark and swap servers. Browser transports use rest; native transports use grpc.

type ServerTransport = 'rest' | 'grpc';

The flat configuration shape passed to the embedded mobile facade. Application code normally supplies RuntimeConfig instead. This internal shape is shown for transport debugging and is not exported from the core package.

type MobileConfig = {
  data_dir?: string;
  network?: string;
  allow_mainnet?: boolean;
  debug_level?: string;
  wallet_type?: 'lwwallet' | 'btcwallet';
  wallet_esplora_url?: string;
  wallet_password_file?: string;
  wallet_poll_interval_seconds?: number;
  wallet_recovery_window?: number;
  wallet_fee_url?: string;
  wallet_block_headers_source?: string;
  wallet_filter_headers_source?: string;
  server_address?: string;
  server_tls_cert_path?: string;
  server_transport?: ServerTransport;
  server_insecure?: boolean;
  swap_server_address?: string;
  swap_server_tls_cert_path?: string;
  swap_server_transport?: ServerTransport;
  swap_server_insecure?: boolean;
  swap_database_file_name?: string;
  max_operator_fee_sat?: number;
  signing_workers?: number;
  buffer_size?: number;
};

The daemon’s start verb accepts this lower-level shape; the SDK builds it from your RuntimeConfig when you call client.start(config). The lifecycle verbs are not reachable through callFacade, which rejects 'start' and 'stop' so the cross-tab runtime lock is never bypassed.

The typed RPC surface every transport implements. Create a client with createWebClient() from wavelength-web or createNativeClient() from wavelength-react-native, call start(config), then use the wallet methods documented in the sections below.

interface WavelengthClient {
  ready(): Promise<void>;
  start(config: RuntimeConfig): Promise<WalletInfo>;
  stop(): Promise<void>;
  getInfo(): Promise<WalletInfo>;
  status(): Promise<WalletStatus>;
  balance(): Promise<Balance>;
  createWallet(req: CreateWalletRequest): Promise<CreateWalletResult>;
  unlockWallet(req: UnlockWalletRequest): Promise<UnlockWalletResult>;
  openWalletFromPasskey(
    req: OpenWalletFromPasskeyRequest,
  ): Promise<OpenWalletFromPasskeyResult>;
  deposit(req?: DepositRequest): Promise<DepositResult>;
  receive(req: ReceiveRequest): Promise<ReceiveResult>;
  prepareSend(req: SendRequest): Promise<PrepareSendResult>;
  sendPrepared(prepared: PrepareSendResult): Promise<SendResult>;
  send(req: SendRequest): Promise<SendResult>;
  list(req?: ListRequest): Promise<ListResult>;
  exit(req: ExitRequest): Promise<ExitResult>;
  exitStatus(req: ExitStatusRequest): Promise<ExitStatusResult>;
  exitSummary(req?: ExitSummaryRequest): Promise<ExitSummaryResult>;
  getExitPlan(req: GetExitPlanRequest): Promise<GetExitPlanResult>;
  sweepWallet(req: SweepWalletRequest): Promise<SweepWalletResult>;
  callFacade<T = unknown>(method: FacadeMethod, params?: unknown): Promise<T>;
  isRunning(): Promise<boolean>;
  subscribe(listener: WavelengthListener): () => void;
  startActivity(opts?: ActivityStreamOptions): Promise<void>;
  stopActivity(): void;
  dispose(): void;
}

Call order. A client’s methods are only meaningful in this order: await ready() once, then start(config) once, then any of the wallet operations (any number of times, in any order appropriate to your app), then stop() when you are done running the daemon, then dispose() to release the client’s own resources. isRunning() is the exception: it can be called before startup or after shutdown to inspect the daemon process state. dispose() is terminal: build a new client to start again.

Resolves once the runtime assets (the wasm daemon and its supporting files) are loaded and the client is otherwise usable. Always await this before start().

ready(): Promise<void>

Starts the embedded daemon with the given config and resolves with its initial WalletInfo. Calling start() while a session is already running coalesces onto it and resolves with the current info; the passed config is ignored, so call stop() first to start under a different one.

start(config: RuntimeConfig): Promise<WalletInfo>

configRuntimeConfig

The runtime configuration to start the daemon with. Build it with your transport package's defaultConfig(network) plus any overrides.

Stops the embedded daemon. The client instance itself remains usable afterward: call start() again to restart the daemon without constructing a new client. Use dispose() instead when you are done with the client entirely, since it also releases the client’s own resources (subscriptions, the activity stream, and, for the worker transport, the underlying Worker).

stop(): Promise<void>

Releases the client’s resources and unsubscribes all listeners: it closes the activity stream opened by startActivity() and, for the worker transport, terminates the underlying Worker. The client is unusable afterward; construct a new one to start again.

dispose(): void

Creates a WalletEngine over any transport client.

function createWalletEngine(options: WalletEngineOptions): WalletEngine

optionsWalletEngineOptions

The client to drive, plus optional default config and autoStart.

WalletEngineOptions

A discriminated union: the types require a config when autoStart is enabled, so autoStart: true without config is a compile error.

type WalletEngineOptions =
  { onPerformance?: WavelengthPerformanceListener } & (
    | { client: WavelengthClient; config: RuntimeConfig; autoStart: true }
    | { client: WavelengthClient; config?: RuntimeConfig; autoStart?: false }
  );

clientWavelengthClient

The transport client the engine drives.

configRuntimeConfig

Required when autoStart is true. Default runtime config used by autoStart and by start() when called with no argument.

autoStarttrue | false

Optional. Start the runtime automatically once it is ready. Setting it to true requires config; start() still throws if later called with no argument and no config.

onPerformanceWavelengthPerformanceListener

Optional. Receives structured timing samples for runtime readiness, wallet create/open RPCs, post-operation info adoption, and sync polling. Instrumentation stays off unless this is supplied: with it omitted no timing is measured and no samples are delivered. A listener that throws cannot break wallet work. Default: unset (disabled).

DistributiveOmit

An advanced utility type used to omit a property from each member of a discriminated union independently. It is exported for transport and binding implementers; application code rarely needs it directly.

type DistributiveOmit<T, K extends PropertyKey> =
  T extends unknown ? Omit<T, K> : never;

The engine interface. Every method mirrors the matching WavelengthClient method plus engine bookkeeping: refetching info, kicking a background refresh, or advancing the phase machine.

interface WalletEngine {
  readonly client: WavelengthClient;
  getSnapshot(): WalletSnapshot;
  subscribe(listener: () => void): () => void;
  start(config?: RuntimeConfig): Promise<WalletInfo>;
  stop(): Promise<void>;
  refresh(): Promise<void>;
  createWallet(req: CreateWalletRequest): Promise<CreateWalletResult>;
  restoreWallet(req: RestoreWalletRequest): Promise<WalletInfo>;
  acknowledgeRecovery(): void;
  unlockWallet(req: UnlockWalletRequest): Promise<UnlockWalletResult>;
  openWalletFromPasskey(
    req: OpenWalletFromPasskeyRequest,
  ): Promise<OpenWalletFromPasskeyResult>;
  deposit(req?: DepositRequest): Promise<DepositResult>;
  receive(req: ReceiveRequest): Promise<ReceiveResult>;
  prepareSend(req: SendRequest): Promise<PrepareSendResult>;
  sendPrepared(prepared: PrepareSendResult): Promise<SendResult>;
  send(req: SendRequest): Promise<SendResult>;
  exit(req: ExitRequest): Promise<ExitResult>;
  exitStatus(req: ExitStatusRequest): Promise<ExitStatusResult>;
  exitSummary(req?: ExitSummaryRequest): Promise<ExitSummaryResult>;
  getExitPlan(req: GetExitPlanRequest): Promise<GetExitPlanResult>;
  sweepWallet(req: SweepWalletRequest): Promise<SweepWalletResult>;
  exitBatch(opts: ExitBatchOptions & {
    signal?: AbortSignal;
    onEvent?: (event: ExitBatchEvent) => void;
  }): Promise<ExitBatchResult>;
  list(req: ListRequest): Promise<ListResult>;
  clearLogs(): void;
  dispose(): void;
}

clientWavelengthClient

The underlying transport client, as an escape hatch.

getSnapshot()() => WalletSnapshot

The current immutable state snapshot; see WalletSnapshot below.

subscribe(listener)(listener: () => void) => () => void

Subscribes to snapshot changes; returns the unsubscribe function. Framework bindings call this via useSyncExternalStore.

start(config?)(config?: RuntimeConfig) => Promise<WalletInfo>

Starts the runtime. Falls back to the engine's configured config when called without an argument; throws if neither exists. On success it dispatches the info and best-effort calls refresh() (a locked or empty wallet can fail balance/list until bootstrap; that failure is swallowed); a failure moves phase to 'error' and rejects. Either way, a stop() the host issued while the start was in flight takes precedence: that stop governs the phase and the start leaves the snapshot to it (no info dispatch and no refresh on success, no error surfaced on failure), though the promise still resolves with the info or rejects as usual.

stop()() => Promise<void>

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

refresh()() => Promise<void>

Re-fetches info, balance, and activity concurrently.

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

Creates a new wallet, refetches info, and kicks a background refresh.

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

Restores a wallet from req.mnemonic. Resolves as soon as the restored wallet is usable; the optional server-assisted recovery scan (req.recoverState) continues in the background, observed through snapshot.recovery. Rejects only when the restore fails before the wallet came up; if the scan itself fails after the wallet is usable, the promise still resolves and the failure surfaces as recovery.status === 'failed' instead. See RestoreWalletRequest below.

acknowledgeRecovery()() => void

Resets snapshot.recovery to { status: 'idle' } (e.g. after dismissing a banner).

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

Unlocks an existing wallet, refetches info, and kicks a background refresh.

openWalletFromPasskey(req)(req: OpenWalletFromPasskeyRequest) => Promise<OpenWalletFromPasskeyResult>

Opens the wallet from a passkey PRF output, refetches info, and kicks a background refresh.

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

Requests an on-chain deposit address and kicks a background refresh.

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

Requests a Lightning receive and kicks a background refresh.

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

Quotes a payment without dispatching it. No refresh: a quote moves no money.

sendPrepared(prepared)(prepared: PrepareSendResult) => Promise<SendResult>

Dispatches a payment quoted by prepareSend and kicks a background refresh.

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

Sends a payment and kicks a background refresh.

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

Starts a single exit (cooperative or unilateral) for one outpoint and kicks a background refresh. See exit below.

exitStatus(req)(req: ExitStatusRequest) => Promise<ExitStatusResult>

Queries the status of an exit job. Read-only: it moves no money, so it does not refresh. See exitStatus below.

exitSummary(req?)(req?: ExitSummaryRequest) => Promise<ExitSummaryResult>

Summarizes all in-progress exits. Read-only; does not refresh. See exitSummary below.

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

Previews unilateral-exit readiness and funding without moving funds. Read-only; does not refresh. See getExitPlan below.

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

Previews (req.broadcast: false) or broadcasts (req.broadcast: true) a sweep of the backing on-chain wallet. Refreshes only when broadcasting, since a preview moves no money. See sweepWallet below.

exitBatch(opts)(opts: ExitBatchOptions & { signal?, onEvent? }) => Promise<ExitBatchResult>

Starts a batch of exits, kicking a background refresh after each one starts. Resolves once every exit is started, not completed. Takes the same opts as the standalone exitBatch() below, minus client, since the engine already owns one. See exitBatch below.

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

Lists wallet activity, VTXOs, or on-chain outputs. Read-only; does not refresh. See list below.

clearLogs()() => void

Clears the buffered log tail.

dispose()() => void

Tears down subscriptions, polls, and streams. The engine is done after this; build a new one to start again.

Background processes

The engine runs these automatically, keyed off phase, so hosts never reimplement them.

Activity-stream auto-refreshphase: 'ready'

Opens the transport's activity stream and, on each event, runs a bounded settle-reconcile: an immediate refresh() followed by up to three re-reads (at 750ms, 1500ms, and 3000ms) that stop early once the balance has moved off its pre-event baseline and held steady across two reads. This covers the daemon reporting an entry settled a beat before balance() reflects the new funds.

Activity-stream recoveryon activityStream

A terminal activityStream event triggers a list() reconciliation, then the engine retries from the last safe numeric activity cursor with bounded exponential backoff. The cursor resets when the runtime stops or restarts. Replayed events trigger the same idempotent snapshot refresh instead of being appended directly, so the snapshot becomes consistent again after a disconnect. The transports do not expose structured gap cursor or reason details.

Sync auto-pollphase: 'syncing'

Calls refresh() every 2000ms until the phase leaves 'syncing'. After 5 consecutive failures it stops polling and escalates to phase 'error' rather than polling forever.

Restore readiness pollphase: 'restoring'

Runs while any restoreWallet() is in flight, polling getInfo() every 1500ms until the wallet reports ready, then settles the restoreWallet() promise and kicks a refresh. When the request sets recoverState: true, the recovery scan is tracked separately through snapshot.recovery.

Background-refresh failure budgetall of the above

Any refresh kicked after a mutation (create, unlock, restore, deposit, receive, send) or by a poll above shares one consecutive-failure counter. At 5 consecutive failures the engine sets snapshot.error and escalates phase to 'error', so a dead daemon cannot hide behind a healthy-looking ready wallet.

Unsolicited stopped transitionon runtimeStopped

A runtimeStopped client event, whether from a clean stop() or a worker crash surfaced by the transport, moves phase to 'stopped' (unless the engine is already in 'error', which is preserved so a failure that caused the stop still surfaces) and wipes info, balance, and activity to null, null, and [] regardless, even if the host never called stop() itself.

The engine’s immutable state snapshot, returned by getSnapshot() and delivered to subscribe() listeners. A new object per change; refresh fetches that changed nothing keep the previous field references, so consumers can cheaply compare slices with Object.is.

type WalletSnapshot = {
phase: RuntimePhase;
error: Error | null;
info: WalletInfo | null;
balance: Balance | null;
activity: Entry[];
recovery: RecoveryState;
logs: WavelengthLogPayload[];
};

phaseRuntimePhase

The current runtime/wallet lifecycle phase.

errorError | null

The last fatal runtime-level error, or null.

infoWalletInfo | null

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

balanceBalance | null

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

activityEntry[]

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

recoveryRecoveryState

The background recovery status set by restoreWallet(); see RecoveryState below.

logsWavelengthLogPayload[]

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

The state of a background wallet recovery started by restoreWallet(), a discriminated union keyed on status.

type RecoveryState =
| { status: 'idle' }
| { status: 'restoring' }
| { status: 'done'; result: CreateWalletResult }
| { status: 'failed'; error: Error; walletUsable: boolean };

{ status: 'idle' }variant

No tracked restore in flight, and none has run since the last acknowledgeRecovery() (or ever).

{ status: 'restoring' }variant

While the daemon's server-assisted scan runs. The wallet is already usable at this point; restoreWallet()'s promise has typically already resolved.

{ status: 'done', result }variant

Once the scan completes successfully. result carries the same CreateWalletResult recovery counters (recoveredVTXOs, recoveredBoardingUTXOs, and so on) documented under CreateWalletResult above.

{ status: 'failed', error, walletUsable }variant

walletUsable is true when the background scan errored on an already-usable wallet (its state may just be incomplete), and false when the restore itself failed before the wallet came up at all. This also covers an untracked restore (a restoreWallet() call whose promise was not awaited, or whose caller unmounted): the failure still lands here, surviving the unmount.

Read it to drive a “restoring your balance and history” banner while the wallet is already usable (walletUsable: true), or a restore-failed message on the onboarding screen when the restore never got that far (walletUsable: false), and call acknowledgeRecovery() to dismiss it back to 'idle'.

Parameters for WalletEngine.restoreWallet(): everything CreateWalletRequest accepts, with mnemonic promoted from optional to required, since a restore is meaningless without one.

type RestoreWalletRequest = CreateWalletRequest & {
  mnemonic: string[];
};

mnemonicstring[]

The recovery phrase to restore from. Required (unlike CreateWalletRequest.mnemonic, which is optional).

passwordstring

The plain password the client base64-encodes into the daemon's byte field.

seedPassphrasestring

Optional. A BIP-39 passphrase applied on top of the mnemonic.

recoverStateboolean

Optional. Opt into server-assisted recovery, tracked through snapshot.recovery. Set this for a restore so funds and activity come back; see CreateWalletRequest.recoverState above for the full description. Defaults to false.

recoveryWindownumber

Optional. The per-key-family address look-ahead used during recovery. Only meaningful when recoverState is true.

Creates a new wallet from the given request: generates (or imports) a mnemonic, enciphers it with password, and returns the seed words for backup display.

createWallet(req: CreateWalletRequest): Promise<CreateWalletResult>

reqCreateWalletRequest

Parameters for creating (or importing) the wallet.

CreateWalletRequest

type CreateWalletRequest = {
  password: string;
  mnemonic?: string[];
  seedPassphrase?: string;
  recoverState?: boolean;
  recoveryWindow?: number;
};

passwordstring

The plain password the client base64-encodes into the daemon's byte field.

mnemonicstring[]

Optional. An existing mnemonic to restore from; a fresh one is generated when omitted.

seedPassphrasestring

Optional. A BIP-39 passphrase applied on top of the mnemonic.

recoverStateboolean

Optional. Opt into server-assisted recovery: rebuild wallet state (boarding UTXOs, VTXOs, receive history) from the seed by querying the operator's indexer. Set it when restoring from a mnemonic so funds and activity come back. Defaults to false.

recoveryWindownumber

Optional. The per-key-family address look-ahead used during recovery. Only meaningful when recoverState is true; omit to let the daemon resolve its own default.

CreateWalletResult

type CreateWalletResult = {
  mnemonic: string[];
  encipheredSeed: string;
  identityPubKey: string;
  recoveryRan: boolean;
  recoveredBoardingAddresses: number;
  recoveredBoardingUTXOs: number;
  recoveredVTXOs: number;
  recoveredOORReceiveScripts: number;
  recoveredOORRecipientEvents: number;
};

mnemonicstring[]

The seed words. Display this to the user for backup; it is not recoverable from the daemon afterward.

encipheredSeedstring

The password-enciphered seed, as stored by the daemon.

identityPubKeystring

The wallet's identity public key.

recoveryRanboolean

True when mnemonic was supplied and the daemon ran chain recovery to rediscover funds.

recoveredBoardingAddressesnumber

Count of boarding addresses recovered. Only meaningful when recoveryRan is true.

recoveredBoardingUTXOsnumber

Count of boarding UTXOs recovered.

recoveredVTXOsnumber

Count of VTXOs recovered.

recoveredOORReceiveScriptsnumber

Count of out-of-round receive scripts recovered.

recoveredOORRecipientEventsnumber

Count of out-of-round recipient events recovered.

Unlocks an existing wallet with the given password.

unlockWallet(req: UnlockWalletRequest): Promise<UnlockWalletResult>

reqUnlockWalletRequest

The password to unlock with.

UnlockWalletRequest

type UnlockWalletRequest = {
  password: string;
};

passwordstring

The plain password the client base64-encodes into the daemon's byte field.

UnlockWalletResult

type UnlockWalletResult = {
  identityPubKey: string;
};

identityPubKeystring

The wallet's identity public key.

Opens a wallet from a passkey assertion: derives a wallet from the PRF output of a PasskeyCeremony ceremony, creating one on first use per device or unlocking the existing one thereafter.

openWalletFromPasskey(
  req: OpenWalletFromPasskeyRequest,
): Promise<OpenWalletFromPasskeyResult>

reqOpenWalletFromPasskeyRequest

The passkey PRF output to derive the wallet from.

OpenWalletFromPasskeyRequest

type OpenWalletFromPasskeyRequest = {
  prfOutput: string;
};

prfOutputstring

The PRF output (hex) derived from the passkey ceremony. See PasskeyAssertion.

OpenWalletFromPasskeyResult

type OpenWalletFromPasskeyResult = {
  imported: boolean;
  mnemonic: string[];
  identityPubKey: string;
};

importedboolean

true when a new local wallet was created from the derived seed (a fresh device that has never seen this passkey); false when an existing local wallet was unlocked.

mnemonicstring[]

The seed words. Populated only when imported is true, for backup display.

identityPubKeystring

The wallet's identity public key.

Returns the current normalized wallet info.

getInfo(): Promise<WalletInfo>

Returns the daemon’s runtime status snapshot.

status(): Promise<WalletStatus>

Returns the current wallet balance.

balance(): Promise<Balance>

Reports whether the embedded daemon is running. This does not report wallet readiness; use getInfo() when you need walletReady.

isRunning(): Promise<boolean>

Wallet and daemon info returned by getInfo() and start().

type WalletInfo = {
  version: string;
  commit: string;
  network: string;
  blockHeight: number;
  serverConnected: boolean;
  walletType: string;
  identityPubKey: string;
  walletState: WalletState;
  walletReady: boolean;
  serverInfo?: ServerInfo;
};

versionstring

The daemon version string.

commitstring

The daemon build commit hash.

networkstring

The Bitcoin network the daemon is running against.

blockHeightnumber

The current chain tip height the wallet has synced to.

serverConnectedboolean

Whether the daemon's connection to the Ark server is currently up.

walletTypestring

The backing wallet implementation in use.

identityPubKeystring

The wallet's identity public key.

walletStateWalletState

The wallet lifecycle state, normalized to the SDK string union.

walletReadyboolean

True iff the wallet is unlocked and ready (mirrors the daemon's Info.WalletReady() method); backfilled by normalizeInfo() since the daemon JSON does not carry it directly.

serverInfoServerInfo

Operator policy hints, when the daemon has learned them from the Ark server; see ServerInfo below. Optional: absent until the daemon has cached the operator terms.

Operator policy hints surfaced on WalletInfo.serverInfo. The daemon learns these from its cached operator terms at bootstrap and on later terms refreshes.

type ServerInfo = {
  freeRefreshWindowBlocks: number;
};

freeRefreshWindowBlocksnumber

The late-lifetime window, in blocks before VTXO expiry, in which a pure refresh receives an operator fee waiver. 0 means the operator advertises no waiver window.

Runtime status snapshot returned by status().

type WalletStatus = {
  ready: boolean;
  unlocked: boolean;
  network: string;
  balance: Balance;
  pendingCount: number;
};

readyboolean

Whether the wallet is unlocked and fully usable.

unlockedboolean

Whether the wallet is currently unlocked (may still be syncing).

networkstring

The Bitcoin network the daemon is running against.

balanceBalance

The current wallet balance; see Balance below.

pendingCountnumber

The number of activity entries currently pending.

Wallet-level balance returned by balance() and embedded in WalletStatus.balance. All amounts are in satoshis.

type Balance = {
  confirmedSat: number;
  pendingInSat: number;
  pendingOutSat: number;
};

confirmedSatnumber

Spendable VTXO balance.

pendingInSatnumber

Inbound amount not yet confirmed.

pendingOutSatnumber

Outbound amount in flight.

Generates an on-chain deposit (boarding) address.

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

reqDepositRequest

Optional. Defaults to {} when omitted.

DepositRequest

type DepositRequest = {
  amountSatHint?: number;
};

amountSatHintnumber

Optional. A hint for the amount (in sats) the caller intends to deposit.

DepositResult

type DepositResult = {
  address: string;
  entry: Entry;
};

addressstring

The boarding (on-chain) address to deposit to.

entryEntry

The activity entry tracking this deposit; see Entry.

Generates a receive invoice for the requested amount.

receive(req: ReceiveRequest): Promise<ReceiveResult>

reqReceiveRequest

The amount (and optional memo) to request.

ReceiveRequest

type ReceiveRequest = {
  amountSat: number;
  memo?: string;
};

amountSatnumber

The amount to request, in sats.

memostring

Optional. A memo attached to the invoice.

ReceiveResult

type ReceiveResult = {
  invoice: string;
  entry: Entry;
};

invoicestring

The BOLT-11 Lightning invoice to be paid.

entryEntry

The activity entry tracking this receive; see Entry.

Quotes a payment without dispatching it: validates the request and returns the expected fee, settlement rail, and a single-use sendIntentId. Pair it with sendPrepared() for a quote → confirm → pay flow.

prepareSend(req: SendRequest): Promise<PrepareSendResult>

reqSendRequest

The Lightning invoice or on-chain address to quote a send for.

Dispatches a payment previously quoted by prepareSend().

sendPrepared(prepared: PrepareSendResult): Promise<SendResult>

preparedPrepareSendResult

The quote returned by prepareSend(). Its sendIntentId is consumed on dispatch; if dispatch fails, prepare a fresh send before retrying.

Quotes and dispatches a payment in a single call, folding prepareSend() and sendPrepared() together.

send(req: SendRequest): Promise<SendResult>

reqSendRequest

The Lightning invoice or on-chain address to pay.

Parameters accepted by prepareSend() and send(), as a discriminated union: supply invoice for a Lightning send or onchainAddress for an on-chain send. The two arms are mutually exclusive, and sweepAll applies only to the on-chain arm.

type SendRequest =
  | {
      invoice: string;
      amountSat?: number;
      note?: string;
      maxFeeSat?: number;
    }
  | {
      onchainAddress: string;
      amountSat?: number;
      sweepAll?: boolean;
      note?: string;
      maxFeeSat?: number;
    };

Lightning arm

invoicestring

A Lightning invoice to pay.

amountSatnumber

Optional. The amount to send, in sats. Ignored on the invoice path: v1 requires an amount-bearing BOLT-11 invoice.

notestring

Optional. A note recorded with the activity.

maxFeeSatnumber

Optional. A cap on the fee, in sats.

On-chain arm

onchainAddressstring

An on-chain address to pay.

amountSatnumber

Optional. The amount to send, in sats. Provide this or set sweepAll.

sweepAllboolean

Optional. When true, sweeps the entire spendable balance to the destination.

notestring

Optional. A note recorded with the activity.

maxFeeSatnumber

Optional. A cap on the fee, in sats.

The quote and intent id returned by prepareSend().

type PrepareSendResult = {
  sendIntentId: string;
  amountSat: number;
  expectedFeeSat: number;
  feeKnown: boolean;
  expectedTotalOutflowSat: number;
  totalOutflowKnown: boolean;
  rail: SendRail;
  quoteStatus: 'unspecified' | 'complete' | 'local_only';
  destinationSummary: string;
  invoiceDescription: string;
  paymentHash: string;
  expiresAtUnix: number;
  selectedOutpoints: string[];
  warning: string;
};

sendIntentIdstring

Single-use id identifying this quote; pass the whole result object to sendPrepared() to dispatch it.

amountSatnumber

The amount that will be sent, in sats.

expectedFeeSatnumber

The expected fee, in sats.

feeKnownboolean

Whether expectedFeeSat is a firm quote rather than an estimate.

expectedTotalOutflowSatnumber

The expected total amount leaving the wallet (amount plus fee), in sats.

totalOutflowKnownboolean

Whether expectedTotalOutflowSat is firm rather than an estimate.

railSendRail

The settlement rail this send is expected to use.

quoteStatus'unspecified' | 'complete' | 'local_only'

How complete the prepare-time quote is: complete means the fee is fully known; local_only means only a local estimate was possible.

destinationSummarystring

A human-readable summary of the destination.

invoiceDescriptionstring

The invoice's embedded description, for Lightning sends.

paymentHashstring

The Lightning payment hash, when applicable.

expiresAtUnixnumber

Unix timestamp after which this quote (and its sendIntentId) is no longer valid.

selectedOutpointsstring[]

The VTXO outpoints selected to fund this send; sendPrepared() spends exactly this set.

warningstring

An optional human-readable warning about this quote (e.g. a high fee).

The result of a dispatched send, returned by sendPrepared() and send().

type SendResult = {
  entry: Entry;
  actualAmountSat: number;
  paymentHash?: string;
};

entryEntry

The activity entry tracking this send; see Entry.

actualAmountSatnumber

The real amount that left the wallet. For invoice sends this matches the invoice principal; for a bounded on-chain send it matches the requested amount; for a sweep-all send it reflects the swept VTXO total, so echo it back to the user before treating the send as confirmed.

paymentHashstring

Optional. The Lightning payment hash, when the send produced one. The daemon returns this from prepareSend (not sendPrepared), so the client folds it into send()'s result here; prefer this field over digging into entry.progress or entry.request, and note that entry.id is an activity id, not a payment hash.

Identifies the expected settlement rail for a prepared send.

type SendRail =
  | 'unspecified'
  | 'offchain_unknown'
  | 'in_ark'
  | 'lightning'
  | 'onchain'
  | 'credit'
  | 'mixed';

Classifies a pasted destination string so a send UI can render only the fields that apply to it. Pure, synchronous, and offline: it reads a BOLT-11 amount from the invoice’s human-readable part without decoding the bech32 payload, so an amountless invoice is detected before any network call.

function classifyDestination(raw: string): Destination

The result of classifyDestination().

type Destination =
  | { kind: 'empty' }
  | { kind: 'invoice'; amount: InvoiceAmount }
  | { kind: 'address' };

{ kind: 'empty' }variant

The input is blank. Render no conditional fields.

{ kind: 'invoice', amount }variant

A BOLT-11 invoice. amount is the InvoiceAmount read from the human-readable part; see below. The daemon ignores a caller-supplied amountSat on the invoice path, and the current daemon rejects an amountless invoice outright, so a UI should never collect an amount for an invoice.

{ kind: 'address' }variant

Anything that is not a BOLT-11 invoice. Treat it as a payable address; the rail is still unknown.

The amount an invoice carries, when it can be read from the human-readable part. A discriminated union keyed on status.

type InvoiceAmount =
  | { status: 'known'; sat: number }
  | { status: 'amountless' }
  | { status: 'unrepresentable' };

{ status: 'known', sat }variant

A whole number of satoshis, read directly from the invoice.

{ status: 'amountless' }variant

The invoice carries no amount at all. The payer must supply one; the current daemon rejects such an invoice outright.

{ status: 'unrepresentable' }variant

The invoice carries an amount that cannot be shown as a whole number of satoshis: a sub-satoshi figure, or one too large to represent exactly. The invoice is still amount-bearing and the daemon pays it (a sub-satoshi amount is rounded up to the next satoshi), so a UI must not ask the payer for an amount. It simply cannot display one.

Lists wallet activity or UTXOs per the request.

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

reqListRequest

Optional. Defaults to {} (the activity view) when omitted.

Filter the activity view by one or more entry kinds:

await client.list({
  view: 'activity',
  kinds: ['receive', 'deposit'],
});

ListRequest

type ListRequest = {
  view?: ListView;
  pendingOnly?: boolean;
  kinds?: EntryKind[];
  limit?: number;
  offset?: number;
  cursor?: string;
};

viewListView

Optional. Which view to list: activity entries, VTXOs, or on-chain outputs. Default: 'activity'.

pendingOnlyboolean

Optional. When true, returns only pending items. Applies to the activity view only.

kindsEntryKind[]

Optional. Returns only the selected entry kinds. Applies to the activity view only.

limitnumber

Optional. The maximum number of items to return; zero uses the daemon default.

offsetnumber

Optional. The number of items to skip for pagination. Applies to the vtxos and onchain views only; the activity view paginates by cursor and ignores offset.

cursorstring

Optional. The opaque pagination token for the activity view. Empty starts from the newest entry; otherwise pass the nextCursor from the previous ActivityList page. Ignored by the vtxos and onchain views.

ListResult

A tagged union on view: exactly one of activity, vtxos, or onchain is populated, matching the requested (or default) view. Switch on view to read the right field.

type ListResult = {
  view: ListView;
  activity?: ActivityList;
  vtxos?: VTXOInventory;
  onchain?: OnchainHistory;
};

viewListView

The populated variant. Mirrors the request’s view; an empty request view is reported as 'activity'.

activityActivityList

Populated when view === 'activity'.

vtxosVTXOInventory

Populated when view === 'vtxos'. See the balances-and-vtxos guide for the VTXO shape.

onchainOnchainHistory

Populated when view === 'onchain'.

ListView

type ListView = 'activity' | 'vtxos' | 'onchain';

ActivityList

type ActivityList = {
  entries: Entry[];
  total: number;
  hasMore: boolean;
  nextCursor: string;
};

entriesEntry[]

The matching activity entries; see Entry.

totalnumber

The number of entries on this page, not a full-feed count. The feed is cursor-paged, so use hasMore to decide whether to fetch again.

hasMoreboolean

Whether more entries exist after this page.

nextCursorstring

The token to pass as ListRequest.cursor to fetch the next page. Empty when hasMore is false.

type VTXOInventory = {
  vtxos: WalletVTXO[];
  total: number;
};

type WalletVTXO = {
  outpoint: string;
  amountSat: number;
  status: string;
  batchExpiry: number;
  relativeExpiry: number;
  commitmentTxid: string;
};

type OnchainHistory = {
  txs: OnchainTx[];
  total: number;
  hasMore: boolean;
};

type OnchainTx = {
  txid: string;
  kind: string;
  amountSat: number;
  feeSat: number;
  status: string;
  confirmationHeight: number;
  createdAt: string;
  description: string;
};

Subscribes a listener to runtime events.

subscribe(listener: WavelengthListener): () => void

listenerWavelengthListener

Callback invoked with each WavelengthEvent.

WavelengthListener

type WavelengthListener = (event: WavelengthEvent) => void;

See WavelengthEvent in the events section below for the event shapes delivered to a listener.

Opens the wallet activity stream and forwards each entry to subscribers as an 'activity' event until stopActivity() is called.

startActivity(opts?: ActivityStreamOptions): Promise<void>

// Replay entries that already exist, then continue with new activity.
await client.startActivity({
  includeExisting: true,
  kinds: ['send', 'receive'],
});

// Resume after the last entry this consumer processed.
await client.startActivity({
  kinds: ['send', 'receive'],
  cursor: lastCursor,
});

opts.includeExistingboolean

Optional. When true, immediately emits an activity event for every entry that already exists, in addition to future changes.

opts.kindsEntryKind[]

Optional. Streams only the selected activity kinds.

opts.cursornumber

Optional. Resumes after the last monotonic Entry.cursor the consumer processed. Must be a nonnegative safe integer.

ActivityStreamOptions

type ActivityStreamOptions = {
  includeExisting?: boolean;
  kinds?: EntryKind[];
  cursor?: number;
};

A direct WavelengthClient receives an activityStream event when the stream ends or fails and chooses its own retry policy. WalletEngine adds reconciliation and bounded cursor-based recovery for apps that want that managed behavior.

Closes the activity stream opened by startActivity().

stopActivity(): void

A single row in the wallet activity feed, returned by list() and streamed via startActivity() as activity events.

type Entry = {
  id: string;
  kind: EntryKind;
  status: EntryStatus;
  amountSat: number;
  feeSat: number;
  counterparty: string;
  createdAt: string;
  updatedAt: string;
  note: string;
  failureReason: string;
  failureCode: EntryFailureCode;
  cursor: number;
  progress?: EntryProgress;
  request?: EntryRequest;
};

idstring

The activity id. Not a payment hash; see SendResult.paymentHash for that.

kindEntryKind

The user-visible activity category.

statusEntryStatus

The collapsed pending/complete/failed state. See the Phase vs Status note below.

amountSatnumber

The activity amount, in sats.

feeSatnumber

The fee associated with this activity, in sats.

counterpartystring

A human-readable counterparty label, when known.

createdAtstring

When the entry was created.

updatedAtstring

When the entry was last updated.

notestring

An optional note recorded with the activity.

failureReasonstring

Human-readable supplement to failureCode; populated only when status is 'failed'.

failureCodeEntryFailureCode

Stable, machine-readable classification of why the entry failed. Empty unless status is 'failed'.

cursornumber

The monotonic position of this update on the activity stream. Persist it to resume with ActivityStreamOptions.cursor. It is zero on entries returned outside the stream.

progressEntryProgress

Optional. Lifecycle metadata the daemon normalized for this entry. Absent when the backing subsystem supplied no progress hint.

requestEntryRequest

Optional. The user-recognizable request that created the entry (an invoice, address, or Ark address). Absent when the backing subsystem did not persist one.

The wrapper-owned view of the lifecycle metadata the daemon computes for an Entry. Fields are populated on a best-effort basis by the backing subsystem; an empty field means not applicable or not yet known.

type EntryProgress = {
  phase: EntryPhase;
  phaseLabel: string;
  paymentHash: string;
  txid: string;
  confirmationHeight: number;
  vTXOOutpoint: string;
  preimage: string;
};

phaseEntryPhase

The coarse lifecycle phase for the entry.

phaseLabelstring

The short lowercase label the daemon emitted; render this directly instead of switching on phase if you prefer.

paymentHashstring

Populated for Lightning-backed send/receive entries.

txidstring

Populated when the backing ledger row has an on-chain txid.

confirmationHeightnumber

Populated once the source records it.

vTXOOutpointstring

Populated when a swap observes the Ark vHTLC output.

preimagestring

The hex-encoded Lightning payment preimage when known. For a completed Lightning-backed send, it is proof of payment for the invoice.

The wrapper-owned, flattened view of the request that created an Entry. Exactly one variant’s fields are populated, named by type; read type first and treat the other fields as zero.

type EntryRequest = {
  type: EntryRequestType;
  lightningInvoice: string;
  paymentHash: string;
  onchainAddress: string;
  arkAddress: string;
};

typeEntryRequestType

Names the populated variant.

lightningInvoicestring

The BOLT-11 payment request. Populated when type is 'lightning'.

paymentHashstring

Identifies the Lightning invoice and stays stable after the invoice is no longer convenient to display. Populated when type is 'lightning'.

onchainAddressstring

The bech32 on-chain address originally issued or targeted. Populated when type is 'onchain'.

arkAddressstring

The Ark address originally issued or targeted. Populated when type is 'ark'.

The user-visible wallet activity category.

type EntryKind = 'send' | 'receive' | 'deposit' | 'exit';

The collapsed wallet activity state.

type EntryStatus = 'pending' | 'complete' | 'failed';

A coarse, wrapper-owned lifecycle phase for an Entry.

type EntryPhase =
  | 'unspecified'
  | 'request_created'
  | 'waiting_for_payment'
  | 'payment_detected'
  | 'settling'
  | 'confirmed'
  | 'refunding'
  | 'refunded'
  | 'failed'
  | 'waiting_for_confirmation';

A wrapper-owned, stable classification of why a failed Entry failed.

type EntryFailureCode =
  | 'timed_out'
  | 'expired'
  | 'refunded'
  | 'needs_intervention'
  | 'failed';

Discriminates which request shape an EntryRequest carries.

type EntryRequestType = 'lightning' | 'onchain' | 'ark';

Exits a single outpoint through one explicit branch: a cooperative leave, optionally to destination, or an acknowledged unilateral unroll. When destination is omitted, the daemon generates a fresh backing-wallet address.

exit(req: ExitRequest): Promise<ExitResult>

reqExitRequest

The outpoint and either an optional cooperative destination or the exact unilateral acknowledgement.

ExitRequest

destination and forceUnrollAck are mutually exclusive. Omit both to make a cooperative exit to a fresh backing-wallet address:

await client.exit({ outpoint });

A cooperative error rejects the call and never falls back to unilateral unroll. Starting unilateral unroll requires the exported FORCE_UNROLL_ACK constant:

await client.exit({
  outpoint,
  forceUnrollAck: FORCE_UNROLL_ACK,
});

type ExitRequest =
  | {
      outpoint: string;
      destination?: string;
      forceUnrollAck?: never;
    }
  | {
      outpoint: string;
      destination?: never;
      forceUnrollAck: typeof FORCE_UNROLL_ACK;
    };

const FORCE_UNROLL_ACK = 'I_KNOW_WHAT_I_AM_DOING' as const;

outpointstring

The VTXO outpoint to exit, in "txid:index" format.

destinationstring

Optional. Cooperative branch only. The on-chain address that receives the leave output. When omitted, the daemon generates a fresh backing-wallet address. Mutually exclusive with forceUnrollAck.

forceUnrollAcktypeof FORCE_UNROLL_ACK

Unilateral branch only. Must be the exact exported acknowledgement constant and cannot be combined with destination.

ExitResult

A tagged union over the three exit paths. Read path first and only inspect the variant fields associated with that path; the remaining fields are zero-valued.

type ExitResult = {
  path: ExitPath;
  cooperative: boolean;
  queuedOutpoints: string[];
  created: boolean;
  actorID: string;
  cooperativeError: string;
};

pathExitPath

Discriminates between the three legal outcomes; switch on this before reading the variant fields below.

cooperativeboolean

true iff path === 'cooperative'. Retained for backwards compatibility; prefer path.

queuedOutpointsstring[]

The outpoints the cooperative leave admitted into a round. Populated only when path === 'cooperative'.

createdboolean

Whether the unilateral-unroll path spawned a fresh job. Populated when path is 'unilateral' or 'unilateral_fallback'.

actorIDstring

Identifies the durable unroll job that owns the unilateral path. Populated when path is 'unilateral' or 'unilateral_fallback'.

cooperativeErrorstring

Retained for source compatibility with a prior SDK fallback shape; current daemon behavior returns cooperative failures directly rather than populating this.

ExitPath

type ExitPath = 'cooperative' | 'unilateral' | 'unilateral_fallback';

Queries the status of an exit.

exitStatus(req: ExitStatusRequest): Promise<ExitStatusResult>

reqExitStatusRequest

The outpoint whose exit status is queried.

ExitStatusRequest

type ExitStatusRequest = {
  outpoint: string;
  detailed?: boolean;
};

outpointstring

The VTXO outpoint whose exit status is queried.

detailedboolean

Optional. Request recovery-tree progress, a CSV maturity countdown, a fee breakdown, and a best-case block countdown. It costs one live actor round-trip plus a fee estimate, so leave it false for a coarse, cheaper phase-only status.

ExitStatusResult

found is false when no job exists for the requested outpoint; that is not an error condition. The detailed fields (phaseDetail, progress, cSV, fees, bestCaseBlocksRemaining, currentHeight) are populated only when the request set detailed; otherwise they are empty, nil, or zero.

type ExitStatusResult = {
  found: boolean;
  status: ExitJobStatus;
  sweepTxid: string;
  lastError: string;
  phaseDetail: string;
  progress?: ExitProgress;
  cSV?: ExitCSV;
  fees?: ExitFees;
  bestCaseBlocksRemaining: number;
  currentHeight: number;
};

foundboolean

Whether an exit job exists for the requested outpoint.

statusExitJobStatus

The job’s current status. Meaningful only when found is true.

sweepTxidstring

The sweep transaction id, once known.

lastErrorstring

The last error the job recorded, if any.

phaseDetailstring

A one-line human description of the current phase. Empty on a coarse (non-detailed) query.

progressExitProgress

Recovery-tree materialization progress. Nil on a coarse query, or when no live actor backs the job.

cSVExitCSV

The target’s CSV maturity countdown. Nil until the target confirms.

feesExitFees

The on-chain cost breakdown for the exit. Nil on a coarse query.

bestCaseBlocksRemainingnumber

The optimistic block count until a confirmed sweep. Zero on a coarse query.

currentHeightnumber

The best block height the exit job has observed. Zero on a coarse query, or when no live actor backs the job.

ExitProgress

Materialization progress through the recovery tree. Populated only for a detailed query against a live exit job.

type ExitProgress = {
  confirmedTxs: number;
  inFlightTxs: number;
  readyTxs: number;
  blockedTxs: number;
  totalTxs: number;
  currentLayer: number;
  totalLayers: number;
  targetConfirmed: boolean;
  allProofConfirmed: boolean;
};

confirmedTxsnumber

Proof transactions confirmed on-chain.

inFlightTxsnumber

Proof transactions broadcast but not yet observed confirmed.

readyTxsnumber

Proof transactions ready to broadcast now.

blockedTxsnumber

Proof transactions still waiting on an unconfirmed in-proof parent.

totalTxsnumber

Total transactions in the exit proof tree.

currentLayernumber

The frontier layer index: the shallowest topological layer (roots first) that still holds an unconfirmed transaction.

totalLayersnumber

The depth of the exit proof tree.

targetConfirmedboolean

True once the target VTXO transaction has confirmed.

allProofConfirmedboolean

True once every proof-tree transaction has confirmed, so only the CSV wait and final sweep remain.

ExitCSV

The target’s CSV maturity countdown. Populated only once the target transaction has confirmed.

type ExitCSV = {
  targetConfirmHeight: number;
  maturityHeight: number;
  blocksRemaining: number;
  mature: boolean;
};

targetConfirmHeightnumber

The height at which the target transaction confirmed.

maturityHeightnumber

The height at which the CSV timelock matures.

blocksRemainingnumber

Blocks remaining until maturity.

matureboolean

Whether the CSV timelock has matured.

ExitFees

The on-chain cost breakdown for the exit. The CPFP total is estimated; sweepFeeActual reports whether sweepFeeSat is the real built-sweep fee rather than an estimate.

type ExitFees = {
  cPFPFeeSat: number;
  sweepFeeSat: number;
  totalCostSat: number;
  spentSoFarSat: number;
  vTXOAmountSat: number;
  netRecoveredSat: number;
  feeRateSatVByte: number;
  sweepFeeActual: boolean;
};

cPFPFeeSatnumber

The estimated total CPFP fee, in sats.

sweepFeeSatnumber

The sweep fee, in sats. Real rather than estimated when sweepFeeActual is true.

totalCostSatnumber

The projected on-chain cost of the whole exit, in sats.

spentSoFarSatnumber

The estimated fee committed so far, in sats.

vTXOAmountSatnumber

The VTXO value being recovered, in sats.

netRecoveredSatnumber

The estimated net recoverable after fees, in sats.

feeRateSatVBytenumber

The fee rate used, in sat/vByte.

sweepFeeActualboolean

Whether sweepFeeSat is the real built-sweep fee rather than an estimate.

ExitJobStatus

Collapses the underlying unroll job phases to a short wallet-facing string set.

type ExitJobStatus =
  | 'unspecified'
  | 'pending'
  | 'materializing'
  | 'csv_pending'
  | 'sweeping'
  | 'completed'
  | 'failed';

Summarizes all in-progress exits: one entry per active exit plus wallet-wide totals for the amount being recovered, the estimated fees, and the estimated net recoverable. Completed and failed exits are omitted; they have no amount left to recover.

exitSummary(req?: ExitSummaryRequest): Promise<ExitSummaryResult>

reqExitSummaryRequest

Takes no arguments; the daemon reports the wallet-wide portfolio.

ExitSummaryRequest

Takes no arguments.

type ExitSummaryRequest = Record<string, never>;

ExitSummaryResult

type ExitSummaryResult = {
  exits: ExitSummaryEntry[];
  totalExits: number;
  totalVTXOAmountSat: number;
  totalEstFeeSat: number;
  totalEstNetRecoveredSat: number;
};

exitsExitSummaryEntry[]

One entry per in-progress exit.

totalExitsnumber

The number of in-progress exits.

totalVTXOAmountSatnumber

The combined VTXO value being recovered, in sats.

totalEstFeeSatnumber

The combined estimated on-chain fees, in sats.

totalEstNetRecoveredSatnumber

The combined estimated net recoverable after fees, in sats.

ExitSummaryEntry

One in-progress exit’s coarse contribution to the portfolio.

type ExitSummaryEntry = {
  outpoint: string;
  status: ExitJobStatus;
  vTXOAmountSat: number;
  estTotalFeeSat: number;
  estNetRecoveredSat: number;
};

outpointstring

The VTXO outpoint being exited.

statusExitJobStatus

The exit job’s current status.

vTXOAmountSatnumber

The VTXO value being recovered, in sats.

estTotalFeeSatnumber

The estimated total on-chain fee for this exit, in sats.

estNetRecoveredSatnumber

The estimated net recoverable after fees, in sats.