routstrd 0.4.10 → 0.4.12

package/src/daemon/wallet/recovery-probe.ts

@@ -0,0 +1,312 @@
+/**
+ * Mint reachability probing and targeted (per-operation) wallet recovery.
+ *
+ * Coco's global recovery sweeps walk every non-terminal operation one at a
+ * time; each operation at an unreachable mint costs a full network timeout.
+ * This module probes every mint that has stuck operations once, in parallel,
+ * and drives recovery per operation only for mints that answer — so one dead
+ * mint costs a single short probe instead of N sequential timeouts, and its
+ * operations stay parked (exactly as coco's "will retry later" path leaves
+ * them) until an explicit mid-session recovery (see recoverStuckOperations
+ * in coco-client.ts) or a later startup finds the mint reachable.
+ */
+import { normalizeMintUrl, type Manager } from "@cashu/coco-core";
+import { recoveryKey, trackRecovery, waitForRecoveryWork, RecoveryWaitTimeout, type RecoveryWork } from "./recovery-work";
+import { logger } from "../../utils/logger";
+
+/** Short probe: a mint that cannot answer /v1/info in 2s slows every op. */
+export const MINT_PROBE_TIMEOUT_MS = 2_000;
+
+type OpsApi = Manager["ops"];
+
+/** Structural subset of the ops APIs used to enumerate and recover operations. */
+export interface StuckOperationSource {
+  send: Pick<OpsApi["send"], "listInFlight" | "refresh" | "diagnostics" | "get">;
+  melt: Pick<OpsApi["melt"], "listInFlight" | "refresh" | "diagnostics">;
+  receive: Pick<OpsApi["receive"], "listInFlight" | "refresh" | "diagnostics">;
+  mint: Pick<OpsApi["mint"], "listInFlight" | "refresh" | "diagnostics">;
+}
+
+export type StuckOperationKind = "send" | "melt" | "receive" | "mint";
+
+export interface StuckOperation {
+  kind: StuckOperationKind;
+  id: string;
+  /** Normalized mint URL. */
+  mintUrl: string;
+  state: string;
+  /** The operation object as returned by the API (needed by service-level recovery). */
+  raw: unknown;
+}
+
+/**
+ * The per-operation send recovery entry points coco keeps private. Send is the
+ * only operation family whose public `refresh()` does not cover `executing`
+ * operations; routstrd already reaches into coco internals the same way for
+ * `mintOperationService` (see coco-client.ts).
+ */
+export interface SendRecoveryService {
+  recoverExecutingOperation(op: unknown): Promise<void>;
+  /**
+   * coco's per-operation lock. It is fail-fast: acquiring an id a live
+   * execute/finalize/recover already holds throws OperationInProgressError
+   * instead of waiting. Holding it across the state re-read and the drive
+   * makes executing-send recovery atomic against a live execute — the same
+   * pattern reopenFailedMintOperation uses for mint operations
+   * (see coco-client.ts).
+   */
+  acquireOperationLock(operationId: string): Promise<() => void>;
+}
+
+export interface RecoveryRunResult {
+  /** Operations for which recovery was attempted (not necessarily completed). */
+  attempted: number;
+  /** Timed-out waits, also included in attempted; underlying work remains tracked. */
+  timedOut: number;
+  /** Locked operations or unfinished work from another pass; retry later. */
+  busy: number;
+  /** Operations skipped for unreachable mints, shutdown, or pass budget exhaustion. */
+  skipped: number;
+  /** Attempts that threw a non-busy, non-timeout error. */
+  failed: number;
+  /** Unreachable mint URL -> number of operations skipped there. */
+  skippedMints: Map<string, number>;
+}
+
+export interface TargetedRecoveryOptions {
+  outstanding?: RecoveryWork;
+  timeoutMs?: number;
+  deadlineMs?: number;
+  shouldStop?: () => boolean;
+  probeTimeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  /** Operation families to recover. Defaults to all four. */
+  kinds?: StuckOperationKind[];
+  /** Pre-collected operations (e.g. from startup gating); default: enumerate now. */
+  stuckOperations?: StuckOperation[];
+  /** Pre-probed unreachable mints; default: probe now. */
+  unreachableMints?: Set<string>;
+  /** Called once per unreachable mint with the number of skipped operations. */
+  onSkippedMint?: (mintUrl: string, opCount: number) => void;
+}
+
+function asStuckOperations(
+  kind: StuckOperationKind,
+  ops: Array<{ id: string; mintUrl: string; state: string }>,
+): StuckOperation[] {
+  const stuck: StuckOperation[] = [];
+  for (const op of ops) {
+    try {
+      stuck.push({
+        kind,
+        id: op.id,
+        mintUrl: normalizeMintUrl(op.mintUrl),
+        state: op.state,
+        raw: op,
+      });
+    } catch {
+      // Preserve malformed persisted URLs; the probe will classify them as
+      // unreachable rather than attempting recovery against an invalid URL.
+      stuck.push({ kind, id: op.id, mintUrl: op.mintUrl, state: op.state, raw: op });
+    }
+  }
+  return stuck;
+}
+
+/**
+ * Enumerate every non-terminal operation across all four operation families.
+ * Returns [] quickly when nothing is stuck, which is the common case.
+ */
+export async function collectStuckOperations(
+  source: StuckOperationSource,
+): Promise<StuckOperation[]> {
+  const [sends, melts, receives, mints] = await Promise.all([
+    source.send.listInFlight(),
+    source.melt.listInFlight(),
+    source.receive.listInFlight(),
+    source.mint.listInFlight(),
+  ]);
+  return [
+    ...asStuckOperations("send", sends),
+    ...asStuckOperations("melt", melts),
+    ...asStuckOperations("receive", receives),
+    ...asStuckOperations("mint", mints),
+  ];
+}
+
+/**
+ * Probe each mint once, in parallel, and return the set of mint URLs that did
+ * not answer `GET /v1/info` in time. A mint that answers with an HTTP error is
+ * still "reachable" — its operations will fail with a real mint error instead
+ * of a network timeout, which is the information recovery needs.
+ */
+export async function probeMintReachability(
+  mintUrls: string[],
+  options: { timeoutMs?: number; fetchImpl?: typeof fetch } = {},
+): Promise<Set<string>> {
+  const fetcher = options.fetchImpl ?? fetch;
+  const timeoutMs = options.timeoutMs ?? MINT_PROBE_TIMEOUT_MS;
+  const unreachable = new Set<string>();
+
+  await Promise.all(
+    mintUrls.map(async (mintUrl) => {
+      try {
+        await fetcher(`${normalizeMintUrl(mintUrl)}/v1/info`, {
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+      } catch (error) {
+        logger.debug("Mint did not answer recovery probe", {
+          mintUrl,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        unreachable.add(mintUrl);
+      }
+    }),
+  );
+
+  return unreachable;
+}
+
+async function recoverStuckOperation(
+  source: StuckOperationSource,
+  sendService: SendRecoveryService,
+  op: StuckOperation,
+): Promise<void> {
+  switch (op.kind) {
+    case "send":
+      if (op.state === "pending") {
+        // Public API: actively re-checks the proofs with the mint.
+        await source.send.refresh(op.id);
+      } else if (op.state === "executing") {
+        // Fail closed: the lock and the drive are private coco internals
+        // (written against coco-core 1.0.1), so a coco bump that renames them
+        // must fail this operation loudly instead of corrupting it.
+        if (
+          typeof sendService.acquireOperationLock !== "function" ||
+          typeof sendService.recoverExecutingOperation !== "function"
+        ) {
+          throw new Error(
+            "coco sendOperationService recovery internals are unavailable; refusing to recover an executing send",
+          );
+        }
+        // recoverExecutingOperation takes no lock and does no state re-read,
+        // so take coco's fail-fast per-operation lock first (throws
+        // OperationInProgressError when a live execute holds the operation —
+        // the driver counts that as busy, not failed) and re-read the state
+        // under it: the snapshot op must still be executing before we drive.
+        const release = await sendService.acquireOperationLock(op.id);
+        try {
+          const latest = await source.send.get(op.id);
+          if (latest?.state === "executing") {
+            await sendService.recoverExecutingOperation(latest);
+          }
+        } finally {
+          release();
+        }
+      }
+      // prepared / rolling_back: the global sweep only warns; nothing to do.
+      return;
+    case "melt":
+      // refresh() covers both pending and executing melt operations.
+      await source.melt.refresh(op.id);
+      return;
+    case "receive":
+      // refresh() actively recovers executing receive operations.
+      await source.receive.refresh(op.id);
+      return;
+    case "mint":
+      // refresh() covers both pending and executing mint operations.
+      await source.mint.refresh(op.id);
+      return;
+  }
+}
+
+/**
+ * Recover every stuck operation whose mint answers a reachability probe,
+ * skipping operations at unreachable mints. Operations are recovered
+ * sequentially per mint (matching the global sweep's ordering guarantees);
+ * skipped operations are left untouched for a later pass, which is exactly
+ * what coco's own "Could not reach mint for recovery, will retry later" path
+ * does with them.
+ */
+export async function runTargetedRecovery(
+  source: StuckOperationSource,
+  sendService: SendRecoveryService,
+  options: TargetedRecoveryOptions = {},
+): Promise<RecoveryRunResult> {
+  const result: RecoveryRunResult = {
+    attempted: 0,
+    timedOut: 0,
+    busy: 0,
+    skipped: 0,
+    failed: 0,
+    skippedMints: new Map(),
+  };
+
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  const deadlineMs = options.deadlineMs ?? 60_000;
+  if (![timeoutMs, deadlineMs].every(n => Number.isFinite(n) && n > 0)) {
+    throw new Error("Recovery budgets must be positive finite numbers");
+  }
+  const deadline = Date.now() + deadlineMs;
+  const outstanding = options.outstanding ?? new Map();
+  const kinds = options.kinds ?? ["send", "melt", "receive", "mint"];
+  const stuck = (options.stuckOperations ?? (await collectStuckOperations(source))).filter(
+    (op) => kinds.includes(op.kind),
+  );
+  if (stuck.length === 0) return result;
+
+  const unreachable =
+    options.unreachableMints ??
+    (await probeMintReachability([...new Set(stuck.map((op) => op.mintUrl))], {
+      timeoutMs: options.probeTimeoutMs,
+      fetchImpl: options.fetchImpl,
+    }));
+
+  for (const mintUrl of unreachable) {
+    const count = stuck.filter((op) => op.mintUrl === mintUrl).length;
+    result.skippedMints.set(mintUrl, count);
+    result.skipped += count;
+    options.onSkippedMint?.(mintUrl, count);
+  }
+
+  for (const op of stuck) {
+    if (unreachable.has(op.mintUrl)) continue;
+    if (options.shouldStop?.() || Date.now() >= deadline) { result.skipped++; continue; }
+    const key = recoveryKey(op.kind, op.id);
+    if (outstanding.has(key)) { result.busy++; continue; }
+    // Cheap pre-filter for live operations; the lock inside
+    // recoverStuckOperation is what actually makes the drive atomic.
+    if (source[op.kind].diagnostics.isLocked(op.id)) {
+      result.busy++;
+      continue;
+    }
+    if (op.kind === "send" && !["pending", "executing"].includes(op.state)) continue;
+    result.attempted++;
+    try {
+      const work = trackRecovery(outstanding, key, recoverStuckOperation(source, sendService, op));
+      await waitForRecoveryWork(work, Math.min(timeoutMs, Math.max(1, deadline - Date.now())));
+    } catch (error) {
+      if (error instanceof RecoveryWaitTimeout) { result.timedOut++; continue; }
+      // A live execute grabbed the operation between the isLocked pre-filter
+      // and the lock acquisition: busy, not failed — leave it for a later
+      // pass. Name-matched like runMintQuoteRecovery does, because the error
+      // crosses a package boundary.
+      if (error instanceof Error && error.name === "OperationInProgressError") {
+        result.busy++;
+        continue;
+      }
+      // Same semantics as coco's tryRecover*: leave the operation for the
+      // next pass. A reachable mint can still reject a specific operation.
+      result.failed++;
+      logger.warn("Targeted operation recovery did not complete", {
+        kind: op.kind,
+        operationId: op.id,
+        mintUrl: op.mintUrl,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return result;
+}

package/src/daemon/wallet/recovery-work.ts

@@ -0,0 +1,45 @@
+/** A timed-out wait is not cancellation: retain work until it actually settles. */
+export type RecoveryWork = Map<string, Promise<unknown>>;
+export const recoveryKey = (kind: string, id: string): string => `${kind}:${id}`;
+
+export function trackRecovery<T>(work: RecoveryWork, key: string, promise: Promise<T>): Promise<T> {
+  work.set(key, promise);
+  const clear = () => { if (work.get(key) === promise) work.delete(key); };
+  void promise.then(clear, clear);
+  return promise;
+}
+
+export class RecoveryWaitTimeout extends Error {
+  constructor() { super("Timed out waiting for recovery; underlying work is still tracked"); }
+}
+
+export async function waitForRecoveryWork<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([promise, new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new RecoveryWaitTimeout()), timeoutMs);
+    })]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/** Drain actual work, including work registered while an earlier task settles. */
+export async function drainRecoveryWork(work: RecoveryWork): Promise<void> {
+  while (work.size) await Promise.allSettled([...work.values()]);
+}
+
+/** Timeout reports incomplete disposal; actual cleanup continues safely. */
+export function createRecoveryDisposer(
+  quiesce: () => void,
+  settle: () => Promise<void>,
+  close: () => Promise<void>,
+  timeoutMs = 30_000,
+): () => Promise<void> {
+  let disposal: Promise<void> | undefined;
+  return async () => {
+    quiesce();
+    disposal ??= (async () => { await settle(); await close(); })();
+    await waitForRecoveryWork(disposal, timeoutMs);
+  };
+}

package/src/daemon/wallet/testing/fake-mint.ts

@@ -0,0 +1,347 @@
+/**
+ * In-process Cashu mint for integration tests.
+ *
+ * Implements just enough of NUT-01/02/04/06/07/09 to drive a real coco
+ * `Manager` against real HTTP: keyset publication, bolt11 mint quotes, minting
+ * blinded outputs with a real secp256k1 blind signature, NUT-09 restore and
+ * NUT-07 proof states. No Lightning, no network, no NPC.
+ *
+ * The signing keys and signatures are genuine (`@cashu/cashu-ts` mint-side
+ * helpers), so a wallet that receives these signatures can unblind and verify
+ * them exactly as with a production mint.
+ */
+import {
+  createBlindSignature,
+  createNewMintKeys,
+  pointFromHex,
+} from "@cashu/cashu-ts";
+
+/** NUT error codes used by the scenarios. */
+export const QUOTE_EXPIRED = 20007;
+export const ALREADY_ISSUED = 20002;
+
+export type FakeQuoteState = "UNPAID" | "PAID" | "ISSUED";
+
+export interface FakeMintQuote {
+  quote: string;
+  request: string;
+  amount: number;
+  unit: string;
+  state: FakeQuoteState;
+  /** Epoch seconds, or null for a quote that never expires. */
+  expiry: number | null;
+  amountPaid: number;
+  amountIssued: number;
+  pubkey: null;
+}
+
+export interface FakeMintRequest {
+  quote: string;
+  outputs: Array<{ amount: number; id: string; B_: string }>;
+}
+
+interface StoredSignature {
+  amount: number;
+  id: string;
+  C_: string;
+}
+
+const toHex = (bytes: Uint8Array) => Buffer.from(bytes).toString("hex");
+
+export class FakeMint {
+  readonly keysetId: string;
+  readonly keysByAmount: Record<string, string>;
+  readonly requests: FakeMintRequest[] = [];
+  /** Every output the mint has ever signed, keyed by B_. */
+  readonly signed = new Map<string, StoredSignature>();
+
+  /** When set, POST /v1/mint/bolt11 fails with this NUT error. */
+  mintError: { code: number; detail: string } | null = null;
+  /** When set, quote creation returns this expiry (epoch seconds). */
+  quoteExpiry: number | null = 3_600;
+  /**
+   * Awaited before responding to a mint request, so a test can hold minting
+   * open and interleave another recovery attempt.
+   */
+  gate: Promise<void> | null = null;
+  /** Awaited before answering a quote-state check, to hold observe open. */
+  observeGate: Promise<void> | null = null;
+  /**
+   * When true, POST /v1/restore answers with NUT-09's spec-legal positional
+   * arrays, including `null` for outputs the mint never signed.
+   *
+   * This is a known interop gap, not a supported path: cashu-ts 3.7.1 (which
+   * coco depends on) dereferences every entry of `signatures` while normalising
+   * amounts, so a `null` makes the wallet throw instead of skipping it. The
+   * switch exists so tests keep that behaviour visible; see
+   * mint-quote-recovery.fake-mint.test.ts.
+   */
+  restoreIncludesNulls = false;
+
+  private readonly quotes = new Map<string, FakeMintQuote>();
+  private counter = 0;
+  private server?: ReturnType<typeof Bun.serve>;
+
+  constructor() {
+    const pair = createNewMintKeys(20, new Uint8Array(32).fill(9));
+    this.keysetId = pair.keysetId;
+    this.keysByAmount = Object.fromEntries(
+      Object.entries(pair.pubKeys).map(([amount, key]) => [
+        amount,
+        typeof key === "string" ? key : toHex(key),
+      ]),
+    );
+    this.privKeys = Object.fromEntries(
+      Object.entries(pair.privKeys) as Array<[string, Uint8Array]>,
+    );
+  }
+
+  private readonly privKeys: Record<string, Uint8Array>;
+
+  get url(): string {
+    if (!this.server) throw new Error("fake mint not started");
+    return `http://127.0.0.1:${this.server.port}`;
+  }
+
+  start(): void {
+    this.server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: (request) => this.handle(request),
+    });
+  }
+
+  stop(): void {
+    this.server?.stop(true);
+    this.server = undefined;
+  }
+
+  /** Test control: the mint sees the invoice as paid but has issued nothing. */
+  markPaid(quoteId: string): void {
+    const quote = this.quotes.get(quoteId);
+    if (!quote) throw new Error(`unknown fake quote ${quoteId}`);
+    quote.state = "PAID";
+    quote.amountPaid = quote.amount;
+  }
+
+  /**
+   * Test control: mark the quote issued without going through the mint
+   * endpoint, simulating a wallet that lost the signatures.
+   */
+  markIssued(quoteId: string): void {
+    const quote = this.quotes.get(quoteId);
+    if (!quote) throw new Error(`unknown fake quote ${quoteId}`);
+    quote.state = "ISSUED";
+    quote.amountPaid = quote.amount;
+    quote.amountIssued = quote.amount;
+  }
+
+  /** Test control: sign outputs directly, as if another wallet had issued them. */
+  signFor(quoteId: string, outputs: FakeMintRequest["outputs"]): void {
+    for (const output of outputs) {
+      this.signOutput(output);
+    }
+    this.markIssued(quoteId);
+  }
+
+  getQuote(quoteId: string): FakeMintQuote | undefined {
+    return this.quotes.get(quoteId);
+  }
+
+  private quoteBody(quote: FakeMintQuote) {
+    return {
+      quote: quote.quote,
+      request: quote.request,
+      amount: quote.amount,
+      unit: quote.unit,
+      state: quote.state,
+      expiry: quote.expiry,
+      amount_paid: quote.amountPaid,
+      amount_issued: quote.amountIssued,
+      pubkey: quote.pubkey,
+    };
+  }
+
+  private signOutput(output: {
+    amount: number;
+    id: string;
+    B_: string;
+  }): StoredSignature {
+    const privKey = this.privKeys[String(output.amount)];
+    if (!privKey) {
+      throw new Error(`fake mint has no key for amount ${output.amount}`);
+    }
+    const signature = createBlindSignature(
+      pointFromHex(output.B_),
+      privKey,
+      this.keysetId,
+    );
+    const stored: StoredSignature = {
+      amount: output.amount,
+      id: this.keysetId,
+      C_: toHex(signature.C_.toBytes(false)),
+    };
+    this.signed.set(output.B_, stored);
+    return stored;
+  }
+
+  private json(body: unknown, status = 200): Response {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  private error(code: number, detail: string, status = 400): Response {
+    return this.json({ code, detail }, status);
+  }
+
+  private async handle(request: Request): Promise<Response> {
+    const { pathname } = new URL(request.url);
+    const body = async () => {
+      try {
+        return (await request.json()) as Record<string, unknown>;
+      } catch {
+        return {};
+      }
+    };
+
+    if (pathname === "/v1/info") {
+      return this.json({
+        name: "fake-mint",
+        version: "0.0.1",
+        nuts: {
+          4: {
+            methods: [
+              {
+                method: "bolt11",
+                unit: "sat",
+                min_amount: 1,
+                max_amount: 1_000_000,
+              },
+            ],
+          },
+          5: {
+            methods: [
+              {
+                method: "bolt11",
+                unit: "sat",
+                min_amount: 1,
+                max_amount: 1_000_000,
+              },
+            ],
+          },
+          7: { supported: true },
+          9: { supported: true },
+        },
+      });
+    }
+
+    if (pathname === "/v1/keys" || pathname.startsWith("/v1/keys/")) {
+      return this.json({
+        keysets: [
+          { id: this.keysetId, unit: "sat", keys: this.keysByAmount },
+        ],
+      });
+    }
+
+    if (pathname === "/v1/keysets") {
+      return this.json({
+        keysets: [{ id: this.keysetId, unit: "sat", active: true }],
+      });
+    }
+
+    if (pathname === "/v1/mint/quote/bolt11" && request.method === "POST") {
+      const input = await body();
+      const amount = Number(input.amount);
+      const unit = typeof input.unit === "string" ? input.unit : "sat";
+      const quote: FakeMintQuote = {
+        quote: `fake-quote-${++this.counter}`,
+        request: `lnbcfake${this.counter}`,
+        amount,
+        unit,
+        state: "UNPAID",
+        expiry:
+          this.quoteExpiry === null
+            ? null
+            : Math.floor(Date.now() / 1000) + this.quoteExpiry,
+        amountPaid: 0,
+        amountIssued: 0,
+        pubkey: null,
+      };
+      this.quotes.set(quote.quote, quote);
+      return this.json(this.quoteBody(quote));
+    }
+
+    const quoteMatch = pathname.match(/^\/v1\/mint\/quote\/bolt11\/(.+)$/);
+    if (quoteMatch?.[1] && request.method === "GET") {
+      if (this.observeGate) await this.observeGate;
+      const quote = this.quotes.get(decodeURIComponent(quoteMatch[1]));
+      if (!quote) return this.error(50000, "Unknown quote");
+      return this.json(this.quoteBody(quote));
+    }
+
+    if (pathname === "/v1/mint/bolt11" && request.method === "POST") {
+      const input = await body();
+      const quoteId = String(input.quote);
+      const outputs = (input.outputs ?? []) as FakeMintRequest["outputs"];
+      this.requests.push({ quote: quoteId, outputs });
+      if (this.gate) await this.gate;
+      if (this.mintError) {
+        return this.error(this.mintError.code, this.mintError.detail);
+      }
+      const quote = this.quotes.get(quoteId);
+      if (!quote) return this.error(50000, "Unknown quote");
+      if (quote.state === "ISSUED" || quote.amountIssued > 0) {
+        return this.error(ALREADY_ISSUED, "Quote already issued");
+      }
+      if (quote.state !== "PAID") {
+        return this.error(20001, "Quote is not paid");
+      }
+      const total = outputs.reduce((sum, o) => sum + Number(o.amount), 0);
+      if (total > quote.amountPaid - quote.amountIssued) {
+        return this.error(10002, "Outputs exceed the paid amount");
+      }
+      const signatures = outputs.map((output) => ({
+        amount: output.amount,
+        id: this.keysetId,
+        C_: this.signOutput(output).C_,
+      }));
+      quote.state = "ISSUED";
+      quote.amountIssued += total;
+      return this.json({ signatures });
+    }
+
+    if (pathname === "/v1/restore" && request.method === "POST") {
+      const input = await body();
+      const outputs = (input.outputs ?? []) as FakeMintRequest["outputs"];
+      if (this.restoreIncludesNulls) {
+        // Spec-legal NUT-09 shape, including nulls. Kept behind a switch
+        // because it is currently unusable with coco's cashu-ts version.
+        return this.json({
+          outputs,
+          signatures: outputs.map(
+            (output) => this.signed.get(output.B_) ?? null,
+          ),
+        });
+      }
+      // Return only the signed outputs; coco matches them by B_ and treats the
+      // rest as "nothing to restore".
+      const signed = outputs.filter((output) => this.signed.has(output.B_));
+      return this.json({
+        outputs: signed,
+        signatures: signed.map((output) => this.signed.get(output.B_)),
+      });
+    }
+
+    if (pathname === "/v1/checkstate" && request.method === "POST") {
+      const input = await body();
+      const ys = (input.Ys ?? []) as string[];
+      return this.json({
+        states: ys.map((Y) => ({ Y, state: "UNSPENT", witness: null })),
+      });
+    }
+
+    return this.error(404, `fake mint has no route for ${pathname}`, 404);
+  }
+}