@openreceive/react 0.4.9 → 0.4.11

package/dist/index.js

@@ -6,8 +6,8 @@ import {
   mergeAttemptIntoCheckout,
   mergeAttemptIntoSnapshot,
   OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES as OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES3,
-  OPENRECEIVE_STYLE_ROOT_ATTRIBUTE as OPENRECEIVE_STYLE_ROOT_ATTRIBUTE2,
   OPENRECEIVE_DEFAULT_PREFIX,
+  OPENRECEIVE_STYLE_ROOT_ATTRIBUTE as OPENRECEIVE_STYLE_ROOT_ATTRIBUTE2,
   orClasses as orClasses7,
   prepareCheckout,
   requestCheckout,
@@ -30,7 +30,8 @@ function useCheckoutSession(options) {
     sessionRef.current = createCheckoutSession({
       snapshot: () => optionsRef.current.snapshot(),
       reference: () => optionsRef.current.reference(),
-      requestCheckout: (reference) => optionsRef.current.requestCheckout?.(reference),
+      prefix: () => optionsRef.current.prefix?.(),
+      requestCheckout: (reference, signal) => optionsRef.current.requestCheckout?.(reference, signal),
       onSnapshot: (snapshot) => optionsRef.current.onSnapshot?.(snapshot),
       // The inner `swap` is always present because the session is built once,
       // on the first render, and the host may only gain swap options later.
@@ -57,7 +58,10 @@ function useCheckoutSession(options) {
       onChange: rerender
     });
   }
-  return sessionRef.current;
+  const session = sessionRef.current;
+  session.syncIdentity();
+  React.useEffect(() => () => session.dispose(), [session]);
+  return session;
 }
 
 // src/components.ts
@@ -712,15 +716,15 @@ function TransactionDetailCopyButton(props) {
 }
 
 // src/use-checkout.ts
-import * as React6 from "react";
 import {
   copyInvoice as copyInvoiceHelper2,
   createCheckoutController,
   createCheckoutState,
   createCheckoutStatusModel as createCheckoutStatusModel2,
-  openWallet as openWalletHelper2,
-  deriveStatus
+  deriveStatus,
+  openWallet as openWalletHelper2
 } from "@openreceive/browser/headless";
+import * as React6 from "react";
 function useCheckout(options) {
   const checkout = options.checkout;
   const [copied, showCopied] = useTransientValue(false);
@@ -857,8 +861,9 @@ function useCheckout(options) {
   }, [logContext, state.invoice, options.open, options.logger]);
   const reloadState = React6.useCallback(async () => {
     try {
-      const next = await controllerRef.current?.reloadState();
-      if (next !== void 0) setState(next);
+      const controller = controllerRef.current;
+      const next = await controller?.reloadState();
+      if (controllerRef.current === controller && next !== void 0) setState(next);
     } catch (error) {
       onErrorRef.current?.(error);
       throw error;
@@ -878,10 +883,11 @@ function useCheckout(options) {
   }, []);
   const stageSwapRefund = React6.useCallback(
     async (refund) => {
+      const controller = swapRefundController();
       try {
-        return await swapRefundController().stageSwapRefund(refund);
+        return await controller.stageSwapRefund(refund);
       } catch (error) {
-        onErrorRef.current?.(error);
+        if (controllerRef.current === controller) onErrorRef.current?.(error);
         throw error;
       }
     },
@@ -889,10 +895,11 @@ function useCheckout(options) {
   );
   const confirmSwapRefund = React6.useCallback(
     async (refund) => {
+      const controller = swapRefundController();
       try {
-        return await swapRefundController().confirmSwapRefund(refund);
+        return await controller.confirmSwapRefund(refund);
       } catch (error) {
-        onErrorRef.current?.(error);
+        if (controllerRef.current === controller) onErrorRef.current?.(error);
         throw error;
       }
     },
@@ -1861,24 +1868,20 @@ function renderKeepOrderNote(options) {
     )
   );
 }
-var REFUND_ADDRESS_DRAFT_LIMIT = 8;
-var refundAddressDraftByAttempt = /* @__PURE__ */ new Map();
-function setRefundAddressDraft(attemptId, value) {
-  refundAddressDraftByAttempt.delete(attemptId);
-  refundAddressDraftByAttempt.set(attemptId, value);
-  while (refundAddressDraftByAttempt.size > REFUND_ADDRESS_DRAFT_LIMIT) {
-    const oldest = refundAddressDraftByAttempt.keys().next().value;
-    if (oldest === void 0) break;
-    refundAddressDraftByAttempt.delete(oldest);
-  }
-}
 function SwapRefundForm(props) {
-  const [refundAddress, setRefundAddress] = React8.useState(
-    () => refundAddressDraftByAttempt.get(props.attemptId) ?? ""
+  const [refundAddress, setRefundAddress] = React8.useState("");
+  const [draftAttemptId, setDraftAttemptId] = React8.useState(props.attemptId);
+  if (draftAttemptId !== props.attemptId) {
+    setDraftAttemptId(props.attemptId);
+    setRefundAddress("");
+  }
+  const generation = React8.useRef(0);
+  React8.useEffect(
+    () => () => {
+      generation.current += 1;
+    },
+    [props.attemptId]
   );
-  React8.useEffect(() => {
-    setRefundAddress(refundAddressDraftByAttempt.get(props.attemptId) ?? "");
-  }, [props.attemptId]);
   const [submitting, setSubmitting] = React8.useState(false);
   const [showAddressError, setShowAddressError] = React8.useState(false);
   const address = refundAddress.trim();
@@ -1898,7 +1901,12 @@ function SwapRefundForm(props) {
           return;
         }
         setSubmitting(true);
-        void props.onRefund(props.attemptId, address, confirm).catch(props.onError).finally(() => setSubmitting(false));
+        const captured = generation.current;
+        void props.onRefund(props.attemptId, address, confirm).catch((error) => {
+          if (captured === generation.current) props.onError?.(error);
+        }).finally(() => {
+          if (captured === generation.current) setSubmitting(false);
+        });
       }
     },
     // The form says what it is and why it is here before it asks for anything:
@@ -1934,7 +1942,6 @@ function SwapRefundForm(props) {
       className: showError ? orClasses5.swapRefundInputInvalid : orClasses5.swapRefundInput,
       onChange: (event) => {
         const value = event.currentTarget.value;
-        setRefundAddressDraft(props.attemptId, value);
         setRefundAddress(value);
       },
       onBlur: () => {
@@ -1998,6 +2005,12 @@ function SwapPayloadQRCode(props) {
 
 // src/wizard.ts
 function PaymentWizard(props) {
+  return React9.createElement(PaymentWizardSession, {
+    ...props,
+    key: JSON.stringify([props.checkout?.reference, props.prefix?.replace(/\/+$/, "")])
+  });
+}
+function PaymentWizardSession(props) {
   const [selection, setSelection] = React9.useState(
     () => createPaymentWizardController().getSelection()
   );
@@ -2014,6 +2027,7 @@ function PaymentWizard(props) {
   const session = useCheckoutSession({
     snapshot: () => checkout,
     reference: () => reference,
+    prefix: () => props.prefix,
     swap: {
       selection: {
         started: () => startedSwapInvoice ?? void 0,
@@ -2076,6 +2090,7 @@ function PaymentWizard(props) {
       if (prefix === void 0 || reference === void 0 || fetcher === void 0) {
         return;
       }
+      const action = session.capture();
       try {
         const invoice = swapRefund !== void 0 ? await (confirm ? swapRefund.confirmSwapRefund : swapRefund.stageSwapRefund).call(
           swapRefund,
@@ -2093,10 +2108,11 @@ function PaymentWizard(props) {
           confirm,
           ...props.logger === void 0 ? {} : { logger: props.logger }
         });
+        if (!action.isCurrent()) return;
         setStartedSwapInvoice(invoice);
         setDismissedSwapInvoiceId(null);
       } catch (error) {
-        props.onError?.(error);
+        if (action.isCurrent()) props.onError?.(error);
       }
     },
     [
@@ -2108,7 +2124,8 @@ function PaymentWizard(props) {
       props.logger,
       swapRefund,
       startedSwapInvoice,
-      checkout?.invoices
+      checkout?.invoices,
+      session
     ]
   );
   const updateWizardSelection = React9.useCallback(
@@ -2917,11 +2934,21 @@ function Checkout(props) {
   if (checkout !== void 0) {
     return React10.createElement(CheckoutSnapshotMode, {
       ...props,
+      key: JSON.stringify([
+        checkout.reference,
+        (props.prefix ?? OPENRECEIVE_DEFAULT_PREFIX).replace(/\/+$/, "")
+      ]),
       checkout,
       prefix: props.prefix ?? OPENRECEIVE_DEFAULT_PREFIX
     });
   }
-  return React10.createElement(CheckoutCreate, props);
+  return React10.createElement(CheckoutCreate, {
+    ...props,
+    key: JSON.stringify([
+      props.reference,
+      (props.prefix ?? OPENRECEIVE_DEFAULT_PREFIX).replace(/\/+$/, "")
+    ])
+  });
 }
 function CheckoutSnapshotMode(props) {
   const { checkout } = props;
@@ -2976,8 +3003,10 @@ function CheckoutCreate(props) {
   const session = useCheckoutSession({
     snapshot: () => createdCheckoutRef.current,
     reference: () => reference,
-    requestCheckout: (id) => requestCheckout({
+    prefix: () => resolvedPrefix,
+    requestCheckout: (id, signal) => requestCheckout({
       prefix: resolvedPrefix,
+      signal,
       reference: id,
       ...csrfHeader === void 0 ? {} : { csrfHeader },
       ...metadataRef.current === void 0 ? {} : { metadata: metadataRef.current },
@@ -2998,14 +3027,17 @@ function CheckoutCreate(props) {
   }, [syncUrl, reference, resumePathPrefix, routeReference]);
   React10.useEffect(() => {
     let cancelled = false;
+    const action = session.capture();
     setCreated({ status: "pending" });
     prepareCheckout({
       prefix: resolvedPrefix,
+      signal: action.signal,
       reference,
       ...csrfHeader === void 0 ? {} : { csrfHeader },
       ...createFetchRef.current === void 0 ? {} : { fetch: createFetchRef.current }
     }).then(
-      (checkout) => resumePaymentHash === void 0 ? checkout : resumeSwapAttempt({
+      (checkout) => cancelled || !action.isCurrent() || resumePaymentHash === void 0 ? checkout : resumeSwapAttempt({
+        signal: action.signal,
         fetch: createFetchRef.current ?? globalThis.fetch,
         prefix: resolvedPrefix,
         ...csrfHeader === void 0 ? {} : { csrfHeader },
@@ -3014,9 +3046,9 @@ function CheckoutCreate(props) {
         snapshot: checkout
       })
     ).then((checkout) => {
-      if (!cancelled) setCreated({ status: "ready", checkout });
+      if (!cancelled && action.isCurrent()) setCreated({ status: "ready", checkout });
     }).catch((error) => {
-      if (cancelled) return;
+      if (cancelled || !action.isCurrent()) return;
       onErrorRef.current?.(error);
       setCreated({
         status: "error",
@@ -3025,6 +3057,7 @@ function CheckoutCreate(props) {
     });
     return () => {
       cancelled = true;
+      session.reset();
     };
   }, [reference, resolvedPrefix, csrfHeader, resumePaymentHash, attempt]);
   const onSwapStarted = React10.useCallback(
@@ -3176,7 +3209,9 @@ function CheckoutView(props) {
   });
   const stampsTheme = !theme.fromScope;
   const ownsTheme = themeToggle && !theme.fromScope && lockedTheme === void 0;
-  const [swapFocused, setSwapFocused] = React10.useState(false);
+  const [swapFocused, setSwapFocused] = React10.useState(
+    () => checkout.invoices.some((invoice) => invoice.rail === "swap" && invoice.swap !== void 0)
+  );
   const [lightningFocused, setLightningFocused] = React10.useState(false);
   const QRCodeComponent = components?.QRCode ?? QRCode;
   const InvoiceSummaryComponent = components?.InvoiceSummary ?? InvoiceSummary;
@@ -3188,7 +3223,7 @@ function CheckoutView(props) {
   const expired = checkoutModel.status === "expired";
   const settled = checkoutModel.status === "settled";
   const showLightning = !!checkoutModel.invoice && (!paymentWizard || lightningFocused) && !swapFocused && !expired;
-  const hideLightning = !showLightning && !expired && !settled;
+  const hideLightning = !settled && (swapFocused || !showLightning && !expired);
   const showSummaryMeta = checkoutModel.status === "settled" || checkoutModel.status === "expired";
   const fiatCurrency = checkoutModel.fiat_quote?.fiat?.currency;
   const decodeInvoiceHref = createLightningInvoiceDecodeUrl2(checkoutModel.invoice, decodeLinkUrl);
@@ -3397,7 +3432,7 @@ function CheckoutView(props) {
             )
           )
         ),
-        paymentWizard && !settled && (!expired || swapFocused) ? React10.createElement(PaymentWizard, {
+        paymentWizard && !settled && (!expired || swapFocused || checkoutModel.checkout?.invoices.some((invoice) => invoice.swap !== void 0)) ? React10.createElement(PaymentWizard, {
           key: "wizard",
           // Only pass invoice when it's a real bolt11 (non-empty, non-deferred).
           invoice: checkoutModel.invoice || void 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/react",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "React components and hooks for Bitcoin Lightning checkout and optional USDT, USDC, SOL and ETH swaps.",
   "keywords": [
     "bitcoin",
@@ -19,8 +19,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@openreceive/browser": "0.4.9",
-    "@openreceive/core": "0.4.9"
+    "@openreceive/browser": "0.4.11",
+    "@openreceive/core": "0.4.11"
   },
   "peerDependencies": {
     "react": ">=18.0.0"

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