routstrd 0.4.10 → 0.4.12

package/src/daemon/wallet/index.ts

@@ -1,11 +1,24 @@
 import { getTokenMetadata } from "@cashu/cashu-ts";
 import { InsufficientBalanceError } from "@routstr/sdk";
 import { WalletConnect } from "applesauce-wallet-connect";
+import { WalletBaseError } from "applesauce-wallet-connect/helpers/error";
 import { RelayPool } from "applesauce-relay";
 import { logger } from "../../utils/logger";
-import { createCocodClient, type CocodClient } from "./cocod-client";
+import { withTimeout } from "../../utils/with-timeout";
+import type { WalletClient } from "./wallet-client";
 import { startAutoRefillLoop, type AutoRefillConfig } from "./auto-refill";
 
+/**
+ * NWC reads (get_info/get_balance) should answer in a couple of seconds. If
+ * they don't, the long-lived relay subscription is presumed stale and the
+ * connection is rebuilt before one retry.
+ */
+const NWC_READ_TIMEOUT_MS = 15_000;
+/** Overall bound including encryption negotiation; replies have a library 30s timeout. */
+const NWC_PAY_TIMEOUT_MS = 45_000;
+
+type NwcPayment = { preimage?: string; fees_paid?: number };
+
 export function decodeCashuTokenAmount(token: string): {
   amount: number;
   unit: "sat" | "msat";
@@ -21,7 +34,7 @@ export function decodeCashuTokenAmount(token: string): {
 }
 
 export async function receiveCashuToken(
-  client: Pick<CocodClient, "receiveCashu">,
+  client: Pick<WalletClient, "receiveCashu">,
   token: string,
 ): Promise<{ message: string; amount: number; unit: "sat" | "msat" }> {
   // Validate the token before handing it to a state-changing wallet call. This
@@ -33,10 +46,14 @@ export async function receiveCashuToken(
 }
 
 export interface WalletAdapterOptions {
-  cocodPath?: string | null;
-  walletClient?: CocodClient;
+  /** The in-process wallet engine. Required — construct it with `createCocoClient()`. */
+  walletClient: WalletClient;
   /** NWC connection string for Lightning funding (uses applesauce-wallet-connect) */
   nwcConnectionString?: string;
+  /** Override the NWC read timeout in milliseconds (test hook). */
+  nwcReadTimeoutMs?: number;
+  /** Override the NWC payment timeout in milliseconds (test hook). */
+  nwcPayTimeoutMs?: number;
   /** Auto-refill configuration (static, for startup only) */
   autoRefill?: AutoRefillConfig;
   /**
@@ -48,10 +65,9 @@ export interface WalletAdapterOptions {
 }
 
 export async function createWalletAdapter(
-  options: WalletAdapterOptions = {},
+  options: WalletAdapterOptions,
 ) {
-  const client =
-    options.walletClient || createCocodClient({ cocodPath: options.cocodPath });
+  const client = options.walletClient;
   let activeMintUrl: string | null = null;
   let mintUnits: Record<string, "sat" | "msat"> = {};
 
@@ -82,19 +98,44 @@ export async function createWalletAdapter(
 
   let wallet: WalletConnect | undefined;
   let pool: RelayPool | undefined;
+  let nwcConnectionString = options.nwcConnectionString;
+  const nwcReadTimeoutMs = options.nwcReadTimeoutMs ?? NWC_READ_TIMEOUT_MS;
+  const nwcPayTimeoutMs = options.nwcPayTimeoutMs ?? NWC_PAY_TIMEOUT_MS;
 
   // Getter for the current wallet instance (used by auto-refill loop)
   const getWallet = (): WalletConnect | undefined => wallet;
 
-  if (options.nwcConnectionString) {
-    pool = new RelayPool();
-    wallet = WalletConnect.fromConnectURI(options.nwcConnectionString, { pool });
+  /** Close the active relay pool, if any. */
+  function closeNwcPool(): void {
+    if (pool) {
+      for (const [url] of pool.relays) {
+        pool.remove(url, true);
+      }
+    }
+    pool = undefined;
+  }
+
+  /**
+   * (Re)create the relay pool + WalletConnect client for a connection string.
+   * Shared by interactive connects and self-healing recovery so both paths use
+   * identical setup.
+   */
+  function connectNwc(connectionString: string, reason: string): void {
+    const nextPool = new RelayPool();
+    const nextWallet = WalletConnect.fromConnectURI(connectionString, {
+      pool: nextPool,
+    });
+
+    pool = nextPool;
+    wallet = nextWallet;
+    nwcConnectionString = connectionString;
 
     // Connect in background (non-blocking)
-    wallet.waitForService()
+    nextWallet
+      .waitForService()
       .then(() => {
         logger.log(
-          `[nwc] NWC wallet connected. Relay: ${wallet!.relays[0]}, Service: ${wallet!.service}`,
+          `[nwc] NWC wallet ${reason}. Relay: ${nextWallet.relays[0]}, Service: ${nextWallet.service}`,
         );
       })
       .catch((err) => {
@@ -102,39 +143,97 @@ export async function createWalletAdapter(
       });
   }
 
+  /**
+   * Rebuild the NWC connection in place after a request stalled. applesauce's
+   * request timeout only covers the response stream, so a stale relay
+   * subscription can leave `getInfo`/`getBalance` pending forever while it
+   * negotiates encryption. Recreating the pool gives the next call a fresh
+   * subscription.
+   */
+  function rebuildNwcConnection(reason: string): void {
+    if (!nwcConnectionString) return;
+    closeNwcPool();
+    wallet = undefined;
+    connectNwc(nwcConnectionString, reason);
+  }
+
+  /**
+   * Run an idempotent NWC read, bounding the wait and rebuilding the connection
+   * once if it stalls.
+   */
+  async function nwcRead<T>(
+    label: string,
+    operation: (w: WalletConnect) => Promise<T>,
+  ): Promise<T> {
+    const first = wallet;
+    if (!first?.service) {
+      throw new Error("NWC not connected");
+    }
+    try {
+      return await withTimeout(
+        operation(first),
+        nwcReadTimeoutMs,
+        `${label} timed out`,
+      );
+    } catch (error) {
+      // A normal NIP-47 error proves the wallet answered. Keep other calls alive.
+      if (error instanceof WalletBaseError || !nwcConnectionString) throw error;
+      logger.warn(
+        `[nwc] ${label} failed (${(error as Error).message}); rebuilding NWC connection and retrying`,
+      );
+      rebuildNwcConnection("reconnected after stall");
+      const retry = wallet;
+      if (!retry?.service) throw error;
+      return await withTimeout(
+        operation(retry),
+        nwcReadTimeoutMs,
+        `${label} timed out after reconnect`,
+      );
+    }
+  }
+
+  /**
+   * Pay a BOLT-11 invoice over NWC with a bounded wait. A timeout rebuilds the
+   * relay connection so later calls recover without a daemon restart. The
+   * payment is not retried here. A timeout is an unknown payment outcome,
+   * not proof of failure; callers must reconcile before trying a fresh invoice.
+   */
+  async function payNwcInvoice(invoice: string): Promise<NwcPayment> {
+    const payer = wallet;
+    if (!payer?.service) throw new Error("NWC not connected");
+    try {
+      return await withTimeout(
+        payer.payInvoice(invoice),
+        nwcPayTimeoutMs,
+        "NWC payment timed out",
+      );
+    } catch (error) {
+      // Include the library's own timeout, but not normal wallet error replies.
+      if (!(error instanceof WalletBaseError)) {
+        rebuildNwcConnection("reconnected after payment stall");
+      }
+      throw error;
+    }
+  }
+
+  if (options.nwcConnectionString) {
+    connectNwc(options.nwcConnectionString, "connected");
+  }
+
   const walletAdapter = {
     async reconnect(connectionString?: string): Promise<void> {
       logger.log(
         `[nwc] Reconnecting NWC wallet... ${connectionString ? "new connection string provided" : "disconnecting"}`,
       );
 
-      // 1. Close existing relay pool connections
-      if (pool) {
-        for (const [url] of pool.relays) {
-          pool.remove(url, true);
-        }
-      }
-
-      // 2. Update wallet reference
+      // Close existing relay pool connections and update the wallet reference
+      closeNwcPool();
       wallet = undefined;
-      pool = undefined;
 
-      // 3. Create new wallet if connection string provided
       if (connectionString) {
-        pool = new RelayPool();
-        wallet = WalletConnect.fromConnectURI(connectionString, { pool });
-
-        // Connect in background (non-blocking)
-        wallet.waitForService()
-          .then(() => {
-            logger.log(
-              `[nwc] NWC wallet reconnected. Relay: ${wallet!.relays[0]}, Service: ${wallet!.service}`,
-            );
-          })
-          .catch((err) => {
-            logger.error(`[nwc] NWC reconnection failed: ${err.message}`);
-          });
+        connectNwc(connectionString, "reconnected");
       } else {
+        nwcConnectionString = undefined;
         logger.log("[nwc] NWC wallet disconnected.");
       }
     },
@@ -192,9 +291,9 @@ export async function createWalletAdapter(
         const { invoice } = await client.receiveBolt11(amount, mintUrl);
         logger.log(`[nwc]   Invoice: ${invoice}`);
 
-        // Step 3: Pay it via NWC
+        // Step 3: Pay it via NWC (bounded — a stale relay must not hang the CLI)
         logger.log("[nwc] Paying invoice via NWC...");
-        const { preimage, fees_paid } = await wallet.payInvoice(invoice);
+        const { preimage, fees_paid } = await payNwcInvoice(invoice);
         logger.log(`[nwc]   ✅ Payment successful!`);
         logger.log(`[nwc]   Preimage: ${preimage}`);
         if (fees_paid !== undefined) {
@@ -244,10 +343,10 @@ export async function createWalletAdapter(
       }
 
       try {
-        const info = await wallet.getInfo();
+        const info = await nwcRead("get_info", (w) => w.getInfo());
         let balance: number | undefined;
         try {
-          const bal = await wallet.getBalance();
+          const bal = await nwcRead("get_balance", (w) => w.getBalance());
           balance = Math.floor(bal.balance / 1000); // msats → sats
         } catch {
           // Balance might not be available
@@ -326,21 +425,40 @@ export async function createWalletAdapter(
 
   let stopAutoRefill: (() => void) | undefined;
 
+  /**
+   * Start the auto-refill loop if it is not already running. Safe to call more
+   * than once; it becomes a no-op after the first call.
+   */
+  function ensureAutoRefillLoop(): void {
+    if (stopAutoRefill) return;
+    const getConfig = options.getAutoRefillConfig ?? (() => options.autoRefill);
+    stopAutoRefill = startAutoRefillLoop(
+      client,
+      getWallet,
+      getConfig,
+      5000,
+      payNwcInvoice,
+    );
+  }
+
   const autoRefillConfig = options.getAutoRefillConfig
     ? options.getAutoRefillConfig()
     : options.autoRefill;
 
-  if (autoRefillConfig && wallet) {
-    const getConfig = options.getAutoRefillConfig ?? (() => options.autoRefill);
-    stopAutoRefill = startAutoRefillLoop(client, getWallet, getConfig);
-    logger.log(
-      `[wallet] Auto-refill enabled: threshold=${autoRefillConfig.threshold} sats, amount=${autoRefillConfig.amount} sats, cooldown=${autoRefillConfig.cooldownMs / 60000} minutes`,
-    );
-  } else if (wallet && options.getAutoRefillConfig) {
-    // Wallet exists but auto-refill is not currently enabled.
-    // Start the loop anyway so it can pick up changes without a restart.
-    stopAutoRefill = startAutoRefillLoop(client, getWallet, options.getAutoRefillConfig);
-    logger.log("[wallet] Auto-refill loop started (currently disabled — enable via CLI to activate)");
+  if (options.getAutoRefillConfig || options.autoRefill) {
+    // Start the loop even when no wallet is connected yet: it reads the wallet
+    // and config fresh each cycle, so a later `nwc connect` activates refills
+    // without a daemon restart.
+    ensureAutoRefillLoop();
+    if (autoRefillConfig) {
+      logger.log(
+        `[wallet] Auto-refill enabled: threshold=${autoRefillConfig.threshold} sats, amount=${autoRefillConfig.amount} sats, cooldown=${autoRefillConfig.cooldownMs / 60000} minutes`,
+      );
+    } else {
+      logger.log(
+        "[wallet] Auto-refill loop started (currently disabled — enable via CLI to activate)",
+      );
+    }
   }
 
   try {

package/src/daemon/wallet/mint-quote-recovery.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure helpers for PAID mint-quote recovery.
+ *
+ * A mint quote can be PAID at the mint while its local operation is still
+ * `pending` (the Lightning payment landed before expiry while the daemon was
+ * down, so no local observation was ever recorded) or even terminally
+ * `failed` (coco gives up when the mint refuses to sign, for example after the
+ * invoice expiry). Claimability still depends on the mint accepting issuance.
+ * This feature retries the stored outputs or restores their signatures; it
+ * does not regenerate outputs rejected by the mint (for example an inactive
+ * keyset). coco already reconciles pending paid quotes at startup and in the
+ * periodic sweep. The new capability is operator-targeted recovery, including
+ * explicitly reopening failed operations, alongside safer cleanup.
+ *
+ * Recovery asks the mint what it thinks, then retries issuance or restore. These helpers decide *what* to do from a remote observation; the
+ * actual state transitions are applied by the in-process coco wallet client
+ * so coco-core's operation services emit their normal events and release
+ * proof reservations. Keeping the decisions here makes them unit testable
+ * without a wallet database or network access.
+ */
+
+/** Subset of coco's mint operation rows that recovery needs. */
+export interface MintQuoteRecoveryCandidate {
+  id: string;
+  mintUrl: string;
+  quoteId?: string;
+  state: string;
+  /** Quote amount in sats. */
+  amount: number;
+  /** Quote expiry in epoch seconds. `0` means unknown/not applicable. */
+  expiry: number;
+  /** Last quote state observed from the mint (UNPAID, PAID, ISSUED). */
+  lastObservedRemoteState?: string;
+  error?: string;
+}
+
+/** Coco's classification of a fresh remote quote check. */
+export type PendingMintCheckCategory =
+  | "waiting"
+  | "ready"
+  | "completed"
+  | "terminal";
+
+/** What recovery should do with a quote after checking it with the mint. */
+export type MintQuoteRecoveryDecision =
+  | { action: "finalize"; observedRemoteState: "PAID" | "ISSUED" }
+  | { action: "waiting" }
+  | { action: "terminal" };
+
+/**
+ * Map a remote quote check onto a recovery action.
+ *
+ * - `ready` means the mint reports the quote PAID but never issued: submit the
+ *   operation's stored outputs to claim the sats.
+ * - `completed` means the mint already issued it: recover the signatures
+ *   (NUT-09) instead of minting again.
+ * - `waiting` means the mint still reports the quote UNPAID: nothing is
+ *   claimable, so leave the operation alone.
+ * - `terminal` means the quote can no longer be issued (for example the mint
+ *   refused an expired quote). coco persists that verdict as a failed
+ *   operation, so recovery must report it rather than treat it as progress.
+ */
+export function classifyMintQuoteObservation(
+  category: PendingMintCheckCategory,
+): MintQuoteRecoveryDecision {
+  switch (category) {
+    case "ready":
+      return { action: "finalize", observedRemoteState: "PAID" };
+    case "completed":
+      return { action: "finalize", observedRemoteState: "ISSUED" };
+    case "waiting":
+      return { action: "waiting" };
+    case "terminal":
+      return { action: "terminal" };
+  }
+}
+
+export interface MintQuoteRecoverySelectionOptions<
+  T extends MintQuoteRecoveryCandidate,
+> {
+  mints: T[];
+  /**
+   * Also consider terminally failed operations. Off by default: re-opening a
+   * failed operation is a mutation, so only an explicit user-invoked recovery
+   * may do it. Startup recovery must never resurrect quotes on its own.
+   */
+  includeFailed?: boolean;
+}
+
+export interface MintQuoteRecoverySelection<
+  T extends MintQuoteRecoveryCandidate,
+> {
+  /** Pending (or executing) operations that need a fresh mint observation. */
+  pending: T[];
+  /** Failed operations the caller may re-open and retry. */
+  failed: T[];
+}
+
+/**
+ * Split operations into those recovery should check and those that were
+ * already given up on.
+ *
+ * Every `pending` operation is selected: only the mint knows whether an
+ * expired quote was paid before the local invoice ran out. `executing`
+ * operations are recovered too, since a crash mid-mint leaves outputs that
+ * may already be signed.
+ */
+export function selectMintQuotesForRecovery<
+  T extends MintQuoteRecoveryCandidate,
+>(options: MintQuoteRecoverySelectionOptions<T>): MintQuoteRecoverySelection<T> {
+  const { mints, includeFailed = false } = options;
+  const pending = mints.filter(
+    (op) => op.state === "pending" || op.state === "executing",
+  );
+  const failed = includeFailed
+    ? mints.filter((op) => op.state === "failed")
+    : [];
+  return { pending, failed };
+}