openreceive-rails 0.4.10 → 0.4.13

data/lib/openreceive/reconcile.rb

@@ -2,17 +2,15 @@
 
 require "json"
 require "openreceive/server"
+require "openreceive/reconcile_scan"
 
 module OpenReceive
   # Floor for the durable reconcile-gate interval (seconds); stretched by
-  # invoice age (2s while any pending invoice is under 2 minutes old, 6s under
+  # invoice age (3s while any pending invoice is under 2 minutes old, 6s under
   # 5 minutes, else 12s). Mirrors the JS OPENRECEIVE_MIN_RECONCILE_INTERVAL_SECONDS.
-  MIN_RECONCILE_INTERVAL_SECONDS = 2
-  # Wall-clock bound on an awaited request-path pass. Enforced as a deadline
-  # the wallet scan checks between page fetches rather than a Timeout.timeout:
-  # Thread#raise at an arbitrary point could tear down an ActiveRecord
-  # connection or kill a host's on_paid fulfillment mid-flight, on every
-  # winning request. A pass that runs out of budget simply stops walking.
+  MIN_RECONCILE_INTERVAL_SECONDS = 3
+  # The deadline reaches the wallet adapter, which bounds only network I/O.
+  # Never interrupt the whole pass: it also runs host/database transactions.
   RECONCILE_SCAN_TIMEOUT_SECONDS = 9
   # Wallet-history pages a request-path pass may walk, mirroring the JS
   # OPENRECEIVE_RECONCILE_SCAN_MAX_PAGES.
@@ -29,8 +27,8 @@ module OpenReceive
     # from a successful wallet scan result observed at or after expiry plus
     # OpenReceive::Server::Reconciliation::EXPIRY_GRACE_SECONDS — a local clock
     # alone never closes a row, because a payment could have settled while the
-    # application was offline. A wallet failure raises and leaves every row
-    # pending for the next pass, and a hash absent from the pass results (a
+    # application was offline. A later wallet failure preserves already committed
+    # finality and leaves unresolved rows pending. A hash absent from pass results (a
     # truncated scan never proved it absent) is no information — the attempt
     # stays untouched.
     #
@@ -41,34 +39,6 @@ module OpenReceive
     # { "payment_hash", "status", "paid_at"?, "details"? } hashes) so callers —
     # notably payments/check — can serve a requested hash straight from the
     # pass instead of adding a second per-invoice wallet walk.
-    def reconcile!(overlap_seconds: 60, now: nil, max_pages: nil, deadline: nil)
-      attempts = OpenReceivePayment.reconcilable_attempts
-      return [] if attempts.empty?
-
-      observed_at = Integer(now || Time.now.to_i)
-      request = {
-        "attempts" => attempts,
-        "overlap_seconds" => overlap_seconds,
-        "until" => observed_at + overlap_seconds
-      }
-      request["max_pages"] = max_pages unless max_pages.nil?
-      request["deadline"] = deadline unless deadline.nil?
-      results = config.service.reconcile_payments(request)
-      log_reconcile_pass(attempts, results, overlap_seconds, observed_at)
-      by_hash = attempts.to_h { |attempt| [attempt.fetch("payment_hash"), attempt] }
-      results.each do |checked|
-        attempt = by_hash[checked.fetch("payment_hash")]
-        next if attempt.nil?
-
-        if checked["status"] == "settled" && checked["paid_at"]
-          settle_attempt(checked)
-        else
-          record_attempt_transition(attempt, checked, observed_at)
-        end
-      end
-      results
-    end
-
     # Opportunistic settlement discovery, piggybacked on any OpenReceive call
     # (the engine's around_action runs it before every mounted route): skip
     # without a wallet call when nothing is pending, try the durable
@@ -87,30 +57,104 @@ module OpenReceive
       setting = config.opportunistic_reconcile
       return { "reason" => "disabled" } if setting == false
 
+      gated_reconcile!(now: now)
+    end
+
+    def reconcile!(overlap_seconds: 60, now: nil)
+      gated_reconcile!(overlap_seconds: overlap_seconds, now: now).fetch("checks", [])
+    end
+
+    def gated_reconcile!(overlap_seconds: 60, now: nil)
       attempts = OpenReceivePayment.reconcilable_attempts
       return { "reason" => "no_pending" } if attempts.empty?
 
       observed_at = Integer(now || Time.now.to_i)
-      interval = reconcile_gate_interval_seconds(attempts, observed_at, setting)
-      unless OpenReceiveMeta.claim_reconcile_gate(now: observed_at, interval_seconds: interval)
-        # Another worker scanned within the interval; this request pays nothing.
-        openreceive_logger&.debug(
-          "[openreceive] opportunistic reconcile: gate_busy " \
-          "(#{attempts.length} pending, interval #{interval}s)"
-        )
-        return { "reason" => "gate_busy" }
+      interval = reconcile_gate_interval_seconds(attempts, observed_at, config.opportunistic_reconcile)
+      claim = OpenReceiveMeta.claim_reconcile_gate(now: observed_at, interval_seconds: interval)
+      return { "reason" => "gate_busy" } if claim.nil?
+
+      scheduler = claim.fetch("scheduler")
+      windows = scheduler.fetch("windows")
+      if windows.length < 2
+        candidates = OpenReceivePayment.reconcilable_attempts(after: scheduler["cursor"])
+        if candidates.empty?
+          scheduler["cursor"] = nil
+          candidates = OpenReceivePayment.reconcilable_attempts
+        end
+        unless candidates.empty?
+          last = candidates.last
+          scheduler["cursor"] = candidates.length < Server::RECONCILE_BATCH_SIZE ? nil : last.slice("created_at", "payment_hash")
+          queued = windows.flat_map { |w| w.fetch("attempts").map { |a| a.fetch("payment_hash") } }
+          cohort = candidates.reject { |a| queued.include?(a.fetch("payment_hash")) }
+          # A host-clock attempt's window spans the whole wallet history. It
+          # gets its own window, so it never drags wallet-timed attempts into
+          # that walk; one the cap leaves out returns on cursor wrap.
+          cohort.partition { |a| a["created_at_source"] == "wallet" }.each do |group|
+            windows << ReconcileScan.new_window(group, observed_at, overlap_seconds) unless group.empty? || windows.length >= 2
+          end
+        end
+      end
+      window = windows.shift
+      # Checkpoint without the active window, so failures and process loss free
+      # its slot. Pending rows return on cursor wrap; successful slices resume.
+      checkpoint_now = now.nil? ? Time.now.to_i : observed_at
+      return { "reason" => "gate_busy" } unless OpenReceiveMeta.checkpoint_reconcile_gate(claim, scheduler, now: checkpoint_now)
+      if window.nil?
+        OpenReceiveMeta.checkpoint_reconcile_gate(claim, scheduler, now: checkpoint_now, release: true)
+        return { "reason" => "no_pending" }
       end
 
-      checks = reconcile!(
-        now: observed_at,
+      by_hash = window.fetch("attempts").to_h { |a| [a.fetch("payment_hash"), a] }
+      delivered = {}
+      before_scan = JSON.parse(JSON.generate(scheduler))
+      deliver_finality = lambda do |checked|
+        hash = checked.fetch("payment_hash")
+        current = now.nil? ? Time.now.to_i : observed_at
+        unless OpenReceiveMeta.checkpoint_reconcile_gate(claim, before_scan, now: current)
+          delivered[hash] = false
+          next
+        end
+        if checked["status"] == "settled" && checked["paid_at"]
+          delivered[hash] = settle_attempt(checked)
+        else
+          record_attempt_transition(by_hash.fetch(hash), checked, observed_at)
+          delivered[hash] = true
+        end
+      end
+      checks, complete, stalled = ReconcileScan.slice(config.service, window,
         max_pages: RECONCILE_SCAN_MAX_PAGES,
-        deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + RECONCILE_SCAN_TIMEOUT_SECONDS
-      )
-      { "reason" => "ran", "checks" => checks }
+        deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + RECONCILE_SCAN_TIMEOUT_SECONDS, on_finality: deliver_finality)
+      lease_owned = OpenReceiveMeta.checkpoint_reconcile_gate(claim, before_scan, now: now.nil? ? Time.now.to_i : observed_at)
+      committed = checks.filter_map do |checked|
+        if delivered.key?(checked.fetch("payment_hash"))
+          next unless delivered.fetch(checked.fetch("payment_hash"))
+        elsif checked["status"] == "settled" && checked["paid_at"]
+          next
+        else
+          next unless lease_owned
+
+          record_attempt_transition(by_hash.fetch(checked.fetch("payment_hash")), checked,
+            checked.fetch("_coverage_started_at", observed_at))
+        end
+        checked.reject { |key, _| key.start_with?("_") }
+      end
+      unless complete || stalled
+        times = window.fetch("attempts").map { |a| a.fetch("created_at") }.uniq.sort
+        if windows.empty? && times.length > 1 && window.fetch("attempts").all? { |a| a["created_at_source"] == "wallet" }
+          middle = times[times.length / 2]
+          window.fetch("attempts").partition { |a| a.fetch("created_at") < middle }.each do |half|
+            windows << ReconcileScan.new_window(half, observed_at, overlap_seconds)
+          end
+        else
+          windows << window
+        end
+      end
+      checkpoint_now = now.nil? ? Time.now.to_i : observed_at
+      OpenReceiveMeta.checkpoint_reconcile_gate(claim, scheduler, now: checkpoint_now, release: true)
+      log_reconcile_pass(window.fetch("attempts"), committed, window)
+      { "reason" => "ran", "checks" => committed }
     rescue StandardError => e
-      openreceive_logger&.warn(
-        "[openreceive] opportunistic reconcile failed (will retry): #{sanitize_failure_message(e)}"
-      )
+      openreceive_logger&.warn("[openreceive] reconciliation failed (will retry): #{sanitize_failure_message(e)}")
       { "reason" => "scan_failed" }
     end
 
@@ -172,13 +216,12 @@ module OpenReceive
     # `openreceive:notifications` worker — the process most likely to see a
     # connect error — logs failures of its own.
     def sanitize_failure_message(error)
-      "#{error.class}: #{error.message}"
-        .gsub(/nostr\+walletconnect:[^\s"'`<>]+/, "[REDACTED_NWC]")
-        .gsub(/lightning\+swapconnect:[^\s"'`<>]+/, "[REDACTED_LSC]")
+      OpenReceive::Nwc.redact_error_text("#{error.class}: #{error.message}")
     end
 
     private
 
+
     # Rails.logger when the engine runs inside Rails; nil in bare-gem tests.
     # Settlement behavior never depends on logging.
     def openreceive_logger
@@ -196,11 +239,13 @@ module OpenReceive
         "paid_at" => checked.fetch("paid_at"),
         "details" => checked["details"]
       )
+      OpenReceivePayment.where(payment_hash: checked.fetch("payment_hash"), status: "settled").exists?
     rescue StandardError => e
       openreceive_logger&.warn(
         "[openreceive] settlement for #{checked.fetch('payment_hash')} failed " \
         "(will retry next pass): #{sanitize_failure_message(e)}"
       )
+      false
     end
 
     # Closure is decided by the shared reconciliation rules from a scan result
@@ -226,14 +271,14 @@ module OpenReceive
       )
     end
 
-    # Info, not debug: passes are durably gated (min 2s apart, and only while
+    # Info, not debug: passes are durably gated (min 3s apart, and only while
     # attempts are pending), so operators can watch settlement discovery and
     # the batched list_transactions window without raising the log level. All
     # pending attempts share one creation-time window walked at most twice —
     # never one wallet call per invoice. One short line per poll: this fires
     # on every status poll while a payer waits. Mirrors the JS
     # payment.reconcile.completed line.
-    def log_reconcile_pass(attempts, results, overlap_seconds, observed_at)
+    def log_reconcile_pass(attempts, results, window)
       logger = openreceive_logger
       return if logger.nil?
 
@@ -245,10 +290,9 @@ module OpenReceive
       decided = ["0 decided"] if decided.empty?
       # Attempts scanned vs hashes decided: a gap is how a truncated scan shows up.
       scanned = results.length == attempts.length ? "" : " of #{attempts.length} attempts"
-      window_from = [attempts.map { |attempt| Integer(attempt.fetch("created_at")) }.min - overlap_seconds, 0].max
       logger.info(
         "[openreceive] payment.reconcile.completed: #{decided.join(', ')}#{scanned} " \
-        "attempt_count=#{attempts.length} window=#{window_from}..#{observed_at + overlap_seconds}"
+        "attempt_count=#{attempts.length} window=#{window.fetch("from")}..#{window["until"] || "unbounded"}"
       )
     rescue StandardError
       # Diagnostics must never affect the pass.
@@ -257,7 +301,7 @@ module OpenReceive
 
     # The gate interval for the current pending set: the configured floor
     # (config.opportunistic_reconcile min_interval_seconds), stretched by
-    # invoice age — 2s while any pending invoice is under 2 minutes old, 6s
+    # invoice age — 3s while any pending invoice is under 2 minutes old, 6s
     # under 5 minutes, else 12s. Mirrors the JS reconcile gate.
     def reconcile_gate_interval_seconds(attempts, now, setting)
       floor = MIN_RECONCILE_INTERVAL_SECONDS
@@ -268,7 +312,7 @@ module OpenReceive
       age_stretch = attempts.map do |attempt|
         elapsed = [now - Integer(attempt.fetch("created_at")), 0].max
         if elapsed < 120
-          2
+          3
         elsif elapsed < 300
           6
         else
@@ -303,7 +347,7 @@ module OpenReceive
       payment_hash = transaction["payment_hash"].to_s.downcase
       return false if payment_hash.empty?
 
-      return false unless OpenReceivePayment.pending.where(payment_hash: payment_hash).exists?
+      return false if OpenReceivePayment.find_pending_attempt(payment_hash).nil?
 
       observed_at = Time.now.to_i
       config.settlement_hook.call(
@@ -315,7 +359,7 @@ module OpenReceive
           "paid_at_source" => transaction["settled_at"] ? "settled_at" : "observed_at"
         }
       )
-      true
+      OpenReceivePayment.where(payment_hash: payment_hash, status: "settled").exists?
     rescue StandardError
       # A direct-settlement failure falls back to the scan-based safety net.
       false

data/lib/openreceive/reconcile_scan.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module OpenReceive
+  # Durable scan slices store only identities, offsets and minimal classifications.
+  module ReconcileScan
+    module_function
+
+    def new_window(attempts, now, overlap)
+      trusted = attempts.all? { |a| a["created_at_source"] == "wallet" }
+      {
+        "attempts" => attempts,
+        "from" => trusted ? [attempts.map { |a| a.fetch("created_at") }.min - overlap, 0].max : 0,
+        "until" => trusted ? attempts.map { |a| a.fetch("created_at") }.max + overlap : nil,
+        "view" => "default", "offset" => 0, "anchor_offset" => nil, "fingerprint" => nil,
+        "started_at" => now, "absence_safe" => true, "observations" => {}
+      }
+    end
+
+    def slice(service, window, max_pages:, deadline:, on_finality: nil)
+      results = {}
+      expected = window.fetch("attempts").map { |a| a.fetch("payment_hash") }
+      resumed = window.fetch("offset").positive? || window.fetch("view") != "default"
+      window["absence_safe"] = false if resumed
+      anchor = resumed ? window["anchor_offset"] : nil
+      replaying = !anchor.nil?
+      previous = window["fingerprint"]
+      max_pages.times do |page_number|
+        break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        offset = replaying ? anchor : window.fetch("offset")
+        request = { "type" => "incoming", "limit" => 20, "offset" => offset, "from" => window.fetch("from") }
+        request["until"] = window["until"] unless window["until"].nil?
+        request["unpaid"] = true if window.fetch("view") == "inclusive"
+        request["_deadline"] = deadline
+        page = begin
+          OpenReceive.normalize_list_transactions_response(service.send(:call_nwc, :list_transactions, request))
+        rescue Server::WalletFailureError
+          # The client cuts the in-flight page at this deadline. After at least
+          # one answered page that ends the slice like a page answered late:
+          # the completed pages keep their progress. Failing the pass would drop
+          # the resume offset, and a wallet too slow to finish the walk in one
+          # slice would then re-walk the same first pages on every pass. A cut
+          # first page made no progress and still fails the pass, so a wallet
+          # that never answers stays visible.
+          raise if page_number.zero? || Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+
+          return [results.values, false, false]
+        end
+        return [results.values, false, false] if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        rows = page.fetch("transactions")
+        physical = rows.length + page.fetch("skipped_rows", 0)
+        fingerprint = Digest::SHA256.hexdigest(JSON.generate(rows.map { |row| row["payment_hash"] }))
+        rows.each do |row|
+          hash = row["payment_hash"]
+          next unless expected.include?(hash) && [nil, "incoming"].include?(row["type"])
+          next if window.fetch("observations").dig(hash, "status") == "settled"
+
+          status = OpenReceive::Settlement.status(row)
+          if %w[settled expired failed].include?(status)
+            results[hash] = service.send(:payment_result, hash, row)
+            on_finality&.call(results[hash]) if Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+          end
+          window.fetch("observations")[hash] = { "status" => status, "transaction_state" => row["transaction_state"] }
+        end
+        if replaying
+          replaying = false
+          window["offset"] = offset + physical
+          previous = fingerprint
+          unless physical.zero?
+            window["anchor_offset"] = offset
+            window["fingerprint"] = fingerprint
+            next
+          end
+        end
+        if physical.zero?
+          if window.fetch("view") == "default"
+            window.merge!("view" => "inclusive", "offset" => 0, "anchor_offset" => nil, "fingerprint" => nil)
+            previous = nil
+            next
+          end
+          if window.fetch("absence_safe")
+            expected.each do |hash|
+              observation = window.fetch("observations")[hash]
+              next if results.key?(hash) || %w[settled expired failed].include?(observation&.fetch("status"))
+
+              result = { "payment_hash" => hash, "status" => observation.nil? ? "not_found" : observation.fetch("status"), "_coverage_started_at" => window.fetch("started_at") }
+              result["details"] = { "transaction" => { "transaction_state" => observation["transaction_state"] } } unless observation.nil?
+              results[hash] = result
+            end
+          end
+          return [results.values, true, false]
+        end
+        return [results.values, false, true] if fingerprint == previous
+
+        window.merge!("anchor_offset" => offset, "fingerprint" => fingerprint, "offset" => offset + physical)
+        previous = fingerprint
+        return [results.values, true, false] if expected.all? { |hash| %w[settled expired failed].include?(window.fetch("observations").dig(hash, "status")) }
+      end
+      [results.values, false, false]
+    end
+  end
+end

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

@@ -49,7 +49,7 @@ same diagnostics redacted, always exit 0 — safe to share.
 ## 4. Paid but never settles
 
 - Settlement is opportunistic: any OpenReceive request runs one reconcile pass
-  through a durable gate (min 2s between wallet scans, stretched by invoice
+  through a durable gate (min 3s between wallet scans, stretched by invoice
   age). A quiet server settles on the next request — or run the optional
   notification worker. No timer is missing; that is the design.
 - An unpaid attempt closes only after a successful wallet scan at/after expiry

data/skills/integrate-openreceive/SKILL.md

@@ -34,9 +34,10 @@ code** (`NWC_URI`).
    - BTCPay Server: [references/btcpay.md](references/btcpay.md) — a plugin,
      configured in BTCPay's store UI or Greenfield API; no application code,
      no npm packages, no gem. The rest of this file is about the library.
-3. Follow its **Step 0** first: confirm `NWC_URI` is set in the server
-   environment before writing code. Never print the value; never invent a
-   placeholder.
+3. Follow its **Step 0** first: before writing code or searching the machine,
+   ask the user for the receive-only NWC code (then the swap URI), one question
+   per message, and store each pasted code in the project's env file yourself.
+   Never print the value; never invent a placeholder.
 
 Install, per adapter — Express: `npm install @openreceive/express @openreceive/react`;
 Fastify: `npm install @openreceive/fastify @openreceive/react`; Next.js:

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.13.
 
 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
@@ -35,10 +35,12 @@ refund path on the same checkout screen.
 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
-   store navigation shows an "OpenReceive" entry). If not, install it from the
-   BTCPay plugin directory (Server Settings → Plugins, search "OpenReceive"),
-   as the quickstart says; do not invent an installer command.
+2. Check whether the plugin is installed (the Plugins menu — the plug icon in
+   the top-right corner — under Installed Plugins, or the store navigation
+   shows an "OpenReceive" entry). If not, install it from the BTCPay plugin
+   directory (the same Plugins menu → Plugin Directory, search "openreceive",
+   then Install and Restart now), as the quickstart says; do not invent an
+   installer command.
 3. Check whether the store already has an OpenReceive connection:
    `GET /api/v1/stores/{storeId}/openreceive/settings` returns
    `lightningNodeIsOpenReceive`. If true, the wallet step is done — go to
@@ -119,6 +121,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
@@ -131,15 +135,15 @@ passes. The page it comes from is https://openreceive.org/guides/quickstart-btcp
 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
-payments through its own settlement machinery. Optionally, payers can pay a
-BTCPay invoice with USDT, USDC, ETH or SOL through a Lightning Swap Connect
-provider; the swap settles into the same wallet. The store's internal node is
+BTCPay store. BTCPay creates every Lightning invoice in that wallet. It records
+payments the same way it records any other payment. You can also let payers pay
+a BTCPay invoice with USDT, USDC, ETH or SOL through a Lightning Swap Connect
+provider. The swap pays into the same wallet. The store's internal node is
 never used.
 
 This is not the Node or Rails library. There are no hooks, no
-`openreceive_payments` table and no OpenReceive HTTP routes: BTCPay's
-invoices, checkout, webhooks and Greenfield API are the host.
+`openreceive_payments` table and no OpenReceive HTTP routes. BTCPay's own
+invoices, checkout, webhooks and Greenfield API do that work.
 
 ### 1. Prerequisites
 
@@ -155,39 +159,66 @@ invoices, checkout, webhooks and Greenfield API are the host.
 
 ### 2. Install the plugin
 
-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.
+Sign in as a **server administrator**. If someone else hosts your server, ask
+them to install the plugin for you.
+
+**1. Open the Plugins menu.** It is the plug icon in the top-right corner.
+
+**2. Click Plugin Directory.**
+
+**3. Search for `openreceive`** and click the **OpenReceive** result.
+
+**4. Click Install in BTCPay Server.** Confirm when prompted, then click
+**Restart now** and wait for BTCPay to come back.
+
+At startup, BTCPay creates the plugin's two tables in its own Postgres
+database: `openreceive_invoices` and `openreceive_swaps`, in the schema
+`BTCPayServer.Plugins.OpenReceive`. 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).
 
 ### 3. Connect the wallet
 
-Follow the plugin README's illustrated walkthrough:
-[OpenReceive for BTCPay Server](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/BTCPayServer.Plugins.OpenReceive/README.md).
-It opens the **OpenReceive** page in the store's sidebar, saves the
-receive-only NWC code, optionally saves the LSC code to turn swaps on, and
-creates a first test invoice. There is nothing else to configure: you never
-open BTCPay's Lightning node screen, and the plugin never reads the internal
-node.
+1. Select your store and open **OpenReceive** in its sidebar, under Wallets.
+2. Paste your receive-only NWC code. To see what the wallet supports first,
+   click **Test connection**.
+3. Click **Save NWC Code**.
+4. To turn swaps on, paste a Lightning Swap Connect code and click **Save swap
+   settings**.
 
-Saving fails closed if the wallet advertises a spend method such as
-`pay_invoice`. Mint a receive-only code instead; the override for a wallet
-that cannot is a deliberate, logged choice. Swaps raise the store's invoice
-expiration to 60 minutes when it is shorter, because a swap needs at least 45
-minutes of invoice life.
+The page then shows **Wallet connected**. If you set up a provider, it also
+shows **Swaps on**. There is nothing else to configure. You never open BTCPay's
+Lightning node screen, and the plugin never reads the internal node.
+
+Screenshots for each of those steps, and for creating a first test invoice,
+are in the plugin's
+[README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/BTCPayServer.Plugins.OpenReceive/README.md).
+
+The plugin refuses to save a code whose wallet advertises a spend method such
+as `pay_invoice`. Create a receive-only code instead. If your wallet cannot
+make one, there is an override, but using it is a deliberate choice and the
+plugin logs it.
+
+Turning swaps on raises the store's invoice expiration to 60 minutes if it is
+shorter. A swap needs the invoice to stay open for at least 45 minutes.
 
 ### 4. Check it
 
-**Run a health check** on the OpenReceive page runs every probe in place:
-the connection, the wallet preflight, payment notifications, the last wallet
-scan, the swap provider and its assets, the invoice expiration, and swaps
-that need a human. Each failing probe carries a fix link.
+Click **Run a health check** on the OpenReceive page. It runs every check
+right there:
+
+- the connection
+- the wallet preflight
+- payment notifications
+- the last wallet scan
+- the swap provider and its assets
+- the invoice expiration
+- swaps that need a human
+
+Each failing check comes with a link to the fix.
 
-Every setting, Greenfield route, swap state, log event and probe is in the
-[BTCPay plugin reference](https://openreceive.org/guides/btcpay-reference.md), including what is
-unsupported by design: every send-side feature, top-up invoices, and a bare
-`nostr+walletconnect://` string in BTCPay's Lightning node screen.
+The [BTCPay plugin reference](https://openreceive.org/guides/btcpay-reference.md) lists every setting,
+Greenfield route, swap state, log event and check. It also lists what the
+plugin does not support by design: every send-side feature, top-up invoices,
+and a bare `nostr+walletconnect://` string in BTCPay's Lightning node screen.