@lightninglabs/wavelength-core 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2026 Lightning Labs and The Lightning Network Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @lightninglabs/wavelength-core
+
+The contract at the base of the [Wavelength](https://wavelength.lightning.engineering) SDK: a
+self-custodial Lightning wallet you embed directly in your app, so your users
+send and receive Lightning payments with no node to run, no channels to open,
+and no inbound liquidity to manage, while their keys stay on their own device.
+
+This package is transport- and framework-agnostic. It carries the
+`WavelengthClient` interface, the request/response types, `RuntimeConfig` and
+its per-network endpoint defaults, the errors and enums, and the generated
+daemon types. It has no DOM and no transport of its own.
+
+You usually don't install this package directly. Each transport re-exports
+everything here, so an app imports the client and its types from one place:
+
+- [`@lightninglabs/wavelength-web`](https://www.npmjs.com/package/@lightninglabs/wavelength-web) for the browser (WebAssembly).
+- [`@lightninglabs/wavelength-react-native`](https://www.npmjs.com/package/@lightninglabs/wavelength-react-native) for React Native.
+
+Install it on its own only when you need the types or the client contract
+without a transport, for example in shared code:
+
+```sh
+npm install @lightninglabs/wavelength-core
+```
+
+```ts
+import type { WavelengthClient, RuntimeConfig } from "@lightninglabs/wavelength-core";
+```
+
+See the [documentation](https://wavelength.lightning.engineering) for the full
+API reference.

package/dist/activity-options.d.ts

@@ -0,0 +1,15 @@
+import type { EntryKind } from './generated.ts';
+/** Controls the wallet activity replay, filtering, and resume position. */
+export type ActivityStreamOptions = {
+    /** When true with a zero cursor, replays existing activity before live updates. */
+    includeExisting?: boolean;
+    /** Restricts updates to the selected activity kinds. */
+    kinds?: EntryKind[];
+    /**
+     * Resumes after this monotonic activity cursor, replaying later events before
+     * live updates. Must be a nonnegative safe integer.
+     */
+    cursor?: number;
+};
+export declare function validateActivityStreamOptions(opts: ActivityStreamOptions): void;
+//# sourceMappingURL=activity-options.d.ts.map

package/dist/activity-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-options.d.ts","sourceRoot":"","sources":["../src/activity-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,2EAA2E;AAC3E,MAAM,MAAM,qBAAqB,GAAG;IAClC,mFAAmF;IACnF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,qBAAqB,GAC1B,IAAI,CAUN"}

package/dist/activity-options.js

@@ -0,0 +1,7 @@
+import { WavelengthError } from "./errors.js";
+export function validateActivityStreamOptions(opts) {
+    if (opts.cursor !== undefined &&
+        (!Number.isSafeInteger(opts.cursor) || opts.cursor < 0)) {
+        throw new WavelengthError('activity cursor must be a nonnegative safe integer', 'invalid_cursor');
+    }
+}

package/dist/base-client.d.ts

@@ -0,0 +1,59 @@
+import type { CreateWalletRequest, DepositRequest, ExitRequest, ExitStatusRequest, ExitSummaryRequest, GetExitPlanRequest, ListRequest, OpenWalletFromPasskeyRequest, ReceiveRequest, SendRequest, SweepWalletRequest, UnlockWalletRequest } from './requests.ts';
+import type { Balance, CreateWalletResult, DepositResult, ExitResult, ExitStatusResult, ExitSummaryResult, GetExitPlanResult, ListResult, OpenWalletFromPasskeyResult, PrepareSendResult, ReceiveResult, SendResult, SweepWalletResult, UnlockWalletResult } from './results.ts';
+import { type RuntimeConfig } from './config.ts';
+import type { WavelengthClient } from './client.ts';
+import type { WavelengthEvent, WavelengthListener } from './events.ts';
+import type { WalletInfo, WalletStatus } from './state.ts';
+import type { FacadeMethod, ServerTransport } from './facade.ts';
+import type { Entry } from './generated.ts';
+import { type ActivityStreamOptions } from './activity-options.ts';
+/**
+ * Implements the transport-agnostic half of {@link WavelengthClient}: every RPC
+ * verb is expressed in terms of the abstract invokeFacade, so a transport (web
+ * wasm, React Native gomobile, or a future one) supplies only the pipe:
+ * invokeFacade, ready, the activity-stream plumbing, and its {@link ServerTransport}
+ * flavor. The shared subscribe/emit listener machinery and typed wrappers live
+ * here. The facade catalog, public contract, native dispatch, and response
+ * normalization remain separate synchronization points.
+ */
+export declare abstract class BaseWavelengthClient implements WavelengthClient {
+    protected readonly listeners: Set<WavelengthListener>;
+    abstract ready(): Promise<void>;
+    protected abstract invokeFacade<T = unknown>(method: FacadeMethod, params?: unknown): Promise<T>;
+    protected abstract openActivityStream(opts: ActivityStreamOptions): Promise<void>;
+    abstract stopActivity(): void;
+    /** How this transport's daemon dials the Ark and swap servers. */
+    protected abstract readonly serverTransport: ServerTransport;
+    callFacade<T = unknown>(method: FacadeMethod, params?: unknown): Promise<T>;
+    isRunning(): Promise<boolean>;
+    startActivity(opts?: ActivityStreamOptions): 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>;
+    subscribe(listener: WavelengthListener): () => void;
+    protected emit(event: WavelengthEvent): void;
+    protected normalizeActivityEntry(raw: unknown): Entry;
+    /**
+     * Closes the activity stream and unsubscribes all listeners. The concrete
+     * transports override this to also tear down their runtime (terminate the
+     * Worker, or drop the main-thread runtime listener).
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=base-client.d.ts.map

package/dist/base-client.d.ts.map

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

package/dist/base-client.js

@@ -0,0 +1,144 @@
+import { validateRuntimeConfig } from "./config.js";
+import { assertFacadeMethod, toGoCreateWalletReq, toGoUnlockWalletReq, toMobileConfig, } from "./facade.js";
+import { errorMessage } from "./errors.js";
+import { normalizeEntry, normalizeFacadeResult, } from "./response-normalization.js";
+import { validateActivityStreamOptions, } from "./activity-options.js";
+/**
+ * Implements the transport-agnostic half of {@link WavelengthClient}: every RPC
+ * verb is expressed in terms of the abstract invokeFacade, so a transport (web
+ * wasm, React Native gomobile, or a future one) supplies only the pipe:
+ * invokeFacade, ready, the activity-stream plumbing, and its {@link ServerTransport}
+ * flavor. The shared subscribe/emit listener machinery and typed wrappers live
+ * here. The facade catalog, public contract, native dispatch, and response
+ * normalization remain separate synchronization points.
+ */
+export class BaseWavelengthClient {
+    listeners = new Set();
+    async callFacade(method, params = {}) {
+        assertFacadeMethod(method);
+        const raw = await this.invokeFacade(method, params);
+        return normalizeFacadeResult(method, raw);
+    }
+    isRunning() {
+        return this.callFacade('isRunning');
+    }
+    async startActivity(opts = {}) {
+        validateActivityStreamOptions(opts);
+        await this.openActivityStream(opts);
+    }
+    // start boots the embedded daemon and returns the post-boot WalletInfo. The
+    // facade's start verb resolves nothing useful on its own, so the client
+    // fetches getInfo afterwards; the React provider derives the runtime phase
+    // from it.
+    async start(config) {
+        validateRuntimeConfig(config, this.serverTransport);
+        await this.callFacade('start', toMobileConfig(config, this.serverTransport));
+        return this.getInfo();
+    }
+    async stop() {
+        await this.callFacade('stop');
+        this.emit({ type: 'runtimeStopped' });
+    }
+    getInfo() {
+        return this.callFacade('getInfo');
+    }
+    status() {
+        return this.callFacade('status');
+    }
+    balance() {
+        // The daemon's Balance shape; generated.ts is the field source of truth.
+        return this.callFacade('balance');
+    }
+    createWallet(req) {
+        return this.callFacade('createWallet', toGoCreateWalletReq(req));
+    }
+    unlockWallet(req) {
+        return this.callFacade('unlockWallet', toGoUnlockWalletReq(req));
+    }
+    openWalletFromPasskey(req) {
+        return this.callFacade('openWalletFromPasskey', req);
+    }
+    deposit(req = {}) {
+        return this.callFacade('deposit', req);
+    }
+    receive(req) {
+        return this.callFacade('receive', req);
+    }
+    // prepareSend quotes a payment without dispatching it, returning the fee and a
+    // single-use sendIntentId. Pair it with sendPrepared for a quote -> confirm ->
+    // pay flow; send() folds the two steps into one.
+    prepareSend(req) {
+        return this.callFacade('prepareSend', req);
+    }
+    // sendPrepared dispatches a payment quoted by prepareSend. It folds the
+    // prepare-time paymentHash into the result so a two-step caller sees the same
+    // shape send() returns (the daemon omits PaymentHash from sendPrepared).
+    async sendPrepared(prepared) {
+        const result = await this.callFacade('sendPrepared', {
+            SendIntentID: prepared.sendIntentId,
+        });
+        return {
+            ...result,
+            paymentHash: result.paymentHash ?? prepared.paymentHash,
+        };
+    }
+    // send composes prepareSend + sendPrepared into one call for the common
+    // fire-and-forget path.
+    async send(req) {
+        return this.sendPrepared(await this.prepareSend(req));
+    }
+    list(req = {}) {
+        return this.callFacade('list', req);
+    }
+    exit(req) {
+        return this.callFacade('exit', req);
+    }
+    exitStatus(req) {
+        return this.callFacade('exitStatus', req);
+    }
+    exitSummary(req = {}) {
+        return this.callFacade('exitSummary', req);
+    }
+    getExitPlan(req) {
+        return this.callFacade('getExitPlan', req);
+    }
+    sweepWallet(req) {
+        return this.callFacade('sweepWallet', req);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                // Isolate a throwing subscriber so it cannot suppress the others or
+                // abort the transport's event dispatch. Reported as a log event
+                // unless the log listener itself is the one that threw.
+                if (event.type !== 'log') {
+                    this.emit({
+                        type: 'log',
+                        payload: { level: 'error', message: errorMessage(err) },
+                    });
+                }
+            }
+        }
+    }
+    normalizeActivityEntry(raw) {
+        return normalizeEntry(raw);
+    }
+    /**
+     * Closes the activity stream and unsubscribes all listeners. The concrete
+     * transports override this to also tear down their runtime (terminate the
+     * Worker, or drop the main-thread runtime listener).
+     */
+    dispose() {
+        this.stopActivity();
+        this.listeners.clear();
+    }
+}

package/dist/casing.d.ts

@@ -0,0 +1,4 @@
+export declare const ACRONYM_OVERRIDES: Record<string, string>;
+export declare function camelKey(name: string): string;
+export declare function camelizeKeys<T = unknown>(value: unknown): T;
+//# sourceMappingURL=casing.d.ts.map

package/dist/casing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"casing.d.ts","sourceRoot":"","sources":["../src/casing.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIpD,CAAC;AAIF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAU7C;AAKD,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAE3D"}

package/dist/casing.js

@@ -0,0 +1,42 @@
+// Shared PascalCase -> camelCase logic, used by BOTH the type generator
+// (scripts/gen-types.mts, at build time) and the runtime response mapping
+// (the shared base client, after transport invocation). One implementation
+// guarantees the generated types and the values the client returns always agree.
+// ACRONYM_OVERRIDES holds field names where a plain lowercase-first-letter would
+// read wrong. Extend this when a new acronym-led field appears (a stale entry is
+// harmless -- the name just falls back to lowercase-first).
+export const ACRONYM_OVERRIDES = {
+    ID: 'id',
+    VTXOs: 'vtxos',
+    SendIntentID: 'sendIntentId',
+};
+// camelKey converts one Go/PascalCase field name to camelCase. Most names just
+// lowercase the first letter; ACRONYM_OVERRIDES covers the few that need more.
+export function camelKey(name) {
+    if (Object.prototype.hasOwnProperty.call(ACRONYM_OVERRIDES, name)) {
+        return ACRONYM_OVERRIDES[name];
+    }
+    if (!name) {
+        return name;
+    }
+    return name.charAt(0).toLowerCase() + name.slice(1);
+}
+// camelizeKeys recursively rewrites object keys to camelCase via camelKey.
+// Arrays are walked; primitives pass through unchanged. This maps the daemon's
+// PascalCase JSON responses onto the SDK's camelCase public shapes.
+export function camelizeKeys(value) {
+    return camelize(value);
+}
+function camelize(value) {
+    if (Array.isArray(value)) {
+        return value.map(camelize);
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, val] of Object.entries(value)) {
+            out[camelKey(key)] = camelize(val);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/client.d.ts

@@ -0,0 +1,90 @@
+import type { WavelengthListener } from './events.ts';
+import type { RuntimeConfig } from './config.ts';
+import type { FacadeMethod } from './facade.ts';
+import type { WalletInfo, WalletStatus } from './state.ts';
+import type { ActivityStreamOptions } from './activity-options.ts';
+import type { CreateWalletRequest, DepositRequest, ExitRequest, ExitStatusRequest, ExitSummaryRequest, GetExitPlanRequest, ListRequest, OpenWalletFromPasskeyRequest, ReceiveRequest, SendRequest, SweepWalletRequest, UnlockWalletRequest } from './requests.ts';
+import type { Balance, CreateWalletResult, DepositResult, ExitResult, ExitStatusResult, ExitSummaryResult, GetExitPlanResult, ListResult, OpenWalletFromPasskeyResult, PrepareSendResult, ReceiveResult, SendResult, SweepWalletResult, UnlockWalletResult } from './results.ts';
+/**
+ * The framework-agnostic contract every Wavelength transport implements. It wraps
+ * the embedded daemon's lifecycle, wallet operations, and activity stream behind
+ * typed, camelCase-normalized methods.
+ */
+export interface WavelengthClient {
+    /** Resolves once the runtime assets are loaded and the client is usable. */
+    ready(): Promise<void>;
+    /** Starts the embedded daemon with the given config and resolves with its initial info. */
+    start(config: RuntimeConfig): Promise<WalletInfo>;
+    /** Stops the embedded daemon. */
+    stop(): Promise<void>;
+    /** 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>;
+    /** Creates a new wallet from the given request. */
+    createWallet(req: CreateWalletRequest): Promise<CreateWalletResult>;
+    /** Unlocks an existing wallet with the given password. */
+    unlockWallet(req: UnlockWalletRequest): Promise<UnlockWalletResult>;
+    /** Opens a wallet from a passkey assertion. */
+    openWalletFromPasskey(req: OpenWalletFromPasskeyRequest): Promise<OpenWalletFromPasskeyResult>;
+    /** Generates an on-chain deposit address. */
+    deposit(req?: DepositRequest): Promise<DepositResult>;
+    /** Generates a receive invoice for the requested amount. */
+    receive(req: ReceiveRequest): Promise<ReceiveResult>;
+    /**
+     * Quotes a payment without dispatching it: it returns the fee and a single-use
+     * sendIntentId. Pair it with {@link sendPrepared} for a quote -> confirm -> pay
+     * flow; {@link send} folds the two steps into one call.
+     */
+    prepareSend(req: SendRequest): Promise<PrepareSendResult>;
+    /** Dispatches a payment previously quoted by {@link prepareSend}. */
+    sendPrepared(prepared: PrepareSendResult): Promise<SendResult>;
+    /** Quotes and dispatches a payment in a single call. */
+    send(req: SendRequest): Promise<SendResult>;
+    /** Lists wallet activity or UTXOs per the request. */
+    list(req?: ListRequest): Promise<ListResult>;
+    /** Exits a single outpoint, attempting a cooperative leave to the optional destination. */
+    exit(req: ExitRequest): Promise<ExitResult>;
+    /** Queries the status of an exit. */
+    exitStatus(req: ExitStatusRequest): Promise<ExitStatusResult>;
+    /**
+     * 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.
+     */
+    exitSummary(req?: ExitSummaryRequest): Promise<ExitSummaryResult>;
+    /**
+     * Previews unilateral-exit readiness (and the backing-wallet funding required)
+     * for a set of VTXO outpoints, without moving funds.
+     */
+    getExitPlan(req: GetExitPlanRequest): Promise<GetExitPlanResult>;
+    /**
+     * Previews or broadcasts a sweep of the backing wallet. Call it with
+     * `broadcast: false` first to preview; `broadcast: true` moves funds.
+     */
+    sweepWallet(req: SweepWalletRequest): Promise<SweepWalletResult>;
+    /** Invokes a portable daemon facade method with a normalized response. */
+    callFacade<T = unknown>(method: FacadeMethod, params?: unknown): Promise<T>;
+    /** Reports whether the embedded daemon is running. */
+    isRunning(): Promise<boolean>;
+    /** Subscribes a listener to runtime events; returns an unsubscribe function. */
+    subscribe(listener: WavelengthListener): () => void;
+    /**
+     * Opens the wallet activity stream and forwards each entry to subscribers as an
+     * `'activity'` event until {@link stopActivity} is called.
+     */
+    startActivity(opts?: ActivityStreamOptions): Promise<void>;
+    /** Closes the activity stream opened by {@link startActivity}. */
+    stopActivity(): void;
+    /**
+     * Releases the client's resources and unsubscribes all listeners: it closes
+     * the activity stream, and transports tear down their runtime resources (the
+     * web transport terminates its Worker; the native transport removes its
+     * event subscription). The client is unusable afterward; build a new one to
+     * start again.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1 @@
+export {};

package/dist/config.d.ts

@@ -0,0 +1,128 @@
+import type { ServerTransport } from './facade.ts';
+/**
+ * Selects the Bitcoin network the embedded daemon runs against. Names match
+ * the daemon's network selector: 'testnet' is Bitcoin testnet3 and 'testnet4'
+ * is Bitcoin testnet4.
+ */
+export type Network = 'mainnet' | 'testnet' | 'testnet4' | 'signet' | 'regtest';
+/**
+ * The networks that carry a public endpoint preset, and so can be passed to a
+ * transport package's defaultConfig helper. mainnet and regtest are excluded:
+ * mainnet has no public deployment yet, and regtest's ports vary per
+ * development environment. A {@link RuntimeConfig} for either is built by hand.
+ */
+export type PresetNetwork = 'testnet' | 'testnet4' | 'signet';
+/**
+ * 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 declare const DEBUG_LEVELS: readonly ["trace", "debug", "info", "warn", "error", "critical", "off"];
+/** One of the daemon log verbosity levels in {@link DEBUG_LEVELS}. */
+export type DebugLevel = (typeof DEBUG_LEVELS)[number];
+/**
+ * The configuration passed to `client.start()`. For the common case prefer
+ * the defaultConfig helper exported by your transport package (wavelength-web
+ * or wavelength-react-native), which preloads the canonical public endpoints
+ * in that transport's flavor, and override only the fields you need.
+ */
+export type RuntimeConfig = {
+    /** The Bitcoin network to run against. `mainnet` also requires {@link allowMainnet}. */
+    network?: Network;
+    /** Explicitly permits mainnet. The SDK rejects mainnet configs unless this is true. */
+    allowMainnet?: boolean;
+    /**
+     * Storage root for daemon and wallet state. This is an OPFS path on web and
+     * a filesystem path on React Native. The daemon chooses a default when unset.
+     */
+    dataDir?: string;
+    /**
+     * Daemon log verbosity. Accepts a standard {@link DebugLevel} or a
+     * per-subsystem expression such as `ROND=debug,info`.
+     */
+    debugLevel?: string;
+    /**
+     * Ark operator and mailbox endpoint. Use a REST URL on web and a `host:port`
+     * gRPC address on React Native. The daemon network default is used when unset.
+     */
+    arkServerAddress?: string;
+    /** Filesystem path to an Ark TLS certificate. The web transport rejects it. */
+    arkServerTlsCertPath?: string;
+    /** Disables TLS for the Ark endpoint. Use only for local development. */
+    arkServerInsecure?: boolean;
+    /** Embedded wallet backend. Defaults to `lwwallet`. */
+    walletType?: 'lwwallet' | 'btcwallet';
+    /** HTTP Esplora endpoint used by the `lwwallet` backend on both platforms. */
+    walletEsploraUrl?: string;
+    /** Password file used by `lwwallet` to unlock automatically. */
+    walletPasswordFile?: string;
+    /**
+     * Chain polling interval in seconds for `lwwallet`. Must be a nonnegative
+     * safe integer.
+     */
+    walletPollIntervalSeconds?: number;
+    /**
+     * Wallet address look-ahead window for either backend. Must be a
+     * nonnegative safe integer that fits in a uint32.
+     */
+    walletRecoveryWindow?: number;
+    /** Fee estimator endpoint used by the `btcwallet` backend. */
+    walletFeeUrl?: string;
+    /**
+     * Local file path or HTTP(S) URL from which `btcwallet` imports block
+     * headers on startup.
+     */
+    walletBlockHeadersSource?: string;
+    /**
+     * Local file path or HTTP(S) URL from which `btcwallet` imports compact
+     * filter headers on startup.
+     */
+    walletFilterHeadersSource?: string;
+    /**
+     * Lightning swap endpoint. Use a REST URL on web and a `host:port` gRPC
+     * address on React Native. The daemon network default is used when unset.
+     */
+    swapServerAddress?: string;
+    /**
+     * Filesystem path to a swap-server TLS certificate. Web rejects it unless
+     * swaps are disabled, in which case every swap field is omitted.
+     */
+    swapServerTlsCertPath?: string;
+    /** Disables TLS for the swap endpoint. Use only for local development. */
+    swapServerInsecure?: boolean;
+    /** Path to the daemon-owned SQLite database that stores swap state. */
+    swapDatabaseFileName?: string;
+    /** Disables Lightning swaps and omits every swap configuration field. */
+    disableSwaps?: boolean;
+    /**
+     * Maximum per-round operator fee the daemon accepts, in satoshis. Must be a
+     * nonnegative safe integer.
+     */
+    maxOperatorFeeSat?: number;
+    /**
+     * Maximum concurrent VTXO signing sessions. Zero selects the wallet-backend
+     * default and one forces serial signing.
+     */
+    signingWorkers?: number;
+    /** Bufconn listener buffer size override. Must be a nonnegative safe integer. */
+    bufferSize?: number;
+};
+/** Validates host-owned runtime settings before the typed start dispatches. */
+export declare function validateRuntimeConfig(config: RuntimeConfig, transport: ServerTransport): void;
+/**
+ * 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 declare function networkDefaults(network: PresetNetwork, transport: ServerTransport): Partial<RuntimeConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;GAIG;AACH,MAAM,MAAM,OAAO,GACf,SAAS,GACT,SAAS,GACT,UAAU,GACV,QAAQ,GACR,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,yEAQf,CAAC;AAEX,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,wFAAwF;IACxF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uFAAuF;IACvF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uDAAuD;IACvD,UAAU,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;IACtC,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAwBF,+EAA+E;AAC/E,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,eAAe,GACzB,IAAI,CA8CN;AA8DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,eAAe,GACzB,OAAO,CAAC,aAAa,CAAC,CAQxB"}