@qntx/wallet-engine 0.6.0 → 0.7.0

package/dist/index.d.mts

@@ -1,20 +1,19 @@
-import { r as NetworkInfo } from "./registry-9oeWs_yZ.mjs";
+import { r as NetworkInfo } from "./registry-LcFSPrE1.mjs";
 import { StoreApi } from "zustand/vanilla";
+import { SignRequest } from "@qntx/wallet-chains";
+import { BackupHeader, BackupInfo, InitialFactor, UnlockFactor, Wallet, WalletInfo } from "@qntx/wallet";
 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 { chains } from "@qntx/wallet/chains";
+import { WalletSyncSigner } from "@qntx/wallet/nostr";
 import { SparkSigner } from "@qntx/wallet/spark";
 import { PublicClient } from "viem";
-import { chains } from "@qntx/wallet/chains";
 import "@solana/kit";
-import { SparkAccountRef, SparkApproveIntent } from "@qntx/wallet/protocol";
-import "@qntx/wallet-chains";
 import "@scure/btc-signer/psbt.js";
-//#region src/controller.d.ts
+import { SparkAccountRef, SparkApproveIntent } from "@qntx/wallet/protocol";
 type ControllerOptions<S> = {
   readonly name: string;
   readonly defaultState: () => S;
@@ -33,8 +32,6 @@ export declare abstract class Controller<S extends Record<string, unknown>> {
   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;
@@ -45,16 +42,12 @@ type EventBus<E> = {
   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.
@@ -70,98 +63,113 @@ 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/addresses/normalize.d.ts
-type AddressFamily = "evm" | "solana" | "bitcoin" | "spark";
-//#endregion
-//#region src/addresses/record.d.ts
-type AddressBookEntry = {
+type ConnectionOrigin = {
+  readonly kind: "browser";
+  readonly origin: string;
+};
+type ConnectionScope = {
+  /** CAIP-10 */
+  readonly accounts: ReadonlyArray<string>;
+  readonly methods: ReadonlyArray<string>;
+  readonly notifications: ReadonlyArray<string>;
+};
+type ConnectionSession = {
   readonly id: string;
-  readonly name: string;
-  readonly family: AddressFamily;
-  readonly address: string;
-  readonly note?: string;
+  readonly origin: ConnectionOrigin;
+  /** Keyed by CAIP-2. */
+  readonly scopes: Readonly<Record<string, ConnectionScope>>;
+  /** The session's current EVM network; only dApp sessions have one. */
+  readonly currentNetwork: string;
   readonly createdAt: number;
-  readonly updatedAt: number;
+  readonly lastUsedAt: number;
 };
-type AddressBookTombstone = {
+/** `connect` asks for accounts; `network` asks to add a network the session does not cover. */
+type PendingConnection = {
   readonly id: string;
-  readonly deleted: true;
-  readonly updatedAt: number;
+  readonly origin: ConnectionOrigin;
+  readonly kind: "connect" | "network";
+  readonly network?: string;
+  readonly createdAt: 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 AccountGroup$1 = {
+  readonly walletId: string;
+  readonly groupIndex: number;
 };
-type AddressBookOptions = {
+type ConnectionState = {
+  readonly sessions: Readonly<Record<string, ConnectionSession>>;
+  readonly pending: Readonly<Record<string, PendingConnection>>;
+};
+type ConnectionControllerOptions = {
   readonly openStore: () => Promise<EngineStore>;
   readonly random: (n: number) => Uint8Array;
   readonly now: () => number;
   readonly logger: EngineLogger;
-};
-export declare class AddressBookController extends Controller<AddressBookState> {
+  /** Development builds also accept `http://localhost`. */
+  readonly allowLocalhost: boolean;
+  /** The group the app currently shows; sessions are bound to it. */
+  readonly selectedGroup: () => AccountGroup$1 | undefined;
+  /** The group's EVM address on `network`. */
+  readonly evmAddress: (group: AccountGroup$1, network: string) => Promise<string>;
+  readonly enabledNetworks: () => ReadonlyArray<string>;
+  /** Voids a page's unfinished requests (revoked, or its network changed). */
+  readonly invalidate: (origin: string) => void;
+};
+export declare class ConnectionController extends Controller<ConnectionState> {
   private readonly options;
   private engineStore;
-  /** Every record, tombstones included, by id. */
-  private records;
-  constructor(options: AddressBookOptions);
+  private readonly waiters;
+  private group;
+  constructor(options: ConnectionControllerOptions);
   init(): Promise<void>;
   destroy(): Promise<void>;
+  /** Locking is not consent: every pending connection is rejected. */
   lock(): void;
-  /** Entries and tombstones, for the metadata document. */
-  syncEntries(): ReadonlyArray<AddressBookRecord>;
+  /** Throws `4100` unless `origin` is `https://host[:port]` (or localhost in development). */
+  checkOrigin(origin: string): ConnectionOrigin;
+  session(origin: string): ConnectionSession | undefined;
+  pending(): ReadonlyArray<PendingConnection>;
+  /** The group sessions are bound to: the host's last `setActiveGroup`, else the app's selection. */
+  activeGroup(): AccountGroup$1 | undefined;
+  /** Whether `network` is an EVM network the wallet has enabled. */
+  isEnabled(network: string): boolean;
+  /** The origin's authorized addresses on its current network; empty when not connected. */
+  accounts(origin: string): ReadonlyArray<string>;
+  /** Throws `4100` unless the origin's session covers `method` on `network`. */
+  authorize(origin: string, network: string, method: string): ConnectionSession;
+  /** Resolves with the session once the host approves; rejects with `4001` when it refuses. */
+  request(origin: string, kind: PendingConnection["kind"], network?: string): Promise<ConnectionSession>;
   /**
-   * 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.
+   * The host's approval, by id: the accounts granted (EVM addresses of the active group) and the
+   * network.
    */
-  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;
+  approveConnection(id: string, grant: {
+    readonly accounts: ReadonlyArray<string>;
+    readonly network: string;
+  }): Promise<ConnectionSession>;
+  rejectConnection(id: string): void;
+  /** Ends the origin's session; its pending connection and unfinished requests are void. */
+  revoke(origin: string): Promise<void>;
+  /** Switches within the session's scope; the origin's unfinished requests are void. */
+  setCurrentNetwork(origin: string, network: string): Promise<void>;
+  touch(origin: string): Promise<void>;
+  /**
+   * The host switched account group: every session's accounts become the new group's addresses. A
+   * session that cannot get one (no address derivable) is left with an empty list and has to be
+   * authorized again.
+   */
+  setActiveGroup(walletId: string, groupIndex: number): Promise<void>;
+  private dropPending;
   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/networks/controller.d.ts
 type SolanaRpc = {
   readonly call: (method: string, params: unknown[]) => Promise<unknown>;
 };
@@ -231,14 +239,71 @@ declare class NetworkController extends Controller<NetworkControllerState> {
   /** 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 AddressFamily = "evm" | "solana" | "bitcoin" | "spark";
+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;
+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;
+}
+type EvmFeeTier = "slow" | "normal" | "fast";
 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
 /**
  * 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
@@ -258,15 +323,11 @@ type PaymentNote = {
 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;
@@ -394,6 +455,10 @@ export declare class SparkController extends Controller<SparkControllerState> {
     amountSats: number;
     memo?: string;
   }): Promise<LightningInvoice>;
+  /** A fresh single-use L1 deposit address (with the SO's proof of possession). */
+  newDepositAddress(ref: SparkAccountRef): Promise<string>;
+  /** Claims a confirmed L1 deposit paying one of the account's unused deposit addresses. */
+  claimDeposit(ref: SparkAccountRef, transaction: Uint8Array): Promise<void>;
   receiveAddress(ref: SparkAccountRef): Promise<string | undefined>;
   /**
    * Cooperative exit to an L1 address. The client exits `amountSats` of leaves and the payout is
@@ -408,8 +473,6 @@ export declare class SparkController extends Controller<SparkControllerState> {
     verify: UnlockFactor;
   }): 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.
@@ -447,8 +510,6 @@ type PreparedSparkAction = {
   /** 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;
@@ -504,8 +565,6 @@ type ParseOptions = {
 };
 /** `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;
@@ -522,8 +581,6 @@ type WithdrawLnurlParams = {
   }>;
   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;
@@ -564,12 +621,18 @@ type PreparedZap = {
 };
 /** 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 ChainApis = ReturnType<typeof chains>;
+type SignParams = Parameters<ChainApis["sign"]>[0];
 type AccountRef = SignParams["request"]["account"];
 type DisplayIntent = ReturnType<typeof decodeEvm>;
 type TxState = "draft" | "signed" | "submitted" | "pending" | "confirmed" | "failed" | "rejected" | "dropped" | "replaced";
+/** A bitcoin transaction that funds the wallet's own Spark account; it is claimed once confirmed. */
+type SparkDepositTag = {
+  readonly walletId: string;
+  readonly groupIndex: number;
+  readonly network: SparkNetwork;
+  readonly claimed?: boolean;
+};
 type TrackedTransaction = {
   readonly id: string;
   readonly family: "evm" | "solana" | "bitcoin";
@@ -585,6 +648,8 @@ type TrackedTransaction = {
   readonly replaces?: string;
   /** CPFP — the unconfirmed parent this child pushes. */
   readonly parentId?: string;
+  /** Set on a Spark deposit; `claimed` flips once the deposit is credited on Spark. */
+  readonly sparkDeposit?: SparkDepositTag;
   /** Bitcoin build record persisted at send for RBF/CPFP rebuilds. */
   readonly btc?: {
     readonly inputs: ReadonlyArray<{
@@ -650,6 +715,14 @@ type PreparedRequest = {
   /** Frees what `prepare` reserved; safe to call more than once. */
   readonly release: () => void;
 };
+type SignatureResult = {
+  readonly kind: "evm.personal-message" | "evm.typed-data";
+  readonly signature: Uint8Array;
+};
+/** A prepared message signature: nothing is broadcast or tracked, `submit` returns the signature. */
+type PreparedMessage = Omit<PreparedRequest, "submit" | "txId"> & {
+  readonly submit: (verify: SendParams["verify"]) => Promise<SignatureResult>;
+};
 type Options$1 = {
   readonly wallet: Wallet;
   readonly networks: NetworkController;
@@ -662,8 +735,6 @@ type Options$1 = {
   /** 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>;
 };
@@ -686,7 +757,17 @@ declare class TransactionController extends Controller<TransactionControllerStat
    * 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>;
+  prepareSend(params: PrepareParams, requestId: string, sparkDeposit?: SparkDepositTag): Promise<PreparedRequest>;
+  /** The group's next unused `btc.bip84` receive address on a bitcoin `network`. */
+  nextReceiveAddress(walletId: string, groupIndex: number, network: string): Promise<string>;
+  /** Records that a Spark deposit was credited; persisted with the transaction. */
+  markDepositClaimed(id: string): Promise<void>;
+  /**
+   * Internal entry for a dApp's EVM signature request: the request is normalized first, a
+   * transaction is rebuilt with fresh nonce and fees (the dApp's own are discarded), and a message
+   * is decoded and signed as is.
+   */
+  prepareDapp(account: AccountRef, request: SignRequest): Promise<PreparedRequest | PreparedMessage>;
   /**
    * 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`.
@@ -696,8 +777,6 @@ declare class TransactionController extends Controller<TransactionControllerStat
   }>, 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`
@@ -707,15 +786,20 @@ type RiskFinding = {
   readonly code: "first-recipient" | "address-poisoning";
   readonly level: "warning" | "danger";
 };
-//#endregion
-//#region src/requests/sign-log.d.ts
+/** A web page; `origin` is `scheme://host[:port]`, computed by the host from the top-level URL. */
+type BrowserOrigin = {
+  readonly kind: "browser";
+  readonly origin: string;
+};
+type RequestOrigin = {
+  readonly kind: "internal";
+} | BrowserOrigin;
+type RequestMethod = ChainRequestMethod | "pay" | "zap" | "evm-sign" | "spark-deposit" | "spark-exit";
 type SignLogOutcome = "submitted" | "rejected" | "failed" | "expired" | "invalidated";
 type SignLogEntry = {
   readonly id: string;
   readonly at: number;
-  readonly origin: {
-    readonly kind: "internal";
-  };
+  readonly origin: RequestOrigin;
   readonly method: RequestMethod;
   readonly account: AccountRef | SparkAccountRef;
   readonly network: string;
@@ -726,8 +810,6 @@ type SignLogEntry = {
   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";
@@ -739,14 +821,41 @@ type ZapInput = {
   readonly zap: PreparedZap;
   readonly maxFeeSats: number;
 };
-type RequestMethod = ChainRequestMethod | "pay" | "zap";
-type RequestInput = ChainRequestInput | PayInput | ZapInput;
+/**
+ * A dApp's EVM request: a transaction (rebuilt here with fresh nonce and fees), a personal message
+ * or EIP-712 typed data.
+ */
+type EvmSignInput = {
+  readonly method: "evm-sign";
+  readonly origin: BrowserOrigin;
+  readonly account: AccountRef;
+  readonly network: string;
+  readonly request: SignRequest;
+};
+/**
+ * Funds the wallet's own Spark account from a bitcoin account of the same wallet; the transaction
+ * is an ordinary bitcoin send to a fresh Spark deposit address and is claimed once confirmed.
+ */
+type SparkDepositInput = {
+  readonly method: "spark-deposit";
+  readonly account: SparkAccountRef;
+  readonly from: AccountRef;
+  readonly amountSats: number;
+  readonly fee: PrepareParams["fee"];
+};
+/** A cooperative exit to the group's own next unused `btc.bip84` receive address. */
+type SparkExitInput = {
+  readonly method: "spark-exit";
+  readonly account: SparkAccountRef;
+  readonly amountSats: number;
+  readonly maxFeeSats: number;
+  readonly speed?: "FAST" | "MEDIUM" | "SLOW";
+};
+type RequestInput = ChainRequestInput | PayInput | ZapInput | EvmSignInput | SparkDepositInput | SparkExitInput;
 type RequestStage = "awaiting-approval" | "signing" | "submitted" | "rejected" | "failed" | "expired" | "invalidated";
 type PendingRequest = {
   readonly id: string;
-  readonly origin: {
-    readonly kind: "internal";
-  };
+  readonly origin: RequestOrigin;
   readonly method: RequestMethod;
   readonly account: AccountRef | SparkAccountRef;
   readonly network: string;
@@ -790,6 +899,7 @@ export declare class RequestController extends Controller<RequestControllerState
   private readonly options;
   private readonly entries;
   private readonly log;
+  private readonly settlers;
   /** Original transaction id → the unfinished request replacing or accelerating it. */
   private readonly targets;
   private locked;
@@ -800,17 +910,30 @@ export declare class RequestController extends Controller<RequestControllerState
   destroy(): Promise<void>;
   /** Locking is not consent: every unfinished request becomes `invalidated` and frees its resources. */
   lock(): void;
+  /** A page navigated away, was revoked or changed network: its unfinished requests are void. */
+  invalidateOrigin(origin: string): void;
   /** The signature record, newest first. */
   signLog(): Promise<ReadonlyArray<SignLogEntry>>;
   clearSignLog(): Promise<void>;
   prepare(input: RequestInput): Promise<PendingRequest>;
+  /**
+   * Resolves with what `approve` returned, or rejects with `RequestEndedError` when the request
+   * ends any other way — how a dApp's pending call learns the outcome.
+   */
+  outcome(id: string): Promise<TrackedTransaction | SparkResult | SignatureResult>;
+  private openSettler;
+  private settle;
+  /** The bitcoin network `account`'s Spark network settles on; any other pairing is refused. */
+  private l1Network;
+  private sparkBuilt;
   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>;
+  approve(id: string, method: ChainRequestMethod | "spark-deposit", verify: SendParams["verify"]): Promise<TrackedTransaction>;
+  approve(id: string, method: "pay" | "zap" | "spark-exit", verify: SendParams["verify"]): Promise<SparkResult>;
+  approve(id: string, method: "evm-sign", verify: SendParams["verify"]): Promise<TrackedTransaction | SignatureResult>;
   /**
    * 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
@@ -835,8 +958,62 @@ export declare class RequestController extends Controller<RequestControllerState
   /** Only a Spark transfer has a recipient to check; Lightning and exits are not assessed. */
   private sparkRisk;
 }
-//#endregion
-//#region src/meta/doc.d.ts
+type Eip1193Request = {
+  readonly method: string;
+  readonly params?: unknown;
+};
+type Eip1193Event = {
+  readonly name: "connect";
+  readonly origin: string;
+  readonly chainId: string;
+} | {
+  readonly name: "accountsChanged";
+  readonly origin: string;
+  readonly accounts: ReadonlyArray<string>;
+} | {
+  readonly name: "chainChanged";
+  readonly origin: string;
+  readonly chainId: string;
+} | {
+  readonly name: "disconnect";
+  readonly origin: string;
+};
+type Eip1193HandlerOptions = {
+  readonly connections: ConnectionController;
+  readonly requests: RequestController;
+  readonly networks: NetworkController;
+  /** The network an unconnected page sees. */
+  readonly defaultNetwork: () => string;
+};
+export declare class Eip1193Handler {
+  private readonly options;
+  private readonly listeners;
+  private unsubscribe;
+  constructor(options: Eip1193HandlerOptions);
+  /** Events for the host to forward to pages; derived from changes to the sessions. */
+  subscribe(listener: (event: Eip1193Event) => void): () => void;
+  handle(origin: string, request: Eip1193Request): Promise<unknown>;
+  private requestAccounts;
+  private permissions;
+  private switchChain;
+  private authorizedAccount;
+  private personalSign;
+  private typedData;
+  private sendTransaction;
+  private signingSession;
+  private sign;
+  private read;
+}
+/** EIP-1193 / EIP-1474 / EIP-3326 error: `code` is what the page's promise rejects with. */
+export declare class ProviderError extends Error {
+  readonly code: number;
+  constructor(code: number, message: string);
+}
+type AddressBookErrorCategory = "invalid-input" | "duplicate" | "not-found" | "locked" | "limit";
+export declare class AddressBookError extends Error {
+  readonly category: AddressBookErrorCategory;
+  constructor(category: AddressBookErrorCategory, message: string);
+}
 /**
  * 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`.
@@ -862,8 +1039,6 @@ type MetaDoc = MetaDocTree & {
   readonly v: 2;
   readonly contacts: ReadonlyArray<AddressBookRecord>;
 };
-//#endregion
-//#region src/accounts/controller.d.ts
 type AccountGroup = {
   readonly walletId: string;
   readonly index: number;
@@ -999,8 +1174,6 @@ export declare class AccountTreeController extends Controller<AccountTreeState>
   private scheduleTotalsPersist;
   private flushTotals;
 }
-//#endregion
-//#region src/assets/controller.d.ts
 type TokenBalance = {
   readonly address: string;
   readonly symbol: string;
@@ -1045,26 +1218,19 @@ declare class AssetsController extends Controller<AssetsControllerState> {
   private readTokens;
   private balanceOfBatch;
   private balanceOf;
-  private callString;
-  private callNumber;
+  private callToken;
   /** Reads symbol/decimals on-chain, marks unverified, persists; throws when the calls fail. */
   addToken(network: string, address: string): Promise<void>;
   private persistToken;
-  private rpc;
-  private rpcHex;
   /** BTC balance = confirmed spendable + own unconfirmed change; frozen 546/330 shown separately. */
   refreshBitcoin(xpub: string, network: string): Promise<void>;
 }
-//#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
@@ -1082,8 +1248,6 @@ type CloudStore = {
   /** 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. */
@@ -1091,7 +1255,6 @@ type BackupControllerState = {
   readonly uploadedAt: number | undefined;
   readonly unprotected: {
     readonly walletIds: ReadonlyArray<string>;
-    readonly nostrKeyIds: ReadonlyArray<string>;
   };
   readonly error: BackupErrorCategory | undefined;
 };
@@ -1153,16 +1316,12 @@ export declare class BackupController extends Controller<BackupControllerState>
   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>;
@@ -1173,7 +1332,7 @@ type MetaSyncConfig = {
   readonly relays: MetaSyncRelayPort;
 };
 type MetaSyncWalletStatus = {
-  readonly status: "unavailable" | "syncing" | "synced" | "error";
+  readonly status: "syncing" | "synced" | "error";
   readonly error?: MetaSyncErrorCategory;
 };
 type MetaSyncState = {
@@ -1194,9 +1353,9 @@ 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. */
+  /** `nostr(wallet).syncSigner` — each wallet signs metadata with its dedicated sync key. */
   readonly nostr: {
-    readonly signer: (ref: NostrKeyRef) => WalletSigner;
+    readonly syncSigner: (walletId: string) => WalletSyncSigner;
   };
   readonly metaSync: MetaSyncConfig | undefined;
   readonly logger: EngineLogger;
@@ -1204,9 +1363,10 @@ type MetaSyncControllerOptions = {
 };
 /**
  * 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.
+ * wallet, authored by its dedicated sync key (WD-070). 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;
@@ -1229,8 +1389,6 @@ export declare class MetaSyncController extends Controller<MetaSyncState> {
   /** Manual re-pull of every wallet that can sync. */
   sync(): Promise<void>;
   private pullAll;
-  private pubkeyFor;
-  private signerFor;
   private setStatus;
   private pullOne;
   /** The wallet's tree plus the shared address book — every wallet's document carries both. */
@@ -1242,8 +1400,6 @@ export declare class MetaSyncController extends Controller<MetaSyncState> {
   private onTreeChange;
   private publishNow;
 }
-//#endregion
-//#region src/engine.d.ts
 type EngineOptions = {
   readonly wallet: Wallet;
   /** Every Spark account the engine touches lives on this network. */
@@ -1269,8 +1425,10 @@ type EngineOptions = {
     readonly installId: string;
   };
   /** Injected timer for transaction polling; defaults to setTimeout. */
+  /** Development builds: also accept `http://localhost` as a dApp origin. */
+  readonly allowLocalhostOrigins?: boolean;
   readonly setTimer?: (ms: number, fn: () => void) => () => void;
-  /** Kind-30078 wallet-metadata sync; absent → every wallet reports `unavailable`. */
+  /** Kind-30078 wallet-metadata sync; absent → no wallet metadata is synced. */
   readonly metaSync?: MetaSyncConfig;
   /** Test seam — defaults to the wallet's real spark proxy. */
   readonly sparkApis?: SparkControllerOptions["spark"];
@@ -1281,6 +1439,8 @@ type WalletEngine = {
   readonly transactions: TransactionController;
   readonly requests: RequestController;
   readonly addressBook: AddressBookController;
+  readonly connections: ConnectionController;
+  readonly eip1193: Eip1193Handler;
   /** Read and receive surface; every payment goes through `requests`. */
   readonly spark: Omit<SparkController, "send" | "payInvoice" | "paySparkInvoice" | "withdraw">;
   readonly accounts: AccountTreeController;
@@ -1301,36 +1461,26 @@ type WalletEngine = {
   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;
 };
@@ -1340,10 +1490,7 @@ type ResolveOptions = ParseOptions & {
  * 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, 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 };
+export type { AccountGroup, AccountTreeState, AddressBookEntry, AddressBookErrorCategory, AddressBookState, AddressFamily, BackupControllerState, BackupErrorCategory, BrowserOrigin, CloudStore, AccountGroup$1 as ConnectionAccountGroup, ConnectionOrigin, ConnectionScope, ConnectionSession, ConnectionState, ControllerOptions, Eip1193Event, Eip1193Request, EngineCollection, EngineErrorCode, EngineLogger, EngineOptions, EngineStore, EventBus, EvmSignInput, MetaDoc, MetaDocGroup, MetaDocTree, MetaDocWallet, MetaSyncConfig, MetaSyncRelayPort, MetaSyncState, MetaSyncWalletStatus, PayInput, PayParams, PaymentNote, PaymentOption, PaymentParse, PaymentRequest, PendingConnection, PendingRequest, PrepareZapContext, PrepareZapParams, PreparedSparkAction, PreparedZap, RequestCheckCode, RequestControllerState, RequestInput, RequestMethod, RequestOrigin, RequestStage, RiskFinding, SignLogEntry, SignLogOutcome, SignatureResult, SparkAccountState, SparkActivity, SparkClientFactory, SparkControllerOptions, SparkControllerState, SparkDepositInput, SparkDisplay, SparkErrorCategory, SparkExitInput, SparkResult, WalletEngine, WithdrawLnurlParams, ZapRecipient };
 //# sourceMappingURL=index.d.mts.map