@qntx/wallet-engine 0.5.2 → 0.6.0

package/dist/index.d.mts

@@ -1,18 +1,19 @@
+import { r as NetworkInfo } from "./registry-9oeWs_yZ.mjs";
 import { StoreApi } from "zustand/vanilla";
+import "@scure/btc-signer";
 import { CooperativeExitResult, LightningInvoice, LightningPayment, SparkClient, SparkExitChain, SparkNetwork, SparkPayment, SparkStore, SparkTransfer } from "@qntx/spark";
+import { decodeEvm } from "@qntx/wallet-chains/evm";
+import { BackupHeader, BackupInfo, InitialFactor, UnlockFactor, Wallet, WalletInfo } from "@qntx/wallet";
+import { LnurlPayRequest, LnurlWithdrawRequest } from "@qntx/spark/lnurl";
+import { Event, Filter, NostrSigner } from "@qntx/nostr";
 import { NostrKeyRef, WalletSigner } from "@qntx/wallet/nostr";
 import { SparkSigner } from "@qntx/wallet/spark";
 import { PublicClient } from "viem";
 import { chains } from "@qntx/wallet/chains";
-import "@scure/btc-signer";
-import { decodeEvm } from "@qntx/wallet-chains/evm";
-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 "@solana/kit";
 import { SparkAccountRef, SparkApproveIntent } from "@qntx/wallet/protocol";
-import "@scure/btc-signer/psbt.js";
 import "@qntx/wallet-chains";
+import "@scure/btc-signer/psbt.js";
 //#region src/controller.d.ts
 type ControllerOptions<S> = {
   readonly name: string;
@@ -76,33 +77,166 @@ export declare function createMemoryEngineStore(backing?: {
   readonly collections?: Map<string, Map<string, Uint8Array>>;
 }): EngineStore;
 //#endregion
+//#region src/addresses/normalize.d.ts
+type AddressFamily = "evm" | "solana" | "bitcoin" | "spark";
+//#endregion
+//#region src/addresses/record.d.ts
+type AddressBookEntry = {
+  readonly id: string;
+  readonly name: string;
+  readonly family: AddressFamily;
+  readonly address: string;
+  readonly note?: string;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+};
+type AddressBookTombstone = {
+  readonly id: string;
+  readonly deleted: true;
+  readonly updatedAt: number;
+};
+type AddressBookRecord = AddressBookEntry | AddressBookTombstone;
+//#endregion
+//#region src/addresses/controller.d.ts
+type AddressBookState = {
+  /** Live entries only; tombstones stay internal. */
+  readonly entries: Record<string, AddressBookEntry>;
+};
+type AddressBookOptions = {
+  readonly openStore: () => Promise<EngineStore>;
+  readonly random: (n: number) => Uint8Array;
+  readonly now: () => number;
+  readonly logger: EngineLogger;
+};
+export declare class AddressBookController extends Controller<AddressBookState> {
+  private readonly options;
+  private engineStore;
+  /** Every record, tombstones included, by id. */
+  private records;
+  constructor(options: AddressBookOptions);
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  lock(): void;
+  /** Entries and tombstones, for the metadata document. */
+  syncEntries(): ReadonlyArray<AddressBookRecord>;
+  /**
+   * Merges records from another device (last writer wins, tombstones win over older entries).
+   * Returns whether anything local changed and whether the merged set holds something `remote`
+   * lacks, i.e. whether the remote copy needs a newer publish.
+   */
+  merge(remote: ReadonlyArray<AddressBookRecord>): Promise<{
+    readonly changed: boolean;
+    readonly localNewer: boolean;
+  }>;
+  add(params: {
+    readonly name: string;
+    readonly family: AddressFamily;
+    readonly address: string;
+    readonly note?: string;
+  }): Promise<AddressBookEntry>;
+  rename(id: string, name: string): Promise<AddressBookEntry>;
+  /** Sets or clears (empty or `undefined`) the note. */
+  setNote(id: string, note: string | undefined): Promise<AddressBookEntry>;
+  /** Removes the entry, leaving a tombstone so other devices drop it too. */
+  remove(id: string): Promise<void>;
+  private checkedNote;
+  private requireEntry;
+  private persist;
+  private requireStore;
+}
+//#endregion
+//#region src/addresses/errors.d.ts
+type AddressBookErrorCategory = "invalid-input" | "duplicate" | "not-found" | "locked" | "limit";
+export declare class AddressBookError extends Error {
+  readonly category: AddressBookErrorCategory;
+  constructor(category: AddressBookErrorCategory, message: string);
+}
+//#endregion
+//#region src/chains/evm.d.ts
+type EvmFeeTier = "slow" | "normal" | "fast";
+//#endregion
 //#region src/chains/bitcoin.d.ts
 type Esplora = {
   readonly get: (path: string) => Promise<unknown>;
   readonly post: (path: string, body: string) => Promise<unknown>;
 };
 //#endregion
-//#region src/meta/doc.d.ts
+//#region src/networks/controller.d.ts
+type SolanaRpc = {
+  readonly call: (method: string, params: unknown[]) => Promise<unknown>;
+};
 /**
- * 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`.
+ * A host-endpoint-only client for cross-checking pre-signing reads. `not-needed`: the gateway is
+ * not this network's first endpoint, so the primary reads already come from the host.
+ * `unavailable`: a cross-check is needed but the network has no host endpoint.
  */
-type MetaDocWallet = {
-  readonly name?: string;
-  readonly updatedAt: number;
+type Independent<T> = {
+  readonly kind: "not-needed";
+} | {
+  readonly kind: "unavailable";
+} | {
+  readonly kind: "available";
+  readonly client: T;
 };
-type MetaDocGroup = {
-  readonly index: number;
-  readonly name?: string;
-  readonly hidden: boolean;
-  readonly boundPubkey?: string;
-  readonly updatedAt: number;
+type NetworkControllerState = {
+  readonly customRpc: Record<string, ReadonlyArray<string>>;
 };
-type MetaDoc = {
-  readonly v: 1;
-  readonly wallet: MetaDocWallet;
-  readonly groups: ReadonlyArray<MetaDocGroup>;
+type Options$2 = {
+  readonly fetch: typeof globalThis.fetch;
+  readonly rpc: Readonly<Record<string, ReadonlyArray<string>>>;
+  readonly openStore: () => Promise<EngineStore>;
+  readonly logger: EngineLogger;
+  readonly gateway?: {
+    readonly url: string;
+    readonly installId: string;
+  } | undefined;
 };
+declare class NetworkController extends Controller<NetworkControllerState> {
+  private readonly options;
+  private engineStore?;
+  private readonly clients;
+  private readonly gatewayBase;
+  private readonly gatewayOrigin;
+  /** Networks the gateway reported at unlock; empty while locked or when the read failed. */
+  private gatewayServed;
+  constructor(options: Options$2);
+  init(): Promise<void>;
+  private loadCustomRpc;
+  /** Reads the gateway's served networks; any failure leaves the gateway unused until next unlock. */
+  private loadGatewayNetworks;
+  /** `fetch` that adds the install id to requests bound for the gateway's origin only. */
+  private readonly gatewayFetch;
+  destroy(): Promise<void>;
+  lock(): void;
+  /**
+   * Ordered endpoints: a network with custom endpoints uses custom → host and never the gateway;
+   * otherwise a gateway-served network uses gateway → host; else host only.
+   */
+  endpoints(network: string): ReadonlyArray<string>;
+  info(network: string): NetworkInfo;
+  client(network: string): PublicClient;
+  /** True when the gateway heads this network's endpoint list (no custom endpoints, gateway-served). */
+  private gatewayFirst;
+  private independent;
+  /** Host-endpoint EVM client for cross-checking reads; never sends the install id. */
+  independentClient(network: string): Independent<PublicClient>;
+  independentSolanaRpc(network: string): Independent<SolanaRpc>;
+  independentEsplora(network: string): Independent<Esplora>;
+  /** Networks with at least one configured endpoint or served by the gateway, by family. */
+  enabled(family: "evm" | "solana" | "bitcoin"): ReadonlyArray<string>;
+  /** Solana JSON-RPC over the ordered endpoint list — kit's transport is single-endpoint. */
+  solanaRpc(network: string): SolanaRpc;
+  /** Bounded-concurrency + 429-aware ordered-failover Esplora client. */
+  esplora(network: string): Esplora;
+  /** Validate a custom endpoint's reported chain id, then persist it first in the list. */
+  addRpc(network: string, url: string): Promise<void>;
+}
+//#endregion
+//#region src/chains/solana.d.ts
+type SolanaFeeTier = "slow" | "normal" | "fast";
+//#endregion
+//#region src/requests/checks.d.ts
+type RequestCheckCode = "decode-partial" | "nonce-mismatch" | "fee-mismatch" | "reads-unverified" | "fee-above-network" | "fee-exceeds-amount";
 //#endregion
 //#region src/spark/notes.d.ts
 /**
@@ -275,6 +409,460 @@ export declare class SparkController extends Controller<SparkControllerState> {
   }): Promise<CooperativeExitResult>;
 }
 //#endregion
+//#region src/payments/action.d.ts
+/**
+ * What the host shows for a Spark, Lightning or exit request; `family` tells it apart from a chain
+ * intent.
+ */
+type SparkDisplay = {
+  readonly family: "spark";
+  readonly network: SparkNetwork;
+  readonly kind: "transfer" | "lightning" | "exit";
+  readonly amountSats: number;
+  readonly maxFeeSats?: number;
+  /** Spark address, Lightning payee public key (hex) or bitcoin address. */
+  readonly receiver: string;
+  /** Invoice description or the LNURL metadata text. */
+  readonly description?: string;
+};
+type SparkResult = {
+  readonly kind: "spark";
+  readonly transfer: SparkTransfer;
+} | {
+  readonly kind: "lightning";
+  readonly payment: LightningPayment;
+} | {
+  readonly kind: "withdraw";
+  readonly exit: CooperativeExitResult;
+};
+/**
+ * A validated, fixed Spark payment: everything that does not need the user's verification has
+ * happened (including any LNURL invoice fetch), so approval only re-checks expiry and executes.
+ */
+type PreparedSparkAction = {
+  readonly display: SparkDisplay;
+  readonly checks: ReadonlyArray<RequestCheckCode>;
+  /** Why the action can no longer be paid at `now` (an expiring invoice), if so. */
+  readonly staleReason: (now: number) => string | undefined;
+  /** Runs the controller's approve-first payment call. */
+  readonly execute: (spark: SparkController, verify: UnlockFactor) => Promise<SparkResult>;
+};
+//#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";
+};
+type WithdrawLnurlParams = {
+  readonly account: SparkAccountRef;
+  readonly option: Extract<PaymentOption, {
+    kind: "lnurl-withdraw";
+  }>;
+  readonly amountSats: number;
+};
+//#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;
+};
+/** Everything up to payment: resolve LNURL, sign the 9734, request the invoice. */
+export declare function prepareZap(params: PrepareZapParams, context: PrepareZapContext): Promise<PreparedZap>;
+//#endregion
+//#region src/transactions/route.d.ts
+type SignParams = Parameters<ReturnType<typeof chains>["sign"]>[0];
+type AccountRef = SignParams["request"]["account"];
+type DisplayIntent = ReturnType<typeof decodeEvm>;
+type TxState = "draft" | "signed" | "submitted" | "pending" | "confirmed" | "failed" | "rejected" | "dropped" | "replaced";
+type TrackedTransaction = {
+  readonly id: string;
+  readonly family: "evm" | "solana" | "bitcoin";
+  readonly network: string;
+  readonly account: string;
+  readonly hash: string | undefined;
+  readonly state: TxState;
+  readonly intent: DisplayIntent | undefined;
+  readonly nonce: number;
+  /** Solana only — the blockhash expiry that turns an unconfirmed tx `dropped`. */
+  readonly lastValidBlockHeight?: number;
+  /** EVM replacement — the earlier transaction this one bumps or cancels. */
+  readonly replaces?: string;
+  /** CPFP — the unconfirmed parent this child pushes. */
+  readonly parentId?: string;
+  /** Bitcoin build record persisted at send for RBF/CPFP rebuilds. */
+  readonly btc?: {
+    readonly inputs: ReadonlyArray<{
+      readonly txid: string;
+      readonly vout: number;
+      readonly value: number;
+      readonly address: string;
+    }>;
+    readonly outputs: ReadonlyArray<{
+      readonly address: string;
+      readonly value: number;
+      readonly own: boolean;
+    }>;
+    readonly vsize: number;
+    readonly fee: number;
+    readonly feeRate: number;
+  };
+  readonly submittedAt: number;
+  readonly error: string | undefined;
+};
+type SendParams = {
+  readonly account: AccountRef;
+  readonly network: string;
+  readonly to: string;
+  readonly amount: bigint;
+  /** ERC-20 contract — when set, `to`/`amount` are the transfer recipient/units and value is 0. */
+  readonly token?: string;
+  readonly fee: EvmFeeTier | SolanaFeeTier;
+  /** SPL mint decimals — required when `token` is a Solana mint. */
+  readonly decimals?: number;
+  readonly verify: SignParams["verify"];
+};
+type PrepareParams = Omit<SendParams, "verify">;
+type ChainRequestMethod = "send" | "speed-up" | "cancel" | "cpfp";
+/** What a request asks for; replacements and CPFP name the original transaction. */
+type ChainRequestInput = ({
+  readonly method: "send";
+} & PrepareParams) | {
+  readonly method: "speed-up" | "cancel";
+  readonly txId: string;
+} | {
+  readonly method: "cpfp";
+  readonly txId: string;
+  readonly feeRate: number;
+};
+/**
+ * A fully built, estimated and cross-checked send that has not been signed. The unsigned content
+ * lives in the closures and cannot change after `prepare` returns.
+ */
+type PreparedRequest = {
+  /** Id of the tracked transaction `submit` creates. */
+  readonly txId: string;
+  readonly account: AccountRef;
+  readonly network: string;
+  /** The transaction being replaced or accelerated; absent for a plain send. */
+  readonly target?: string;
+  readonly intent: DisplayIntent;
+  readonly checks: ReadonlyArray<RequestCheckCode>;
+  /** Why the build can no longer be signed (nonce taken, blockhash expired), if so. */
+  readonly staleReason: () => string | undefined | Promise<string | undefined>;
+  /** Signs, finalizes, broadcasts and hands the transaction to tracking. */
+  readonly submit: (verify: SendParams["verify"]) => Promise<TrackedTransaction>;
+  /** Frees what `prepare` reserved; safe to call more than once. */
+  readonly release: () => void;
+};
+type Options$1 = {
+  readonly wallet: Wallet;
+  readonly networks: NetworkController;
+  readonly openStore: () => Promise<EngineStore>;
+  readonly random: (n: number) => Uint8Array;
+  readonly setTimer: (ms: number, fn: () => unknown) => () => void;
+  readonly now: () => number;
+  readonly logger: EngineLogger;
+  readonly pollMs?: number;
+  /** Test seam — defaults to the wallet's real chains proxy. */
+  readonly chains?: ReturnType<typeof chains>;
+};
+//#endregion
+//#region src/transactions/controller.d.ts
+type TransactionControllerState = {
+  readonly txs: Record<string, TrackedTransaction>;
+};
+declare class TransactionController extends Controller<TransactionControllerState> {
+  private readonly options;
+  private engineStore?;
+  private readonly timers;
+  private evmRoute;
+  private bitcoinRoute;
+  private locked;
+  constructor(options: Options$1);
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  lock(): void;
+  private persist;
+  private transition;
+  private routeCtx;
+  /**
+   * Internal entry for the request pipeline: builds, estimates and cross-checks a send without
+   * signing it. Bitcoin outputs it selects stay locked under `requestId` until the returned
+   * `release` runs or the broadcast moves them to the transaction.
+   */
+  prepareSend(params: PrepareParams, requestId: string): Promise<PreparedRequest>;
+  /**
+   * Internal entry for replacements and CPFP: builds, cross-checks and reserves what the
+   * replacement needs without signing it. The original must be `submitted` or `pending`.
+   */
+  prepareReplacement(input: Exclude<ChainRequestInput, {
+    method: "send";
+  }>, requestId: string): Promise<PreparedRequest>;
+  private track;
+}
+//#endregion
+//#region src/requests/risk.d.ts
+/**
+ * Recipient risk, pure: a recipient the wallet has never paid or saved is a `warning`; one that
+ * looks like a known address (same first and last four characters, different address) is a `danger`
+ * — the shape of an address-poisoning lookalike. Both can apply to one recipient.
+ */
+type RiskFinding = {
+  readonly code: "first-recipient" | "address-poisoning";
+  readonly level: "warning" | "danger";
+};
+//#endregion
+//#region src/requests/sign-log.d.ts
+type SignLogOutcome = "submitted" | "rejected" | "failed" | "expired" | "invalidated";
+type SignLogEntry = {
+  readonly id: string;
+  readonly at: number;
+  readonly origin: {
+    readonly kind: "internal";
+  };
+  readonly method: RequestMethod;
+  readonly account: AccountRef | SparkAccountRef;
+  readonly network: string;
+  readonly summary: string;
+  readonly verification: "verified" | "unverifiable";
+  readonly checks: ReadonlyArray<RequestCheckCode>;
+  readonly risk: ReadonlyArray<RiskFinding>;
+  readonly outcome: SignLogOutcome;
+  readonly error?: string;
+};
+//#endregion
+//#region src/requests/controller.d.ts
+/** A Spark, Lightning (including LNURL-pay and lightning addresses) or cooperative-exit payment. */
+type PayInput = {
+  readonly method: "pay";
+} & PayParams;
+/** A prepared zap; its invoice was fetched by `engine.zaps.prepare` and is paid as-is. */
+type ZapInput = {
+  readonly method: "zap";
+  readonly account: SparkAccountRef;
+  readonly zap: PreparedZap;
+  readonly maxFeeSats: number;
+};
+type RequestMethod = ChainRequestMethod | "pay" | "zap";
+type RequestInput = ChainRequestInput | PayInput | ZapInput;
+type RequestStage = "awaiting-approval" | "signing" | "submitted" | "rejected" | "failed" | "expired" | "invalidated";
+type PendingRequest = {
+  readonly id: string;
+  readonly origin: {
+    readonly kind: "internal";
+  };
+  readonly method: RequestMethod;
+  readonly account: AccountRef | SparkAccountRef;
+  readonly network: string;
+  readonly stage: RequestStage;
+  /** Decoded locally from the exact content that will be signed; `family` tells the shapes apart. */
+  readonly display: DisplayIntent | SparkDisplay;
+  /** `unverifiable` as soon as any check is recorded; the host must ask for explicit confirmation. */
+  readonly verification: "verified" | "unverifiable";
+  readonly checks: ReadonlyArray<RequestCheckCode>;
+  /**
+   * Recipient risk; independent of `verification`. A `danger` needs the user's explicit
+   * acknowledgement.
+   */
+  readonly risk: ReadonlyArray<RiskFinding>;
+  readonly createdAt: number;
+  readonly expiresAt: number;
+  /** The transaction being replaced or accelerated; absent for a plain send. */
+  readonly target?: string;
+  /** The tracked transaction once submitted. */
+  readonly txId?: string;
+  readonly error?: string;
+};
+type RequestControllerState = {
+  readonly requests: Record<string, PendingRequest>;
+};
+type RequestControllerOptions = {
+  readonly transactions: TransactionController;
+  /** The full controller: its payment methods are reachable only through this pipeline. */
+  readonly spark: SparkController;
+  readonly addressBook: AddressBookController;
+  readonly openStore: () => Promise<EngineStore>;
+  readonly fetch: typeof globalThis.fetch;
+  readonly random: (n: number) => Uint8Array;
+  readonly now: () => number;
+  readonly setTimer: (ms: number, fn: () => unknown) => () => void;
+  readonly logger: EngineLogger;
+};
+/** Requests expire this long after creation. */
+export declare const REQUEST_TTL_MS: number;
+export declare class RequestController extends Controller<RequestControllerState> {
+  private readonly options;
+  private readonly entries;
+  private readonly log;
+  /** Original transaction id → the unfinished request replacing or accelerating it. */
+  private readonly targets;
+  private locked;
+  /** Bumped on every unlock and lock so work that outlives a session never touches the next one. */
+  private session;
+  constructor(options: RequestControllerOptions);
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  /** Locking is not consent: every unfinished request becomes `invalidated` and frees its resources. */
+  lock(): void;
+  /** The signature record, newest first. */
+  signLog(): Promise<ReadonlyArray<SignLogEntry>>;
+  clearSignLog(): Promise<void>;
+  prepare(input: RequestInput): Promise<PendingRequest>;
+  private build;
+  /**
+   * Signs and submits a request. Anything but a live, unexpired `send` request with this id throws
+   * before any signing; a stale build (nonce taken, blockhash expired) fails without signing.
+   */
+  approve(id: string, method: ChainRequestMethod, verify: SendParams["verify"]): Promise<TrackedTransaction>;
+  approve(id: string, method: "pay" | "zap", verify: SendParams["verify"]): Promise<SparkResult>;
+  /**
+   * A cancelled or refused verification is `rejected`; anything after it is `failed`. Chain
+   * requests record which step failed on the tracked transaction; for Spark, the approval round is
+   * the only source of `WalletError`.
+   */
+  private failureStage;
+  reject(id: string): void;
+  private requireRequest;
+  private put;
+  private unclaim;
+  /** Ends a request in a terminal stage and frees what it reserved. */
+  private finish;
+  /** Appends the final stage to the signature record; a failed write is a warning, not an error. */
+  private record;
+  private appendLog;
+  /**
+   * Addresses the wallet already knows for a family: contacts, plus recipients of tracked chain
+   * sends (Spark payments are not tracked).
+   */
+  private knownAddresses;
+  private chainRisk;
+  /** Only a Spark transfer has a recipient to check; Lightning and exits are not assessed. */
+  private sparkRisk;
+}
+//#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;
+};
+/** The per-wallet part of the document: this wallet's name and account groups. */
+type MetaDocTree = {
+  readonly wallet: MetaDocWallet;
+  readonly groups: ReadonlyArray<MetaDocGroup>;
+};
+/** Every wallet's document also carries the whole address book, which is shared across wallets. */
+type MetaDoc = MetaDocTree & {
+  readonly v: 2;
+  readonly contacts: ReadonlyArray<AddressBookRecord>;
+};
+//#endregion
 //#region src/accounts/controller.d.ts
 type AccountGroup = {
   readonly walletId: string;
@@ -374,14 +962,14 @@ export declare class AccountTreeController extends Controller<AccountTreeState>
     groupIndex: number;
   } | undefined;
   /** The wallet's metadata document — every group, hidden included. */
-  exportMeta(walletId: string): MetaDoc;
+  exportMeta(walletId: string): MetaDocTree;
   /**
    * 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): {
+  mergeMeta(walletId: string, doc: MetaDocTree): {
     changed: boolean;
     localNewer: boolean;
   };
@@ -389,80 +977,27 @@ export declare class AccountTreeController extends Controller<AccountTreeState>
   discoverSpark(walletId: string): Promise<number[]>;
   /**
    * Per-group chain-family discovery — same stop rule as `discoverSpark`: group 0 always, stop
-   * after two consecutive fully-unused groups. A family error is reported on the group and does NOT
-   * count as unused (the group stays in `found` — it can't be proven empty).
-   */
-  discoverGroups(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/networks/registry.d.ts
-/**
- * Built-in EVM network registry: the 8 mainnets from chains.mdx plus their main testnets. Each
- * chain id was checked against the chain's official documentation (source URL per entry).
- * Signing-time chainId always comes from this table, never from an RPC endpoint.
- */
-type NetworkInfo = {
-  readonly id: string;
-  readonly chainId: number;
-  readonly name: string;
-  readonly symbol: string;
-  readonly multicall3?: string;
-  /** CAIP-2 family — `solana:<ref>` networks are validated against genesis-hash, not chainId. */
-  readonly family: "evm" | "solana" | "bitcoin";
-  readonly genesisHash?: string;
-  readonly decimals: number;
-  readonly testnet: boolean;
-};
-//#endregion
-//#region src/networks/controller.d.ts
-type SolanaRpc = {
-  readonly call: (method: string, params: unknown[]) => Promise<unknown>;
-};
-type NetworkControllerState = {
-  readonly customRpc: Record<string, ReadonlyArray<string>>;
-};
-type Options$2 = {
-  readonly fetch: typeof globalThis.fetch;
-  readonly rpc: Readonly<Record<string, ReadonlyArray<string>>>;
-  readonly openStore: () => Promise<EngineStore>;
-  readonly logger: EngineLogger;
-};
-declare class NetworkController extends Controller<NetworkControllerState> {
-  private readonly options;
-  private engineStore?;
-  private readonly clients;
-  constructor(options: Options$2);
-  init(): Promise<void>;
-  destroy(): Promise<void>;
-  lock(): void;
-  endpoints(network: string): ReadonlyArray<string>;
-  info(network: string): NetworkInfo;
-  client(network: string): PublicClient;
-  /** Validate a custom endpoint's reported chain id, then persist it first in the list. */
-  /** Solana JSON-RPC over the ordered endpoint list — kit's transport is single-endpoint. */
-  /** Networks with at least one configured endpoint, filtered by family. */
-  enabled(family: "evm" | "solana" | "bitcoin"): ReadonlyArray<string>;
-  solanaRpc(network: string): SolanaRpc;
-  /** Bounded-concurrency + 429-aware ordered-failover Esplora client. */
-  esplora(network: string): Esplora;
-  addRpc(network: string, url: string): Promise<void>;
+   * after two consecutive fully-unused groups. A family error is reported on the group and does NOT
+   * count as unused (the group stays in `found` — it can't be proven empty).
+   */
+  discoverGroups(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/assets/controller.d.ts
@@ -484,7 +1019,7 @@ type AccountBalances = {
 type AssetsControllerState = {
   readonly balances: Record<string, AccountBalances>;
 };
-type Options$1 = {
+type Options = {
   readonly networks: NetworkController;
   readonly openStore: () => Promise<EngineStore>;
   readonly setTimer: (ms: number, fn: () => unknown) => () => void;
@@ -497,7 +1032,7 @@ declare class AssetsController extends Controller<AssetsControllerState> {
   private visible;
   private cancelPoll;
   private readonly customTokens;
-  constructor(options: Options$1);
+  constructor(options: Options);
   init(): Promise<void>;
   lock(): void;
   destroy(): Promise<void>;
@@ -644,9 +1179,21 @@ type MetaSyncWalletStatus = {
 type MetaSyncState = {
   readonly wallets: Readonly<Record<string, MetaSyncWalletStatus>>;
 };
+/** What the sync needs from the address book: its records, a merge, and a change subscription. */
+type AddressBookSync = {
+  readonly syncEntries: () => ReadonlyArray<AddressBookRecord>;
+  readonly merge: (remote: ReadonlyArray<AddressBookRecord>) => Promise<{
+    readonly changed: boolean;
+    readonly localNewer: boolean;
+  }>;
+  readonly store: {
+    readonly subscribe: (listener: () => void) => () => void;
+  };
+};
 type MetaSyncControllerOptions = {
   readonly wallet: Wallet;
   readonly accounts: AccountTreeController;
+  readonly addressBook: AddressBookSync;
   /** `nostr(wallet)` — the signer is requested per wallet for its group-0 derived key. */
   readonly nostr: {
     readonly signer: (ref: NostrKeyRef) => WalletSigner;
@@ -670,6 +1217,7 @@ export declare class MetaSyncController extends Controller<MetaSyncState> {
   private readonly timers;
   private readonly inflight;
   private accountsUnsubscribe;
+  private addressBookUnsubscribe;
   constructor(options: MetaSyncControllerOptions);
   /** Unlocked: pull every wallet whose group-0 identity exists, then watch the tree. */
   init(): Promise<void>;
@@ -685,6 +1233,8 @@ export declare class MetaSyncController extends Controller<MetaSyncState> {
   private signerFor;
   private setStatus;
   private pullOne;
+  /** The wallet's tree plus the shared address book — every wallet's document carries both. */
+  private exportDoc;
   private filterFor;
   private acceptableEvent;
   /** Snapshot the wallet's exported doc — the debounce publishes only on a real change. */
@@ -693,243 +1243,6 @@ export declare class MetaSyncController extends Controller<MetaSyncState> {
   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/chains/evm.d.ts
-type EvmFeeTier = "slow" | "normal" | "fast";
-//#endregion
-//#region src/chains/solana.d.ts
-type SolanaFeeTier = "slow" | "normal" | "fast";
-//#endregion
-//#region src/transactions/route.d.ts
-type SignParams = Parameters<ReturnType<typeof chains>["sign"]>[0];
-type AccountRef = SignParams["request"]["account"];
-type DisplayIntent = ReturnType<typeof decodeEvm>;
-type TxState = "draft" | "signed" | "submitted" | "pending" | "confirmed" | "failed" | "rejected" | "dropped" | "replaced";
-type TrackedTransaction = {
-  readonly id: string;
-  readonly family: "evm" | "solana" | "bitcoin";
-  readonly network: string;
-  readonly account: string;
-  readonly hash: string | undefined;
-  readonly state: TxState;
-  readonly intent: DisplayIntent | undefined;
-  readonly nonce: number;
-  /** Solana only — the blockhash expiry that turns an unconfirmed tx `dropped`. */
-  readonly lastValidBlockHeight?: number;
-  /** EVM replacement — the earlier transaction this one bumps or cancels. */
-  readonly replaces?: string;
-  /** CPFP — the unconfirmed parent this child pushes. */
-  readonly parentId?: string;
-  /** Bitcoin build record persisted at send for RBF/CPFP rebuilds. */
-  readonly btc?: {
-    readonly inputs: ReadonlyArray<{
-      readonly txid: string;
-      readonly vout: number;
-      readonly value: number;
-      readonly address: string;
-    }>;
-    readonly outputs: ReadonlyArray<{
-      readonly address: string;
-      readonly value: number;
-      readonly own: boolean;
-    }>;
-    readonly vsize: number;
-    readonly fee: number;
-    readonly feeRate: number;
-  };
-  readonly submittedAt: number;
-  readonly error: string | undefined;
-};
-type SendParams = {
-  readonly account: AccountRef;
-  readonly network: string;
-  readonly to: string;
-  readonly amount: bigint;
-  /** ERC-20 contract — when set, `to`/`amount` are the transfer recipient/units and value is 0. */
-  readonly token?: string;
-  readonly fee: EvmFeeTier | SolanaFeeTier;
-  /** SPL mint decimals — required when `token` is a Solana mint. */
-  readonly decimals?: number;
-  readonly verify: SignParams["verify"];
-};
-type Options = {
-  readonly wallet: Wallet;
-  readonly networks: NetworkController;
-  readonly openStore: () => Promise<EngineStore>;
-  readonly random: (n: number) => Uint8Array;
-  readonly setTimer: (ms: number, fn: () => unknown) => () => void;
-  readonly now: () => number;
-  readonly logger: EngineLogger;
-  readonly pollMs?: number;
-  /** Test seam — defaults to the wallet's real chains proxy. */
-  readonly chains?: ReturnType<typeof chains>;
-};
-//#endregion
-//#region src/transactions/controller.d.ts
-type TransactionControllerState = {
-  readonly txs: Record<string, TrackedTransaction>;
-};
-declare class TransactionController extends Controller<TransactionControllerState> {
-  private readonly options;
-  private engineStore?;
-  private readonly timers;
-  private evmRoute;
-  private readonly bitcoinRoute;
-  private locked;
-  constructor(options: Options);
-  init(): Promise<void>;
-  destroy(): Promise<void>;
-  lock(): void;
-  private persist;
-  private transition;
-  private routeCtx;
-  send(params: SendParams): Promise<TrackedTransaction>;
-  /**
-   * Speed up or cancel a pending/submitted EVM transaction at the same nonce — a fresh signature is
-   * required and a rejection leaves the original untouched.
-   */
-  replace(id: string, mode: "speed-up" | "cancel", verify: SendParams["verify"]): Promise<TrackedTransaction>;
-  /**
-   * CPFP — spend an unconfirmed tx's own outputs into a higher-fee child so the package mines.
-   * Bitcoin only; the child is linked via `parentId`.
-   */
-  bumpChild(id: string, targetRate: number, verify: SendParams["verify"]): Promise<TrackedTransaction>;
-  private track;
-}
-//#endregion
 //#region src/engine.d.ts
 type EngineOptions = {
   readonly wallet: Wallet;
@@ -942,8 +1255,19 @@ type EngineOptions = {
   readonly openStore: () => Promise<EngineStore>;
   /** Cloud file transport for the backup controller; absent → `unavailable`. */
   readonly cloud?: CloudStore;
-  /** RPC endpoints per network (CAIP-2), ordered by preference for the viem fallback transport. */
+  /**
+   * Host endpoints per network (CAIP-2), ordered by preference, for all three chain families: EVM
+   * and Solana JSON-RPC URLs, and for Bitcoin the Esplora base URL.
+   */
   readonly rpc?: Readonly<Record<string, ReadonlyArray<string>>>;
+  /**
+   * The wallet gateway: tried first for the networks it serves (read at each unlock) unless a
+   * network has custom endpoints. The install id is sent only to the gateway's origin.
+   */
+  readonly gateway?: {
+    readonly url: string;
+    readonly installId: string;
+  };
   /** Injected timer for transaction polling; defaults to setTimeout. */
   readonly setTimer?: (ms: number, fn: () => void) => () => void;
   /** Kind-30078 wallet-metadata sync; absent → every wallet reports `unavailable`. */
@@ -955,18 +1279,24 @@ type WalletEngine = {
   readonly networks: NetworkController;
   readonly assets: AssetsController;
   readonly transactions: TransactionController;
-  readonly spark: SparkController;
+  readonly requests: RequestController;
+  readonly addressBook: AddressBookController;
+  /** Read and receive surface; every payment goes through `requests`. */
+  readonly spark: Omit<SparkController, "send" | "payInvoice" | "paySparkInvoice" | "withdraw">;
   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<PayResult>;
+    /** Receives funds from an LNURL-withdraw service; needs no verification factor. */
+    readonly withdrawLnurl: (params: WithdrawLnurlParams) => Promise<{
+      readonly kind: "lnurl-withdraw";
+      readonly invoice: LightningInvoice;
+    }>;
   };
   readonly unsubscribe: () => void;
 };
@@ -1015,5 +1345,5 @@ export declare function resolvePayment(input: string, options: ResolveOptions):
 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, PayParams, PayResult, PayZapOptions, PaymentNote, PaymentOption, PaymentParse, PaymentRequest, PrepareZapContext, PrepareZapParams, PreparedZap, SparkAccountState, SparkActivity, SparkClientFactory, SparkControllerOptions, SparkControllerState, SparkErrorCategory, WalletEngine, ZapRecipient };
+export type { AccountGroup, AccountTreeState, AddressBookEntry, AddressBookErrorCategory, AddressBookState, AddressFamily, BackupControllerState, BackupErrorCategory, CloudStore, ControllerOptions, EngineCollection, EngineErrorCode, EngineLogger, EngineOptions, EngineStore, EventBus, MetaDoc, MetaDocGroup, MetaDocTree, MetaDocWallet, MetaSyncConfig, MetaSyncRelayPort, MetaSyncState, MetaSyncWalletStatus, PayInput, PayParams, PaymentNote, PaymentOption, PaymentParse, PaymentRequest, PendingRequest, PrepareZapContext, PrepareZapParams, PreparedSparkAction, PreparedZap, RequestCheckCode, RequestControllerState, RequestInput, RequestMethod, RequestStage, RiskFinding, SignLogEntry, SignLogOutcome, SparkAccountState, SparkActivity, SparkClientFactory, SparkControllerOptions, SparkControllerState, SparkDisplay, SparkErrorCategory, SparkResult, WalletEngine, WithdrawLnurlParams, ZapRecipient };
 //# sourceMappingURL=index.d.mts.map