openreceive-rails 0.4.11 → 0.4.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b819ffb0e4f2872cd4de6da728c6404804496da560443a928d54d0aa25a5ac6
-  data.tar.gz: 674d40eb671af219dbaafd038eb4e8bee4849649e8bf32d82bf3fd1f45405414
+  metadata.gz: e427ecbaa9d1cbb7007ea7799ff14eeef1a88b5e9b354d79dc9ad1c2d1fc4c53
+  data.tar.gz: e5a92ea94f6edb67a171c03d1bd1367bd66973d672bfd9cdf4f6eb16a52c9307
 SHA512:
-  metadata.gz: a2ad30551213e01ce2fce1ccd0f083d0a26aacf8782a0e38d78c8e628d5a8bf68ebb765ba122fc8c9f8375c375bf7582e0fce8f92a5c8902d6e5a0f7effece7e
-  data.tar.gz: 16b67e1d5797202128acb827f388f371c6d391158c5227f6d8f5acf5fd530b2f3b32604ebbe81609b51cf03b4049f6fcf41a756cf5e81c8119c986e4eec466e9
+  metadata.gz: 2c2a061b4ce15de084a423ee8f440e4bcaf6ac2ce0b156855daae25492ac1df0a51d788739e3008c81c08faeb924cdb8faa83c1ca7f6e1b29e3919b0a139b93f
+  data.tar.gz: 933f003c11889f222970ca79353b04a468b9076f82466a6d3f9f76790b0b9d267c483b135f81852ddeb03f0c0e79e2dcf60291e09cab6c699dc2b8cef087c737

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.4.14 - 2026-10-04
+
+Fixes two 0.4.13 reconciliation regressions. A host-clock attempt could be
+skipped indefinitely: with one scan-window slot taken, selection moved its
+cursor past the whole batch and dropped the batch's host-clock attempts. The
+cursor now moves only past attempts it has queued. And a wallet that answers
+only one history page per slice re-read the same overlap page forever; an
+overlap answered alone is now spent, and the next slice reads the unseen page
+first. Both are pinned by new `reconcile-progress.json` vectors. The bundled
+integration skill also documents the plain-HTML checkout's way back to a swap
+refund (`resume-payment-hash`, `resumable`, the `openreceive-state` event).
+
+## 0.4.13 - 2026-10-01
+
+Reconciliation no longer livelocks on a slow wallet. A wallet-history page
+still in flight at the scan deadline (`Timeout` in the nwc-ruby adapter) failed
+the whole pass and dropped its resume offset, so a long walk restarted at
+offset 0 on every pass and logged `reconciliation failed (will retry):
+OpenReceive::Server::WalletFailureError: execution expired` forever. A cut page
+now ends the slice and keeps the completed pages' progress. A first page cut
+before the wallet answers still fails the pass. Host-clock attempts (legacy
+rows without `created_at_source`) get their own full-history cohort instead of
+widening the window of every wallet-timed attempt pending with them. The gate
+floor rises from 2 s to 3 s (`OpenReceive::MIN_RECONCILE_INTERVAL_SECONDS`).
+
+## 0.4.12 - 2026-10-01
+
+Release in lockstep with the 0.4.12 checkout fixes. The Rails Buy a Button
+demo's checkout now returns to the method grid on every "Switch payment
+method" click. No Rails engine API change.
+
 ## 0.4.11 - 2026-09-21
 
 Reconciliation progress is durable and bounded. A capped wallet walk now

data/lib/generators/openreceive/install/templates/initializer.rb

@@ -90,7 +90,7 @@ OpenReceive.configure do |config|
 
   # Settlement discovery is opportunistic by default: every engine request
   # first runs one reconcile pass through the durable openreceive_meta gate
-  # (shared by all Puma workers; min 2s between real wallet scans), so pending
+  # (shared by all Puma workers; min 3s between real wallet scans), so pending
   # attempts settle or close on any later OpenReceive call — no scheduled job
   # required. Set false only if a dedicated worker owns scanning.
   # config.opportunistic_reconcile = false

data/lib/openreceive/configuration.rb

@@ -81,7 +81,7 @@ module OpenReceive
       # durably gated reconcile pass when attempts are pending, so abandoned
       # checkouts settle on any later OpenReceive call with no scheduled job.
       # The openreceive_meta gate row is shared by every Puma worker/process on
-      # the host database (min 2s between real wallet scans, stretched by
+      # the host database (min 3s between real wallet scans, stretched by
       # invoice age). Set false to disable (e.g. when the optional
       # `bin/rails openreceive:notifications` worker owns scanning), or a Hash
       # with min_interval_seconds to tune.

data/lib/openreceive/rails/version.rb

@@ -5,6 +5,6 @@ module OpenReceive
   # top-level `::Rails` framework constant — engine code always references the framework as
   # `::Rails` to avoid shadowing.
   module Rails
-    VERSION = "0.4.11"
+    VERSION = "0.4.14"
   end
 end

data/lib/openreceive/reconcile.rb

@@ -6,9 +6,9 @@ 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
+  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
@@ -82,11 +82,30 @@ module OpenReceive
           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")) }
-          windows << ReconcileScan.new_window(cohort, observed_at, overlap_seconds) unless cohort.empty?
+          # 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. Candidates are taken in keyset order, and the cursor
+          # moves only past those already queued or admitted: one whose clock
+          # source has no free slot stops the selection and is read again next
+          # time, never skipped.
+          cohorts = {}
+          taken = 0
+          candidates.each do |attempt|
+            unless queued.include?(attempt.fetch("payment_hash"))
+              wallet = attempt["created_at_source"] == "wallet"
+              break if !cohorts.key?(wallet) && windows.length + cohorts.length >= 2
+
+              (cohorts[wallet] ||= []) << attempt
+            end
+            taken += 1
+          end
+          # A short batch taken whole already reached the ledger's tail: wrap now.
+          tail = taken == candidates.length && candidates.length < Server::RECONCILE_BATCH_SIZE
+          scheduler["cursor"] = tail ? nil : candidates[taken - 1].slice("created_at", "payment_hash")
+          [true, false].each do |wallet|
+            windows << ReconcileScan.new_window(cohorts[wallet], observed_at, overlap_seconds) if cohorts.key?(wallet)
+          end
         end
       end
       window = windows.shift
@@ -266,7 +285,7 @@ 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 —
@@ -296,7 +315,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
@@ -307,7 +326,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

data/lib/openreceive/reconcile_scan.rb

@@ -27,7 +27,16 @@ module OpenReceive
       anchor = resumed ? window["anchor_offset"] : nil
       replaying = !anchor.nil?
       previous = window["fingerprint"]
-      max_pages.times do
+      # The last answered page was the overlap re-read. A slice that ends here
+      # spends the overlap, so the next slice reads the unseen page first: a
+      # wallet answering one page per slice still advances. The fingerprint
+      # stays, to catch a wallet that ignores offset.
+      overlap_only = false
+      continued = lambda do
+        window["anchor_offset"] = nil if overlap_only
+        [results.values, false, false]
+      end
+      max_pages.times do |page_number|
         break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
 
         offset = replaying ? anchor : window.fetch("offset")
@@ -35,8 +44,23 @@ module OpenReceive
         request["until"] = window["until"] unless window["until"].nil?
         request["unpaid"] = true if window.fetch("view") == "inclusive"
         request["_deadline"] = deadline
-        page = OpenReceive.normalize_list_transactions_response(service.send(:call_nwc, :list_transactions, request))
-        return [results.values, false, false] if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= 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 continued.call
+        end
+        return continued.call if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        overlap_only = false
 
         rows = page.fetch("transactions")
         physical = rows.length + page.fetch("skipped_rows", 0)
@@ -60,6 +84,7 @@ module OpenReceive
           unless physical.zero?
             window["anchor_offset"] = offset
             window["fingerprint"] = fingerprint
+            overlap_only = true
             next
           end
         end
@@ -87,7 +112,7 @@ module OpenReceive
         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]
+      continued.call
     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.11.
+These directions describe OpenReceive 0.4.14.
 
 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
@@ -133,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
 
@@ -157,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 two tables (`openreceive_invoices` and
-`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.