lightning-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeletor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# ⚡ lightning-agent
+
+Lightning payments for AI agents. Two functions: charge and pay.
+
+A tiny SDK that gives any AI agent the ability to send and receive Bitcoin Lightning payments using [Nostr Wallet Connect (NWC)](https://nwc.dev). No browser, no UI — just code. Connect your agent to an NWC-compatible wallet (Alby Hub, Mutiny, etc.) and start transacting in sats.
+
+## Install
+
+```bash
+npm install lightning-agent
+```
+
+## Quick Start
+
+```javascript
+const { createWallet } = require('lightning-agent');
+
+const wallet = createWallet('nostr+walletconnect://...');
+
+// Check balance
+const { balanceSats } = await wallet.getBalance();
+console.log(`Balance: ${balanceSats} sats`);
+
+// Create an invoice (get paid)
+const { invoice, paymentHash } = await wallet.createInvoice({
+  amountSats: 50,
+  description: 'Text generation query'
+});
+console.log(`Pay me: ${invoice}`);
+
+// Wait for payment
+const { paid } = await wallet.waitForPayment(paymentHash, { timeoutMs: 60000 });
+
+// Pay an invoice (spend)
+const { preimage } = await wallet.payInvoice(someInvoice);
+console.log(`Paid! Preimage: ${preimage}`);
+
+// Done
+wallet.close();
+```
+
+## API Reference
+
+### `createWallet(nwcUrl?)`
+
+Create a wallet instance. Pass an NWC URL directly or set the `NWC_URL` environment variable.
+
+```javascript
+const wallet = createWallet('nostr+walletconnect://...');
+// or
+process.env.NWC_URL = 'nostr+walletconnect://...';
+const wallet = createWallet();
+```
+
+### `wallet.getBalance(opts?)`
+
+Get the wallet balance.
+
+```javascript
+const { balanceSats, balanceMsats } = await wallet.getBalance();
+```
+
+**Options:** `{ timeoutMs: 15000 }`
+
+### `wallet.createInvoice(opts)`
+
+Create a Lightning invoice (receive payment).
+
+```javascript
+const { invoice, paymentHash, amountSats } = await wallet.createInvoice({
+  amountSats: 100,
+  description: 'API call fee',
+  expiry: 3600,        // optional, seconds
+  timeoutMs: 15000     // optional
+});
+```
+
+### `wallet.payInvoice(invoice, opts?)`
+
+Pay a Lightning invoice.
+
+```javascript
+const { preimage, paymentHash } = await wallet.payInvoice('lnbc50u1p...');
+```
+
+**Options:** `{ timeoutMs: 30000 }`
+
+### `wallet.waitForPayment(paymentHash, opts?)`
+
+Poll until an invoice is paid (or timeout).
+
+```javascript
+const { paid, preimage, settledAt } = await wallet.waitForPayment(hash, {
+  timeoutMs: 60000,      // total wait (default 60s)
+  pollIntervalMs: 2000   // poll frequency (default 2s)
+});
+```
+
+### `wallet.decodeInvoice(invoice)`
+
+Decode a bolt11 invoice offline (no wallet connection needed). Extracts amount and network.
+
+```javascript
+const { amountSats, network } = wallet.decodeInvoice('lnbc50u1p...');
+// { amountSats: 5000, network: 'mainnet', description: null, paymentHash: null }
+```
+
+### `wallet.close()`
+
+Close the relay connection. Call when done.
+
+### `decodeBolt11(invoice)`
+
+Standalone bolt11 decoder (no wallet instance needed).
+
+```javascript
+const { decodeBolt11 } = require('lightning-agent');
+const { amountSats } = decodeBolt11('lnbc210n1p...');
+// amountSats = 21
+```
+
+### `parseNwcUrl(url)`
+
+Parse an NWC URL into its components.
+
+```javascript
+const { parseNwcUrl } = require('lightning-agent');
+const { walletPubkey, relay, secret } = parseNwcUrl('nostr+walletconnect://...');
+```
+
+## CLI
+
+```bash
+# Set your NWC URL
+export NWC_URL="nostr+walletconnect://..."
+
+# Check balance
+lightning-agent balance
+
+# Create an invoice for 50 sats
+lightning-agent invoice 50 "Text generation query"
+
+# Pay an invoice
+lightning-agent pay lnbc50u1p...
+
+# Decode an invoice (offline)
+lightning-agent decode lnbc50u1p...
+
+# Wait for a payment
+lightning-agent wait <payment_hash> [timeout_ms]
+```
+
+## Getting an NWC URL
+
+You need a Nostr Wallet Connect URL from a compatible wallet:
+
+- **[Alby Hub](https://albyhub.com)** — Self-hosted Lightning node with NWC. Recommended for agents.
+- **[Mutiny Wallet](https://mutinywallet.com)** — Mobile-first with NWC support.
+- **[Coinos](https://coinos.io)** — Web wallet with NWC.
+
+The URL looks like: `nostr+walletconnect://<wallet_pubkey>?relay=wss://...&secret=<hex>`
+
+## How It Works
+
+lightning-agent uses the [NWC protocol (NIP-47)](https://github.com/nostr-protocol/nips/blob/master/47.md):
+
+1. Your agent signs NWC requests (kind 23194) with the secret from the NWC URL
+2. Requests are encrypted with NIP-04 and sent to the wallet's relay
+3. The wallet service processes the request and returns an encrypted response (kind 23195)
+4. All communication happens over Nostr relays — no direct connection to the wallet needed
+
+## Design Philosophy
+
+This is built for AI agents, not humans:
+
+- **Minimal deps** — just `nostr-tools` and `ws`
+- **No UI** — pure code, works in any Node.js environment
+- **Connection reuse** — maintains a single relay connection across requests
+- **Timeouts everywhere** — agents can't afford to hang
+- **Simple API** — `createInvoice` to charge, `payInvoice` to pay
+
+## License
+
+MIT

package/bin/lightning-agent.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createWallet, decodeBolt11 } = require('../lib');
+
+const USAGE = `
+lightning-agent — Lightning payments for AI agents
+
+Usage:
+  lightning-agent balance                        Check wallet balance
+  lightning-agent invoice <sats> [description]   Create an invoice
+  lightning-agent pay <bolt11>                   Pay an invoice
+  lightning-agent decode <bolt11>                Decode an invoice (offline)
+  lightning-agent wait <payment_hash> [timeout]  Wait for payment
+
+Environment:
+  NWC_URL   Nostr Wallet Connect URL (nostr+walletconnect://...)
+
+Examples:
+  export NWC_URL="nostr+walletconnect://..."
+  lightning-agent balance
+  lightning-agent invoice 50 "AI query fee"
+  lightning-agent pay lnbc50u1p...
+  lightning-agent decode lnbc50u1p...
+`.trim();
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  // decode is offline — no wallet needed
+  if (command === 'decode') {
+    const invoice = args[1];
+    if (!invoice) {
+      console.error('Error: bolt11 invoice required');
+      process.exit(1);
+    }
+    try {
+      const details = decodeBolt11(invoice);
+      console.log(JSON.stringify(details, null, 2));
+    } catch (err) {
+      console.error('Error:', err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // All other commands need a wallet
+  if (!process.env.NWC_URL) {
+    console.error('Error: NWC_URL environment variable not set');
+    console.error('Set it: export NWC_URL="nostr+walletconnect://..."');
+    process.exit(1);
+  }
+
+  let wallet;
+  try {
+    wallet = createWallet(process.env.NWC_URL);
+  } catch (err) {
+    console.error('Error creating wallet:', err.message);
+    process.exit(1);
+  }
+
+  try {
+    switch (command) {
+      case 'balance': {
+        const { balanceSats } = await wallet.getBalance();
+        console.log(`${balanceSats} sats`);
+        break;
+      }
+
+      case 'invoice': {
+        const sats = parseInt(args[1], 10);
+        if (!sats || sats <= 0) {
+          console.error('Error: amount in sats required (positive integer)');
+          process.exit(1);
+        }
+        const description = args.slice(2).join(' ') || undefined;
+        const result = await wallet.createInvoice({ amountSats: sats, description });
+        console.log(result.invoice);
+        if (result.paymentHash) {
+          console.error(`Payment hash: ${result.paymentHash}`);
+        }
+        break;
+      }
+
+      case 'pay': {
+        const invoice = args[1];
+        if (!invoice) {
+          console.error('Error: bolt11 invoice required');
+          process.exit(1);
+        }
+        const result = await wallet.payInvoice(invoice);
+        console.log(`Paid! Preimage: ${result.preimage}`);
+        break;
+      }
+
+      case 'wait': {
+        const paymentHash = args[1];
+        if (!paymentHash) {
+          console.error('Error: payment_hash required');
+          process.exit(1);
+        }
+        const timeoutMs = parseInt(args[2], 10) || 60000;
+        console.error(`Waiting for payment (timeout: ${timeoutMs}ms)...`);
+        const result = await wallet.waitForPayment(paymentHash, { timeoutMs });
+        if (result.paid) {
+          console.log(`Paid! Preimage: ${result.preimage}`);
+        } else {
+          console.log('Not paid (timed out)');
+          process.exit(1);
+        }
+        break;
+      }
+
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.log(USAGE);
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error('Error:', err.message);
+    process.exit(1);
+  } finally {
+    wallet.close();
+  }
+}
+
+main();

package/lib/index.js

@@ -0,0 +1,10 @@
+'use strict';
+
+const { createWallet, parseNwcUrl, decodeBolt11, NWCWallet } = require('./wallet');
+
+module.exports = {
+  createWallet,
+  parseNwcUrl,
+  decodeBolt11,
+  NWCWallet
+};

package/lib/wallet.js

@@ -0,0 +1,331 @@
+'use strict';
+
+const { finalizeEvent, getPublicKey } = require('nostr-tools');
+const { Relay } = require('nostr-tools/relay');
+const nip04 = require('nostr-tools/nip04');
+
+// ─── Bolt11 minimal decoder ───
+
+const MULTIPLIERS = {
+  m: 1e-3,   // milli-BTC
+  u: 1e-6,   // micro-BTC
+  n: 1e-9,   // nano-BTC
+  p: 1e-12   // pico-BTC
+};
+const BTC_TO_SATS = 1e8;
+
+/**
+ * Decode a bolt11 invoice's human-readable part to extract amount in sats.
+ * Format: ln<network><amount><multiplier>
+ * Examples: lnbc50u = 50 micro-BTC = 5000 sats
+ *           lnbc210n = 210 nano-BTC = 21 sats
+ *           lnbc1m = 1 milli-BTC = 100000 sats
+ */
+function decodeBolt11(invoice) {
+  if (!invoice || typeof invoice !== 'string') {
+    throw new Error('Invalid bolt11 invoice');
+  }
+
+  const lower = invoice.toLowerCase();
+
+  // Find the separator: last '1' before the data part
+  // The human-readable part is everything before the last '1' that's followed by data
+  // Bolt11 uses bech32: <hrp>1<data><checksum>
+  const lastOneIdx = lower.lastIndexOf('1');
+  if (lastOneIdx < 4) throw new Error('Invalid bolt11: no separator found');
+
+  const hrp = lower.substring(0, lastOneIdx);
+
+  // Parse HRP: ln + network prefix + amount
+  // Network prefixes: bc (mainnet), tb (testnet), bcrt (regtest), tbs (signet)
+  let rest;
+  if (hrp.startsWith('lnbc')) {
+    rest = hrp.substring(4);
+  } else if (hrp.startsWith('lntbs')) {
+    rest = hrp.substring(5);
+  } else if (hrp.startsWith('lntb')) {
+    rest = hrp.substring(4);
+  } else if (hrp.startsWith('lnbcrt')) {
+    rest = hrp.substring(6);
+  } else {
+    throw new Error('Unknown bolt11 network prefix');
+  }
+
+  let amountSats = null;
+
+  if (rest.length > 0) {
+    // Last char might be a multiplier
+    const lastChar = rest[rest.length - 1];
+    if (MULTIPLIERS[lastChar] !== undefined) {
+      const numStr = rest.substring(0, rest.length - 1);
+      const num = parseFloat(numStr);
+      if (isNaN(num)) throw new Error('Invalid bolt11 amount: ' + numStr);
+      const btcAmount = num * MULTIPLIERS[lastChar];
+      amountSats = Math.round(btcAmount * BTC_TO_SATS);
+    } else {
+      // No multiplier — amount is in BTC
+      const num = parseFloat(rest);
+      if (isNaN(num)) throw new Error('Invalid bolt11 amount: ' + rest);
+      amountSats = Math.round(num * BTC_TO_SATS);
+    }
+  }
+  // If rest is empty, it's a zero-amount invoice
+
+  // Try to extract description from tagged fields (best effort)
+  // Tagged fields are in the data part after the separator, bech32-decoded
+  // This is complex — we do minimal extraction
+  let description = null;
+  let paymentHash = null;
+
+  try {
+    const dataPart = lower.substring(lastOneIdx + 1);
+    // First 7 chars = timestamp (bech32 chars, 35 bits)
+    // Then tagged fields follow
+    // Each tag: 1 char type + 2 chars data length + data
+    // We'd need full bech32 decoding for this — skip for now
+    // Payment hash and description require full bech32 decode
+  } catch (_) { /* best effort */ }
+
+  return {
+    amountSats,
+    description,
+    paymentHash,
+    network: hrp.startsWith('lntb') ? 'testnet' :
+             hrp.startsWith('lnbcrt') ? 'regtest' :
+             hrp.startsWith('lntbs') ? 'signet' : 'mainnet'
+  };
+}
+
+// ─── NWC URL parser ───
+
+function parseNwcUrl(nwcUrl) {
+  if (!nwcUrl || typeof nwcUrl !== 'string') {
+    throw new Error('NWC URL is required');
+  }
+
+  if (!nwcUrl.startsWith('nostr+walletconnect://')) {
+    throw new Error('Invalid NWC URL: must start with nostr+walletconnect://');
+  }
+
+  const url = new URL(nwcUrl);
+  const walletPubkey = url.hostname || url.pathname.replace('//', '');
+  const relay = url.searchParams.get('relay');
+  const secret = url.searchParams.get('secret');
+
+  if (!walletPubkey || walletPubkey.length !== 64) {
+    throw new Error('Invalid NWC URL: bad wallet pubkey');
+  }
+  if (!relay) {
+    throw new Error('Invalid NWC URL: missing relay parameter');
+  }
+  if (!secret || secret.length !== 64) {
+    throw new Error('Invalid NWC URL: missing or invalid secret');
+  }
+
+  return { walletPubkey, relay, secret };
+}
+
+// ─── Wallet class ───
+
+class NWCWallet {
+  constructor(nwcUrl) {
+    const parsed = parseNwcUrl(nwcUrl);
+    this.walletPubkey = parsed.walletPubkey;
+    this.relayUrl = parsed.relay;
+    this.secret = parsed.secret;
+    this.secretBytes = Uint8Array.from(Buffer.from(parsed.secret, 'hex'));
+    this.clientPubkey = getPublicKey(this.secretBytes);
+
+    this._closed = false;
+  }
+
+  // ─── Core NWC request ───
+  // Uses a fresh relay connection per request for reliability.
+  // NWC relays (especially Alby) handle connection reuse poorly.
+
+  async _nwcRequest(method, params = {}, timeoutMs = 15000) {
+    const payload = JSON.stringify({ method, params });
+    const encrypted = await nip04.encrypt(this.secretBytes, this.walletPubkey, payload);
+
+    const event = finalizeEvent({
+      kind: 23194,
+      created_at: Math.floor(Date.now() / 1000),
+      tags: [['p', this.walletPubkey]],
+      content: encrypted
+    }, this.secretBytes);
+
+    // Fresh connection per request — more reliable than reuse
+    const relay = await Relay.connect(this.relayUrl);
+    await relay.publish(event);
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        sub.close();
+        try { relay.close(); } catch (_) {}
+        reject(new Error(`NWC request timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      const sub = relay.subscribe(
+        [{ kinds: [23195], '#e': [event.id], limit: 1 }],
+        {
+          onevent: async (e) => {
+            clearTimeout(timer);
+            try {
+              const decrypted = await nip04.decrypt(this.secretBytes, e.pubkey, e.content);
+              const parsed = JSON.parse(decrypted);
+
+              if (parsed.error) {
+                reject(new Error(`NWC error (${parsed.error.code}): ${parsed.error.message}`));
+              } else {
+                resolve(parsed);
+              }
+            } catch (err) {
+              reject(new Error('NWC decrypt failed: ' + err.message));
+            }
+            sub.close();
+            try { relay.close(); } catch (_) {}
+          }
+        }
+      );
+    });
+  }
+
+  // ─── Public API ───
+
+  /**
+   * Get wallet balance in sats.
+   */
+  async getBalance(opts = {}) {
+    const timeoutMs = opts.timeoutMs || 15000;
+    const res = await this._nwcRequest('get_balance', {}, timeoutMs);
+    // NWC returns balance in millisats
+    const balanceMsats = res.result?.balance || 0;
+    return {
+      balanceSats: Math.round(balanceMsats / 1000),
+      balanceMsats
+    };
+  }
+
+  /**
+   * Create a Lightning invoice (get paid).
+   * @param {object} opts
+   * @param {number} opts.amountSats - Amount in satoshis
+   * @param {string} [opts.description] - Invoice description
+   * @param {number} [opts.timeoutMs] - Request timeout
+   */
+  async createInvoice(opts = {}) {
+    if (!opts.amountSats || opts.amountSats <= 0) {
+      throw new Error('amountSats is required and must be positive');
+    }
+
+    const params = {
+      amount: opts.amountSats * 1000, // NWC uses millisats
+    };
+    if (opts.description) params.description = opts.description;
+    if (opts.expiry) params.expiry = opts.expiry;
+
+    const timeoutMs = opts.timeoutMs || 15000;
+    const res = await this._nwcRequest('make_invoice', params, timeoutMs);
+
+    return {
+      invoice: res.result?.invoice,
+      paymentHash: res.result?.payment_hash,
+      description: res.result?.description || opts.description || null,
+      amountSats: opts.amountSats
+    };
+  }
+
+  /**
+   * Pay a Lightning invoice.
+   * @param {string} invoice - Bolt11 invoice string
+   * @param {object} [opts]
+   * @param {number} [opts.timeoutMs] - Request timeout (default 30s for payments)
+   */
+  async payInvoice(invoice, opts = {}) {
+    if (!invoice || typeof invoice !== 'string') {
+      throw new Error('invoice is required');
+    }
+
+    const timeoutMs = opts.timeoutMs || 30000; // Longer default for payments
+    const res = await this._nwcRequest('pay_invoice', { invoice }, timeoutMs);
+
+    return {
+      preimage: res.result?.preimage,
+      paymentHash: res.result?.payment_hash || null
+    };
+  }
+
+  /**
+   * Wait for an invoice to be paid by polling lookup_invoice.
+   * @param {string} paymentHash - Payment hash to check
+   * @param {object} [opts]
+   * @param {number} [opts.timeoutMs] - Total wait timeout (default 60s)
+   * @param {number} [opts.pollIntervalMs] - Poll interval (default 2s)
+   */
+  async waitForPayment(paymentHash, opts = {}) {
+    if (!paymentHash) throw new Error('paymentHash is required');
+
+    const timeoutMs = opts.timeoutMs || 60000;
+    const pollIntervalMs = opts.pollIntervalMs || 2000;
+    const start = Date.now();
+
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const res = await this._nwcRequest('lookup_invoice', { payment_hash: paymentHash }, 10000);
+        // Check if settled
+        if (res.result?.settled_at || res.result?.preimage) {
+          return {
+            paid: true,
+            preimage: res.result.preimage || null,
+            settledAt: res.result.settled_at || null
+          };
+        }
+      } catch (err) {
+        // lookup_invoice might not be supported — continue polling
+        if (err.message.includes('NOT_IMPLEMENTED')) {
+          throw new Error('lookup_invoice not supported by this wallet');
+        }
+        // Other errors: retry
+      }
+
+      // Wait before next poll
+      await new Promise(r => setTimeout(r, pollIntervalMs));
+    }
+
+    return { paid: false, preimage: null, settledAt: null };
+  }
+
+  /**
+   * Decode a bolt11 invoice (offline, no NWC needed).
+   * @param {string} invoice - Bolt11 invoice string
+   */
+  decodeInvoice(invoice) {
+    return decodeBolt11(invoice);
+  }
+
+  /**
+   * Close the relay connection.
+   */
+  close() {
+    this._closed = true;
+  }
+}
+
+// ─── Factory function ───
+
+function createWallet(nwcUrl) {
+  const url = nwcUrl || process.env.NWC_URL;
+  if (!url) {
+    throw new Error('NWC URL required. Pass it directly or set NWC_URL env var.');
+  }
+  return new NWCWallet(url);
+}
+
+// ─── Exports ───
+
+module.exports = {
+  createWallet,
+  parseNwcUrl,
+  decodeBolt11,
+  NWCWallet
+};

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "lightning-agent",
+  "version": "0.1.0",
+  "description": "Lightning payments for AI agents. Two functions: charge and pay.",
+  "main": "lib/index.js",
+  "bin": {
+    "lightning-agent": "bin/lightning-agent.js"
+  },
+  "keywords": ["lightning", "bitcoin", "ai", "agent", "nostr", "nwc", "payments"],
+  "author": "Jeletor",
+  "license": "MIT",
+  "dependencies": {
+    "nostr-tools": "^2.0.0",
+    "ws": "^8.0.0"
+  }
+}

package/test.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const { createWallet, parseNwcUrl, decodeBolt11, NWCWallet } = require('./lib');
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, message) {
+  if (condition) {
+    passed++;
+    console.log(`  ✅ ${message}`);
+  } else {
+    failed++;
+    console.log(`  ❌ ${message}`);
+  }
+}
+
+function assertThrows(fn, message) {
+  try {
+    fn();
+    failed++;
+    console.log(`  ❌ ${message} (did not throw)`);
+  } catch (_) {
+    passed++;
+    console.log(`  ✅ ${message}`);
+  }
+}
+
+// ─── NWC URL Parsing ───
+console.log('\n📡 NWC URL Parsing');
+
+const testNwcUrl = 'nostr+walletconnect://962852f75958e8920c8dfeffd59baa8a75bc7029143a7cea82875772863b0721?relay=wss://relay.getalby.com/v1&secret=7ed367a99f9bde637f4f960f398ab310aaadb0e10ff8273ca6f97e136146272f';
+
+const parsed = parseNwcUrl(testNwcUrl);
+assert(parsed.walletPubkey === '962852f75958e8920c8dfeffd59baa8a75bc7029143a7cea82875772863b0721', 'extracts walletPubkey');
+assert(parsed.relay === 'wss://relay.getalby.com/v1', 'extracts relay URL');
+assert(parsed.secret === '7ed367a99f9bde637f4f960f398ab310aaadb0e10ff8273ca6f97e136146272f', 'extracts secret');
+
+assertThrows(() => parseNwcUrl('https://example.com'), 'rejects non-NWC URL');
+assertThrows(() => parseNwcUrl(''), 'rejects empty string');
+assertThrows(() => parseNwcUrl(null), 'rejects null');
+assertThrows(
+  () => parseNwcUrl('nostr+walletconnect://abc?relay=wss://x.com&secret=abc'),
+  'rejects bad pubkey length'
+);
+assertThrows(
+  () => parseNwcUrl('nostr+walletconnect://962852f75958e8920c8dfeffd59baa8a75bc7029143a7cea82875772863b0721?secret=7ed367a99f9bde637f4f960f398ab310aaadb0e10ff8273ca6f97e136146272f'),
+  'rejects missing relay'
+);
+
+// ─── Bolt11 Decoding ───
+console.log('\n⚡ Bolt11 Amount Decoding');
+
+// lnbc1u = 1 micro-BTC = 100 sats
+const d1 = decodeBolt11('lnbc1u1ptest');
+assert(d1.amountSats === 100, 'lnbc1u = 100 sats');
+
+// lnbc210n = 210 nano-BTC = 21 sats
+const d2 = decodeBolt11('lnbc210n1ptest');
+assert(d2.amountSats === 21, 'lnbc210n = 21 sats');
+
+// lnbc50u = 50 micro-BTC = 5000 sats
+const d3 = decodeBolt11('lnbc50u1ptest');
+assert(d3.amountSats === 5000, 'lnbc50u = 5000 sats');
+
+// lnbc1m = 1 milli-BTC = 100000 sats
+const d4 = decodeBolt11('lnbc1m1ptest');
+assert(d4.amountSats === 100000, 'lnbc1m = 100000 sats');
+
+// lnbc100n = 100 nano-BTC = 10 sats
+const d5 = decodeBolt11('lnbc100n1ptest');
+assert(d5.amountSats === 10, 'lnbc100n = 10 sats');
+
+// lnbc2500u = 2500 micro-BTC = 250000 sats
+const d6 = decodeBolt11('lnbc2500u1ptest');
+assert(d6.amountSats === 250000, 'lnbc2500u = 250000 sats');
+
+// lnbc10m = 10 milli-BTC = 1000000 sats
+const d7 = decodeBolt11('lnbc10m1ptest');
+assert(d7.amountSats === 1000000, 'lnbc10m = 1000000 sats');
+
+// lnbc1500p = 1500 pico-BTC = 0.15 sats ≈ 0 sats (rounds)
+const d8 = decodeBolt11('lnbc1500p1ptest');
+assert(d8.amountSats === 0, 'lnbc1500p = 0 sats (sub-sat)');
+
+// lnbc20n = 20 nano-BTC = 2 sats
+const d9 = decodeBolt11('lnbc20n1ptest');
+assert(d9.amountSats === 2, 'lnbc20n = 2 sats');
+
+// Network detection
+console.log('\n🌐 Network Detection');
+assert(decodeBolt11('lnbc50u1ptest').network === 'mainnet', 'lnbc = mainnet');
+assert(decodeBolt11('lntb50u1ptest').network === 'testnet', 'lntb = testnet');
+
+// No amount (zero-amount invoice)
+const d10 = decodeBolt11('lnbc1ptesttesttest');
+assert(d10.amountSats === null, 'lnbc with no amount = null');
+
+// Error cases
+console.log('\n🚫 Bolt11 Error Cases');
+assertThrows(() => decodeBolt11(''), 'rejects empty string');
+assertThrows(() => decodeBolt11(null), 'rejects null');
+assertThrows(() => decodeBolt11('notaninvoice'), 'rejects garbage');
+
+// ─── createWallet interface ───
+console.log('\n🔧 createWallet Interface');
+
+const wallet = new NWCWallet(testNwcUrl);
+assert(typeof wallet.getBalance === 'function', 'has getBalance()');
+assert(typeof wallet.createInvoice === 'function', 'has createInvoice()');
+assert(typeof wallet.payInvoice === 'function', 'has payInvoice()');
+assert(typeof wallet.waitForPayment === 'function', 'has waitForPayment()');
+assert(typeof wallet.decodeInvoice === 'function', 'has decodeInvoice()');
+assert(typeof wallet.close === 'function', 'has close()');
+
+// Test decodeInvoice works via wallet instance
+const decoded = wallet.decodeInvoice('lnbc50u1ptest');
+assert(decoded.amountSats === 5000, 'wallet.decodeInvoice works');
+wallet.close();
+
+// createWallet from env
+console.log('\n🌍 createWallet from env');
+process.env.NWC_URL = testNwcUrl;
+const walletFromEnv = createWallet();
+assert(walletFromEnv instanceof NWCWallet, 'createWallet() reads NWC_URL env');
+walletFromEnv.close();
+delete process.env.NWC_URL;
+
+assertThrows(() => createWallet(), 'createWallet() throws without URL or env');
+
+// ─── Summary ───
+console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+console.log(`Results: ${passed} passed, ${failed} failed`);
+if (failed > 0) {
+  process.exit(1);
+} else {
+  console.log('All tests passed! ✅');
+}