openreceive 0.4.10 → 0.4.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e612d1c8beae58671f0e863dbf26622b07a689010b81c3f05abd1463b7f1a4ff
-  data.tar.gz: 68c216cd101ad1d50dd6175b4e565793f7b147a26e1d07e1cda18ffe42659ed6
+  metadata.gz: 01e1bb860a7a293671cf05f57aab92369123dcade28a58bdb21c7c0917d3e53c
+  data.tar.gz: ccdce9021e041361aa8340972fea01cdf4e762bcf4798903900185ec9535f63c
 SHA512:
-  metadata.gz: 24f0505bb26aa2b2b06f439854cf8839825c24d4b1634ecc184c86a6914269f25c621664efc7ba792e04fc644ab2107784b7b78737564669bf57e77e5a8e5452
-  data.tar.gz: a3edc8c5fdda1f703da32f6abe8e87c2ee65fe0d8957c6da7d539b64a8f5762b2a9b0ec952c4f6ef7ee9d4ee5671d8d3675f67693eeff89c5f227b9d0026e089
+  metadata.gz: 72862dc8a7059c13ff37db4261c4c6f37daaf2eba0e7bceebaf6cc2eeae8754938bb2aa853790856a0429922d6eff465d65f8e293759d9757c998b7b7060b107
+  data.tar.gz: c3f5e0fc7c645e3a298579f29f926e1c33ee7bfa9fc5f764ef5e826d0905f34705439adde32156eb3758944dd14346ef18a50a4b315901683a3a512a056509e0

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.4.13 - 2026-10-01
+
+Release in lockstep with the 0.4.13 reconciliation fixes (in
+`openreceive-rails`: a slow wallet no longer livelocks the reconcile pass,
+host-clock attempts get their own scan window, the gate floor is 3 s). No
+change to this gem's API.
+
+## 0.4.12 - 2026-10-01
+
+Release in lockstep with the 0.4.12 checkout fixes ("Switch payment method"
+always returns to the method grid; the swap deposit warning drops its "pay
+with one method only" sentence). No Ruby core changes.
+
+## 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.13"
 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.