routstrd 0.3.11 → 0.4.1

package/src/daemon/wallet/migration.ts

@@ -0,0 +1,154 @@
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+} from "fs";
+import { Database } from "bun:sqlite";
+import { basename, dirname, join } from "path";
+import { legacyCocodDir, walletDir } from "./paths";
+import {
+  summarizeWalletDirectory,
+  verifyDatabase,
+  WalletMigrationConflictError,
+  type WalletSummary,
+} from "./diagnostics";
+import { classifyWalletMigration } from "./wallet-state";
+
+export type WalletMigrationResult =
+  | { status: "fresh" }
+  | { status: "already-current" }
+  | { status: "migrated"; from: string; to: string; cleanupWarnings: string[] };
+
+export interface WalletMigrationOptions {
+  walletDir?: string;
+  legacyDir?: string;
+  /** Called after state validation and before legacy files are copied. */
+  assertLegacyStopped?: () => void | Promise<void>;
+  /** Claims the legacy cocod exclusion lock for the duration of the copy. */
+  acquireLegacyLock?: () => (() => void) | Promise<() => void>;
+}
+
+function sqlString(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+/** Write a standalone SQLite snapshot containing committed WAL frames. */
+function snapshotDatabase(sourcePath: string, destinationPath: string): void {
+  const source = new Database(sourcePath);
+  let sourceSummary: WalletSummary;
+  try {
+    sourceSummary = verifyDatabase(source, "Legacy wallet database");
+    source.exec(`VACUUM INTO ${sqlString(destinationPath)}`);
+  } finally {
+    source.close();
+  }
+
+  const destination = new Database(destinationPath, { readonly: true });
+  try {
+    const destinationSummary = verifyDatabase(destination, "Staged wallet database");
+    if (JSON.stringify(sourceSummary) !== JSON.stringify(destinationSummary)) {
+      throw new Error(
+        "Staged wallet database does not contain the same proofs, counters, operations, and mints as the legacy database.",
+      );
+    }
+  } finally {
+    destination.close();
+  }
+}
+
+/**
+ * Copy a legacy cocod wallet into the canonical routstrd wallet directory.
+ * The staging directory is renamed atomically, so the canonical path is never
+ * exposed with only one of its two required files.
+ */
+export async function migrateLegacyWallet(
+  options: WalletMigrationOptions = {},
+): Promise<WalletMigrationResult> {
+  const targetDir = options.walletDir || walletDir();
+  const sourceDir = options.legacyDir || legacyCocodDir();
+  const sourceConfig = join(sourceDir, "config.json");
+  const sourceDb = join(sourceDir, "coco.db");
+  const sourceWal = `${sourceDb}-wal`;
+  const sourceShm = `${sourceDb}-shm`;
+  const classification = classifyWalletMigration(targetDir, sourceDir);
+  switch (classification.kind) {
+    case "fresh":
+      return { status: "fresh" };
+    case "already-current":
+      return { status: "already-current" };
+    case "migrate":
+      break;
+    case "conflict":
+      throw new WalletMigrationConflictError(
+        summarizeWalletDirectory(targetDir, "canonical"),
+        summarizeWalletDirectory(sourceDir, "legacy"),
+      );
+    case "orphaned-sidecars":
+      throw new Error(
+        `Cannot migrate wallet: ${sourceDir} contains SQLite sidecar files without coco.db. ` +
+          "Restore the matching main database before migration.",
+      );
+    case "database-only":
+      throw new Error(
+        `Cannot migrate wallet: ${targetDir} is ${classification.targetState} and ${sourceDir} is ${classification.sourceState}. ` +
+          "A coco.db without config.json cannot be opened; restore the matching config first.",
+      );
+  }
+
+  await options.assertLegacyStopped?.();
+  const releaseLegacyLock = await options.acquireLegacyLock?.();
+  const stagingDir = join(
+    dirname(targetDir),
+    `.${targetDir.split(/[\\/]/).at(-1) || "wallet"}.staging-${process.pid}-${Date.now()}`,
+  );
+
+  try {
+    // Recheck after claiming the exclusion lock to close the probe/claim race.
+    await options.assertLegacyStopped?.();
+    mkdirSync(dirname(targetDir), { recursive: true, mode: 0o700 });
+    mkdirSync(stagingDir, { mode: 0o700 });
+    const stagedConfig = join(stagingDir, "config.json");
+    const stagedDb = join(stagingDir, "coco.db");
+    copyFileSync(sourceConfig, stagedConfig);
+    chmodSync(stagedConfig, 0o600);
+    const hasSourceDb = existsSync(sourceDb);
+    if (hasSourceDb) {
+      // A SQLite WAL is part of the logical database. Raw-copying coco.db can
+      // silently omit proofs and counters that have not yet been checkpointed.
+      snapshotDatabase(sourceDb, stagedDb);
+      chmodSync(stagedDb, 0o600);
+    }
+
+    if (statSync(stagedConfig).size !== statSync(sourceConfig).size) {
+      throw new Error("Cannot migrate wallet: staged config failed size validation.");
+    }
+
+    renameSync(stagingDir, targetDir);
+  } catch (error) {
+    rmSync(stagingDir, { recursive: true, force: true });
+    throw error;
+  } finally {
+    releaseLegacyLock?.();
+  }
+
+  // Preserve the complete legacy SQLite file set for manual recovery instead
+  // of deleting the only rollback copy immediately after migration.
+  const cleanupWarnings: string[] = [];
+  const sourceFiles = [sourceConfig, sourceDb, sourceWal, sourceShm].filter(existsSync);
+  if (sourceFiles.length > 0) {
+    const archiveDir = join(sourceDir, `wallet-migrated-${Date.now()}`);
+    try {
+      mkdirSync(archiveDir, { mode: 0o700 });
+      for (const path of sourceFiles) renameSync(path, join(archiveDir, basename(path)));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      cleanupWarnings.push(`Could not archive legacy wallet files: ${message}`);
+    }
+  }
+
+  return { status: "migrated", from: sourceDir, to: targetDir, cleanupWarnings };
+}

package/src/daemon/wallet/paths.ts

@@ -0,0 +1,33 @@
+import { join } from "path";
+
+function homeDir(): string {
+  return process.env.HOME || process.env.USERPROFILE || "";
+}
+
+/** Root directory for routstrd state. Evaluated lazily so env overrides work in tests. */
+export function routstrdConfigDir(): string {
+  return process.env.ROUTSTRD_DIR || join(homeDir(), ".routstrd");
+}
+
+/** Canonical directory for the in-process Cashu wallet. */
+export function walletDir(): string {
+  return process.env.ROUTSTRD_WALLET_DIR || join(routstrdConfigDir(), "wallet");
+}
+
+/** Lock owned by an in-process routstrd wallet instance. */
+export function walletPidPath(): string {
+  return process.env.ROUTSTRD_WALLET_PID || join(walletDir(), "wallet.pid");
+}
+
+/** Legacy external cocod directory. This is not the routstrd wallet directory. */
+export function legacyCocodDir(): string {
+  return process.env.COCOD_DIR || join(homeDir(), ".cocod");
+}
+
+export function legacyCocodSocketPath(): string {
+  return process.env.COCOD_SOCKET || join(legacyCocodDir(), "cocod.sock");
+}
+
+export function legacyCocodPidPath(): string {
+  return process.env.COCOD_PID || join(legacyCocodDir(), "cocod.pid");
+}

package/src/daemon/wallet/receive-dedup.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from "bun:test";
+import type { ReceiveOperation } from "@cashu/coco-core";
+import { Database } from "bun:sqlite";
+import {
+  clearInterruptedReceiveReservations,
+  deleteReceiveTokenReservation,
+  groupExecutingReceives,
+  hashReceiveToken,
+  initReceiveDedupSchema,
+  listProcessingReceiveTokens,
+  reconcileExecutingReceives,
+  reserveReceiveToken,
+  updateReceiveToken,
+  type ReceiveReconcileSource,
+} from "./receive-dedup";
+
+function operation(
+  id: string,
+  secret: string,
+  outputB: string,
+  createdAt = 1,
+): Extract<ReceiveOperation, { state: "executing" }> {
+  return {
+    id,
+    mintUrl: "https://mint.example",
+    unit: "sat",
+    amount: 1,
+    state: "executing",
+    createdAt,
+    updatedAt: createdAt,
+    fee: 0,
+    inputProofs: [{ amount: 1, id: "keyset", secret, C: "02" }],
+    outputData: {
+      keep: [
+        {
+          blindedMessage: { amount: 1, id: "keyset", B_: outputB },
+          blindingFactor: "1",
+          secret: "00",
+        },
+      ],
+      send: [],
+    },
+  };
+}
+
+function source(options: {
+  operations: ReceiveOperation[];
+  states?: string[];
+  restored?: string[];
+  saved?: string[];
+}) {
+  const rolledBack: Array<{ id: string; reason: string }> = [];
+  let stateChecks = 0;
+  let restoreChecks = 0;
+  const reconcileSource: ReceiveReconcileSource = {
+    listExecuting: async () => options.operations,
+    checkProofStates: async (op) => {
+      stateChecks++;
+      return (options.states ?? op.inputProofs.map(() => "SPENT")).map((state) => ({ state }));
+    },
+    restoreOutputs: async (_mintUrl, outputs) => {
+      restoreChecks++;
+      const restored = new Set(options.restored ?? []);
+      return outputs.filter((output) => restored.has(output.B_));
+    },
+    hasSavedOutputs: async (op) => (options.saved ?? []).includes(op.id),
+    rollBack: async (op, reason) => {
+      rolledBack.push({ id: op.id, reason });
+    },
+  };
+  return {
+    source: reconcileSource,
+    rolledBack,
+    stateChecks: () => stateChecks,
+    restoreChecks: () => restoreChecks,
+  };
+}
+
+describe("receive token hashing and reservation", () => {
+  it("hashes the exact encoded token deterministically", () => {
+    expect(hashReceiveToken("cashuA")).toBe(hashReceiveToken("cashuA"));
+    expect(hashReceiveToken("cashuA")).not.toBe(hashReceiveToken("cashuB"));
+  });
+
+  it("atomically reserves an exact token once", () => {
+    const database = new Database(":memory:");
+    initReceiveDedupSchema(database);
+    const first = reserveReceiveToken(database, "cashuA");
+    const second = reserveReceiveToken(database, "cashuA");
+    expect(first.acquired).toBe(true);
+    expect(second).toMatchObject({
+      acquired: false,
+      existing: { state: "processing", operationId: null },
+    });
+    database.close();
+  });
+
+  it("persists successful status and releases retryable reservations", () => {
+    const database = new Database(":memory:");
+    initReceiveDedupSchema(database);
+    const reservation = reserveReceiveToken(database, "cashuA");
+    updateReceiveToken(database, reservation.tokenHash, {
+      state: "succeeded",
+      operationId: "receive-1",
+    });
+    expect(reserveReceiveToken(database, "cashuA").existing).toMatchObject({
+      state: "succeeded",
+      operationId: "receive-1",
+    });
+    deleteReceiveTokenReservation(database, reservation.tokenHash);
+    expect(reserveReceiveToken(database, "cashuA").acquired).toBe(true);
+    database.close();
+  });
+
+  it("clears only interrupted reservations without Coco operation ids", () => {
+    const database = new Database(":memory:");
+    initReceiveDedupSchema(database);
+    const orphan = reserveReceiveToken(database, "orphan");
+    const linked = reserveReceiveToken(database, "linked");
+    updateReceiveToken(database, linked.tokenHash, {
+      state: "processing",
+      operationId: "receive-1",
+    });
+    expect(clearInterruptedReceiveReservations(database)).toBe(1);
+    expect(listProcessingReceiveTokens(database)).toEqual([
+      expect.objectContaining({ tokenHash: linked.tokenHash, operationId: "receive-1" }),
+    ]);
+    expect(reserveReceiveToken(database, "orphan").tokenHash).toBe(orphan.tokenHash);
+    database.close();
+  });
+});
+
+describe("legacy receive grouping", () => {
+  it("groups identical input proofs independent of operation id", () => {
+    const groups = groupExecutingReceives([
+      operation("one", "same", "B1"),
+      operation("two", "same", "B2"),
+      operation("three", "different", "B3"),
+    ]);
+    expect(groups.map((group) => group.map((op) => op.id))).toEqual([
+      ["one", "two"],
+      ["three"],
+    ]);
+  });
+
+  it("checks an unspent duplicate group once and retains one operation", async () => {
+    const mock = source({
+      operations: [operation("one", "same", "B1", 1), operation("two", "same", "B2", 2)],
+      states: ["UNSPENT"],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.stateChecks()).toBe(1);
+    expect(mock.restoreChecks()).toBe(0);
+    expect(mock.rolledBack.map((entry) => entry.id)).toEqual(["two"]);
+    expect(result).toMatchObject({ rolledBack: 1, retained: 1, unresolved: 0 });
+  });
+
+  it("rolls back all spent duplicates when restore finds no outputs", async () => {
+    const mock = source({
+      operations: [operation("one", "same", "B1"), operation("two", "same", "B2")],
+      states: ["SPENT"],
+      restored: [],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.stateChecks()).toBe(1);
+    expect(mock.restoreChecks()).toBe(1);
+    expect(mock.rolledBack.map((entry) => entry.id)).toEqual(["one", "two"]);
+    expect(result.rolledBack).toBe(2);
+  });
+
+  it("retains the operation whose output the mint can restore", async () => {
+    const mock = source({
+      operations: [operation("one", "same", "B1"), operation("two", "same", "B2")],
+      states: ["SPENT"],
+      restored: ["B2"],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.rolledBack.map((entry) => entry.id)).toEqual(["one"]);
+    expect(result).toMatchObject({ rolledBack: 1, retained: 1 });
+  });
+
+  it("leaves a group untouched when the mint returns incomplete states", async () => {
+    const first = operation("one", "same", "B1");
+    first.inputProofs.push({ amount: 1, id: "keyset", secret: "other", C: "03" });
+    const second = operation("two", "same", "B2");
+    second.inputProofs.push({ amount: 1, id: "keyset", secret: "other", C: "03" });
+    const mock = source({
+      operations: [first, second],
+      states: ["SPENT"],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.rolledBack).toEqual([]);
+    expect(mock.restoreChecks()).toBe(0);
+    expect(result.unresolved).toBe(2);
+  });
+
+  it("leaves a group untouched when proof states are mixed", async () => {
+    const first = operation("one", "same", "B1");
+    first.inputProofs.push({ amount: 1, id: "keyset", secret: "other", C: "03" });
+    const second = operation("two", "same", "B2");
+    second.inputProofs.push({ amount: 1, id: "keyset", secret: "other", C: "03" });
+    const mock = source({
+      operations: [first, second],
+      states: ["SPENT", "UNSPENT"],
+    });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.rolledBack).toEqual([]);
+    expect(result.unresolved).toBe(2);
+  });
+
+  it("scales mint checks with unique input groups rather than row count", async () => {
+    const operations: ReceiveOperation[] = [];
+    for (let group = 0; group < 47; group++) {
+      const repeats = group < 44 ? 41 : 40; // 1,924 rows total
+      for (let index = 0; index < repeats; index++) {
+        operations.push(
+          operation(
+            `operation-${group}-${index}`,
+            `secret-${group}`,
+            `B-${group}-${index}`,
+            index,
+          ),
+        );
+      }
+    }
+    expect(operations).toHaveLength(1924);
+    const mock = source({ operations, states: ["SPENT"], restored: [] });
+    const result = await reconcileExecutingReceives(mock.source);
+    expect(mock.stateChecks()).toBe(47);
+    expect(mock.restoreChecks()).toBe(47);
+    expect(result).toMatchObject({
+      executing: 1924,
+      uniqueGroups: 47,
+      rolledBack: 1924,
+      unresolved: 0,
+    });
+  });
+});