@lightninglabs/wavelength-core 0.1.0

package/dist/config.js

@@ -0,0 +1,142 @@
+import { WavelengthError } from "./errors.js";
+/**
+ * The daemon log verbosity levels accepted by {@link RuntimeConfig.debugLevel},
+ * 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'.
+ */
+export const DEBUG_LEVELS = [
+    'trace',
+    'debug',
+    'info',
+    'warn',
+    'error',
+    'critical',
+    'off',
+];
+const lwwalletOnly = [
+    'walletEsploraUrl',
+    'walletPasswordFile',
+    'walletPollIntervalSeconds',
+];
+const btcwalletOnly = [
+    'walletFeeUrl',
+    'walletBlockHeadersSource',
+    'walletFilterHeadersSource',
+];
+const numericFields = [
+    'walletPollIntervalSeconds',
+    'walletRecoveryWindow',
+    'maxOperatorFeeSat',
+    'signingWorkers',
+    'bufferSize',
+];
+function invalidConfig(message) {
+    throw new WavelengthError(message, 'invalid_config');
+}
+/** Validates host-owned runtime settings before the typed start dispatches. */
+export function validateRuntimeConfig(config, transport) {
+    const walletType = config.walletType ?? 'lwwallet';
+    if (walletType !== 'lwwallet' && walletType !== 'btcwallet') {
+        invalidConfig(`unsupported walletType: ${String(walletType)}`);
+    }
+    if (config.network === 'mainnet' && config.allowMainnet !== true) {
+        invalidConfig('mainnet requires allowMainnet: true');
+    }
+    if (walletType === 'lwwallet') {
+        for (const field of btcwalletOnly) {
+            if (config[field] !== undefined) {
+                invalidConfig(`${field} applies only to walletType btcwallet`);
+            }
+        }
+    }
+    else {
+        for (const field of lwwalletOnly) {
+            if (config[field] !== undefined) {
+                invalidConfig(`${field} applies only to walletType lwwallet`);
+            }
+        }
+    }
+    for (const field of numericFields) {
+        const value = config[field];
+        if (value !== undefined &&
+            (!Number.isSafeInteger(value) || value < 0)) {
+            invalidConfig(`${field} must be a nonnegative safe integer`);
+        }
+    }
+    if (config.walletRecoveryWindow !== undefined &&
+        config.walletRecoveryWindow > 0xffff_ffff) {
+        invalidConfig('walletRecoveryWindow must fit in uint32');
+    }
+    if (transport === 'rest' && config.arkServerTlsCertPath !== undefined) {
+        invalidConfig('arkServerTlsCertPath is unavailable on the web transport');
+    }
+    if (transport === 'rest' &&
+        !config.disableSwaps &&
+        config.swapServerTlsCertPath !== undefined) {
+        invalidConfig('swapServerTlsCertPath is unavailable on the web transport');
+    }
+}
+// The hosted public deployments per network, mirroring the daemon's own
+// per-network defaults. Record over PresetNetwork so that adding a preset
+// network without its endpoints here is a compile error.
+const NETWORK_ENDPOINTS = {
+    signet: {
+        ark: {
+            rest: 'https://signet.wavelength-rest.lightning.finance',
+            grpc: 'signet.wavelength.lightning.finance:443',
+        },
+        swap: {
+            rest: 'https://signet.swapd-rest.lightning.finance',
+            grpc: 'swap.signet.wavelength.lightning.finance:443',
+        },
+        esplora: 'https://mempool-signet.testnet.lightningcluster.com/api',
+    },
+    testnet: {
+        ark: {
+            rest: 'https://test.wavelength-rest.lightning.finance',
+            grpc: 'test.wavelength.lightning.finance:443',
+        },
+        swap: {
+            rest: 'https://test.swapd-rest.lightning.finance',
+            grpc: 'swap.test.wavelength.lightning.finance:443',
+        },
+        esplora: 'https://mempool-testnet3.testnet.lightningcluster.com/api',
+    },
+    testnet4: {
+        ark: {
+            rest: 'https://test4.wavelength-rest.lightning.finance',
+            // testnet4's public gRPC NLB is still disabled, so the daemon keeps
+            // dialing the raw cluster hostname; a friendly-domain CNAME follows
+            // once its certificate work lands.
+            grpc: 'lumosd-testnet4.testnet.lightningcluster.com:443',
+        },
+        swap: {
+            rest: 'https://test4.swapd-rest.lightning.finance',
+            grpc: 'swapd-testnet4.testnet.lightningcluster.com:443',
+        },
+        esplora: 'https://mempool-testnet4.testnet.lightningcluster.com/api',
+    },
+};
+/**
+ * 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 those instead.
+ *
+ * Only the preset networks are accepted (see {@link PresetNetwork}); mainnet
+ * and regtest have no preset and their {@link RuntimeConfig} is built by hand.
+ *
+ * @param network - The Bitcoin network to look up.
+ * @param transport - The endpoint flavor the caller's transport dials.
+ * @returns The preset config fields for that network and transport.
+ */
+export function networkDefaults(network, transport) {
+    const endpoints = NETWORK_ENDPOINTS[network];
+    return {
+        arkServerAddress: endpoints.ark[transport],
+        walletEsploraUrl: endpoints.esplora,
+        swapServerAddress: endpoints.swap[transport],
+    };
+}

package/dist/destination.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The classification of a pasted send destination. It decides which input
+ * fields a send UI should render and nothing more.
+ *
+ * It deliberately does not name a settlement rail: an `invoice` may still
+ * quote as `lightning`, `in_ark`, `credit`, or `mixed`. Read `rail` from the
+ * `prepareSend` result for that.
+ */
+export type Destination = 
+/** The input is blank. Render no conditional fields. */
+{
+    kind: 'empty';
+} | {
+    /** The input is a BOLT-11 invoice. */
+    kind: 'invoice';
+    /** The amount the invoice carries, when it can be read from the HRP. */
+    amount: InvoiceAmount;
+}
+/** The input is not an invoice. Treat it as a payable address. */
+ | {
+    kind: 'address';
+};
+/**
+ * The amount an invoice carries, when it can be read from the human-readable
+ * part.
+ */
+export type InvoiceAmount = 
+/** A whole number of satoshis, read from the invoice. */
+{
+    status: 'known';
+    sat: number;
+}
+/** The invoice carries no amount at all. The payer must supply one. */
+ | {
+    status: 'amountless';
+}
+/**
+ * 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.
+ */
+ | {
+    status: 'unrepresentable';
+};
+/**
+ * Classifies a pasted destination so a send UI can render only the fields that
+ * apply to it. Whitespace is trimmed before matching.
+ *
+ * Reading the amount from the human-readable part means an amountless invoice
+ * is detected without decoding the bech32 payload, so the UI can ask for an
+ * amount up front rather than discovering the need after a round trip.
+ */
+export declare function classifyDestination(raw: string): Destination;
+//# sourceMappingURL=destination.d.ts.map

package/dist/destination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"destination.d.ts","sourceRoot":"","sources":["../src/destination.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW;AACrB,wDAAwD;AACtD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IACE,sCAAsC;IACtC,IAAI,EAAE,SAAS,CAAC;IAChB,wEAAwE;IACxE,MAAM,EAAE,aAAa,CAAC;CACvB;AACH,kEAAkE;GAChE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,aAAa;AACvB,yDAAyD;AACvD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAClC,uEAAuE;GACrE;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE;AAC1B;;;;;;GAMG;GACD;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AA6ElC;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAyB5D"}

package/dist/destination.js

@@ -0,0 +1,90 @@
+/**
+ * Matches a BOLT-11 human-readable part and captures its optional amount.
+ *
+ * The network alternation is listed longest-first for legibility, not because
+ * it changes the match: JS regex alternation backtracks, so `bc|bcrt` and
+ * `bcrt|bc` parse every input identically. What actually makes the parse
+ * unambiguous is bech32's data charset, which excludes the digit `1`, so the
+ * last `1` in the string before the data part is always the separator and an
+ * amount can never contain one. Group 1 is the amount digits and group 2 its
+ * multiplier; both are absent for an amountless invoice.
+ */
+const BOLT11_HRP = /^ln(?:bcrt|tbs|bc|tb)(?:(\d+)([munp])?)?1/i;
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+/** The number of decimal places in one satoshi, as an exponent of one bitcoin. */
+const SATS_EXPONENT = 8;
+/**
+ * The BOLT-11 amount multipliers, as the negative power of ten each applies to
+ * one bitcoin. An absent multiplier means the digits are already bitcoin. The
+ * key type is pinned to the multiplier group of {@link BOLT11_HRP} so a future
+ * drift between the two cannot reach `10n ** BigInt(NaN)`, which throws a
+ * RangeError during render.
+ */
+const TEN_EXPONENT = {
+    m: 3,
+    u: 6,
+    n: 9,
+    p: 12,
+};
+/**
+ * Converts a BOLT-11 HRP amount to sats, or returns null when the amount is not
+ * a whole number of sats (a nano- or pico-bitcoin figure can be sub-satoshi) or
+ * is too large to represent exactly.
+ *
+ * The arithmetic is exact. Every multiplier is a power of ten, so the conversion
+ * is a decimal shift and BigInt performs it without rounding. Doing this in
+ * floating point silently loses ordinary amounts: 1000n is exactly 100 sats, but
+ * `1000 * 1e-9 * 1e8` evaluates to 100.00000000000001.
+ */
+function satsFromHrp(digits, multiplier) {
+    const exponent = SATS_EXPONENT -
+        (multiplier
+            ? TEN_EXPONENT[multiplier.toLowerCase()]
+            : 0);
+    const value = BigInt(digits);
+    // A non-negative exponent scales up exactly. A negative one yields a whole
+    // number of sats only when its divisor divides the digits evenly; anything
+    // left over is a sub-satoshi amount the wallet cannot send.
+    let sats;
+    if (exponent >= 0) {
+        sats = value * 10n ** BigInt(exponent);
+    }
+    else {
+        const divisor = 10n ** BigInt(-exponent);
+        if (value % divisor !== 0n) {
+            return null;
+        }
+        sats = value / divisor;
+    }
+    if (sats <= 0n || sats > MAX_SAFE) {
+        return null;
+    }
+    return Number(sats);
+}
+/**
+ * Classifies a pasted destination so a send UI can render only the fields that
+ * apply to it. Whitespace is trimmed before matching.
+ *
+ * Reading the amount from the human-readable part means an amountless invoice
+ * is detected without decoding the bech32 payload, so the UI can ask for an
+ * amount up front rather than discovering the need after a round trip.
+ */
+export function classifyDestination(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '') {
+        return { kind: 'empty' };
+    }
+    const match = BOLT11_HRP.exec(trimmed);
+    if (!match) {
+        return { kind: 'address' };
+    }
+    const [, digits, multiplier] = match;
+    if (digits === undefined) {
+        return { kind: 'invoice', amount: { status: 'amountless' } };
+    }
+    const sat = satsFromHrp(digits, multiplier);
+    return {
+        kind: 'invoice',
+        amount: sat === null ? { status: 'unrepresentable' } : { status: 'known', sat },
+    };
+}

package/dist/engine/activity.d.ts

@@ -0,0 +1,25 @@
+import type { WavelengthClient } from '../client.ts';
+import type { Entry } from '../results.ts';
+/**
+ * Owns the daemon activity subscription while the wallet is ready: opening
+ * (with an includeExisting replay so changes missed while down are caught),
+ * reopening with a capped exponential backoff, debouncing activity events into
+ * onActivity, and giving up through onDead after too many consecutive failed
+ * opens (the counter includes the initial open, not just reopens).
+ */
+export declare class ActivityStream {
+    #private;
+    constructor(opts: {
+        client: Pick<WavelengthClient, 'startActivity' | 'stopActivity'>;
+        onActivity: () => void;
+        onReconcile: () => void;
+        onDead: (error: Error) => void;
+    });
+    start(): void;
+    stop(): void;
+    /** Forwarded 'activity' client events; debounced into one onActivity call. */
+    noteActivity(entry: Pick<Entry, 'cursor'>): void;
+    /** Forwarded 'activityStream' client events: the stream was lost; reopen. */
+    noteStreamLost(): void;
+}
+//# sourceMappingURL=activity.d.ts.map

package/dist/engine/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../src/engine/activity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAQ3C;;;;;;GAMG;AACH,qBAAa,cAAc;;gBAmBb,IAAI,EAAE;QAChB,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,GAAG,cAAc,CAAC,CAAC;QACjE,UAAU,EAAE,MAAM,IAAI,CAAC;QACvB,WAAW,EAAE,MAAM,IAAI,CAAC;QACxB,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;KAChC;IAID,KAAK,IAAI,IAAI;IAYb,IAAI,IAAI,IAAI;IAaZ,8EAA8E;IAC9E,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAI;IAWhD,6EAA6E;IAC7E,cAAc,IAAI,IAAI;CAoEvB"}

package/dist/engine/activity.js

@@ -0,0 +1,119 @@
+import { ACTIVITY_DEBOUNCE_MS, STREAM_BACKOFF_CAP_MS, STREAM_BACKOFF_MS, STREAM_FAILURE_LIMIT, } from "./constants.js";
+/**
+ * Owns the daemon activity subscription while the wallet is ready: opening
+ * (with an includeExisting replay so changes missed while down are caught),
+ * reopening with a capped exponential backoff, debouncing activity events into
+ * onActivity, and giving up through onDead after too many consecutive failed
+ * opens (the counter includes the initial open, not just reopens).
+ */
+export class ActivityStream {
+    #running = false;
+    #cursor = 0;
+    #backoff = STREAM_BACKOFF_MS;
+    #failures = 0;
+    #lifecycleGeneration = 0;
+    #retryTimer;
+    #debounce;
+    // Tracks the lifecycle whose startActivity() call is unsettled. A stream
+    // loss within that lifecycle must not double-subscribe, while a stop/start
+    // must be able to open even if the stopped lifecycle has not settled yet.
+    #openingGeneration;
+    #opts;
+    constructor(opts) {
+        this.#opts = opts;
+    }
+    start() {
+        if (this.#running) {
+            return;
+        }
+        this.#running = true;
+        this.#lifecycleGeneration += 1;
+        this.#cursor = 0;
+        this.#backoff = STREAM_BACKOFF_MS;
+        this.#failures = 0;
+        this.#open(this.#lifecycleGeneration);
+    }
+    stop() {
+        if (!this.#running) {
+            this.#cursor = 0;
+            return;
+        }
+        this.#running = false;
+        this.#lifecycleGeneration += 1;
+        this.#cursor = 0;
+        clearTimeout(this.#retryTimer);
+        clearTimeout(this.#debounce);
+        this.#opts.client.stopActivity();
+    }
+    /** Forwarded 'activity' client events; debounced into one onActivity call. */
+    noteActivity(entry) {
+        if (!this.#running) {
+            return;
+        }
+        if (Number.isSafeInteger(entry.cursor) && entry.cursor > this.#cursor) {
+            this.#cursor = entry.cursor;
+        }
+        clearTimeout(this.#debounce);
+        this.#debounce = setTimeout(() => this.#opts.onActivity(), ACTIVITY_DEBOUNCE_MS);
+    }
+    /** Forwarded 'activityStream' client events: the stream was lost; reopen. */
+    noteStreamLost() {
+        if (this.#running) {
+            this.#opts.onReconcile();
+            this.#scheduleRetry(this.#lifecycleGeneration);
+        }
+    }
+    #open(lifecycle) {
+        if (this.#openingGeneration === lifecycle) {
+            return;
+        }
+        this.#openingGeneration = lifecycle;
+        this.#opts.client.startActivity({
+            includeExisting: this.#cursor === 0,
+            cursor: this.#cursor,
+        }).then(() => {
+            if (this.#openingGeneration === lifecycle) {
+                this.#openingGeneration = undefined;
+            }
+            if (!this.#running || lifecycle !== this.#lifecycleGeneration) {
+                return;
+            }
+            // The initial open replays existing entries. Cursor reopens rely on
+            // noteStreamLost's immediate reconciliation before resuming.
+            this.#backoff = STREAM_BACKOFF_MS;
+            this.#failures = 0;
+        }, () => {
+            if (this.#openingGeneration === lifecycle) {
+                this.#openingGeneration = undefined;
+            }
+            this.#onReopenFailure(lifecycle);
+        });
+    }
+    #onReopenFailure(lifecycle) {
+        if (!this.#running || lifecycle !== this.#lifecycleGeneration) {
+            return;
+        }
+        this.#failures += 1;
+        if (this.#failures >= STREAM_FAILURE_LIMIT) {
+            // The stream could not be re-established after repeated attempts;
+            // surface it instead of leaving the wallet looking healthy while its
+            // balance and history silently stop updating.
+            this.#running = false;
+            clearTimeout(this.#retryTimer);
+            clearTimeout(this.#debounce);
+            this.#opts.onDead(new Error('lost the activity stream and could not reconnect'));
+            return;
+        }
+        this.#scheduleRetry(lifecycle);
+    }
+    #scheduleRetry(lifecycle) {
+        clearTimeout(this.#retryTimer);
+        this.#retryTimer = setTimeout(() => {
+            if (!this.#running || lifecycle !== this.#lifecycleGeneration) {
+                return;
+            }
+            this.#backoff = Math.min(this.#backoff * 2, STREAM_BACKOFF_CAP_MS);
+            this.#open(lifecycle);
+        }, this.#backoff);
+    }
+}

package/dist/engine/constants.d.ts

@@ -0,0 +1,29 @@
+/** Bounds the in-memory log tail the engine keeps. */
+export declare const MAX_LOGS = 200;
+/** Consecutive failed activity-stream opens before the stream is dead. */
+export declare const STREAM_FAILURE_LIMIT = 5;
+/** Initial reopen backoff for a lost activity stream. */
+export declare const STREAM_BACKOFF_MS = 1000;
+/** Safety ceiling on activity-stream reopen backoff. Only approached when reopen attempts hang while losses keep arriving, doubling the backoff each time without incrementing the failure count. */
+export declare const STREAM_BACKOFF_CAP_MS = 30000;
+/** Debounce applied to activity events before the background refresh runs. */
+export declare const ACTIVITY_DEBOUNCE_MS = 250;
+/** Interval of the refresh poll while the wallet is syncing. */
+export declare const SYNC_POLL_MS = 2000;
+/** Consecutive failed sync-poll refreshes before escalating to error. */
+export declare const SYNC_POLL_FAILURE_LIMIT = 5;
+/** Interval of the readiness poll during a background restore. */
+export declare const RESTORE_POLL_MS = 1500;
+/**
+ * Follow-up refresh delays used to reconcile a possibly-stale balance after an
+ * activity event: the daemon can report an entry settled a beat before
+ * balance() reflects the new funds.
+ */
+export declare const SETTLE_RECONCILE_DELAYS_MS: number[];
+/** Consecutive failed background refreshes before escalating to error. */
+export declare const BACKGROUND_REFRESH_FAILURE_LIMIT = 5;
+/** Retries for the post-create/unlock info refetch before escalating. */
+export declare const ADOPT_INFO_RETRIES = 3;
+/** Delay between #adoptInfo retries. */
+export declare const ADOPT_INFO_RETRY_MS = 1000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/engine/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/engine/constants.ts"],"names":[],"mappings":"AAEA,sDAAsD;AACtD,eAAO,MAAM,QAAQ,MAAM,CAAC;AAE5B,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,qMAAqM;AACrM,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,gEAAgE;AAChE,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,kEAAkE;AAClE,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,UAAoB,CAAC;AAE5D,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,wCAAwC;AACxC,eAAO,MAAM,mBAAmB,OAAO,CAAC"}

package/dist/engine/constants.js

@@ -0,0 +1,29 @@
+// Timing and budget constants for the engine's background processes.
+/** Bounds the in-memory log tail the engine keeps. */
+export const MAX_LOGS = 200;
+/** Consecutive failed activity-stream opens before the stream is dead. */
+export const STREAM_FAILURE_LIMIT = 5;
+/** Initial reopen backoff for a lost activity stream. */
+export const STREAM_BACKOFF_MS = 1000;
+/** Safety ceiling on activity-stream reopen backoff. Only approached when reopen attempts hang while losses keep arriving, doubling the backoff each time without incrementing the failure count. */
+export const STREAM_BACKOFF_CAP_MS = 30000;
+/** Debounce applied to activity events before the background refresh runs. */
+export const ACTIVITY_DEBOUNCE_MS = 250;
+/** Interval of the refresh poll while the wallet is syncing. */
+export const SYNC_POLL_MS = 2000;
+/** Consecutive failed sync-poll refreshes before escalating to error. */
+export const SYNC_POLL_FAILURE_LIMIT = 5;
+/** Interval of the readiness poll during a background restore. */
+export const RESTORE_POLL_MS = 1500;
+/**
+ * Follow-up refresh delays used to reconcile a possibly-stale balance after an
+ * activity event: the daemon can report an entry settled a beat before
+ * balance() reflects the new funds.
+ */
+export const SETTLE_RECONCILE_DELAYS_MS = [750, 1500, 3000];
+/** Consecutive failed background refreshes before escalating to error. */
+export const BACKGROUND_REFRESH_FAILURE_LIMIT = 5;
+/** Retries for the post-create/unlock info refetch before escalating. */
+export const ADOPT_INFO_RETRIES = 3;
+/** Delay between #adoptInfo retries. */
+export const ADOPT_INFO_RETRY_MS = 1000;

package/dist/engine/engine.d.ts

@@ -0,0 +1,115 @@
+import type { WavelengthClient } from '../client.ts';
+import type { RuntimeConfig } from '../config.ts';
+import { type ExitBatchEvent, type ExitBatchOptions, type ExitBatchResult } from '../exit.ts';
+import type { CreateWalletRequest, DepositRequest, ExitRequest, ExitStatusRequest, ExitSummaryRequest, GetExitPlanRequest, ListRequest, OpenWalletFromPasskeyRequest, ReceiveRequest, RestoreWalletRequest, SendRequest, SweepWalletRequest, UnlockWalletRequest } from '../requests.ts';
+import type { CreateWalletResult, DepositResult, ExitResult, ExitStatusResult, ExitSummaryResult, GetExitPlanResult, ListResult, OpenWalletFromPasskeyResult, PrepareSendResult, ReceiveResult, SendResult, SweepWalletResult, UnlockWalletResult } from '../results.ts';
+import { type WalletInfo } from '../state.ts';
+import type { WalletSnapshot } from './snapshot.ts';
+/**
+ * Options for {@link createWalletEngine}. A discriminated union: the type
+ * requires config when autoStart is true, so autoStart cannot be set without
+ * a config to start from.
+ */
+export type WalletEngineOptions = {
+    /** The transport client the engine drives. */
+    client: WavelengthClient;
+    /** Default runtime config used by autoStart and by start() with no argument. */
+    config: RuntimeConfig;
+    /** Start the runtime automatically once it is ready. */
+    autoStart: true;
+} | {
+    /** The transport client the engine drives. */
+    client: WavelengthClient;
+    /** Default runtime config used by start() with no argument. */
+    config?: RuntimeConfig;
+    /** Start the runtime automatically once it is ready. Requires config; omit or set false when config is unset. */
+    autoStart?: false;
+};
+/**
+ * Removes a key from every arm of a union type. TypeScript's built-in Omit
+ * does not distribute over unions (it flattens to the union of all keys
+ * first), which would erase the discriminant on types like
+ * {@link WalletEngineOptions}. This distributes the omission per arm instead.
+ */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * The headless wallet orchestrator: it owns the lifecycle phase machine, the
+ * state snapshot (phase, info, balance, activity, recovery, logs), and the
+ * background processes that keep them fresh (activity stream, settle
+ * reconcile, syncing poll, restore readiness poll). Framework bindings
+ * subscribe via getSnapshot()/subscribe(); vanilla consumers can use it
+ * directly. Create one with {@link createWalletEngine} or a transport factory
+ * such as createWebWalletEngine.
+ */
+export interface WalletEngine {
+    /** The underlying transport client, as an escape hatch. */
+    readonly client: WavelengthClient;
+    /** The current immutable state snapshot. */
+    getSnapshot(): WalletSnapshot;
+    /** Subscribes to snapshot changes; returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Starts the runtime. Falls back to the engine's configured config when
+     * called without an argument; throws if neither exists. A failure moves the
+     * phase to 'error' and rejects.
+     */
+    start(config?: RuntimeConfig): Promise<WalletInfo>;
+    /** Stops the runtime and clears the in-memory snapshot (info, balance, activity, error); persisted wallet data is untouched. A failure moves the phase to 'error'. */
+    stop(): Promise<void>;
+    /** Re-fetches info, balance, and activity concurrently. */
+    refresh(): Promise<void>;
+    /** Creates a new wallet, refetches info, and refreshes in the background. */
+    createWallet(req: CreateWalletRequest): Promise<CreateWalletResult>;
+    /**
+     * Restores a wallet from a mnemonic. Resolves as soon as the restored
+     * wallet is usable; the optional server-assisted recovery scan continues in
+     * the background, observed through snapshot.recovery. Rejects when the
+     * restore fails before the wallet came up, when a restore is already in
+     * flight, when req.mnemonic is missing or empty, or if the engine has been
+     * disposed.
+     */
+    restoreWallet(req: RestoreWalletRequest): Promise<WalletInfo>;
+    /** Resets snapshot.recovery to idle (e.g. after dismissing a banner). */
+    acknowledgeRecovery(): void;
+    /** Unlocks an existing wallet, refetches info, and refreshes in the background. */
+    unlockWallet(req: UnlockWalletRequest): Promise<UnlockWalletResult>;
+    /** Opens the wallet from a passkey PRF output, refetches info, and refreshes in the background. */
+    openWalletFromPasskey(req: OpenWalletFromPasskeyRequest): Promise<OpenWalletFromPasskeyResult>;
+    /** Requests an on-chain deposit address and refreshes in the background. */
+    deposit(req?: DepositRequest): Promise<DepositResult>;
+    /** Requests a Lightning receive and refreshes in the background. */
+    receive(req: ReceiveRequest): Promise<ReceiveResult>;
+    /** Quotes a payment without dispatching it. No refresh: a quote moves no money. */
+    prepareSend(req: SendRequest): Promise<PrepareSendResult>;
+    /** Dispatches a payment quoted by prepareSend and refreshes in the background. */
+    sendPrepared(prepared: PrepareSendResult): Promise<SendResult>;
+    /** Sends a payment and refreshes in the background. */
+    send(req: SendRequest): Promise<SendResult>;
+    /** Starts a single exit (cooperative or unilateral) and refreshes wallet state. */
+    exit(req: ExitRequest): Promise<ExitResult>;
+    /** Queries the status of an exit. Read-only; does not refresh. */
+    exitStatus(req: ExitStatusRequest): Promise<ExitStatusResult>;
+    /** Summarizes all in-progress exits. Read-only; does not refresh. */
+    exitSummary(req?: ExitSummaryRequest): Promise<ExitSummaryResult>;
+    /** Previews unilateral-exit readiness and funding. Read-only; does not refresh. */
+    getExitPlan(req: GetExitPlanRequest): Promise<GetExitPlanResult>;
+    /** Previews (broadcast:false) or broadcasts (broadcast:true) a backing-wallet sweep. Refreshes only when broadcasting. */
+    sweepWallet(req: SweepWalletRequest): Promise<SweepWalletResult>;
+    /**
+     * Starts a batch of exits, refreshing wallet state after each one starts.
+     * Resolves once every exit is started, not completed.
+     */
+    exitBatch(opts: ExitBatchOptions & {
+        signal?: AbortSignal;
+        onEvent?: (event: ExitBatchEvent) => void;
+    }): Promise<ExitBatchResult>;
+    /** Lists wallet activity, VTXOs, or on-chain outputs. Read-only; does not refresh. */
+    list(req: ListRequest): Promise<ListResult>;
+    /** Clears the buffered log tail. */
+    clearLogs(): void;
+    /** Tears down subscriptions, polls, and streams. The engine is done after this. */
+    dispose(): void;
+}
+/** Creates a {@link WalletEngine} over any transport client. */
+export declare function createWalletEngine(options: WalletEngineOptions): WalletEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine/engine.ts"],"names":[],"mappings":"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"}