@qntx/wallet-engine 0.0.0-stage → 0.4.0

package/dist/index.d.mts

@@ -0,0 +1,758 @@
+import { StoreApi } from "zustand/vanilla";
+import { CooperativeExitResult, LightningInvoice, LightningPayment, SparkClient, SparkExitChain, SparkNetwork, SparkPayment, SparkStore, SparkTransfer } from "@qntx/spark";
+import { NostrKeyRef, WalletSigner } from "@qntx/wallet/nostr";
+import { SparkSigner } from "@qntx/wallet/spark";
+import { BackupHeader, BackupInfo, InitialFactor, UnlockFactor, Wallet, WalletInfo } from "@qntx/wallet";
+import { Event, Filter, NostrSigner } from "@qntx/nostr";
+import { LnurlPayRequest, LnurlWithdrawRequest } from "@qntx/spark/lnurl";
+import { SparkAccountRef, SparkApproveIntent } from "@qntx/wallet/protocol";
+//#region src/controller.d.ts
+type ControllerOptions<S> = {
+  readonly name: string;
+  readonly defaultState: () => S;
+};
+/**
+ * Controller base: a zustand vanilla store plus lifecycle. `update` applies a recipe that must
+ * return a NEW state object; returning the same reference is a no-op (no set, no notification).
+ * Persistence and migrations layer on later — this package carries only what its first user needs.
+ */
+export declare abstract class Controller<S extends Record<string, unknown>> {
+  readonly name: string;
+  readonly store: StoreApi<S>;
+  protected constructor(options: ControllerOptions<S>);
+  getState(): S;
+  protected update(recipe: (state: S) => S): void;
+  abstract init(): Promise<void>;
+  abstract destroy(): Promise<void>;
+}
+//#endregion
+//#region src/events.d.ts
+/** Log port: listener failures are reported here and never reach the emitter or peers. */
+type EngineLogger = {
+  readonly warn: (message: string, error?: unknown) => void;
+};
+type EventBus<E> = {
+  /** Synchronous dispatch to every current listener in registration order. */
+  emit: <K extends keyof E>(type: K, payload: E[K]) => void;
+  on: <K extends keyof E>(type: K, listener: (payload: E[K]) => void) => () => void;
+};
+export declare function createEventBus<E>(logger: EngineLogger): EventBus<E>;
+//#endregion
+//#region src/errors.d.ts
+type EngineErrorCode = "closed" | "integrity" | "invalid-input";
+/** Typed engine errors: store codes are `closed` and `integrity` (decrypt or bind failure). */
+export declare class EngineStoreError extends Error {
+  readonly code: EngineErrorCode;
+  constructor(code: EngineErrorCode, message: string);
+}
+//#endregion
+//#region src/store/port.d.ts
+/**
+ * Engine storage port: named collections of byte values. `collection` is synchronous and cheap —
+ * the same collection object backs every call, so guards (closed) live on the store.
+ */
+type EngineCollection = {
+  readonly get: (key: string) => Promise<Uint8Array | undefined>;
+  readonly put: (key: string, bytes: Uint8Array) => Promise<void>;
+  readonly delete: (key: string) => Promise<void>;
+  /** Every key in the collection, in an unspecified order. */
+  readonly list: () => Promise<ReadonlyArray<string>>;
+};
+type EngineStore = {
+  readonly collection: (name: string) => EngineCollection;
+  readonly close: () => Promise<void>;
+};
+//#endregion
+//#region src/store/memory.d.ts
+/** In-memory EngineStore: the Node/test implementation — same contract, no durability. */
+export declare function createMemoryEngineStore(backing?: {
+  readonly collections?: Map<string, Map<string, Uint8Array>>;
+}): EngineStore;
+//#endregion
+//#region src/meta/doc.d.ts
+/**
+ * Wallet metadata document — the plaintext exchanged over kind-30078 events between this wallet's
+ * own devices. One document per wallet; entry-level last-writer-wins on `updatedAt`.
+ */
+type MetaDocWallet = {
+  readonly name?: string;
+  readonly updatedAt: number;
+};
+type MetaDocGroup = {
+  readonly index: number;
+  readonly name?: string;
+  readonly hidden: boolean;
+  readonly boundPubkey?: string;
+  readonly updatedAt: number;
+};
+type MetaDoc = {
+  readonly v: 1;
+  readonly wallet: MetaDocWallet;
+  readonly groups: ReadonlyArray<MetaDocGroup>;
+};
+//#endregion
+//#region src/spark/notes.d.ts
+/**
+ * Local, engine-side metadata pinned to a history entry by transfer id. Written after the payment
+ * it annotates has already succeeded — a missing or malformed note must never affect the payment
+ * itself.
+ */
+type PaymentNote = {
+  readonly kind: "zap";
+  /** 64 lowercase hex. */
+  readonly recipientPubkey: string;
+  /** 64 lowercase hex — event zaps carry the zapped event's id. */
+  readonly eventId?: string;
+  /** At most 2000 characters. */
+  readonly comment?: string;
+  /** The lud16 or LNURL the zap resolved. */
+  readonly lightning: string;
+};
+type SparkActivity = SparkPayment & {
+  readonly note?: PaymentNote;
+};
+//#endregion
+//#region src/spark/store.d.ts
+/**
+ * SparkStore over one EngineCollection: chains keyed by leafId, plus an index record listing them
+ * (`exitChains` is a full listing — the port has no secondary index).
+ */
+export declare function sparkStore(col: EngineCollection): SparkStore;
+//#endregion
+//#region src/spark/controller.d.ts
+type SparkAccountState = {
+  readonly status: "locked" | "connecting" | "ready" | "error";
+  readonly balanceSats?: number;
+  readonly identityPublicKey?: string;
+  readonly sparkAddress?: string;
+  readonly errorCategory?: string;
+  /** First history page (20 entries, newest first), refreshed alongside the balance. */
+  readonly recent?: ReadonlyArray<SparkActivity>;
+};
+type SparkControllerState = {
+  readonly accounts: Readonly<Record<string, SparkAccountState>>;
+};
+type SparkApis = {
+  readonly signer: (ref: SparkAccountRef) => SparkSigner;
+  readonly approve: (params: {
+    account: SparkAccountRef;
+    intent: SparkApproveIntent;
+    verify: UnlockFactor;
+  }) => Promise<unknown>;
+};
+type SparkClientFactory = (options: {
+  readonly ref: SparkAccountRef;
+  readonly store: ReturnType<typeof sparkStore>;
+  readonly signer: SparkSigner;
+  readonly fetch: typeof globalThis.fetch;
+}) => SparkClient;
+type SparkControllerOptions = {
+  readonly spark: SparkApis;
+  readonly fetch: typeof globalThis.fetch;
+  readonly random: (length: number) => Uint8Array;
+  readonly now: () => number;
+  readonly logger: EngineLogger;
+  readonly createClient: SparkClientFactory;
+};
+export declare class SparkController extends Controller<SparkControllerState> {
+  private readonly options;
+  private engineStore;
+  private readonly accounts;
+  private readonly clients;
+  private readonly recentSeq;
+  private readonly aborts;
+  constructor(options: SparkControllerOptions);
+  /** Engine calls this with the open store on unlock; `undefined` on lock. */
+  setStore(store: EngineStore | undefined): void;
+  /**
+   * Declarative account set: refs not yet tracked are patched `locked` and started when the store
+   * is open; tracked refs no longer listed are stopped and dropped; running refs stay untouched.
+   */
+  setAccounts(refs: ReadonlyArray<SparkAccountRef>): void;
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  private stopAccount;
+  /** Lock: abort every event loop, close every client, reset state. */
+  lockAll(): Promise<void>;
+  private startAccount;
+  private runEvents;
+  private handleTransfer;
+  private notesCollection;
+  /** Attach locally written notes to a history page; malformed records warn and drop. */
+  private withNotes;
+  /**
+   * Refill `recent` from the first history page. A failure keeps the previous page — it never
+   * touches `status`/`errorCategory`. A per-account sequence keeps a slower older refresh from
+   * overwriting a newer one.
+   */
+  private refreshRecent;
+  private patch;
+  private clientFor;
+  private guarded;
+  /**
+   * One-off balance + activity probe for an account that may not be running: builds a temporary
+   * client through the same factory on the account's own exit-chain collection (nothing diverges —
+   * `balance()`/`transfers.history` never write it), reads, and closes it in `finally`.
+   */
+  inspect(ref: SparkAccountRef): Promise<{
+    balanceSats: number;
+    used: boolean;
+  }>;
+  /** History for one account: a client page merged with locally written notes by id. */
+  history(ref: SparkAccountRef, options?: {
+    readonly limit?: number;
+    readonly offset?: number;
+  }): Promise<{
+    readonly items: ReadonlyArray<SparkActivity>;
+    readonly nextOffset: number | undefined;
+  }>;
+  send(ref: SparkAccountRef, params: {
+    receiver: string;
+    amountSats: number;
+    verify: UnlockFactor;
+  }): Promise<SparkTransfer>;
+  registerLightningAddress(ref: SparkAccountRef, params: {
+    serverUrl: string;
+    domain: string;
+    username: string;
+    description: string;
+  }): Promise<{
+    lnurl: string;
+    lightningAddress: string;
+  }>;
+  unregisterLightningAddress(ref: SparkAccountRef, params: {
+    serverUrl: string;
+    domain: string;
+    username: string;
+  }): Promise<void>;
+  payInvoice(ref: SparkAccountRef, params: {
+    invoice: string;
+    amountSats?: number;
+    maxFeeSats: number;
+    verify: UnlockFactor;
+    /** Local annotation written under the payment's transfer id after it succeeds. */
+    note?: PaymentNote;
+  }): Promise<LightningPayment>;
+  /**
+   * Pays a Spark invoice address. The approval intent mirrors `send`: receiver identity and amount
+   * come from the parsed invoice (the supplied `amountSats` fills an open invoice). Then
+   * `client.invoices.pay` executes it.
+   */
+  paySparkInvoice(ref: SparkAccountRef, params: {
+    invoice: string;
+    amountSats?: number;
+    verify: UnlockFactor;
+  }): Promise<SparkTransfer>;
+  createInvoice(ref: SparkAccountRef, params: {
+    amountSats: number;
+    memo?: string;
+  }): Promise<LightningInvoice>;
+  receiveAddress(ref: SparkAccountRef): Promise<string | undefined>;
+  /**
+   * Cooperative exit to an L1 address. The client exits `amountSats` of leaves and the payout is
+   * `amountSats - fee`, so the approval intent carries the PAYOUT: `amountSats: exit - fee` and
+   * `maxFeeSats: fee` — the kernel matches the exit output against the intent, not the leaf total.
+   */
+  withdraw(ref: SparkAccountRef, params: {
+    address: string;
+    amountSats?: number;
+    speed: "FAST" | "MEDIUM" | "SLOW";
+    maxFeeSats?: number;
+    verify: UnlockFactor;
+  }): Promise<CooperativeExitResult>;
+}
+//#endregion
+//#region src/accounts/controller.d.ts
+type AccountGroup = {
+  readonly walletId: string;
+  readonly index: number;
+  readonly name?: string;
+  readonly hidden: boolean;
+  /** A social identity (64 lowercase hex) bound to this group; one identity binds one group. */
+  readonly boundPubkey?: string;
+  /** Last local modification time (ms); reconcile-created entries start at 0. */
+  readonly updatedAt: number;
+};
+type AccountTreeState = {
+  readonly status: "locked" | "ready";
+  readonly wallets: ReadonlyArray<{
+    readonly walletId: string;
+    readonly name?: string;
+    readonly updatedAt: number;
+  }>;
+  readonly groups: Readonly<Record<string, ReadonlyArray<AccountGroup>>>;
+  readonly selected: {
+    readonly walletId: string;
+    readonly groupIndex: number;
+  } | null;
+  readonly totals: Readonly<Record<string, number>>;
+};
+type AccountTreeControllerOptions = {
+  readonly wallet: Wallet;
+  readonly spark: SparkController;
+  readonly sparkNetwork: SparkNetwork;
+  readonly logger: EngineLogger;
+  readonly now: () => number;
+};
+/**
+ * Declarative account tree: wallets come from the Wallet snapshot (reconciled on unlock and on
+ * every snapshot change while unlocked), groups/names/hidden/selected/totals persist to the engine
+ * store under `accounts/tree`. The controller drives `spark.setAccounts` with the selected group
+ * only — an unselected group needs no live client (incoming transfers are claimed whenever it is
+ * selected again). The active account's `balanceSats` feeds `totals`, debounced 1 s before
+ * persist.
+ */
+export declare class AccountTreeController extends Controller<AccountTreeState> {
+  private readonly options;
+  private col;
+  private sparkUnsubscribe;
+  private totalsTimer;
+  private persistChain;
+  constructor(options: AccountTreeControllerOptions);
+  setStore(store: EngineStore | undefined): void;
+  /** Load persisted state, reconcile with the snapshot, start driving Spark. */
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  /** Locked: stop every Spark client, flush pending persists, then drop to the empty state. */
+  lock(): Promise<void>;
+  /** Reconcile groups/names/selected with `wallet.getSnapshot().wallets`; persists on change. */
+  reconcile(): void;
+  addGroup(walletId: string): number;
+  addGroups(walletId: string, indices: ReadonlyArray<number>): void;
+  renameWallet(walletId: string, name: string): void;
+  renameGroup(walletId: string, index: number, name: string): void;
+  setHidden(walletId: string, index: number, hidden: boolean): void;
+  select(walletId: string, index: number): void;
+  /**
+   * Binds a social identity to one group. The identity is unique across the whole tree — every
+   * group in every wallet carrying it loses the binding (each entry re-stamped).
+   */
+  bind(walletId: string, index: number, pubkey: string): void;
+  unbind(walletId: string, index: number): void;
+  /**
+   * Which group currently holds a pubkey — merges can leave the same identity on groups in two
+   * wallets; the newest `updatedAt` wins, ties resolve by snapshot wallet order then lower index.
+   */
+  bindingOf(pubkey: string): {
+    walletId: string;
+    groupIndex: number;
+  } | undefined;
+  /** The wallet's metadata document — every group, hidden included. */
+  exportMeta(walletId: string): MetaDoc;
+  /**
+   * Entry-level last-writer-wins merge: a newer remote `updatedAt` replaces the local entry, a tie
+   * keeps local; remote-only groups are added. `selected`/hidden rules are re-validated — if the
+   * merge hides the selected group it is re-selected, and a merge may never leave every group
+   * hidden (the selected one stays visible and is re-stamped so the fix propagates).
+   */
+  mergeMeta(walletId: string, doc: MetaDoc): {
+    changed: boolean;
+    localNewer: boolean;
+  };
+  /** Sequential inspect from 0 upward; index 0 always included; stop after 2 consecutive unused. */
+  discoverSpark(walletId: string): Promise<number[]>;
+  /** Refresh `totals` for every other visible group; per-group failures are logged and skipped. */
+  refreshTotals(): Promise<void>;
+  private onSparkState;
+  private setTotal;
+  private driveSpark;
+  private visibleGroups;
+  private validSelection;
+  private selectFallback;
+  private mutateGroups;
+  private mustWallet;
+  private mustGroup;
+  private checkedName;
+  private load;
+  /** Queues a store write behind the previous one — the last queued write always lands last. */
+  private persist;
+  private scheduleTotalsPersist;
+  private flushTotals;
+}
+//#endregion
+//#region src/backup/errors.d.ts
+/** BackupController error categories — never carry file contents, digests or secrets. */
+type BackupErrorCategory = "cloud" | "conflict" | "unavailable";
+export declare class BackupControllerError extends Error {
+  readonly category: BackupErrorCategory;
+  constructor(category: BackupErrorCategory, message: string);
+}
+//#endregion
+//#region src/backup/port.d.ts
+/**
+ * Cloud-file storage port (design/backup.mdx "存储"): the cloud is an opaque key-value namespace —
+ * names are file names (`qntx-wallet-backup-<id>.json`), contents are envelope texts. The kernel
+ * never sees it; only the engine transports ciphertext across it.
+ */
+type CloudStore = {
+  /** Cloud account usable and the drive reachable. */
+  readonly available: () => Promise<boolean>;
+  /** Every file name in the namespace. */
+  readonly list: () => Promise<ReadonlyArray<string>>;
+  /** File contents, or undefined when the name does not exist. */
+  readonly read: (name: string) => Promise<string | undefined>;
+  /** Overwrites the whole file atomically from the caller's perspective. */
+  readonly write: (name: string, text: string) => Promise<void>;
+  /** Deleting a missing file succeeds. */
+  readonly delete: (name: string) => Promise<void>;
+};
+//#endregion
+//#region src/backup/controller.d.ts
+type BackupControllerState = {
+  readonly status: "locked" | "unavailable" | "off" | "syncing" | "synced" | "conflict" | "error";
+  /** The retained backup key's public summary from the wallet snapshot. */
+  readonly backup: BackupInfo | null;
+  readonly uploadedAt: number | undefined;
+  readonly unprotected: {
+    readonly walletIds: ReadonlyArray<string>;
+    readonly nostrKeyIds: ReadonlyArray<string>;
+  };
+  readonly error: BackupErrorCategory | undefined;
+};
+type BackupControllerOptions = {
+  readonly wallet: Wallet;
+  readonly cloud: CloudStore | undefined;
+  readonly now: () => number;
+  readonly logger: EngineLogger;
+};
+export declare class BackupController extends Controller<BackupControllerState> {
+  private readonly wallet;
+  private readonly cloud;
+  private readonly now;
+  private readonly logger;
+  private engineStore;
+  private generation;
+  private current;
+  private rerun;
+  /** Set by restore() before the store opens — written as a record on the first reconcile. */
+  private pendingAdoption;
+  constructor(options: BackupControllerOptions);
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  /** The engine hands over the store on unlock and takes it back on lock. */
+  setStore(store: EngineStore | undefined): void;
+  /** Bumps the generation: an in-flight reconcile writes nothing after this point. */
+  lock(): void;
+  trigger(): void;
+  private triggerAsync;
+  /** Explicit sync — awaits the run so callers see its outcome. */
+  sync(): Promise<void>;
+  enable(options: {
+    readonly verify: UnlockFactor;
+    readonly factors: ReadonlyArray<UnlockFactor>;
+  }): Promise<void>;
+  disable(): Promise<void>;
+  /** Files under our prefix with a parseable header. */
+  list(): Promise<ReadonlyArray<{
+    readonly name: string;
+    readonly header: BackupHeader;
+  }>>;
+  restore(options: {
+    readonly name: string;
+    readonly backupFactor: UnlockFactor;
+    readonly factor?: InitialFactor;
+  }): Promise<ReadonlyArray<WalletInfo>>;
+  private reconcileOrThrow;
+  private readRecord;
+  private writeRecord;
+  private deleteRecord;
+  private snapshot;
+  private unprotected;
+  private coverage;
+  private setStatus;
+  /**
+   * Single-flight: a trigger during a run flags exactly one rerun inside the same promise, so
+   * `sync()`/`enable()` await real convergence instead of a mid-run snapshot.
+   */
+  private reconcile;
+  private pass;
+}
+//#endregion
+//#region src/meta/errors.d.ts
+/** Meta-sync error categories — messages never carry event or document content. */
+type MetaSyncErrorCategory = "network" | "internal" | "unsupported" | "corrupt";
+export declare class MetaSyncError extends Error {
+  readonly category: MetaSyncErrorCategory;
+  constructor(category: MetaSyncErrorCategory, message: string, cause?: unknown);
+}
+//#endregion
+//#region src/meta/controller.d.ts
+type MetaSyncRelayPort = {
+  readonly fetch: (filter: Filter) => Promise<ReadonlyArray<Event>>;
+  readonly publish: (event: Event) => Promise<void>;
+};
+type MetaSyncConfig = {
+  /** The `d` tag that names this wallet's metadata document. */
+  readonly tag: string;
+  readonly relays: MetaSyncRelayPort;
+};
+type MetaSyncWalletStatus = {
+  readonly status: "unavailable" | "syncing" | "synced" | "error";
+  readonly error?: MetaSyncErrorCategory;
+};
+type MetaSyncState = {
+  readonly wallets: Readonly<Record<string, MetaSyncWalletStatus>>;
+};
+type MetaSyncControllerOptions = {
+  readonly wallet: Wallet;
+  readonly accounts: AccountTreeController;
+  /** `nostr(wallet)` — the signer is requested per wallet for its group-0 derived key. */
+  readonly nostr: {
+    readonly signer: (ref: NostrKeyRef) => WalletSigner;
+  };
+  readonly metaSync: MetaSyncConfig | undefined;
+  readonly logger: EngineLogger;
+  readonly now: () => number;
+};
+/**
+ * Wallet-metadata sync over kind-30078 addressable events: one NIP-44-encrypted document per
+ * wallet, authored by its group-0 derived key. Pull always precedes publish in an unlock session —
+ * replaceable events would otherwise let a stale local tree overwrite a newer remote document.
+ * Debounced publishes are per wallet; a generation counter cancels in-flight write-backs on lock.
+ */
+export declare class MetaSyncController extends Controller<MetaSyncState> {
+  private readonly options;
+  private generation;
+  private readonly pulled;
+  private readonly lastRemoteCreatedAt;
+  private readonly lastExported;
+  private readonly timers;
+  private readonly inflight;
+  private accountsUnsubscribe;
+  constructor(options: MetaSyncControllerOptions);
+  /** Unlocked: pull every wallet whose group-0 identity exists, then watch the tree. */
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  /** Locked: cancel debounces and in-flight write-backs, forget the pull/publish bookkeeping. */
+  lock(): Promise<void>;
+  /** Snapshot changed while unlocked: pull newly-seen wallets, drop removed ones. */
+  reconcile(): void;
+  /** Manual re-pull of every wallet that can sync. */
+  sync(): Promise<void>;
+  private pullAll;
+  private pubkeyFor;
+  private signerFor;
+  private setStatus;
+  private pullOne;
+  private filterFor;
+  private acceptableEvent;
+  /** Snapshot the wallet's exported doc — the debounce publishes only on a real change. */
+  private rememberExport;
+  private onTreeChange;
+  private publishNow;
+}
+//#endregion
+//#region src/payments/parse.d.ts
+type PaymentOption = {
+  readonly kind: "spark";
+  readonly address: string;
+} | {
+  readonly kind: "spark-invoice";
+  readonly invoice: string;
+  readonly amountSats?: number;
+  readonly memo?: string;
+  readonly expiresAt?: number;
+} | {
+  readonly kind: "lightning";
+  readonly invoice: string;
+  readonly amountSats?: number;
+  readonly paymentHash: string;
+  readonly description?: string;
+  readonly expiresAt: number;
+} | {
+  readonly kind: "lnurl-pay";
+  readonly request: LnurlPayRequest;
+  readonly address?: string;
+} | {
+  readonly kind: "lnurl-withdraw";
+  readonly request: LnurlWithdrawRequest;
+} | {
+  readonly kind: "bitcoin";
+  readonly address: string;
+};
+type PaymentRequest = {
+  readonly options: ReadonlyArray<PaymentOption>;
+  readonly amountSats?: number;
+  readonly label?: string;
+  readonly message?: string;
+};
+type PaymentParse = {
+  readonly kind: "request";
+  readonly request: PaymentRequest;
+} | {
+  readonly kind: "lnurl";
+  readonly url: string;
+  readonly address?: string;
+} | {
+  readonly kind: "unsupported";
+  readonly format: "bolt12" | "silent-payment" | "lnurl-auth" | "spark-token-invoice" | "nostr-wallet-connect";
+} | {
+  readonly kind: "invalid";
+  readonly reason: "network" | "expired" | "amount-mismatch" | "malformed";
+} | {
+  readonly kind: "unrecognized";
+};
+type ParseOptions = {
+  readonly network: SparkNetwork;
+  readonly now: number;
+};
+/** `input` → PaymentParse. Never throws: every failure is a structured result. */
+export declare function parsePayment(input: string, options: ParseOptions): PaymentParse;
+//#endregion
+//#region src/payments/pay.d.ts
+type PayParams = {
+  readonly account: SparkAccountRef;
+  readonly option: PaymentOption;
+  /** Caller-supplied amount — required by open invoices, the `spark` option, and LNURL flows. */
+  readonly amountSats?: number;
+  readonly comment?: string;
+  readonly maxFeeSats?: number;
+  readonly speed?: "FAST" | "MEDIUM" | "SLOW";
+  readonly verify: UnlockFactor;
+};
+type PayResult = {
+  readonly kind: "spark";
+  readonly transfer: SparkTransfer;
+} | {
+  readonly kind: "lightning";
+  readonly payment: LightningPayment;
+} | {
+  readonly kind: "withdraw";
+  readonly exit: CooperativeExitResult;
+} | {
+  readonly kind: "lnurl-withdraw";
+  readonly invoice: LightningInvoice;
+};
+//#endregion
+//#region src/payments/zap.d.ts
+/** A profile zap names the recipient pubkey; an event zap carries the event it zaps. */
+type ZapRecipient = {
+  readonly pubkey: string;
+  readonly lightning: string;
+} | {
+  readonly event: Event;
+  readonly lightning: string;
+};
+type PrepareZapParams = {
+  /** Any `NostrSigner` — wallet key, external key, NIP-07/46 — signs the 9734. */
+  readonly signer: NostrSigner;
+  readonly recipient: ZapRecipient;
+  readonly amountSats: number;
+  readonly comment?: string | undefined;
+  readonly relays: ReadonlyArray<string>;
+  readonly network: SparkNetwork;
+};
+type PrepareZapContext = {
+  readonly fetch: typeof globalThis.fetch;
+  readonly now: () => number;
+};
+/** Everything a payer needs: the signed 9734, the invoice, and the note fields. */
+type PreparedZap = {
+  readonly zapRequest: Event;
+  readonly invoice: string;
+  /** Hex payment hash decoded from the invoice. */
+  readonly paymentHash: string;
+  /** Millisecond expiry decoded from the invoice. */
+  readonly expiresAt: number;
+  readonly amountSats: number;
+  /** The LNURL service's 9735 signing pubkey. */
+  readonly receiptPubkey: string;
+  readonly recipientPubkey: string;
+  readonly eventId?: string;
+  readonly comment?: string;
+  /** The lud16 or LNURL as given. */
+  readonly lightning: string;
+};
+type PayZapOptions = {
+  readonly maxFeeSats: number;
+  readonly verify: UnlockFactor;
+  readonly now: () => number;
+};
+/** Everything up to payment: resolve LNURL, sign the 9734, request the invoice. */
+export declare function prepareZap(params: PrepareZapParams, context: PrepareZapContext): Promise<PreparedZap>;
+/**
+ * Pays a prepared zap through the controller's approve-first path. A nearly-expired invoice is
+ * rejected before approval — the user may have sat on the confirm screen since `prepareZap`.
+ */
+export declare function payZap(spark: SparkController, account: SparkAccountRef, prepared: PreparedZap, options: PayZapOptions): Promise<LightningPayment>;
+//#endregion
+//#region src/engine.d.ts
+type EngineOptions = {
+  readonly wallet: Wallet;
+  /** Every Spark account the engine touches lives on this network. */
+  readonly sparkNetwork: SparkNetwork;
+  readonly fetch: typeof globalThis.fetch;
+  readonly random: (length: number) => Uint8Array;
+  readonly now: () => number;
+  readonly logger: EngineLogger;
+  readonly openStore: () => Promise<EngineStore>;
+  /** Cloud file transport for the backup controller; absent → `unavailable`. */
+  readonly cloud?: CloudStore;
+  /** Kind-30078 wallet-metadata sync; absent → every wallet reports `unavailable`. */
+  readonly metaSync?: MetaSyncConfig;
+  /** Test seam — defaults to the wallet's real spark proxy. */
+  readonly sparkApis?: SparkControllerOptions["spark"];
+};
+type WalletEngine = {
+  readonly spark: SparkController;
+  readonly accounts: AccountTreeController;
+  readonly metaSync: MetaSyncController;
+  readonly backup: BackupController;
+  readonly zaps: {
+    readonly prepare: (params: PrepareZapParams) => Promise<PreparedZap>;
+    readonly pay: (account: SparkAccountRef, prepared: PreparedZap, options: Omit<PayZapOptions, "now">) => Promise<LightningPayment>;
+  };
+  readonly payments: {
+    readonly parse: (input: string, network: SparkNetwork) => PaymentParse;
+    readonly resolve: (input: string, network: SparkNetwork) => Promise<PaymentParse>;
+    readonly pay: (params: PayParams) => Promise<unknown>;
+  };
+  readonly unsubscribe: () => void;
+};
+export declare function createWalletEngine(options: EngineOptions): WalletEngine;
+//#endregion
+//#region src/backup/memory.d.ts
+/** In-memory CloudStore for tests and the playground; swap the Map for cross-engine sharing. */
+export declare function createMemoryCloudStore(backing?: Map<string, string>): CloudStore;
+//#endregion
+//#region src/spark/errors.d.ts
+/** SparkController error categories — never carry request bytes or secrets. */
+type SparkErrorCategory = "network" | "approval-required" | "insufficient-funds" | "rejected" | "internal";
+export declare class SparkControllerError extends Error {
+  readonly category: SparkErrorCategory;
+  constructor(category: SparkErrorCategory, message: string, cause?: unknown);
+}
+//#endregion
+//#region src/accounts/errors.d.ts
+/** Account-tree error categories — messages never carry secrets. */
+type AccountTreeErrorCategory = "invalid-input" | "rejected" | "not-found" | "locked";
+export declare class AccountTreeError extends Error {
+  readonly category: AccountTreeErrorCategory;
+  constructor(category: AccountTreeErrorCategory, message: string, cause?: unknown);
+}
+//#endregion
+//#region src/payments/errors.d.ts
+/** Payment layer error categories — messages never carry remote or secret content. */
+type PaymentErrorCategory = "invalid-input" | "network" | "rejected";
+export declare class PaymentError extends Error {
+  readonly category: PaymentErrorCategory;
+  constructor(category: PaymentErrorCategory, message: string, cause?: unknown);
+}
+//#endregion
+//#region src/payments/resolve.d.ts
+type ResolveOptions = ParseOptions & {
+  readonly fetch: typeof globalThis.fetch;
+};
+/**
+ * `parsePayment` plus LNURL dereferencing: an `lnurl` result is fetched and turned into a concrete
+ * `lnurl-pay` / `lnurl-withdraw` request (`tag=login` endpoints report as unsupported). Network
+ * failures throw `PaymentError("network")` — remote error bodies never enter the message.
+ */
+export declare function resolvePayment(input: string, options: ResolveOptions): Promise<PaymentParse>;
+//#endregion
+//#region src/spark/exit-chain-codec.d.ts
+export declare function encodeExitChain(chain: SparkExitChain): Uint8Array;
+export declare function decodeExitChain(bytes: Uint8Array): SparkExitChain;
+//#endregion
+export type { AccountGroup, AccountTreeState, BackupControllerState, BackupErrorCategory, CloudStore, ControllerOptions, EngineCollection, EngineErrorCode, EngineLogger, EngineOptions, EngineStore, EventBus, MetaDoc, MetaDocGroup, MetaDocWallet, MetaSyncConfig, MetaSyncRelayPort, MetaSyncState, MetaSyncWalletStatus, PayResult, PayZapOptions, PaymentNote, PaymentOption, PaymentParse, PaymentRequest, PrepareZapContext, PrepareZapParams, PreparedZap, SparkAccountState, SparkActivity, SparkClientFactory, SparkControllerOptions, SparkControllerState, SparkErrorCategory, WalletEngine, ZapRecipient };
+//# sourceMappingURL=index.d.mts.map