openreceive 0.4.10 → 0.4.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e612d1c8beae58671f0e863dbf26622b07a689010b81c3f05abd1463b7f1a4ff
-  data.tar.gz: 68c216cd101ad1d50dd6175b4e565793f7b147a26e1d07e1cda18ffe42659ed6
+  metadata.gz: aee376cce5e82f9c6ae2ee504114fa40d2995777e7086dac85e0680090c3d8d8
+  data.tar.gz: 9f110e0321f717f63f1bd8680a7d541288022dc9d0635141c6b9ad2a5ee45fa4
 SHA512:
-  metadata.gz: 24f0505bb26aa2b2b06f439854cf8839825c24d4b1634ecc184c86a6914269f25c621664efc7ba792e04fc644ab2107784b7b78737564669bf57e77e5a8e5452
-  data.tar.gz: a3edc8c5fdda1f703da32f6abe8e87c2ee65fe0d8957c6da7d539b64a8f5762b2a9b0ec952c4f6ef7ee9d4ee5671d8d3675f67693eeff89c5f227b9d0026e089
+  metadata.gz: 8e66dba7f7fad1c0ef978822f8d1780bc16bfe7af21d848a16e61744e7c2bc48b62829f0398842baa86d7e046f4c0a91c57e6ce8a9ade61b2ba4c356acf4f025
+  data.tar.gz: c32ecc88207d4b80cb582ef7f810efd7e31872e4bc7ef5278920116206057ffcf69cc4acaa0af72425044aabc05653635671baa0d04cde460d3a7ff6419596c0

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.4.11 - 2026-09-21
+
+Wallet history scans stop trusting a page's usable length. A page the wallet
+sent full but that lost a malformed row to normalization no longer reads as
+the end of the history, the skipped-row count survives a second normalization
+(the walk normalizes a page the client already normalized), and the offset
+advances by the rows the wallet actually sent. A non-object transaction row is
+now a skipped row rather than a normalization crash. Two new cases in
+`spec/test-vectors/wallet-scan-truncation.json` cover both shapes.
+
+Normalized wallet errors are redacted: `nostr+walletconnect:` and
+`lightning+swapconnect:` URIs and `key=`/`token=`/`preimage=`-style parameters
+never survive into a message, and `redact_secrets` is available for diagnostic
+payloads. The nwc-ruby adapter enforces a scan deadline inside the wallet
+request itself (`_deadline`), bounding only wallet I/O — no database
+transaction or fulfillment callback is interrupted.
+
 ## 0.4.10 - 2026-09-16
 
 Release in lockstep with the 0.4.10 stablecoin checkout fix. The shared

data/lib/openreceive/core.rb

@@ -185,9 +185,13 @@ module OpenReceive
       # settle nor close pending attempts (a permanent livelock while the bad
       # row stays inside the scan window). Bad rows are skipped and counted.
       # Mirrors the JS normalizeListTransactionsResult policy.
+      # A page a client already normalized arrives with its count: the wallet
+      # walk normalizes again, and must still see how many rows the wallet sent.
       transactions = []
-      skipped_rows = 0
+      skipped_rows = data["skipped_rows"].is_a?(Integer) ? data["skipped_rows"] : 0
       rows.each do |row|
+        raise ArgumentError, "non-object transaction row" unless row.respond_to?(:each_pair)
+
         transactions << normalize_transaction(row)
       rescue StandardError
         skipped_rows += 1
@@ -357,6 +361,23 @@ module OpenReceive
     # Normalize any wallet/library failure into the canonical error body shape
     # shared with JS (spec/test-vectors/error-normalization.json):
     # { "code", "message", "retryable", "request_id"?, "details"? }.
+    def redact_error_text(value)
+      value.to_s.gsub(/nostr\+walletconnect:[^\s"'`<>]+/i, "[REDACTED_NWC]")
+           .gsub(/lightning\+swapconnect:[^\s"'`<>]+/i, "[REDACTED_LSC]")
+           .gsub(/((?:key|secret|client_secret|provider_token|api_key|apikey|token|preimage)=)[^&\s"'<>]+/i, '\\1[REDACTED]')
+    end
+
+    def redact_secrets(value)
+      case value
+      when String then redact_error_text(value)
+      when Array then value.map { |item| redact_secrets(item) }
+      when Hash
+        sensitive = %w[secret clientsecret providertoken apikey key token preimage invoice bolt11 swapdata authorization password nwc nwcuri lscuri]
+        value.to_h { |key, item| [key, sensitive.include?(key.to_s.downcase.gsub(/[^a-z0-9]/, "")) ? "[REDACTED]" : redact_secrets(item)] }
+      else value
+      end
+    end
+
     def normalize_wallet_error(raw)
       records = collect_error_records(raw)
       code = error_code_from_records(records) ||
@@ -364,7 +385,7 @@ module OpenReceive
              "OTHER"
       {
         "code" => code,
-        "message" => error_message_from(records, raw, code),
+        "message" => redact_error_text(error_message_from(records, raw, code)),
         "retryable" => first_boolean(records, "retryable") { RETRYABLE_ERROR_CODES.include?(code) },
         "request_id" => first_string(records, %w[request_id requestId]),
         "details" => records.filter_map { |record| record["details"] if record["details"].is_a?(Hash) }.first
@@ -496,7 +517,8 @@ module OpenReceive
         request["unpaid"] = true if include_unpaid
         request["from"] = scan_from unless scan_from.nil?
         request["until"] = scan_until unless scan_until.nil?
-        page = Nwc.normalize_list_transactions_response(client.list_transactions(request)).fetch("transactions")
+        response = Nwc.normalize_list_transactions_response(client.list_transactions(request))
+        page = response.fetch("transactions")
         page.each do |row|
           next unless row["type"].nil? || row["type"] == "incoming"
           payment_hash = row_payment_hash(row)
@@ -504,7 +526,10 @@ module OpenReceive
           rows[payment_hash] = row
           outstanding.delete(payment_hash)
         end
-        if outstanding.empty? || page.length < TRANSACTION_PAGE_LIMIT
+        # The wallet ran out of rows only when the page IT sent was short: a
+        # row the normalizer dropped was still a row, and a full page with one
+        # of them dropped must not read as the end of the history.
+        if outstanding.empty? || page.length + response.fetch("skipped_rows", 0) == 0
           truncated = false
           break
         end
@@ -513,7 +538,7 @@ module OpenReceive
         page_key = page.map { |row| row["payment_hash"].to_s }.join(",")
         break if page_key == previous_page
         previous_page = page_key
-        offset += TRANSACTION_PAGE_LIMIT
+        offset += page.length + response.fetch("skipped_rows", 0)
       end
       { rows: rows, truncated: truncated }
     end

data/lib/openreceive/nwc_ruby.rb

@@ -6,6 +6,7 @@
 # `openreceive` umbrella, which loads this adapter — carries everything the
 # adapter calls, so requiring this file directly keeps working.
 require_relative "core"
+require "timeout"
 
 module OpenReceive
   # Thin adapter binding the engine to the nwc-ruby gem (NwcRuby::Client).
@@ -29,7 +30,18 @@ module OpenReceive
     def list_transactions(request)
       params = symbolize_keys(OpenReceive.list_transactions_nip47_request(request))
       params[:until_ts] = params.delete(:until) if params.key?(:until)
-      OpenReceive.normalize_list_transactions_response(@client.list_transactions(**params))
+      deadline = request["_deadline"]
+      response = if deadline.nil?
+                   @client.list_transactions(**params)
+                 else
+                   remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                   raise Timeout::Error, "Wallet history scan deadline exceeded." unless remaining.positive?
+
+                   # Bound only wallet I/O. The gem closes its per-call socket in
+                   # ensure; no database transaction or fulfillment is interrupted.
+                   Timeout.timeout(remaining) { @client.list_transactions(**params) }
+                 end
+      OpenReceive.normalize_list_transactions_response(response)
     end
 
     def preflight

data/lib/openreceive/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenReceive
-  VERSION = "0.4.10"
+  VERSION = "0.4.11"
 end

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.10.
+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
@@ -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
@@ -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).

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.10.
+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
@@ -307,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
@@ -480,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.
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.10.
+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
@@ -301,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
@@ -475,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.
 
@@ -524,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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.10.
+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
@@ -284,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
@@ -477,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.
 
@@ -526,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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.10.
+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
@@ -291,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
@@ -456,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.
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.10.
+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
@@ -290,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
@@ -496,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.
 
@@ -576,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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.10.
+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
@@ -276,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
@@ -454,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.
 
@@ -503,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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.10.
+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
@@ -301,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
@@ -512,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.
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.10.
+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
@@ -285,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
@@ -432,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.
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.10.
+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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive
 version: !ruby/object:Gem::Version
-  version: 0.4.10
+  version: 0.4.11
 platform: ruby
 authors:
 - OpenReceive