openreceive 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcf74bd2d30e343699aec8c8cde07877a32fe35e6dd0b9bd13024c8001b3e76f
-  data.tar.gz: ce4b49f8a5e973223bfbaebde4facb23b02f9f0cb57ee467fbd8a8a9dac2576c
+  metadata.gz: 34ae80bac72c06fbd721f83d77e972048e8fe5e279f837318b223fe089f63af1
+  data.tar.gz: d51e11f2c282f1816b5d86de0db98a76039f3c21cfb0190b2cf4286941d98724
 SHA512:
-  metadata.gz: 983f8761fe5e9aa080ff7847e7987fe962d6edb07e31aae868b966c957b1d2180c9926ba70b554785c734608f4638e38d644d940ba225562d00d7e8144056484
-  data.tar.gz: 6e2863ec1643a2013d30028c0485c4e69b79bc809968bb51b457942c648b89fc6913e47d20c6ea52c53799e12298fa0d3a38e1159d0ad8f23d786bc21e353728
+  metadata.gz: 241ceb79663eb4fb7ffdcc617342784521830a1e12208ffea8286d1b8b577102a3926328757647dcfccaef7955f4e5445ee16710ec8c57574db907d0ab62f7ae
+  data.tar.gz: 72b4e5ba4aadc646d46858808432558a8f7a4aec45ad7274c8ccad6603d485271a75a22d0923d29384eee88a825771592b4191e466bef7a1460f012ebd8bb87a

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.5 - 2026-09-07
+
+Release in lockstep with the Python/PHP publishing workflow fixes and complete
+WooCommerce integration documentation. Shared HTTP golden fixtures now use
+the canonical placeholder definitions. No Ruby public API change.
+
+## 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:
+
+- `OpenReceive::Generated` (`lib/openreceive/generated/tables.rb`) is rendered
+  from `spec/data/kernel-tables.json` and now also carries the FixedFloat
+  status decision table (`spec/data/swap-state-table.json`); engine code
+  reads the rendering instead of restating the vocabularies by hand.
+- Four attention reasons no engine has emitted since 0.1.1
+  (`provider_order_creation_stale`, `provider_order_creation_failed`,
+  `provider_order_creation_needs_reconcile`,
+  `provider_order_expires_after_shadow_invoice`) leave the vocabulary;
+  `provider_completed_without_wallet_settlement` stays reserved. Wire output
+  is unchanged.
+- 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

data/lib/openreceive/core.rb

@@ -5,15 +5,19 @@ require "json"
 require "uri"
 
 require_relative "version"
+# Generated kernel vocabularies (spec/data/kernel-tables.json); required here as
+# well as from openreceive.rb because tests and nwc_ruby.rb load core directly.
+require_relative "generated/tables"
 
 module OpenReceive
   NWC_CODE_HELP_URL = "https://openreceive.org/get_a_nwc_code_to_receive_payments"
-  NWC_METADATA_MAX_BYTES = 3900
-  MIN_AMOUNT_MSATS = 1000
-  MAX_AMOUNT_MSATS = 9_007_199_254_740_991
-  # Mirrors JS OPENRECEIVE_TRANSACTION_PAGE_LIMIT: the page size every
-  # wallet-history walk requests.
-  TRANSACTION_PAGE_LIMIT = 20
+  # Kernel constants shared with the JS engine and the BTCPay plugin, generated
+  # from spec/data/kernel-tables.json into OpenReceive::Generated.
+  NWC_METADATA_MAX_BYTES = Generated::NWC_METADATA_MAX_BYTES
+  MIN_AMOUNT_MSATS = Generated::MIN_AMOUNT_MSATS
+  MAX_AMOUNT_MSATS = Generated::MAX_AMOUNT_MSATS
+  # The page size every wallet-history walk requests.
+  TRANSACTION_PAGE_LIMIT = Generated::TRANSACTION_PAGE_LIMIT
   HEX_64_PATTERN = /\A[0-9a-fA-F]{64}\z/
 
   class NwcUriParseError < StandardError
@@ -295,14 +299,10 @@ module OpenReceive
       "#{text[0..query_start]}#{redacted}#{text[query_end..]}"
     end
 
-    # Canonical OpenReceive error codes (mirrors the JS generated contract).
-    ERROR_CODES = %w[
-      NOT_IMPLEMENTED RESTRICTED UNAUTHORIZED FORBIDDEN RATE_LIMITED QUOTA_EXCEEDED
-      INTERNAL UNSUPPORTED_ENCRYPTION
-      OTHER NOT_FOUND TIMEOUT INVALID_REQUEST WALLET_UNAVAILABLE
-      INVOICE_EXPIRED UNSUPPORTED_METHOD CONFLICT
-    ].freeze
-    RETRYABLE_ERROR_CODES = %w[RATE_LIMITED QUOTA_EXCEEDED TIMEOUT WALLET_UNAVAILABLE INTERNAL].freeze
+    # Canonical OpenReceive error codes and the retryable subset, generated from
+    # spec/schemas/error.schema.json and spec/data/kernel-tables.json.
+    ERROR_CODES = Generated::ERROR_CODES
+    RETRYABLE_ERROR_CODES = Generated::RETRYABLE_ERROR_CODES
     # Wallet/library spellings that map onto canonical codes (mirrors JS
     # NWC_ERROR_CODE_ALIASES).
     ERROR_CODE_ALIASES = {

data/lib/openreceive/generated/tables.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+# GENERATED FILE — DO NOT EDIT.
+# Source: spec/data/kernel-tables.json, spec/data/swap-state-table.json,
+# spec/schemas/error.schema.json and the OpenAPI document (npm run generate:models).
+# JS twins: packages/js/core/src/generated/contracts.ts,
+#           packages/js/node/src/generated/swap-tables.ts and
+#           packages/js/node/src/generated/swap-state-table.ts
+# C# twin:  packages/dotnet/BTCPayServer.Plugins.OpenReceive/Generated/OpenReceiveTables.cs
+# Every engine reads the same vocabularies from its rendering, so none can drift.
+
+module OpenReceive
+  module Generated
+    HTTP_CONTRACT_VERSION = "0.4.1"
+
+    ERROR_CODES = [
+      "NOT_IMPLEMENTED",
+      "RESTRICTED",
+      "UNAUTHORIZED",
+      "FORBIDDEN",
+      "RATE_LIMITED",
+      "QUOTA_EXCEEDED",
+      "INTERNAL",
+      "UNSUPPORTED_ENCRYPTION",
+      "OTHER",
+      "NOT_FOUND",
+      "TIMEOUT",
+      "INVALID_REQUEST",
+      "WALLET_UNAVAILABLE",
+      "INVOICE_EXPIRED",
+      "UNSUPPORTED_METHOD",
+      "CONFLICT",
+    ].freeze
+    RETRYABLE_ERROR_CODES = [
+      "RATE_LIMITED",
+      "QUOTA_EXCEEDED",
+      "TIMEOUT",
+      "WALLET_UNAVAILABLE",
+      "INTERNAL",
+    ].freeze
+    PAYMENT_STATUSES = [
+      "pending",
+      "settled",
+      "expired",
+      "failed",
+      "not_found",
+    ].freeze
+    PAYMENT_HASH_PATTERN = "^[0-9a-f]{64}$"
+    MIN_AMOUNT_MSATS = 1000
+    MAX_AMOUNT_MSATS = 9_007_199_254_740_991
+
+    NWC_REQUIRED_RECEIVE_METHODS = [
+      "make_invoice",
+      "list_transactions",
+    ].freeze
+    NWC_SPEND_METHODS = [
+      "pay_invoice",
+      "multi_pay_invoice",
+      "pay_keysend",
+      "multi_pay_keysend",
+    ].freeze
+    # Preference order: the first mode the wallet advertises wins.
+    NWC_ENCRYPTION_MODES = [
+      "nip44_v2",
+      "nip04",
+    ].freeze
+    NWC_NOTIFICATION_TYPES = [
+      "payment_received",
+    ].freeze
+    NWC_METADATA_MAX_BYTES = 3900
+    # The page size every wallet-history walk requests.
+    TRANSACTION_PAGE_LIMIT = 20
+
+    # Seconds past an attempt's expiry during which reconciliation still scans
+    # for a settlement before closing the attempt.
+    ATTEMPT_EXPIRY_GRACE_SECONDS = 900
+
+    SWAP_PAY_IN_ASSETS = [
+      "SOL_SOL",
+      "USDT_TRON",
+      "USDT_SOL",
+      "USDC_SOL",
+      "ETH_ETH",
+      "USDT_ETH",
+      "USDC_ETH",
+    ].freeze
+    SWAP_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
+
+    # phase: coarse UI bucket; terminal: the attempt will not change again.
+    # "completed" is deliberately NOT terminal: provider completion is not
+    # wallet settlement.
+    SWAP_STATES = {
+      "creating_provider_order" => { "phase" => "preparing", "terminal" => false }.freeze,
+      "awaiting_deposit" => { "phase" => "awaiting_deposit", "terminal" => false }.freeze,
+      "confirming" => { "phase" => "processing", "terminal" => false }.freeze,
+      "exchanging" => { "phase" => "processing", "terminal" => false }.freeze,
+      "paying_invoice" => { "phase" => "processing", "terminal" => false }.freeze,
+      "completed" => { "phase" => "settling", "terminal" => false }.freeze,
+      "expired" => { "phase" => "terminal", "terminal" => true }.freeze,
+      "refund_required" => { "phase" => "refund", "terminal" => false }.freeze,
+      "refund_pending" => { "phase" => "refund", "terminal" => false }.freeze,
+      "refunded" => { "phase" => "terminal", "terminal" => true }.freeze,
+      "attention" => { "phase" => "attention", "terminal" => true }.freeze,
+      "failed" => { "phase" => "terminal", "terminal" => true }.freeze,
+    }.freeze
+    SWAP_PROVIDER_STATES = SWAP_STATES.keys.freeze
+
+    SWAP_ATTENTION_REASONS = [
+      "provider_reported_emergency",
+      "provider_status_unrecognized",
+      "provider_completed_without_wallet_settlement",
+    ].freeze
+    SWAP_REFUND_REASONS = [
+      "underpaid",
+      "overpaid",
+      "late_deposit",
+      "underpaid_and_late",
+      "overpaid_and_late",
+    ].freeze
+    SWAP_AVAILABILITY_REASONS = [
+      "provider_unconfigured",
+      "amount_too_small",
+      "amount_too_large",
+      "pair_temporarily_unavailable",
+      "region_unsupported",
+      "provider_rate_limited",
+      "provider_unreachable",
+    ].freeze
+
+    # spec/data/swap-state-table.json: the FixedFloat status → state/reason decision
+    # table. Ordered, first-match-wins; the last row is a catch-all. "status"
+    # is the upper-cased provider status or "*" (narrowed by "status_contains");
+    # "refund_tx_present" is true, false or "any"; "choice" is the upper-cased
+    # emergency choice, "absent" or "any". How to read it lives once, in the
+    # JSON's how_to_read. Pinned by spec/test-vectors/swap-state.json.
+    SWAP_STATUS_ROWS = [
+      {
+        "status" => "DONE",
+        "refund_tx_present" => true,
+        "choice" => "any",
+        "state" => "refunded",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "FINISHED",
+        "refund_tx_present" => true,
+        "choice" => "any",
+        "state" => "refunded",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "NEW",
+        "refund_tx_present" => "any",
+        "choice" => "any",
+        "state" => "awaiting_deposit",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "PENDING",
+        "refund_tx_present" => "any",
+        "choice" => "any",
+        "state" => "confirming",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "EXCHANGE",
+        "refund_tx_present" => "any",
+        "choice" => "any",
+        "state" => "exchanging",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "WITHDRAW",
+        "refund_tx_present" => "any",
+        "choice" => "any",
+        "state" => "paying_invoice",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "DONE",
+        "refund_tx_present" => "any",
+        "choice" => "any",
+        "state" => "completed",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "EXPIRED",
+        "refund_tx_present" => "any",
+        "choice" => "any",
+        "state" => "expired",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "EMERGENCY",
+        "refund_tx_present" => true,
+        "choice" => "REFUND",
+        "state" => "refunded",
+        "refund_reason_from_emergency" => true
+      }.freeze,
+      {
+        "status" => "EMERGENCY",
+        "refund_tx_present" => "any",
+        "choice" => "REFUND",
+        "state" => "refund_pending",
+        "refund_reason_from_emergency" => true
+      }.freeze,
+      {
+        "status" => "EMERGENCY",
+        "refund_tx_present" => "any",
+        "choice" => "EXCHANGE",
+        "state" => "attention",
+        "attention_reason" => "provider_reported_emergency",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "EMERGENCY",
+        "refund_tx_present" => "any",
+        "choice" => "any",
+        "state" => "refund_required",
+        "refund_reason_from_emergency" => true
+      }.freeze,
+      {
+        "status" => "*",
+        "status_contains" => "FAIL",
+        "refund_tx_present" => "any",
+        "choice" => "any",
+        "state" => "failed",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+      {
+        "status" => "*",
+        "refund_tx_present" => "any",
+        "choice" => "any",
+        "state" => "attention",
+        "attention_reason" => "provider_status_unrecognized",
+        "refund_reason_from_emergency" => false
+      }.freeze,
+    ].freeze
+    # Emergency status spellings folded onto their canonical name before matching.
+    SWAP_EMERGENCY_STATUS_ALIASES = {
+      "OVER" => "MORE",
+      "OVERPAID" => "MORE",
+    }.freeze
+    # Ordered; a row matches when every "all_of" status is present. No match,
+    # no refund_reason.
+    SWAP_REFUND_REASON_ROWS = [
+      { "all_of" => ["LESS", "EXPIRED"].freeze, "refund_reason" => "underpaid_and_late" }.freeze,
+      { "all_of" => ["MORE", "EXPIRED"].freeze, "refund_reason" => "overpaid_and_late" }.freeze,
+      { "all_of" => ["LESS"].freeze, "refund_reason" => "underpaid" }.freeze,
+      { "all_of" => ["MORE"].freeze, "refund_reason" => "overpaid" }.freeze,
+      { "all_of" => ["EXPIRED"].freeze, "refund_reason" => "late_deposit" }.freeze,
+    ].freeze
+  end
+end

data/lib/openreceive/version.rb

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

data/lib/openreceive.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "openreceive/version"
+# The kernel vocabularies every engine shares, generated from spec/ (npm run
+# generate:models). Loaded first: core and the server gem alias its constants.
+require_relative "openreceive/generated/tables"
 require_relative "openreceive/core"
 require_relative "openreceive/nwc_ruby"
 require_relative "openreceive/rates"

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,25 @@ 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)
+   - WordPress + WooCommerce: [references/woocommerce.md](references/woocommerce.md) — the packaged gateway and merchant settings.
+   - 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.5.
+
+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.