openreceive-server 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8531811b5ffc69913bcf13970f0c18f6de494360f0ee746251fccd7c0d73ea92
-  data.tar.gz: 38e4a6c85d95235b12a907bf6852b286f498c8aaceb6b91ca0ec8bc4aa7862c4
+  metadata.gz: '08bf7311603d77400f63f99b2ac15650105a25fdeb21ac3f38f8cf2df243f394'
+  data.tar.gz: 07ff30f8eab72b50544bc4022135dcf9a4d1e80e28e5062ccb22793bf01222fc
 SHA512:
-  metadata.gz: 5b4484815ec4ff40aaf49e6a374a2d9a512843b29c15447bd7476a7828cee9cc8ce8d0a6b8c59823daae9e0f920b231c3f0cab1ee6a88aca7b3ac6c38608ba4e
-  data.tar.gz: f7c1edd3b2ec73d908e3b3698fe0389f9afc1479e1010be41983c53b36b405360ae64ee247082b20a2e3538e6236e5def2ba708b7a93eb4838900557b8a5525b
+  metadata.gz: 1f3aa5d0622a47af6f2b0d1f40866f2763359564875cbfa7299781e840ee6a503e0e8bae78ce8d8825545f49d19c7c1a8a047b35780368410df65818ec8da3af
+  data.tar.gz: b7012062378dcbc8da84cd8ed9488c1e9efff9a0e54abd9580e5093cb38617b35760073d0748b1737807364299a3217ed86ad715f8cb8a70cc78ce678bddc501

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.4 - 2026-09-07
+
+Version lockstep with the 0.4.4 npm release (every checkout image now ships
+inside the JavaScript; no asset option). Ruby changes in this gem:
+
+- The FixedFloat status normalizer (`OpenReceive::Server::Swap::FixedFloat`)
+  is now a short interpreter of the generated swap-state table shared with
+  every engine, pinned by the `swap-state` test vector. Same states and
+  reasons as before for every input.
+- The bundled agent skill gains references for Django, FastAPI, Fastify,
+  Laravel and Next.js beside Node, Rails and BTCPay Server.
+
+## 0.4.3 - 2026-09-03
+
+Version lockstep with the 0.4.3 npm release (container-query checkout
+layout, themed pre-create screens, padded root, money caption). No Ruby
+changes in this gem.
+
 ## 0.4.2 - 2026-09-03
 
 Version lockstep with the 0.4.2 npm release (the scoped frontend stylesheet).

data/lib/openreceive/server/reconciliation.rb

@@ -10,10 +10,10 @@ module OpenReceive
       # Seconds past an attempt's expiry during which reconciliation still scans
       # for a settlement before closing the attempt. Covers clock skew and
       # wallets that accept a payment moments after nominal invoice expiry.
-      # The value 900 is pinned by spec/test-vectors/attempt-reconciliation.json
-      # ("expiry_grace_seconds", asserted by tools/conformance/ruby-crosslang.rb)
-      # and mirrored by JS OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS.
-      EXPIRY_GRACE_SECONDS = 900
+      # The value comes from spec/data/kernel-tables.json (generated into
+      # OpenReceive::Generated), is pinned by spec/test-vectors/attempt-
+      # reconciliation.json, and is the JS OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS.
+      EXPIRY_GRACE_SECONDS = OpenReceive::Generated::ATTEMPT_EXPIRY_GRACE_SECONDS
 
       module_function
 

data/lib/openreceive/server/swap/assets.rb

@@ -5,44 +5,15 @@ require "openreceive"
 module OpenReceive
   module Server
     module Swap
-      # Ruby port of packages/js/node/src/swap/assets.ts: the OpenReceive
+      # Ruby twin of packages/js/node/src/swap/assets.ts: the OpenReceive
       # pay-in asset catalog (labels, network labels, provider matching) and
       # the network helpers the FixedFloat provider uses to map /ccies rows.
       module Assets
-        PAY_IN_ASSETS = %w[
-          SOL_SOL USDT_TRON USDT_SOL USDC_SOL ETH_ETH USDT_ETH USDC_ETH
-        ].freeze
-
-        ASSET_INFO = {
-          "SOL_SOL" => {
-            "pay_in_asset" => "SOL_SOL", "label" => "SOL", "network_label" => "Solana",
-            "coin" => "SOL", "network" => "SOL"
-          }.freeze,
-          "USDT_TRON" => {
-            "pay_in_asset" => "USDT_TRON", "label" => "USDT", "network_label" => "Tron",
-            "coin" => "USDT", "network" => "TRX"
-          }.freeze,
-          "USDT_SOL" => {
-            "pay_in_asset" => "USDT_SOL", "label" => "USDT", "network_label" => "Solana",
-            "coin" => "USDT", "network" => "SOL"
-          }.freeze,
-          "USDC_SOL" => {
-            "pay_in_asset" => "USDC_SOL", "label" => "USDC", "network_label" => "Solana",
-            "coin" => "USDC", "network" => "SOL"
-          }.freeze,
-          "ETH_ETH" => {
-            "pay_in_asset" => "ETH_ETH", "label" => "ETH", "network_label" => "Ethereum",
-            "coin" => "ETH", "network" => "ETH"
-          }.freeze,
-          "USDT_ETH" => {
-            "pay_in_asset" => "USDT_ETH", "label" => "USDT", "network_label" => "Ethereum",
-            "coin" => "USDT", "network" => "ETH"
-          }.freeze,
-          "USDC_ETH" => {
-            "pay_in_asset" => "USDC_ETH", "label" => "USDC", "network_label" => "Ethereum",
-            "coin" => "USDC", "network" => "ETH"
-          }.freeze
-        }.freeze
+        # The asset table is kernel vocabulary (spec/data/kernel-tables.json),
+        # generated into every engine; this module adds the lookups and the
+        # provider network matching on top of it.
+        PAY_IN_ASSETS = OpenReceive::Generated::SWAP_PAY_IN_ASSETS
+        ASSET_INFO = OpenReceive::Generated::SWAP_ASSET_INFO
 
         module_function
 

data/lib/openreceive/server/swap/fixedfloat.rb

@@ -609,72 +609,46 @@ module OpenReceive
             { "currency" => "USD", "pay_in_fiat" => pay_in_fiat, "payout_fiat" => payout_fiat }
           end
 
+          # FixedFloat status + emergency block + refund-tx presence → state and
+          # reasons: an interpreter of spec/data/swap-state-table.json (rendered
+          # into OpenReceive::Generated), first-match-wins. Pinned across engines
+          # by spec/test-vectors/swap-state.json; how to read the rows lives in
+          # the JSON. The validator asserts the table ends in a catch-all row.
           def normalize_status(status, emergency, refund_tx_id)
             normalized = status.to_s.upcase
-            if !refund_tx_id.nil? && %w[DONE FINISHED].include?(normalized)
-              return { "state" => "refunded" }
+            refund_tx_present = !refund_tx_id.nil?
+            choice = read_string(emergency["choice"])&.upcase
+            row = OpenReceive::Generated::SWAP_STATUS_ROWS.find do |candidate|
+              status_matches =
+                if candidate["status"] == "*"
+                  candidate["status_contains"].nil? || normalized.include?(candidate["status_contains"])
+                else
+                  candidate["status"] == normalized
+                end
+              status_matches &&
+                (candidate["refund_tx_present"] == "any" || candidate["refund_tx_present"] == refund_tx_present) &&
+                (candidate["choice"] == "any" ||
+                  (choice.nil? ? candidate["choice"] == "absent" : candidate["choice"] == choice))
             end
-            case normalized
-            when "NEW" then return { "state" => "awaiting_deposit" }
-            when "PENDING" then return { "state" => "confirming" }
-            when "EXCHANGE" then return { "state" => "exchanging" }
-            when "WITHDRAW" then return { "state" => "paying_invoice" }
-            when "DONE" then return { "state" => "completed" }
-            when "EXPIRED" then return { "state" => "expired" }
+            result = { "state" => row.fetch("state") }
+            if row["attention_reason"]
+              result["attention"] = true
+              result["attention_reason"] = row["attention_reason"]
             end
-            if normalized == "EMERGENCY"
-              choice = read_string(emergency["choice"])&.upcase
-              statuses = read_string_array(emergency["status"]).map(&:upcase)
-              refund_reason = refund_reason_from_emergency_statuses(statuses)
-              if choice == "REFUND" && !refund_tx_id.nil?
-                result = { "state" => "refunded" }
-                result["refund_reason"] = refund_reason unless refund_reason.nil?
-                return result
-              end
-              if choice == "REFUND"
-                result = { "state" => "refund_pending" }
-                result["refund_reason"] = refund_reason unless refund_reason.nil?
-                return result
-              end
-              if choice == "EXCHANGE"
-                return {
-                  "state" => "attention", "attention" => true,
-                  "attention_reason" => "provider_reported_emergency"
-                }
-              end
-              # An overpay (MORE) takes the same self-serve full-refund path as
-              # LESS and EXPIRED — it is what the provider itself does with it.
-              # There is no partial refund of the surplus: the payout invoice is
-              # a fixed amount, so an emergency deposit is returned whole or not
-              # at all.
-              result = { "state" => "refund_required" }
+            if row["refund_reason_from_emergency"]
+              refund_reason = refund_reason_from_emergency_statuses(read_string_array(emergency["status"]))
               result["refund_reason"] = refund_reason unless refund_reason.nil?
-              return result
             end
-            return { "state" => "failed" } if normalized.include?("FAIL")
-
-            # An unrecognized status is NOT a provider-reported emergency:
-            # label it as unknown so operators land on the right runbook section.
-            {
-              "state" => "attention", "attention" => true,
-              "attention_reason" => "provider_status_unrecognized"
-            }
+            result
           end
 
-          # LIMIT rides along with LESS/MORE when the deposit fell outside the
-          # pair's limits. It says nothing the payer can act on beyond the
-          # amount itself, so it names no reason of its own.
           def refund_reason_from_emergency_statuses(statuses)
-            less = statuses.include?("LESS")
-            more = (statuses & %w[MORE OVER OVERPAID]).any?
-            expired = statuses.include?("EXPIRED")
-            return "underpaid_and_late" if less && expired
-            return "overpaid_and_late" if more && expired
-            return "underpaid" if less
-            return "overpaid" if more
-            return "late_deposit" if expired
-
-            nil
+            aliases = OpenReceive::Generated::SWAP_EMERGENCY_STATUS_ALIASES
+            present = statuses.map { |item| aliases.fetch(item.upcase, item.upcase) }
+            row = OpenReceive::Generated::SWAP_REFUND_REASON_ROWS.find do |candidate|
+              (candidate["all_of"] - present).empty?
+            end
+            row && row["refund_reason"]
           end
 
           def refund_path_state?(state)

data/lib/openreceive/server/version.rb

@@ -2,6 +2,6 @@
 
 module OpenReceive
   module Server
-    VERSION = "0.4.2"
+    VERSION = "0.4.4"
   end
 end

data/lib/openreceive/server/wallet_info.rb

@@ -10,8 +10,10 @@ module OpenReceive
     # encryption-mode choice, spend-capability detection, and receive
     # readiness must be identical in both engines.
     module WalletInfo
-      REQUIRED_RECEIVE_METHODS = %w[make_invoice list_transactions].freeze
-      SPEND_METHODS = %w[pay_invoice multi_pay_invoice pay_keysend multi_pay_keysend].freeze
+      # Kernel vocabulary (spec/data/kernel-tables.json), shared with the JS
+      # engine and the BTCPay plugin.
+      REQUIRED_RECEIVE_METHODS = OpenReceive::Generated::NWC_REQUIRED_RECEIVE_METHODS
+      SPEND_METHODS = OpenReceive::Generated::NWC_SPEND_METHODS
 
       module_function
 

data/skills/integrate-openreceive/SKILL.md

@@ -5,7 +5,8 @@ description: >
   Use when adding Bitcoin, Lightning, or crypto checkout to a Node.js, Express,
   Fastify, Next.js, Rails, React, Vue, Svelte, Angular, or plain-HTML
   application with OpenReceive (the @openreceive/* npm packages or the
-  openreceive-rails gem).
+  openreceive-rails gem), or when connecting a BTCPay Server store to a
+  receive-only NWC wallet with the OpenReceive plugin.
 license: MIT
 ---
 
@@ -23,15 +24,24 @@ code** (`NWC_URI`).
 1. Identify the server stack of the application you are in.
 2. Open the matching reference — it is complete (quickstart inlined) and needs
    no network access:
-   - Node (Express / Fastify / Next.js): [references/node.md](references/node.md)
+   - Node, Express: [references/node.md](references/node.md)
+   - Node, Fastify: [references/fastify.md](references/fastify.md)
+   - Node, Next.js App Router: [references/next.md](references/next.md)
    - Rails: [references/rails.md](references/rails.md)
+   - Django: [references/django.md](references/django.md)
+   - Laravel: [references/laravel.md](references/laravel.md)
+   - 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.
 
-Install (Node): `npm install @openreceive/express @openreceive/react` — swap
-the adapter (`fastify`, `next`) and UI package (`vue`, `svelte`, `angular`,
-`elements`) for the stack. Install (Rails): `bundle add openreceive-rails`.
+Install, per adapter — Express: `npm install @openreceive/express @openreceive/react`;
+Fastify: `npm install @openreceive/fastify @openreceive/react`; Next.js:
+`npm install @openreceive/next @openreceive/react`. Swap the UI package (`vue`,
+`svelte`, `angular`, `elements`) for the frontend the app already has. Install
+(Rails): `bundle add openreceive-rails`.
 
 ## The three server objects
 

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

@@ -0,0 +1,193 @@
+# OpenReceive agent directions (BTCPay Server)
+
+These directions describe OpenReceive 0.4.4.
+
+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
+SOL. You do not need a copy of the OpenReceive source, and there is no
+application code to write: the plugin is configured through BTCPay's store UI
+or its Greenfield API, and the quickstart is appended to this file in full.
+
+This is the BTCPay plugin, not the Node or Rails library. Do not install
+`@openreceive/*` packages or the `openreceive-rails` gem into a BTCPay
+deployment, do not add `openreceive_payments` tables, and do not mount
+OpenReceive HTTP routes. BTCPay's invoices, checkout, webhooks and Greenfield
+API are the host; the plugin only supplies the Lightning backend and the swap
+rail.
+
+## What the plugin is
+
+A BTCPay Server plugin (`BTCPayServer.Plugins.OpenReceive`) that registers a
+Lightning connection-string handler for `type=openreceive;nwc=<NWC URI>`.
+Saving that string makes the NWC wallet the store's Lightning node: BTCPay
+mints every Lightning invoice in that wallet and its own `LightningListener`
+records the payments. The plugin never calls a NIP-47 `pay_*` method, so
+every send-side BTCPay feature (Lightning payouts, pull-payment refunds over
+Lightning, the send tab) is unavailable by design.
+
+The one required credential is a receive-only NWC code. A Lightning Swap
+Connect (LSC) code optionally adds server-side swaps: a provider order aimed at
+the invoice's existing BOLT11, tracked in the plugin's own table, with the
+refund path on the same checkout screen.
+
+## Step 0 — check the deployment before you change anything
+
+1. Confirm the BTCPay Server version is 2.4.2 or later (Server Settings →
+   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.
+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
+   swaps only if the user wants them.
+4. If no receive-only NWC code is available, stop and tell the user exactly
+   what to create:
+
+   > OpenReceive cannot mint an invoice without a receive-only NWC code. Get
+   > one at https://openreceive.org/get_a_nwc_code_to_receive_payments and
+   > paste it into Store → OpenReceive → Test connection, or hand it to me and
+   > I will set it through the Greenfield API.
+
+   Never print, log or echo the code; report only whether it is set. Never
+   paste a bare `nostr+walletconnect://` string into BTCPay's Lightning node
+   screen — that form is claimed by the Nostr plugin, without the receive-only
+   guard.
+5. If the user wants altcoin payments, ask for an LSC code from
+   https://openreceive.org/set_up_swap_provider. Do not wait for it: the
+   wallet works without it, and swaps switch on later with one settings change.
+
+Only then start the quickstart.
+
+## Non-negotiables
+
+- The connection string is `type=openreceive;nwc=<NWC URI>[;allow-spend=true]`
+  and nothing else. Set it through the setup page or
+  `PUT /api/v1/stores/{storeId}/openreceive/settings` with `nwcUri`, never by
+  editing BTCPay's Lightning node screen by hand.
+- Receive-only is required. A code that advertises `pay_invoice` or another
+  spend method is refused on save. The override (`allowSpendCapableWallet`,
+  the checkbox on the setup page) is the user's explicit choice; never tick it
+  to make a save succeed.
+- The wallet's network must match BTCPay's. A mismatch is a refusal, not a
+  warning.
+- The wallet must grant `make_invoice` and `list_transactions`.
+  `lookup_invoice` is optional; do not ask the user for a code that grants it.
+- Swaps require the store's Lightning node to be the OpenReceive connection.
+  Enabling swaps on a store using the internal node is refused
+  (`wallet_required`).
+- Swaps set the store's invoice expiration to 60 minutes when it is shorter,
+  and the plugin refuses to create a swap on an invoice with less than the
+  provider's window left. Do not lower the expiration below 45 minutes on a
+  swap-enabled store.
+- Top-up (amountless) invoices are unsupported on this backend. Do not
+  configure a point of sale or payment link that relies on them with this
+  wallet.
+- Secrets stay server-side. The NWC code and LSC code live in BTCPay's
+  database like every other BTCPay credential; never copy them into
+  screenshots, tickets, browser code or logs. The provider's order token never
+  leaves the server.
+- BTCPay's `LightningListener` is the settlement authority. Provider
+  `completed` is not payment; only the wallet reporting the Lightning invoice
+  settled is. Do not build anything that fulfils on a provider state.
+- There is no merchant-initiated refund of a settled Lightning payment. A swap
+  refund is a payer reclaiming a deposit that never converted, and only from
+  the `refund_required` provider state.
+
+## Verifying
+
+Store → OpenReceive → **Run a health check** (the doctor page) runs every probe now: connection, preflight,
+notifications, last scan, provider reachability, invoice expiration, swaps
+needing attention. On a regtest machine, `packages/dotnet/docker/up.sh` then
+`e2e.sh` in the OpenReceive repository proves the whole path end to end, and
+that is the only situation where cloning the repository is the right move.
+
+## More documentation
+
+Fetch one when the moment comes. Each is raw markdown, so a plain GET is
+enough; drop the `.md` for the same page a person would read.
+
+- https://openreceive.org/guides/btcpay-reference.md — every setting, route, swap state, doctor probe and log event of the plugin
+- https://openreceive.org/guides/security.md — why receive-only is the only wallet credential
+- https://openreceive.org/guides/lightning-swap-connect.md — what an LSC code actually is
+- https://openreceive.org/guides/automated-swaps.md — provider states, and what turning swaps on commits a merchant to
+- https://openreceive.org/guides/swap-refunds.md — the refund states; the route back is BTCPay's own invoice checkout page here
+- https://openreceive.org/guides.md — the index, if what you need is not above
+
+Questions, or a problem with the plugin itself:
+https://openreceive.org/contact
+
+---
+
+## The quickstart, in full
+
+Inlined verbatim so this file needs no network access — follow it once Step 0
+passes. The page it comes from is https://openreceive.org/guides/quickstart-btcpay.
+
+## BTCPay Server quickstart
+
+Requires BTCPay Server ≥ 2.4.2.
+
+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
+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.
+
+### 1. Prerequisites
+
+- A BTCPay Server, version 2.4.2 or later, on any network (mainnet, testnet,
+  signet, regtest). The wallet must be on the same network.
+- A receive-only NWC code for the wallet you want to receive into
+  ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
+  The code must grant `make_invoice` and `list_transactions` and must not
+  advertise any spend method. `lookup_invoice` is optional.
+- Optionally, a Lightning Swap Connect (LSC) code from a
+  [swap provider](https://openreceive.org/set_up_swap_provider), if payers
+  should be able to pay with USDT, USDC, ETH or SOL.
+
+### 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.
+
+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.
+
+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.
+
+### 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.
+
+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.