diff --git a/README.md b/README.md index d595888..f423590 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,10 @@ A modular Vue 3 + TypeScript application with Nostr protocol integration and Lig The application provides seamless Lightning Network wallet integration: +- **Lightning Invoice Creation**: Create BOLT11 invoices for receiving payments with QR codes +- **Smart Payment Scanning**: QR code scanner for Lightning invoices, LNURL, and Lightning addresses +- **Universal Payment Support**: Send to Lightning invoices, Lightning addresses (user@domain.com), and LNURL +- **Smart Amount Fields**: Amount input only appears when needed (LNURL, Lightning addresses, or zero-amount invoices) - **Instant Balance Updates**: WebSocket connection provides real-time balance updates when payments are sent or received - **Live Notifications**: Toast notifications for incoming payments - **Connection Management**: Automatic reconnection with exponential backoff diff --git a/docs/02-modules/wallet-module/index.md b/docs/02-modules/wallet-module/index.md index 84de301..5b700bf 100644 --- a/docs/02-modules/wallet-module/index.md +++ b/docs/02-modules/wallet-module/index.md @@ -19,10 +19,12 @@ The Wallet Module provides comprehensive Lightning Network wallet functionality for the Ario application. It integrates with LNbits to handle payments, manage wallet balances, and provide real-time updates through WebSocket connections. ### **Key Capabilities** +- **Lightning invoice creation** (BOLT11) for receiving payments with QR codes +- **QR code scanning** for Lightning invoices, LNURL, and Lightning addresses +- **Smart payment processing** with automatic payment type detection +- **Universal payment support** for Lightning invoices, Lightning addresses, and LNURL - **Real-time balance updates** via WebSocket connection to LNbits -- **Payment processing** for Lightning invoices, Lightning addresses, and LNURL - **Transaction management** with comprehensive history and status tracking -- **Pay link creation** for receiving payments with LNURL and Lightning addresses - **Multi-wallet support** with automatic wallet selection - **Battery optimization** through VisibilityService integration @@ -43,11 +45,14 @@ Automatic wallet balance synchronization without page refreshes: - **Connection Management** - Automatic reconnection with exponential backoff ### **💸 Payment Processing** -Comprehensive Lightning payment handling: +Comprehensive Lightning payment handling with smart detection: -- **Lightning Invoices** - Pay BOLT11 invoices directly +- **Lightning Invoices** - Pay BOLT11 invoices directly with amount detection - **Lightning Addresses** - Send to Lightning addresses (user@domain.com) - **LNURL Pay** - Support for LNURL payment requests +- **QR Code Scanning** - Camera-based scanning for all payment types +- **Smart Amount Fields** - Amount input only appears when needed (LNURL, Lightning addresses, zero-amount invoices) +- **Lightning URI Support** - Handles "lightning:" prefixes and BIP-21 URIs - **Payment Validation** - Pre-flight checks for sufficient balance - **Error Handling** - User-friendly error messages and recovery @@ -60,14 +65,16 @@ Complete transaction history and tracking: - **Transaction Types** - Sent, received, pending, confirmed, failed - **Search and Filter** - Find specific transactions quickly -### **🔗 Payment Links (LNURL)** -Create reusable payment endpoints: +### **⚡ Lightning Invoice Creation** +Create BOLT11 invoices for receiving payments: -- **LNURL Generation** - Create payment links for receiving -- **Lightning Addresses** - Generate username@domain addresses -- **Amount Ranges** - Set minimum and maximum payment amounts -- **Comments Support** - Allow payment comments -- **Link Management** - Create, view, and delete payment links +- **BOLT11 Invoice Generation** - Create Lightning invoices with specified amounts +- **QR Code Generation** - Automatic QR code creation for easy sharing +- **Expiry Management** - Configurable invoice expiration times +- **Description Support** - Add payment descriptions and memos +- **Real-time Status** - Live payment status updates (pending, paid, expired) +- **Mobile Optimization** - Responsive design for mobile devices +- **Copy Functionality** - Easy copying of invoice strings and payment hashes ## Architecture @@ -82,13 +89,25 @@ src/modules/wallet/services/ ### **Component Layer** ``` src/modules/wallet/components/ -├── SendDialog.vue # Payment sending interface -├── ReceiveDialog.vue # Payment receiving interface +├── SendDialog.vue # Payment sending interface with QR scanning +├── ReceiveDialog.vue # Lightning invoice creation interface ├── TransactionList.vue # Transaction history display -├── PayLinkManager.vue # LNURL payment link management └── BalanceDisplay.vue # Wallet balance component ``` +### **UI Components** +``` +src/components/ui/ +├── qr-scanner.vue # Camera-based QR code scanner +└── ... # Other Shadcn/UI components +``` + +### **Composables** +``` +src/composables/ +└── useQRScanner.ts # QR scanner functionality with camera access +``` + ### **Views Layer** ``` src/modules/wallet/views/ @@ -150,27 +169,25 @@ if (payment.amount < 0) { **Token:** `SERVICE_TOKENS.WALLET_SERVICE` **Key Features:** -- Send Lightning payments (invoices, addresses, LNURL) -- Create and manage LNURL payment links -- Transaction history management -- Payment link generation with Lightning addresses +- Send Lightning payments (invoices, addresses, LNURL) with smart type detection +- Create Lightning invoices (BOLT11) for receiving payments +- Transaction history management with real-time updates +- QR code generation for payment sharing **Reactive State:** ```typescript interface WalletService { transactions: ComputedRef // Transaction history - payLinks: ComputedRef // Created payment links - isCreatingPayLink: ComputedRef // Pay link creation state + isCreatingInvoice: ComputedRef // Invoice creation state isSendingPayment: ComputedRef // Payment sending state error: ComputedRef // Error state } ``` **Key Methods:** -- `sendPayment(request: SendPaymentRequest)` - Send Lightning payment -- `createReceiveAddress(params)` - Create LNURL payment link -- `deletePayLink(linkId: string)` - Remove payment link -- `refresh()` - Reload transactions and payment links +- `sendPayment(request: SendPaymentRequest)` - Send Lightning payment with type detection +- `createInvoice(params: CreateInvoiceRequest)` - Create BOLT11 Lightning invoice +- `refresh()` - Reload transactions and balance data ### **WalletWebSocketService** ⚡ **Purpose:** Real-time wallet balance updates via WebSocket @@ -217,36 +234,37 @@ The wallet module integrates with the core PaymentService: ## Components ### **SendDialog.vue** 📤 -Payment sending interface with comprehensive validation: +Payment sending interface with smart payment detection and QR scanning: **Features:** -- Support for Lightning invoices, addresses, and LNURL -- Amount validation against available balance +- QR code scanner for Lightning invoices, LNURL, and Lightning addresses +- Automatic payment type detection (BOLT11, LNURL, Lightning address) +- Smart amount field visibility (only shows when needed) +- Lightning URI prefix handling ("lightning:" prefixes, BIP-21 URIs) - Payment request parsing and validation -- Real-time fee estimation +- Amount validation against available balance - Error handling with user-friendly messages **Form Fields:** -- Destination (invoice, address, or LNURL) -- Amount (when not specified in invoice) -- Comment (for Lightning addresses) +- Destination (invoice, address, or LNURL) with QR scanner button +- Amount (conditionally visible based on payment type) +- Comment (for Lightning addresses and LNURL) ### **ReceiveDialog.vue** 📥 -Payment receiving interface for creating payment requests: +Lightning invoice creation interface for receiving payments: **Features:** -- LNURL payment link creation -- Lightning address generation -- Customizable amount ranges -- Comment support configuration -- QR code generation for sharing +- BOLT11 Lightning invoice generation +- QR code generation for easy sharing +- Real-time payment status tracking (pending, paid, expired) +- Mobile-responsive design with optimized layouts +- Copy functionality for invoice string and payment hash +- Payment success/failure indicators +- Configurable invoice expiry times **Form Fields:** -- Description -- Minimum amount -- Maximum amount -- Username (for Lightning address) -- Allow comments toggle +- Amount (required, in satoshis) +- Description/Memo (optional payment description) ### **TransactionList.vue** 📋 Comprehensive transaction history display: @@ -268,17 +286,48 @@ Wallet balance component with real-time updates: - Loading state indicators - Connection status awareness +### **QRScanner Component** 📷 +Camera-based QR code scanning for payments: + +**Features:** +- WebRTC camera access with permission handling +- Real-time QR code detection using qr-scanner library +- Support for all Lightning payment types (BOLT11, LNURL, Lightning addresses) +- Lightning URI prefix cleaning ("lightning:" removal) +- Professional camera interface with scanning overlays +- Flash/torch support for low-light conditions +- Error handling for camera access issues +- Mobile-optimized scanning experience + +**Technical Details:** +- Uses `qr-scanner` library for robust QR detection +- Handles camera permissions with user-friendly error messages +- Automatic cleanup on component unmount +- Configurable scan rate and highlighting options + ## Payment Processing ### **Payment Flow Architecture** ``` -User Action ──→ Validation ──→ Payment ──→ Confirmation ──→ UI Update - │ │ │ │ │ - │ │ │ │ └─ Real-time via WebSocket - │ │ │ └─ Transaction recorded - │ │ └─ LNbits API call - │ └─ Balance check, format validation - └─ Send/Receive dialog interaction +User Action ──→ Type Detection ──→ Validation ──→ Payment ──→ Confirmation ──→ UI Update + │ │ │ │ │ │ + │ │ │ │ │ └─ Real-time via WebSocket + │ │ │ │ └─ Transaction recorded + │ │ │ └─ LNbits API call + │ │ └─ Balance check, format validation + │ └─ BOLT11/LNURL/Lightning address detection + └─ Send/Receive dialog or QR scan +``` + +### **QR Code Scanning Flow** +``` +Camera Access ──→ QR Detection ──→ URI Cleaning ──→ Type Detection ──→ Form Population + │ │ │ │ │ + │ │ │ │ └─ Auto-fill destination field + │ │ │ └─ BOLT11/LNURL/Lightning address + │ │ └─ Remove "lightning:" prefixes + │ └─ Real-time scanning with qr-scanner + └─ Permission handling with user-friendly errors ``` ### **Payment Types Supported** @@ -311,6 +360,33 @@ await walletService.sendPayment({ }) ``` +### **Lightning Invoice Creation** +Create BOLT11 invoices for receiving payments: + +#### **Invoice Creation** +```typescript +// Create Lightning invoice +const invoice = await walletService.createInvoice({ + amount: 1000, // Amount in satoshis + memo: "Payment for services", // Optional description + expiry: 3600 // Optional expiry in seconds (default: 1 hour) +}) + +// Returns invoice object with: +// - payment_request: BOLT11 invoice string +// - payment_hash: Payment hash for tracking +// - amount: Invoice amount in sats +// - memo: Invoice description +// - expiry: Expiration time +``` + +#### **QR Code Generation** +```typescript +// QR code is automatically generated for created invoices +// Available in the UI for easy sharing +const qrCodeDataUrl = await paymentService.generateQRCode(invoice.payment_request) +``` + ### **Error Handling** Comprehensive error handling for payment failures: @@ -468,6 +544,37 @@ describe('WalletService', () => { const result = await service.sendPayment(request) expect(result).toBe(true) }) + + it('should create Lightning invoice', async () => { + const invoiceData = { + amount: 1000, + memo: 'Test payment' + } + + const invoice = await service.createInvoice(invoiceData) + expect(invoice.payment_request).toMatch(/^lnbc/) + expect(invoice.amount).toBe(1000) + }) +}) +``` + +#### **QR Scanner Tests** +```typescript +describe('QRScanner', () => { + it('should detect BOLT11 invoices', async () => { + const invoice = 'lnbc1000n1p3xh4v...' + const result = parsePaymentDestination(invoice) + + expect(result.type).toBe('bolt11') + expect(result.amount).toBe(100) + }) + + it('should clean Lightning URIs', () => { + const uri = 'lightning:lnbc1000n1p3xh4v...' + const cleaned = normalizePaymentRequest(uri) + + expect(cleaned).toBe('lnbc1000n1p3xh4v...') + }) }) ```