Add Wallet Module documentation and WebSocket integration

- Introduced comprehensive documentation for the new Wallet Module, detailing its purpose, features, and key components. - Added WebSocket integration documentation, outlining real-time balance updates, connection management, and error handling. - Updated README and module index files to include references to the Wallet Module, enhancing overall module visibility and accessibility. These changes improve the clarity and usability of the Wallet Module, providing developers with essential information for implementation and integration.
2025-09-18 09:56:19 +02:00 · 2025-09-18 09:56:19 +02:00 · 71cec00bfc
commit 71cec00bfc
parent 832bf4d4ca
6 changed files with 1748 additions and 1 deletions
--- a/docs/02-modules/wallet-module/index.md
+++ b/docs/02-modules/wallet-module/index.md
@ -0,0 +1,512 @@
+# 💰 Wallet Module
+
+> **Lightning Network wallet management** with real-time balance updates, payment processing, and comprehensive transaction management integrated with LNbits.
+
+## Table of Contents
+
+- [[#Overview]]
+- [[#Core Features]]
+- [[#Architecture]]
+- [[#Real-Time WebSocket Integration]]
+- [[#Services]]
+- [[#Components]]
+- [[#Payment Processing]]
+- [[#Configuration]]
+- [[#Development Guide]]
+
+## Overview
+
+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**
+- **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
+
+### **Dependencies**
+- `['base']` - Requires base module for authentication and core services
+- **LNbits Server** - External Lightning wallet backend
+- **PaymentService** - Core payment processing service
+
+## Core Features
+
+### **🔄 Real-Time Balance Updates**
+Automatic wallet balance synchronization without page refreshes:
+
+- **WebSocket Connection** - Direct connection to LNbits WebSocket API
+- **Instant Updates** - Balance changes reflect immediately in UI
+- **Smart Unit Conversion** - Handles LNbits sats/millisats conversion differences
+- **Payment Notifications** - Toast notifications for incoming payments
+- **Connection Management** - Automatic reconnection with exponential backoff
+
+### **💸 Payment Processing**
+Comprehensive Lightning payment handling:
+
+- **Lightning Invoices** - Pay BOLT11 invoices directly
+- **Lightning Addresses** - Send to Lightning addresses (user@domain.com)
+- **LNURL Pay** - Support for LNURL payment requests
+- **Payment Validation** - Pre-flight checks for sufficient balance
+- **Error Handling** - User-friendly error messages and recovery
+
+### **📊 Transaction Management**
+Complete transaction history and tracking:
+
+- **Transaction History** - Chronological list of all payments
+- **Real-time Updates** - New transactions appear instantly
+- **Transaction Details** - Amount, description, timestamp, fees, status
+- **Transaction Types** - Sent, received, pending, confirmed, failed
+- **Search and Filter** - Find specific transactions quickly
+
+### **🔗 Payment Links (LNURL)**
+Create reusable payment endpoints:
+
+- **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
+
+## Architecture
+
+### **Service Layer**
+```
+src/modules/wallet/services/
+├── WalletService.ts                # Core wallet operations
+├── WalletWebSocketService.ts      # Real-time balance updates
+└── WalletAPI.ts                   # LNbits API integration
+```
+
+### **Component Layer**
+```
+src/modules/wallet/components/
+├── SendDialog.vue                 # Payment sending interface
+├── ReceiveDialog.vue              # Payment receiving interface
+├── TransactionList.vue           # Transaction history display
+├── PayLinkManager.vue            # LNURL payment link management
+└── BalanceDisplay.vue            # Wallet balance component
+```
+
+### **Views Layer**
+```
+src/modules/wallet/views/
+└── WalletPage.vue                # Main wallet interface
+```
+
+## Real-Time WebSocket Integration
+
+### **Connection Architecture**
+The WebSocket service provides seamless real-time updates:
+
+```typescript
+// WebSocket URL format
+wss://your-lnbits-server/api/v1/ws/{walletInkey}
+
+// Connection lifecycle
+┌─ Authentication Event ──→ Connect WebSocket
+├─ Payment Received ─────→ Update Balance + Show Toast
+├─ Payment Sent ─────────→ Update Balance
+├─ Connection Lost ──────→ Automatic Reconnection
+└─ App Hidden ───────────→ Pause (Battery Optimization)
+```
+
+### **Balance Update Logic**
+Handles LNbits WebSocket behavior differences:
+
+```typescript
+// Incoming payments: LNbits sends post-payment balance
+if (payment.amount > 0) {
+  // Use balance as-is (already includes received amount)
+  updateBalance(websocket_balance)
+}
+
+// Outgoing payments: LNbits sends pre-payment balance
+if (payment.amount < 0) {
+  // Subtract payment amount from reported balance
+  final_balance = websocket_balance - payment_amount_sats
+  updateBalance(final_balance)
+}
+```
+
+### **Connection Management**
+- **Auto-reconnection** with exponential backoff (1s, 2s, 4s, 8s, 16s)
+- **VisibilityService integration** for battery optimization
+- **Connection health monitoring** with status indicators
+- **Graceful disconnection** on logout
+
+### **Error Handling**
+- Connection failures with retry logic
+- Invalid wallet credentials handling
+- Network interruption recovery
+- WebSocket protocol error handling
+
+## Services
+
+### **WalletService** 🏦
+**Purpose:** Core wallet operations and transaction management
+**Location:** `src/modules/wallet/services/WalletService.ts`
+**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
+
+**Reactive State:**
+```typescript
+interface WalletService {
+  transactions: ComputedRef<PaymentTransaction[]>    // Transaction history
+  payLinks: ComputedRef<PayLink[]>                  // Created payment links
+  isCreatingPayLink: ComputedRef<boolean>           // Pay link creation state
+  isSendingPayment: ComputedRef<boolean>            // Payment sending state
+  error: ComputedRef<string | null>                 // 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
+
+### **WalletWebSocketService** ⚡
+**Purpose:** Real-time wallet balance updates via WebSocket
+**Location:** `src/modules/wallet/services/WalletWebSocketService.ts`
+**Token:** `SERVICE_TOKENS.WALLET_WEBSOCKET_SERVICE`
+
+**Key Features:**
+- WebSocket connection to LNbits
+- Real-time balance updates
+- Payment notification handling
+- Connection health management
+- Battery optimization via VisibilityService
+
+**Reactive State:**
+```typescript
+interface WalletWebSocketService {
+  isConnected: Ref<boolean>                         // Connection status
+  connectionStatus: Ref<string>                     // Connection state
+}
+```
+
+**Connection States:**
+- `disconnected` - Not connected
+- `connecting` - Connection in progress
+- `connected` - Successfully connected
+- `reconnecting` - Attempting to reconnect
+- `error` - Connection failed
+- `failed` - Max reconnection attempts reached
+
+**Key Methods:**
+- `reconnect()` - Manual reconnection trigger
+- `disconnect()` - Graceful disconnection
+- `cleanup()` - Service disposal
+
+### **PaymentService Integration** 💳
+The wallet module integrates with the core PaymentService:
+
+**Shared Functionality:**
+- Wallet balance management via `PaymentService.updateWalletBalance()`
+- Preferred wallet selection with `PaymentService.getPreferredWallet()`
+- Admin/invoice key access for API operations
+- Multi-wallet support with consistent selection logic
+
+## Components
+
+### **SendDialog.vue** 📤
+Payment sending interface with comprehensive validation:
+
+**Features:**
+- Support for Lightning invoices, addresses, and LNURL
+- Amount validation against available balance
+- Payment request parsing and validation
+- Real-time fee estimation
+- Error handling with user-friendly messages
+
+**Form Fields:**
+- Destination (invoice, address, or LNURL)
+- Amount (when not specified in invoice)
+- Comment (for Lightning addresses)
+
+### **ReceiveDialog.vue** 📥
+Payment receiving interface for creating payment requests:
+
+**Features:**
+- LNURL payment link creation
+- Lightning address generation
+- Customizable amount ranges
+- Comment support configuration
+- QR code generation for sharing
+
+**Form Fields:**
+- Description
+- Minimum amount
+- Maximum amount
+- Username (for Lightning address)
+- Allow comments toggle
+
+### **TransactionList.vue** 📋
+Comprehensive transaction history display:
+
+**Features:**
+- Chronological transaction listing
+- Real-time transaction updates
+- Transaction status indicators
+- Amount formatting with proper units
+- Transaction type differentiation (sent/received)
+- Fee information display
+
+### **BalanceDisplay.vue** 💰
+Wallet balance component with real-time updates:
+
+**Features:**
+- Real-time balance updates via WebSocket
+- Multiple unit display (sats, millisats)
+- Loading state indicators
+- Connection status awareness
+
+## 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
+```
+
+### **Payment Types Supported**
+
+#### **Lightning Invoices (BOLT11)**
+```typescript
+// Direct invoice payment
+await walletService.sendPayment({
+  destination: "lnbc1000n1p3xh4v...",
+  amount: 1000 // Optional if invoice has amount
+})
+```
+
+#### **Lightning Addresses**
+```typescript
+// Lightning address payment
+await walletService.sendPayment({
+  destination: "user@stacker.news",
+  amount: 1000,
+  comment: "Great post!"
+})
+```
+
+#### **LNURL Pay**
+```typescript
+// LNURL payment
+await walletService.sendPayment({
+  destination: "LNURL1DP68GURN8GHJ7UM9WFMXJCM99E3K7MF0V9CXJ0M385EKVCENXC6R2C35XVUKXEFCV5MKVV34X5EKZD3EV56NYD3HXQURZEPEXEJXXEPNXSCRVWFNV9NXZCN9XQ6XYEFHVGCXXCMYXYMNSERXFQ5FNS",
+  amount: 1000
+})
+```
+
+### **Error Handling**
+Comprehensive error handling for payment failures:
+
+- **Insufficient balance** - Clear messaging with current balance
+- **Invalid payment request** - Format validation errors
+- **Network failures** - Retry options and offline handling
+- **Payment routing failures** - Lightning network routing errors
+- **Timeout handling** - Payment timeout with status updates
+
+## Configuration
+
+### **Module Configuration**
+Configure the wallet module in `src/app.config.ts`:
+
+```typescript
+modules: {
+  wallet: {
+    enabled: true,
+    config: {
+      // WebSocket configuration
+      websocket: {
+        enabled: true,           // Enable real-time updates
+        reconnectDelay: 1000,    // Initial reconnection delay (ms)
+        maxReconnectAttempts: 5  // Maximum reconnection attempts
+      },
+
+      // Payment configuration
+      payments: {
+        defaultUnit: 'sats',     // Default amount unit
+        showFees: true,          // Display fee information
+        confirmLarge: 10000      // Confirm payments above this amount
+      },
+
+      // UI configuration
+      ui: {
+        showBalance: true,       // Display balance in UI
+        showTransactions: true,  // Show transaction history
+        transactionLimit: 100    // Max transactions to display
+      }
+    }
+  }
+}
+```
+
+### **Environment Variables**
+Required environment setup:
+
+```bash
+# LNbits server URL
+VITE_LNBITS_BASE_URL=https://your-lnbits-server.com
+
+# Optional: Default wallet configuration
+VITE_DEFAULT_CURRENCY=sats
+VITE_PAYMENT_TIMEOUT=30000
+```
+
+## Development Guide
+
+### **Adding New Payment Types**
+To add support for new payment methods:
+
+1. **Extend SendPaymentRequest interface:**
+```typescript
+interface SendPaymentRequest {
+  destination: string
+  amount: number
+  comment?: string
+  newPaymentType?: NewPaymentParams  // Add new type
+}
+```
+
+2. **Update WalletService.sendPayment():**
+```typescript
+async sendPayment(request: SendPaymentRequest): Promise<boolean> {
+  // Add detection logic
+  if (this.isNewPaymentType(request.destination)) {
+    return this.handleNewPaymentType(request)
+  }
+  // ... existing logic
+}
+```
+
+3. **Add validation and processing:**
+```typescript
+private isNewPaymentType(destination: string): boolean {
+  // Detection logic
+}
+
+private async handleNewPaymentType(request: SendPaymentRequest): Promise<boolean> {
+  // Processing logic
+}
+```
+
+### **Extending Transaction Types**
+To add new transaction types:
+
+1. **Update PaymentTransaction interface:**
+```typescript
+interface PaymentTransaction {
+  // ... existing fields
+  type: 'sent' | 'received' | 'new_type'
+  metadata?: NewTypeMetadata
+}
+```
+
+2. **Update transaction mapping:**
+```typescript
+private mapPaymentToTransaction(payment: any): PaymentTransaction {
+  // Add new type detection and mapping
+}
+```
+
+### **Custom WebSocket Handlers**
+To add custom WebSocket message handling:
+
+```typescript
+class WalletWebSocketService extends BaseService {
+  private handleMessage(event: MessageEvent): void {
+    const data = JSON.parse(event.data)
+
+    // Handle existing message types
+    if (data.payment) {
+      this.handlePaymentNotification(data.payment)
+    }
+
+    // Add custom message handling
+    if (data.custom_event) {
+      this.handleCustomEvent(data.custom_event)
+    }
+  }
+
+  private handleCustomEvent(event: CustomEvent): void {
+    // Custom event processing
+  }
+}
+```
+
+### **Testing Wallet Functionality**
+
+#### **Unit Tests**
+```typescript
+describe('WalletService', () => {
+  let service: WalletService
+
+  beforeEach(() => {
+    service = new WalletService()
+  })
+
+  it('should send Lightning payment', async () => {
+    const request = {
+      destination: 'lnbc1000n...',
+      amount: 1000
+    }
+
+    const result = await service.sendPayment(request)
+    expect(result).toBe(true)
+  })
+})
+```
+
+#### **Integration Tests**
+```typescript
+describe('Wallet Integration', () => {
+  it('should update balance after payment', async () => {
+    const websocketService = new WalletWebSocketService()
+    const paymentService = new PaymentService()
+
+    // Mock payment notification
+    await websocketService.handlePaymentNotification({
+      amount: 1000,
+      wallet_balance: 5000
+    })
+
+    expect(paymentService.totalBalance).toBe(5000000) // millisats
+  })
+})
+```
+
+## See Also
+
+### Related Documentation
+- **[[../base-module/index|🏗️ Base Module]]** - Authentication and core services
+- **[[../../03-core-services/payment-service|💳 Payment Service]]** - Core payment processing
+- **[[websocket-integration|⚡ WebSocket Integration]]** - Real-time update details
+- **[[payment-processing|💸 Payment Processing]]** - Payment flow documentation
+
+### API References
+- **[[../../05-api-reference/lnbits-api|⚡ LNbits API]]** - Backend API integration
+- **[[../../05-api-reference/lightning-payments|💰 Lightning Payments]]** - Payment protocol details
+
+### Development Guides
+- **[[../../04-development/testing|🧪 Testing Guide]]** - Testing strategies
+- **[[../../04-development/debugging|🐛 Debugging]]** - Troubleshooting guide
+
+---
+
+**Tags:** #wallet #lightning #payments #websocket #real-time #module
+**Last Updated:** 2025-09-18
+**Author:** Development Team