feat: add NWC payments processor (#323) (#539)

Author: Justxd22

.changeset/seven-lines-heal.md

@@ -0,0 +1,5 @@
+---
+"nostream": minor
+---
+
+Add NWC (NIP-47) as a payments processor for admission invoices, including configurable invoice expiry and reply timeout handling, compatibility for legacy NWC URI schemes, and docs/env updates.

.env.example

@@ -41,6 +41,7 @@ WORKER_COUNT=2 # Defaults to CPU count. Use 1 or 2 for local testing.
 # NODELESS_WEBHOOK_SECRET=
 # OPENNODE_API_KEY=
 # LNBITS_API_KEY=
+# ALBY_NWC_URL=nostr+walletconnect://<wallet-service-pubkey>?relay=<wss-relay-url>&secret=<secret>
 
 # --- READ REPLICAS (Optional) ---
 # READ_REPLICA_ENABLED=false

CONFIGURATION.md

@@ -57,6 +57,7 @@ The following environment variables can be set:
 | NOSTR_CONFIG_DIR                 | Configuration directory          | <project_root>/.nostr/ |
 | DEBUG                            | Debugging filter                 |                        |
 | ZEBEDEE_API_KEY                  | Zebedee Project API Key          |                        |
+| NWC_URL                          | NWC connection URL (`nostr+walletconnect://...`) | |
 
 ## I2P
 
@@ -222,5 +223,5 @@ The settings below are listed in alphabetical order by name. Please keep this ta
 | payments.feeSchedules.admission[].enabled   | Enables admission fee. Defaults to false. |
 | payments.feeSchedules.admission[].whitelists.event_kinds | List of event kinds to waive admission fee. Use `[min, max]` for ranges. |
 | payments.feeSchedules.admission[].whitelists.pubkeys | List of pubkeys to waive admission fee. |
-| payments.processor                          | Either `zebedee`, `lnbits`, `lnurl`. |
+| payments.processor                          | Either `zebedee`, `lnbits`, `lnurl`, `nodeless`, `opennode`, `nwc`. |
 | workers.count                               | Number of workers to spin up to handle incoming connections. Spin workers as many CPUs are available when set to zero. Defaults to zero. |

README.md

@@ -97,7 +97,7 @@ Install Docker from their [official guide](https://docs.docker.com/engine/instal
      - Set `payments.enabled` to `true`
      - Set `payments.feeSchedules.admission.enabled` to `true`
      - Set `limits.event.pubkey.minBalance` to the minimum balance in msats required to accept events (i.e. `1000000` to require a balance of `1000` sats)
-   - Choose one of the following payment processors: `zebedee`, `nodeless`, `opennode`, `lnbits`, `lnurl`
+   - Choose one of the following payment processors: `zebedee`, `nodeless`, `opennode`, `lnbits`, `lnurl`, `nwc`
 
 2. [ZEBEDEE](https://zebedee.io)
    - Complete the step "Before you begin"
@@ -172,7 +172,20 @@ Install Docker from their [official guide](https://docs.docker.com/engine/instal
       - Set `lnurl.invoiceURL` to your LNURL (e.g. `https://getalby.com/lnurlp/your-username`)
     - Restart Nostream (`nostream stop` followed by `nostream start`)
 
-7. Ensure payments are required for your public key
+7. Nostr Wallet Connect (NIP-47 / NWC)
+    - Complete the step "Before you begin"
+    - Create an app connection in your NWC-compatible wallet and copy the generated NWC URL
+    - Set `NWC_URL` environment variable on your `.env` file
+
+      ```
+      NWC_URL={NOSTR_WALLET_CONNECT_URL}
+      ```
+
+    - On your `.nostr/settings.yaml` file make the following changes:
+      - Set `payments.processor` to `nwc`
+    - Restart Nostream (`./scripts/stop` followed by `./scripts/start`)
+
+8. Ensure payments are required for your public key
    - Visit https://{YOUR-DOMAIN}/
    - You should be presented with a form requesting an admission fee to be paid
    - Fill out the form and take the necessary steps to pay the invoice

package.json

@@ -152,6 +152,7 @@
     "node": ">=24.14.1"
   },
   "dependencies": {
+    "@getalby/sdk": "^5.0.0",
     "@clack/prompts": "^1.2.0",
     "@noble/secp256k1": "1.7.1",
     "accepts": "^1.3.8",

pnpm-lock.yaml

@@ -39,6 +39,9 @@ paymentsProcessors:
   opennode:
     baseURL: api.opennode.com
     callbackBaseURL: https://nostream.your-domain.com/callbacks/opennode
+  nwc:
+    invoiceExpirySeconds: 900
+    replyTimeoutMs: 10000
 nip05:
   # NIP-05 verification of event authors as a spam reduction measure.
   # mode: 'enabled' requires NIP-05 for publishing (except kind 0),

resources/default-settings.yaml

@@ -203,9 +203,9 @@ export interface OpenNodePaymentsProcessor {
   callbackBaseURL: string
 }
 
-export interface NodelessPaymentsProcessor {
-  baseURL: string
-  storeId: string
+export interface NwcPaymentsProcessor {
+  invoiceExpirySeconds: number
+  replyTimeoutMs: number
 }
 
 export interface PaymentsProcessors {
@@ -214,6 +214,7 @@ export interface PaymentsProcessors {
   lnbits?: LNbitsPaymentsProcessor
   nodeless?: NodelessPaymentsProcessor
   opennode?: OpenNodePaymentsProcessor
+  nwc?: NwcPaymentsProcessor
 }
 
 export interface Local {

src/@types/settings.ts

@@ -2,6 +2,7 @@ import { createLNbitsPaymentProcessor } from './payments-processors/lnbits-payme
 import { createLnurlPaymentsProcessor } from './payments-processors/lnurl-payments-processor-factory'
 import { createLogger } from './logger-factory'
 import { createNodelessPaymentsProcessor } from './payments-processors/nodeless-payments-processor-factory'
+import { createNwcPaymentsProcessor } from './payments-processors/nwc-payments-processor-factory'
 import { createOpenNodePaymentsProcessor } from './payments-processors/opennode-payments-processor-factory'
 import { createSettings } from './settings-factory'
 import { createZebedeePaymentsProcessor } from './payments-processors/zebedee-payments-processor-factory'
@@ -29,6 +30,8 @@ export const createPaymentsProcessor = (): IPaymentsProcessor => {
       return createNodelessPaymentsProcessor(settings)
     case 'opennode':
       return createOpenNodePaymentsProcessor(settings)
+    case 'nwc':
+      return createNwcPaymentsProcessor(settings)
     default:
       return new NullPaymentsProcessor()
   }

src/factories/payments-processor-factory.ts

@@ -0,0 +1,53 @@
+import { createSettings } from '../settings-factory'
+import { NwcPaymentsProcessor } from '../../payments-processors/nwc-payments-processor'
+import { createLogger } from '../logger-factory'
+import { IPaymentsProcessor } from '../../@types/clients'
+import { Settings } from '../../@types/settings'
+
+const logger = createLogger('nwc-payments-processor-factory')
+
+const getNwcConfig = (settings: Settings): { nwcUrl: string; replyTimeoutMs: number } => {
+  const nwcUrl = process.env.NWC_URL
+
+  if (!nwcUrl) {
+    const error = new Error('NWC_URL must be set.')
+    logger('Unable to create NWC payments processor. %o', error)
+    throw error
+  }
+
+  if (!nwcUrl.startsWith('nostr+walletconnect://') && !nwcUrl.startsWith('nostrwalletconnect://')) {
+    const error = new Error('NWC_URL must be a valid nostr+walletconnect:// or nostrwalletconnect:// URI.')
+    logger('Unable to create NWC payments processor. %o', error)
+    throw error
+  }
+
+  try {
+    new URL(nwcUrl)
+  } catch {
+    const error = new Error('NWC_URL is not parseable as a URL.')
+    logger('Unable to create NWC payments processor. %o', error)
+    throw error
+  }
+
+  const replyTimeoutMs = settings.paymentsProcessors?.nwc?.replyTimeoutMs
+  if (typeof replyTimeoutMs !== 'number' || replyTimeoutMs <= 0) {
+    const error = new Error('Setting paymentsProcessors.nwc.replyTimeoutMs must be a positive number.')
+    logger('Unable to create NWC payments processor. %o', error)
+    throw error
+  }
+
+  const invoiceExpirySeconds = settings.paymentsProcessors?.nwc?.invoiceExpirySeconds
+  if (typeof invoiceExpirySeconds !== 'number' || !Number.isInteger(invoiceExpirySeconds) || invoiceExpirySeconds <= 0) {
+    const error = new Error('Setting paymentsProcessors.nwc.invoiceExpirySeconds must be a positive integer.')
+    logger('Unable to create NWC payments processor. %o', error)
+    throw error
+  }
+
+  return { nwcUrl, replyTimeoutMs }
+}
+
+export const createNwcPaymentsProcessor = (settings: Settings): IPaymentsProcessor => {
+  const { nwcUrl, replyTimeoutMs } = getNwcConfig(settings)
+
+  return new NwcPaymentsProcessor(nwcUrl, replyTimeoutMs, createSettings)
+}