@openreceive/node 0.4.9 → 0.4.11

package/dist/{chunk-65UPROSE.js → chunk-7WTXLEDH.js}

@@ -2,7 +2,8 @@
 import {
   isErrorCode,
   isRetryableErrorCode,
-  OpenReceiveError
+  OpenReceiveError,
+  publicErrorBody
 } from "@openreceive/core";
 var WalletPreflightError = class extends Error {
   code;
@@ -69,7 +70,8 @@ var OPENRECEIVE_ERROR_MESSAGES = {
   CONFLICT: "NWC wallet service reported a conflicting request."
 };
 function normalizeNwcWalletError(error) {
-  if (error instanceof OpenReceiveError) return error;
+  if (error instanceof OpenReceiveError)
+    return new OpenReceiveError(publicErrorBody(error.toJSON()));
   const records = collectErrorRecords(error);
   const code = knownErrorCode(error) ?? errorCodeFromRecords(records) ?? (typeof error === "string" ? normalizeNwcErrorCode(error) : void 0) ?? "OTHER";
   const message = errorMessageFromRecords(records, error, code);
@@ -83,7 +85,7 @@ function normalizeNwcWalletError(error) {
     ...requestId === void 0 ? {} : { request_id: requestId },
     ...details === void 0 ? {} : { details }
   };
-  return new OpenReceiveError(body, { cause: error });
+  return new OpenReceiveError(publicErrorBody(body));
 }
 function knownErrorCode(error) {
   if (error instanceof ReceiveCheckoutValidationError) {
@@ -309,7 +311,7 @@ function normalizeMakeInvoiceResult(rawResult) {
   const expiresAt = parseOptionalInteger(result.expires_at ?? result.expiresAt, "expires_at");
   return {
     invoice,
-    payment_hash: paymentHash,
+    payment_hash: paymentHash.toLowerCase(),
     amount_msats: amountMsats,
     ...createdAt === void 0 ? {} : { created_at: createdAt },
     ...expiresAt === void 0 ? {} : { expires_at: expiresAt }
@@ -331,6 +333,10 @@ function normalizeListTransactionsResult(rawResult) {
   const transactions = [];
   let skippedRows = 0;
   for (const rawTransaction of rawTransactions) {
+    if (typeof rawTransaction !== "object" || rawTransaction === null || Array.isArray(rawTransaction)) {
+      skippedRows += 1;
+      continue;
+    }
     try {
       transactions.push(normalizeNwcTransaction(rawTransaction));
     } catch {
@@ -354,7 +360,7 @@ function normalizeNwcTransaction(rawTransaction) {
     if (!/^[0-9a-fA-F]{64}$/.test(paymentHash)) {
       throw new TypeError("payment_hash must be 64 hexadecimal characters");
     }
-    normalized.payment_hash = paymentHash;
+    normalized.payment_hash = paymentHash.toLowerCase();
   }
   if (result.amount_msats !== void 0 || result.amount !== void 0) {
     normalized.amount_msats = toBigInt(result.amount_msats ?? result.amount, "amount_msats");
@@ -394,7 +400,7 @@ function normalizeNwcNotification(rawNotification) {
     }
   }
   const rawHash = payload.payment_hash ?? payload.paymentHash ?? record.payment_hash ?? record.paymentHash;
-  const paymentHash = typeof rawHash === "string" && rawHash.length > 0 ? rawHash : transaction?.payment_hash;
+  const paymentHash = typeof rawHash === "string" && rawHash.length > 0 ? rawHash.toLowerCase() : transaction?.payment_hash;
   return {
     type,
     ...paymentHash === void 0 ? {} : { payment_hash: paymentHash },
@@ -485,15 +491,85 @@ function unwrapNwcResult(value) {
 import { createRequire } from "module";
 import { pathToFileURL } from "url";
 import { recordOrEmpty as recordOrEmpty2 } from "@openreceive/core";
+
+// src/nwc/history-request.ts
+async function historyRequest(client, params, signal) {
+  signal.throwIfAborted();
+  const content = await client.encrypt(
+    client.walletPubkey,
+    JSON.stringify({ method: "list_transactions", params })
+  );
+  signal.throwIfAborted();
+  const event = await client.signEvent({
+    kind: 23194,
+    created_at: Math.floor(Date.now() / 1e3),
+    tags: [
+      ["p", client.walletPubkey],
+      ["v", client.encryptionType === "nip44_v2" ? "1.0" : "0.0"],
+      ["encryption", client.encryptionType]
+    ],
+    content
+  });
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    let done = false;
+    let subscription;
+    const finish = (error, result) => {
+      if (done) return;
+      done = true;
+      signal.removeEventListener("abort", abort);
+      controller.abort();
+      subscription?.close();
+      if (error === void 0) resolve(result);
+      else reject(error);
+    };
+    const abort = () => finish(signal.reason ?? new Error("Wallet scan cancelled."));
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) {
+      abort();
+      return;
+    }
+    try {
+      subscription = client.pool.subscribe(
+        client.relayUrls,
+        { kinds: [23195], authors: [client.walletPubkey], "#e": [event.id] },
+        {
+          abort: controller.signal,
+          onevent: async (reply) => {
+            if (done || reply.pubkey !== client.walletPubkey || !reply.tags.some((tag) => tag[0] === "e" && tag[1] === event.id))
+              return;
+            try {
+              const body = JSON.parse(await client.decrypt(client.walletPubkey, reply.content));
+              if (done || signal.aborted) return;
+              if (body.error !== void 0 && body.error !== null) finish(body.error);
+              else finish(void 0, body.result);
+            } catch (error) {
+              finish(error);
+            }
+          }
+        }
+      );
+      if (done) {
+        subscription.close();
+        return;
+      }
+      void Promise.any(
+        client.pool.publish(client.relayUrls, event, { abort: controller.signal })
+      ).catch((error) => finish(error));
+    } catch (error) {
+      finish(error);
+    }
+  });
+}
+
+// src/nwc/transport.ts
 var require2 = createRequire(import.meta.url);
-async function callRequiredMethod(client, names, request) {
+async function callRequiredMethod(client, names, request, options) {
   for (const name of names) {
     const method = client[name];
     if (typeof method === "function") {
-      return await method.call(
-        client,
-        request
-      );
+      return await method.call(client, request, options);
     }
   }
   throw new WalletPreflightError(
@@ -515,9 +591,10 @@ async function createDefaultAlbyNwcClient(connectionString) {
     );
   }
   const NWCClientConstructor = Constructor;
-  return new NWCClientConstructor({
-    nostrWalletConnectUrl: connectionString
-  });
+  const client = new NWCClientConstructor({ nostrWalletConnectUrl: connectionString });
+  const receiveClient = client;
+  receiveClient.listTransactions = (request, options) => historyRequest(client, request, options?.signal ?? AbortSignal.timeout(1e4));
+  return receiveClient;
 }
 function ensureNodeWebSocket() {
   if (globalThis.WebSocket !== void 0) return;
@@ -555,7 +632,6 @@ var AlbyNwcReceiveClient = class {
   #clientFactory;
   #preflightSummary;
   #preflightPromise;
-  #requirePreflight;
   #logger;
   #allowSpendCapableWallet;
   #spendCapabilityWarningDelayMs;
@@ -572,7 +648,6 @@ var AlbyNwcReceiveClient = class {
     };
     this.#client = options.client;
     this.#clientFactory = options.clientFactory;
-    this.#requirePreflight = options.requirePreflight ?? true;
     this.#logger = options.logger;
     this.#allowSpendCapableWallet = options.allowSpendCapableWallet ?? false;
     this.#spendCapabilityWarningDelayMs = options.spendCapabilityWarningDelayMs ?? 0;
@@ -729,7 +804,7 @@ var AlbyNwcReceiveClient = class {
     });
     return result;
   }
-  async listTransactions(request) {
+  async listTransactions(request, options) {
     await this.ensurePreflight();
     validateListTransactionsRequest(request);
     this.#log(
@@ -752,7 +827,8 @@ var AlbyNwcReceiveClient = class {
       rawResult = await callRequiredMethod(
         await this.getClient(),
         ["listTransactions", "list_transactions"],
-        toNip47ListTransactionsParams(request)
+        toNip47ListTransactionsParams(request),
+        options
       );
     } catch (error) {
       const normalized = normalizeNwcWalletError(error);
@@ -909,7 +985,7 @@ var AlbyNwcReceiveClient = class {
     await client?.close?.();
   }
   async ensurePreflight() {
-    if (!this.#requirePreflight || this.#preflightSummary !== void 0) return;
+    if (this.#preflightSummary !== void 0) return;
     this.#preflightPromise ??= this.preflight();
     try {
       await this.#preflightPromise;
@@ -963,21 +1039,24 @@ var OPENRECEIVE_SWAP_ASSET_INFO = {
     label: "USDT",
     network_label: "Tron",
     coin: "USDT",
-    network: "TRX"
+    network: "TRX",
+    pegged_to: "USD"
   },
   USDT_SOL: {
     pay_in_asset: "USDT_SOL",
     label: "USDT",
     network_label: "Solana",
     coin: "USDT",
-    network: "SOL"
+    network: "SOL",
+    pegged_to: "USD"
   },
   USDC_SOL: {
     pay_in_asset: "USDC_SOL",
     label: "USDC",
     network_label: "Solana",
     coin: "USDC",
-    network: "SOL"
+    network: "SOL",
+    pegged_to: "USD"
   },
   ETH_ETH: {
     pay_in_asset: "ETH_ETH",
@@ -991,14 +1070,16 @@ var OPENRECEIVE_SWAP_ASSET_INFO = {
     label: "USDT",
     network_label: "Ethereum",
     coin: "USDT",
-    network: "ETH"
+    network: "ETH",
+    pegged_to: "USD"
   },
   USDC_ETH: {
     pay_in_asset: "USDC_ETH",
     label: "USDC",
     network_label: "Ethereum",
     coin: "USDC",
-    network: "ETH"
+    network: "ETH",
+    pegged_to: "USD"
   }
 };
 var OPENRECEIVE_SWAP_PROVIDER_STATES = [
@@ -1735,6 +1816,7 @@ function fixedFloatAvailabilityMessage(reason) {
 
 // src/swap/fixedfloat-transport.ts
 import { createHmac } from "crypto";
+import { isRecord } from "@openreceive/core";
 var FixedFloatApiError = class _FixedFloatApiError extends Error {
   path;
   kind;
@@ -1871,22 +1953,31 @@ var FixedFloatTransport = class {
     return parsed.data;
   }
   logApiRequest(path, body = {}) {
-    this.apiRequestLogger?.({
-      provider: this.provider,
-      path,
-      body
-    });
+    try {
+      this.apiRequestLogger?.({
+        provider: this.provider,
+        path,
+        has_body: Object.keys(body).length > 0,
+        has_token: body.token != null
+      });
+    } catch {
+    }
   }
   logApiResponse(input) {
-    this.apiResponseLogger?.({
-      provider: this.provider,
-      path: input.path,
-      status: input.status,
-      ok: input.ok,
-      code: input.code,
-      msg: input.msg,
-      data: input.data
-    });
+    const pairCount = isRecord(input.data) ? input.data.pair_count : void 0;
+    try {
+      this.apiResponseLogger?.({
+        provider: this.provider,
+        path: input.path,
+        status: input.status,
+        ok: input.ok,
+        code: typeof input.code === "number" ? input.code : void 0,
+        has_data: input.data != null,
+        items: Array.isArray(input.data) ? input.data.length : void 0,
+        pair_count: typeof pairCount === "number" ? pairCount : void 0
+      });
+    } catch {
+    }
   }
 };
 function formatFixedFloatApiErrorMessage(path, status, msg) {
@@ -2375,7 +2466,8 @@ function providerIdFromUri(uri) {
 }
 
 // src/service/logging.ts
-import { compact as compact3, isRecord } from "@openreceive/core";
+import { isSensitiveLogKey, sanitizeLogValue } from "@openreceive/core";
+import { isSensitiveLogKey as isSensitiveLogKey2, redactSecrets } from "@openreceive/core";
 function emitLog(options, level, event, message, fields = {}) {
   emitEvent(options, {
     level,
@@ -2421,113 +2513,25 @@ function sanitizeEvent(entry) {
   }
   return clean;
 }
-function sanitizeLogValue(value) {
-  if (typeof value === "string") return redactSecrets(value);
-  if (Array.isArray(value)) return value.map(sanitizeLogValue);
-  if (typeof value !== "object" || value === null) return value;
-  const clean = {};
-  for (const [key, nested] of Object.entries(value)) {
-    if (isSensitiveLogKey(key)) {
-      clean[key] = "[REDACTED]";
-    } else {
-      clean[key] = sanitizeLogValue(nested);
-    }
-  }
-  return clean;
-}
-function isSensitiveLogKey(key) {
-  if (/_present$/i.test(key)) return false;
-  return /secret|token|authorization|cookie|nwc|dsn|preimage|invoice|bolt11|swap_?data|(?:private|api)[_-]?key|^key$|api[_-]?sign/i.test(
-    key
-  );
-}
-function redactSecrets(value) {
-  return value.replace(/nostr\+walletconnect:[^\s"'`<>]+/g, "[REDACTED_NWC]").replace(/lightning\+swapconnect:[^\s"'`<>]+/g, "[REDACTED_LSC]").replace(/([?&](?:token|secret|key)=)[^&\s"'`<>]+/gi, "$1[REDACTED]");
-}
 function summarizeSwapProviderApiRequest(entry) {
-  const body = isRecord(entry.body) ? entry.body : void 0;
-  return compact3({
+  return {
     provider: entry.provider,
     path: entry.path,
-    reference: optionalLogString(body?.id),
-    choice: optionalLogString(body?.choice),
-    from_ccy: optionalLogString(body?.fromCcy),
-    to_ccy: optionalLogString(body?.toCcy),
-    amount: optionalLogString(body?.amount) ?? optionalLogNumber(body?.amount)
-  });
+    has_body: entry.has_body,
+    has_token: entry.has_token
+  };
 }
 function summarizeSwapProviderApiResponse(entry) {
-  const summary = {
+  return {
     provider: entry.provider,
     path: entry.path,
     status: entry.status,
-    ok: entry.ok
+    ok: entry.ok,
+    code: entry.code,
+    has_data: entry.has_data,
+    items: entry.items,
+    pair_count: entry.pair_count
   };
-  if (entry.code !== void 0 && entry.code !== null) summary.code = entry.code;
-  const msg = optionalLogString(entry.msg);
-  if (msg !== void 0 && msg !== "OK") summary.msg = msg;
-  const data = entry.data;
-  if (Array.isArray(data)) {
-    summary.items = data.length;
-    return summary;
-  }
-  if (!isRecord(data)) return summary;
-  const pairCount = optionalLogNumber(data.pair_count);
-  if (pairCount !== void 0) {
-    summary.pair_count = pairCount;
-    return summary;
-  }
-  const reference = optionalLogString(data.id);
-  const orderStatus = optionalLogString(data.status);
-  if (reference !== void 0) summary.reference = reference;
-  if (orderStatus !== void 0) summary.order_status = orderStatus;
-  const from = summarizeSwapProviderSide(data.from);
-  const to = summarizeSwapProviderSide(data.to);
-  if (from !== void 0) summary.from = from;
-  if (to !== void 0) summary.to = to;
-  if (isRecord(data.time)) {
-    const left = optionalLogNumber(data.time.left);
-    if (left !== void 0) summary.left = left;
-  }
-  if (isRecord(data.emergency)) {
-    const choice = optionalLogString(data.emergency.choice);
-    if (choice !== void 0 && choice !== "NONE") summary.emergency = choice;
-    const statuses = Array.isArray(data.emergency.status) ? data.emergency.status.filter((item) => typeof item === "string" && item.length > 0).map((item) => item.toUpperCase()) : [];
-    if (statuses.length > 0) summary.emergency_status = statuses.join(",");
-    const repeat = data.emergency.repeat;
-    if (repeat === true || repeat === "1" || repeat === 1) summary.emergency_repeat = true;
-  }
-  if (isRecord(data.from) && isRecord(data.from.tx)) {
-    const received = optionalLogString(data.from.tx.amount);
-    if (received !== void 0) summary.deposit_received = received;
-  }
-  if (isRecord(data.back)) {
-    const refundAmount = optionalLogString(data.back.amount);
-    if (refundAmount !== void 0) summary.refund_amount = refundAmount;
-  }
-  if (reference === void 0) {
-    const fromRecord = isRecord(data.from) ? data.from : void 0;
-    const toRecord = isRecord(data.to) ? data.to : void 0;
-    const fromAmount = optionalLogString(fromRecord?.amount) ?? optionalLogString(data.fromAmount);
-    const toAmount = optionalLogString(toRecord?.amount) ?? optionalLogString(data.toAmount);
-    if (fromAmount !== void 0) summary.from_amount = fromAmount;
-    if (toAmount !== void 0) summary.to_amount = toAmount;
-  }
-  return summary;
-}
-function summarizeSwapProviderSide(side) {
-  if (!isRecord(side)) return void 0;
-  const code = optionalLogString(side.code) ?? optionalLogString(side.coin);
-  const amount = optionalLogString(side.amount);
-  if (code === void 0 && amount === void 0) return void 0;
-  if (code !== void 0 && amount !== void 0) return `${code} ${amount}`;
-  return code ?? amount;
-}
-function optionalLogString(value) {
-  return typeof value === "string" && value.length > 0 ? value : void 0;
-}
-function optionalLogNumber(value) {
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
 
 export {
@@ -2550,7 +2554,7 @@ export {
   createNwcEndpointLogger,
   summarizeReconcilePass,
   sanitizeEvent,
-  redactSecrets,
   summarizeSwapProviderApiRequest,
-  summarizeSwapProviderApiResponse
+  summarizeSwapProviderApiResponse,
+  redactSecrets
 };

package/dist/cli.js

@@ -2,7 +2,7 @@ import {
   createNwcReceiveClient,
   readLscConnectionsFromEnvironment,
   redactSecrets
-} from "./chunk-65UPROSE.js";
+} from "./chunk-7WTXLEDH.js";
 
 // src/cli.ts
 import { existsSync } from "fs";

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { WalletCapabilitySummary, ReceiveNwcClient, NwcTransaction, ParsedNwcConnection, RedactedNwcConnection, MakeInvoiceRequest, MakeInvoiceResult, ListTransactionsRequest, ListTransactionsResult, ErrorCode, ErrorBody, RateQuote, SourcedPriceProvider, SimplePriceFetch, PaidPayment, PaymentCheck, BtcFiatRateMapWithSource, MoneyAmount, CachedPriceFeed } from '@openreceive/core';
+import { WalletCapabilitySummary, ReceiveNwcClient, NwcTransaction, ParsedNwcConnection, RedactedNwcConnection, MakeInvoiceRequest, MakeInvoiceResult, ListTransactionsRequest, ListTransactionsResult, ErrorCode, ErrorBody, RateQuote, SourcedPriceProvider, SimplePriceFetch, PaidPayment, PaymentCheck, PaymentScanWindow, PaymentScanSlice, BtcFiatRateMapWithSource, MoneyAmount, CachedPriceFeed } from '@openreceive/core';
 export { ErrorBody, ErrorCode, NwcTransaction, OpenReceiveError, PaidPayment, PaymentCheck, RateQuote, ReceiveNwcClient } from '@openreceive/core';
 
 /**
@@ -12,8 +12,12 @@ interface AlbyNwcCompatibleClient {
     getWalletServiceInfo?: () => Promise<unknown>;
     makeInvoice?: (request: Record<string, unknown>) => Promise<unknown>;
     make_invoice?: (request: Record<string, unknown>) => Promise<unknown>;
-    listTransactions?: (request: Record<string, unknown>) => Promise<unknown>;
-    list_transactions?: (request: Record<string, unknown>) => Promise<unknown>;
+    listTransactions?: (request: Record<string, unknown>, options?: {
+        readonly signal?: AbortSignal;
+    }) => Promise<unknown>;
+    list_transactions?: (request: Record<string, unknown>, options?: {
+        readonly signal?: AbortSignal;
+    }) => Promise<unknown>;
     subscribeNotifications?: (callback: (notification: unknown) => void, notificationTypes?: string[]) => unknown;
     close?: () => Promise<void> | void;
 }
@@ -97,7 +101,6 @@ interface AlbyNwcReceiveClientOptions {
     connectionString: string;
     client?: AlbyNwcCompatibleClient;
     clientFactory?: AlbyNwcClientFactory;
-    requirePreflight?: boolean;
     logger?: NwcEndpointLogger;
     /**
      * Explicit override: boot even when the connection advertises spend methods
@@ -128,7 +131,9 @@ declare class AlbyNwcReceiveClient implements ReceiveNwcClient {
     constructor(options: AlbyNwcReceiveClientOptions);
     preflight(): Promise<WalletCapabilitySummary>;
     makeInvoice(request: MakeInvoiceRequest): Promise<MakeInvoiceResult>;
-    listTransactions(request: ListTransactionsRequest): Promise<ListTransactionsResult>;
+    listTransactions(request: ListTransactionsRequest, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ListTransactionsResult>;
     /**
      * Opt-in NWC-02 notification subscription, limited to `payment_received`.
      * Notifications are authenticated wallet data: the handler receives the
@@ -227,6 +232,11 @@ interface SwapProviderAsset {
  * swap fee the payer absorbs is `pay_in_fiat` − `payout_fiat` (exchange spread plus
  * network fees, which the provider bakes into the deposit amount). All values are
  * decimal strings so hosts can round-trip them exactly when retaining an audit snapshot.
+ *
+ * These are VALUATIONS that explain the spread, never amounts a payer is told to
+ * send — `deposit_amount` is the only such amount. For a stablecoin pegged to
+ * `currency` the checkout renders the breakdown in the token and never shows
+ * `pay_in_fiat`, which would read as the deposit amount with a typo.
  */
 interface SwapFee {
     /** Fiat currency the equivalents are expressed in, e.g. "USD". */
@@ -274,32 +284,23 @@ interface SwapOrder {
     readonly fee?: SwapFee;
     readonly raw?: unknown;
 }
-/**
- * A single raw provider API response, surfaced for server-side observability.
- * Carries the HTTP status and the parsed `{code, msg, data}` envelope. Emitted
- * through the service's sanitizing log sink, so any nested secret (e.g. a
- * FixedFloat order token) is redacted before it reaches a log line.
- */
+/** Allowlisted metadata, sanitized before invoking any diagnostic sink. */
 interface SwapProviderApiResponseLog {
     readonly provider: string;
     readonly path: string;
     readonly status: number;
     readonly ok: boolean;
-    readonly code: unknown;
-    readonly msg: unknown;
-    readonly data: unknown;
+    readonly code?: number;
+    readonly has_data: boolean;
+    readonly items?: number;
+    readonly pair_count?: number;
 }
-/**
- * A single outbound provider API request, surfaced for server-side observability
- * alongside {@link SwapProviderApiResponseLog}. Carries the request path and body.
- * Emitted through the service's sanitizing log sink, so any secret in the body
- * (e.g. a FixedFloat order token on status/refund calls) is redacted; provider
- * auth headers are never included here.
- */
+/** Request bodies, credentials, invoices and addresses never enter this hook. */
 interface SwapProviderApiRequestLog {
     readonly provider: string;
     readonly path: string;
-    readonly body: unknown;
+    readonly has_body: boolean;
+    readonly has_token: boolean;
 }
 interface SwapProvider {
     readonly name: string;
@@ -309,15 +310,13 @@ interface SwapProvider {
     attachSwapCache?(cache: TransientSwapCache): void;
     /**
      * Attach a sink for outbound provider API requests, mirroring
-     * {@link attachApiResponseLogger}. The
-     * service routes entries through its sanitizing log sink, so secrets in the body
-     * are redacted. Providers that make no remote calls may omit this.
+     * {@link attachApiResponseLogger}. Emit only the allowlisted metadata;
+     * diagnostics must not affect payment behavior. Providers without remote calls may omit this.
      */
     attachApiRequestLogger?(log: (entry: SwapProviderApiRequestLog) => void): void;
     /**
-     * Attach a sink for raw provider API responses. The service routes entries through
-     * its sanitizing log sink, so nested secrets are redacted. Providers that make no
-     * remote calls may omit this.
+     * Attach a sink for allowlisted response metadata, never raw envelopes.
+     * Providers without remote calls may omit this.
      */
     attachApiResponseLogger?(log: (entry: SwapProviderApiResponseLog) => void): void;
     /**
@@ -542,6 +541,8 @@ interface Checkout {
     readonly bolt11: string;
     readonly amountMsats: number;
     readonly createdAt: number;
+    /** Missing on legacy snapshots; only wallet timestamps narrow history scans. */
+    readonly createdAtSource?: "wallet" | "host";
     readonly expiresAt: number;
     readonly fiatQuote: RateQuote | null;
 }
@@ -700,6 +701,14 @@ interface OpenReceive {
     }>;
     createCheckout(input: CreateCheckoutRequest): Promise<Checkout>;
     reconcilePayments(input: ReconcilePaymentsRequest): Promise<readonly PaymentCheck[]>;
+    /** Bounded durable history slice used by repository-backed HTTP and workers. */
+    scanPaymentSlice(input: {
+        window: PaymentScanWindow;
+        maxPages?: number;
+        deadline?: number;
+        signal?: AbortSignal;
+        onFinality?: (check: PaymentCheck) => Promise<void>;
+    }): Promise<PaymentScanSlice>;
     /**
      * Opt-in NWC-02 notifications: subscribe to wallet `payment_received`
      * notifications. Notifications are authenticated wallet data — a payload

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   summarizeReconcilePass,
   summarizeSwapProviderApiRequest,
   summarizeSwapProviderApiResponse
-} from "./chunk-65UPROSE.js";
+} from "./chunk-7WTXLEDH.js";
 
 // src/index.ts
 import { OpenReceiveError as OpenReceiveError2 } from "@openreceive/core";
@@ -33,6 +33,7 @@ import {
   OpenReceiveError,
   parseNwcUri,
   reconcilePaymentAttempts,
+  scanPaymentSlice,
   unixSeconds
 } from "@openreceive/core";
 
@@ -765,6 +766,7 @@ async function createCheckout(context, request) {
     bolt11: walletInvoice.invoice,
     amountMsats: toSafeInteger(walletInvoice.amount_msats, "amount_msats"),
     createdAt,
+    createdAtSource: walletInvoice.created_at === void 0 ? "host" : "wallet",
     expiresAt,
     fiatQuote: resolved.fiatQuote
   };
@@ -1184,11 +1186,14 @@ function parsePayInAsset(value) {
   return value;
 }
 function parseRefundAddress(value, payInAsset) {
+  if (!isSwapPayInAsset(payInAsset)) {
+    throw serviceError(503, "INTERNAL", "Swap recovery requires a supported pay-in asset/network.");
+  }
   const normalized = value.trim();
   if (normalized.length === 0 || normalized.length > 300) {
     throw serviceError(400, "INVALID_REQUEST", "refundAddress is invalid.");
   }
-  if (typeof payInAsset === "string" && !isValidSwapAddressForPayInAsset(payInAsset, normalized)) {
+  if (!isValidSwapAddressForPayInAsset(payInAsset, normalized)) {
     throw serviceError(
       400,
       "INVALID_REQUEST",
@@ -1347,6 +1352,7 @@ async function createOpenReceive(supplied = {}) {
   };
   const service = {
     priceCurrencies,
+    scanPaymentSlice: (input) => scanPaymentSlice({ ...input, client, clock }),
     prepareCheckout: (input) => prepareCheckout(context, input),
     createCheckout: (input) => createCheckout(context, input),
     reconcilePayments: async (input) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/node",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "Accept Bitcoin Lightning payments in Node.js with your own wallet and optional USDT, USDC, SOL and ETH swaps.",
   "keywords": [
     "bitcoin",
@@ -17,7 +17,7 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@getalby/sdk": "^8.0.3",
-    "@openreceive/core": "0.4.9"
+    "@openreceive/core": "0.4.11"
   },
   "bin": {
     "openreceive": "./bin/openreceive.mjs"

package/skills/debug-openreceive-payment/SKILL.md

@@ -70,6 +70,14 @@ same diagnostics redacted, always exit 0 — safe to share.
 - Refunds exist only for swap deposits from `refund_required`. There is **no
   Lightning refund** — the wallet cannot spend. Do not chase one.
   https://openreceive.org/guides/swap-refunds.md
+- "Payer reports two different amounts on a stablecoin checkout" (50.05 or
+  50.03?): the deposit amount is a token quantity, `fee.pay_in_fiat` is its
+  fiat valuation. Only `swap.deposit_amount` is an instruction. From 0.4.10 the
+  packaged checkout renders a USD stablecoin's breakdown in the token and never
+  shows `pay_in_fiat`; on an older bundle, upgrade `@openreceive/*`. To verify,
+  read the row's `deposit_amount` and `fee` and confirm the UI shows only the
+  deposit amount. A custom UI must call `createSwapFeeBreakdown(fee, swap)`
+  with the swap, not the fee alone.
 
 ## 6. Checkout UI shows nothing
 

package/skills/integrate-openreceive/SKILL.md

@@ -86,6 +86,17 @@ state; do not retry-loop it, and do not build an idempotency store around it —
 that serialization is the library's job. (A hook failure while persisting an
 attempt is a **503 retryable**, deliberately distinct.)
 
+## Amounts on the deposit panel
+
+`swap.deposit_amount` is the ONLY amount a payer is ever told to send, in the
+pay-in token. `swap.fee.pay_in_fiat` / `payout_fiat` are fiat valuations that
+explain the spread (why the deposit exceeds the cart total); they are not
+instructions. For a stablecoin pegged to the fee currency (USDT, USDC) the
+packaged checkout expresses the breakdown in the token and never renders
+`pay_in_fiat` — "$50.03" under "50.05 USDC" reads as the same number with a
+typo. A custom UI gets the same rule from `createSwapFeeBreakdown(fee, swap)`;
+pass the swap, not just the fee.
+
 ## Secrets
 
 `NWC_URI` and `LSC_URI_*` are server-only. Never put them in browser code,

package/skills/integrate-openreceive/references/btcpay.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
 plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or
@@ -32,7 +32,7 @@ refund path on the same checkout screen.
 
 ## Step 0 — check the deployment before you change anything
 
-1. Confirm the BTCPay Server version is 2.4.2 or later (Server Settings →
+1. Confirm the BTCPay Server version is 2.4.4 or later (Server Settings →
    About, or `GET /api/v1/server/info`). The plugin declares that minimum and
    BTCPay refuses to load it below.
 2. Check whether the plugin is installed (Server Settings → Plugins, or the
@@ -119,6 +119,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the plugin itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -128,7 +130,7 @@ passes. The page it comes from is https://openreceive.org/guides/quickstart-btcp
 
 ## BTCPay Server quickstart
 
-Requires BTCPay Server ≥ 2.4.2.
+Requires BTCPay Server ≥ 2.4.4.
 
 The OpenReceive plugin makes a receive-only NWC wallet the Lightning node of a
 BTCPay store. BTCPay mints every Lightning invoice in that wallet and records
@@ -143,7 +145,7 @@ invoices, checkout, webhooks and Greenfield API are the host.
 
 ### 1. Prerequisites
 
-- A BTCPay Server, version 2.4.2 or later, on any network (mainnet, testnet,
+- A BTCPay Server, version 2.4.4 or later, on any network (mainnet, testnet,
   signet, regtest). The wallet must be on the same network.
 - A receive-only NWC code for the wallet you want to receive into
   ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
@@ -157,9 +159,9 @@ invoices, checkout, webhooks and Greenfield API are the host.
 
 In BTCPay, open **Server Settings → Plugins**, search the plugin directory
 for **OpenReceive**, click **Install**, and restart BTCPay when prompted.
-BTCPay creates the plugin's one table (`openreceive_swaps`, schema
-`BTCPayServer.Plugins.OpenReceive`) in its own Postgres at startup; nothing
-else is created.
+BTCPay creates the plugin's two tables (`openreceive_invoices` and
+`openreceive_swaps`, schema `BTCPayServer.Plugins.OpenReceive`) in its own
+Postgres at startup; nothing else is created.
 
 To build the plugin from source instead, follow
 [the .NET workspace README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/README.md).

package/skills/integrate-openreceive/references/django.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Django project — the app you are already working in. You
 do not need a copy of the OpenReceive source: the Python package is on PyPI
@@ -130,7 +130,7 @@ itself, and they hold for every integration.
   a placeholder that allows everything (`manage.py check` warns
   `openreceive.W002` while it is set) — replace it with this app's real
   ownership check, same as `on_paid`.
-- `on_paid` must be idempotent. It runs once per `reference` — your order
+- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -231,6 +231,13 @@ built on `@openreceive/browser/headless`. Read that before writing components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -300,6 +307,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -473,7 +482,7 @@ The host class needs three things: authorization, the trusted price, and
 fulfillment. All three receive the `reference` — a string you choose, and the
 fulfillment identity: your order id, one per thing you fulfill, created before
 checkout, kept across retries, never reused. OpenReceive never looks inside
-it, but `on_paid` runs once per reference, a new checkout under a reference
+it, but `on_paid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

package/skills/integrate-openreceive/references/fastapi.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a FastAPI application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI
@@ -116,7 +116,7 @@ itself, and they hold for every integration.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read the Starlette request's session, cookie or
   auth dependency; never trust a body field.
-- `on_paid` must be idempotent. It runs once per `reference` — your order id, one
+- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -228,6 +228,13 @@ components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -294,6 +301,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -468,7 +477,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `on_paid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -517,7 +526,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A page without a bundler renders the same checkout as a custom element:
 `<openreceive-checkout reference="…" prefix="/openreceive">` from

package/skills/integrate-openreceive/references/fastify.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Fastify application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the packages are on npm, and
@@ -107,7 +107,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -211,6 +211,13 @@ components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -277,6 +284,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -470,7 +479,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -519,7 +528,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

package/skills/integrate-openreceive/references/laravel.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist
@@ -121,7 +121,7 @@ itself, and they hold for every integration.
   scaffolds `use AllowAllAuthorize;`, a placeholder trait that allows
   everything (the engine warns at boot while it is there) — replace it with
   this app's real ownership check, same as `onPaid`.
-- `onPaid` must be idempotent. It runs once per `reference` — your order
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -216,6 +216,13 @@ built on `@openreceive/browser/headless`. Read that before writing components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -284,6 +291,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -449,7 +458,7 @@ variable as set/unset only.
 price, and fulfillment. All three receive the `reference` — a string you
 choose, and the fulfillment identity: your order id, one per thing you
 fulfill, created before checkout, kept across retries, never reused.
-OpenReceive never looks inside it, but `onPaid` runs once per reference, a new
+OpenReceive never looks inside it, but `onPaid` commits fulfillment once per reference, a new
 checkout under a reference that already settled is refused with 409, and a
 fresh id per page load lets one order be paid twice.
 

package/skills/integrate-openreceive/references/next.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Next.js App Router application — the app you are already
 working in. You do not need a copy of the OpenReceive source: the packages are
@@ -109,7 +109,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -217,6 +217,13 @@ components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -283,6 +290,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -489,7 +498,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -569,7 +578,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

package/skills/integrate-openreceive/references/node.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Node application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the packages are on npm, and the
@@ -104,7 +104,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -203,6 +203,13 @@ components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -269,6 +276,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -447,7 +456,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -496,7 +505,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

package/skills/integrate-openreceive/references/php.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a PHP application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the engine is on Packagist
@@ -125,7 +125,7 @@ itself, and they hold for every integration.
   is a placeholder that allows everything (the engine warns at boot while a
   host uses it) — replace it with this app's real ownership check, same as
   `onPaid`'s `Hosts\LoggingOnPaid`.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -229,6 +229,13 @@ of https://openreceive.org/guides/checkout-ux.md, for a UI built on
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -294,6 +301,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -505,7 +514,7 @@ prices with exact decimal math, and returns the order id the page will pass as
 the `reference`. OpenReceive never prices from payer input. The `reference` is
 a string you choose, and it is the fulfillment identity: your order id — one
 per thing you fulfill, created before checkout, kept across retries, never
-reused. `onPaid` runs once per reference, a new checkout under a reference
+reused. `onPaid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

package/skills/integrate-openreceive/references/rails.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Rails application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the gem is on RubyGems, the
@@ -116,7 +116,7 @@ itself, and they hold for every integration.
   body field. The generator installs `OpenReceive::ALLOW_ALL_AUTHORIZE`, a
   placeholder that allows everything (the engine warns at boot while it is
   set) — replace it with this app's real ownership check, same as `on_paid`.
-- `config.on_paid` must be idempotent. It runs once per `reference` — your order
+- `config.on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -210,6 +210,13 @@ built on `@openreceive/browser/headless`. Read that before writing components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -278,6 +285,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -425,7 +434,7 @@ The initializer needs three things: authorization, the trusted price, and
 fulfillment. All three receive the `reference` — a string you choose, and the
 fulfillment identity: your order id, one per thing you fulfill, created before
 checkout, kept across retries, never reused. OpenReceive never looks inside
-it, but `on_paid` runs once per reference, a new checkout under a reference
+it, but `on_paid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

package/skills/integrate-openreceive/references/woocommerce.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Install and configure the OpenReceive gateway in the existing WooCommerce
 store. Preserve its theme, checkout, customer accounts, order model and prices.
@@ -73,6 +73,8 @@ flows; a receive-only NWC wallet cannot send payments.
 - [Agent Directions: BTCPay Server](https://openreceive.org/guides/agent-directions-btcpay.md)
 - [WordPress + WooCommerce Quickstart](https://openreceive.org/guides/quickstart-woocommerce.md)
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full