padreug/web-app
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add Wallet Module documentation and WebSocket integration

Browse source 
- 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.
This commit is contained in:
padreug 2025-09-18 09:56:19 +02:00
parent 832bf4d4ca
commit 71cec00bfc
6 changed files with 1748 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

512
docs/02-modules/wallet-module/index.md Normal file
View file

@ -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

590
docs/02-modules/wallet-module/websocket-integration.md Normal file
View file

@ -0,0 +1,590 @@
# ⚡ WebSocket Integration
> **Real-time wallet balance updates** through LNbits WebSocket API with automatic reconnection, battery optimization, and smart unit conversion handling.
## Table of Contents
- [[#Overview]]
- [[#Architecture]]
- [[#Connection Management]]
- [[#Message Processing]]
- [[#Balance Update Logic]]
- [[#Error Handling]]
- [[#Battery Optimization]]
- [[#Configuration]]
- [[#Troubleshooting]]
## Overview
The Wallet WebSocket integration provides real-time synchronization between the Ario wallet interface and the LNbits Lightning backend. This enables instant balance updates and payment notifications without requiring page refreshes or manual polling.
### **Key Benefits**
- **Instant UI Updates** - Balance changes appear immediately when payments are sent or received
- **Payment Notifications** - Toast notifications for incoming payments
- **Battery Efficient** - Pauses when app is not visible to save mobile battery
- **Reliable Connection** - Automatic reconnection with exponential backoff
- **Smart Conversion** - Handles LNbits sats/millisats behavior differences
### **WebSocket Endpoint**
```
wss://your-lnbits-server/api/v1/ws/{walletInkey}
```
Where `walletInkey` is the invoice/readonly key for the wallet.
## Architecture
### **Service Integration**
```
┌─ WalletWebSocketService ─┐ ┌─ PaymentService ─┐ ┌─ UI Components ─┐
│ │ │ │ │ │
│ • WebSocket Connection │───▶│ • Balance Update │───▶│ • Balance Display│
│ • Message Processing │ │ • Wallet Mgmt │ │ • Toast Notifications
│ • Reconnection Logic │ │ • Multi-wallet │ │ • Transaction List │
│ • Battery Optimization │ │ │ │ │
└──────────────────────────┘ └──────────────────┘ └──────────────────┘
│ │
│ │
▼ ▼
┌─ VisibilityService ─────┐ ┌─ AuthService ──────┐
│ │ │ │
│ • App Visibility │ │ • User Wallets │
│ • Connection Pausing │ │ • Authentication │
│ • Resume Management │ │ • Wallet Selection │
└─────────────────────────┘ └────────────────────┘
```
### **Dependency Graph**
```
WalletWebSocketService
├── BaseService (lifecycle management)
├── PaymentService (balance updates)
├── WalletService (transaction management)
├── AuthService (wallet credentials)
└── VisibilityService (battery optimization)
```
### **Initialization Flow**
```
1. Module Installation
├── Create WalletWebSocketService instance
├── Register in DI container
└── Initialize with dependencies
2. Service Initialization
├── Wait for dependencies (AuthService, PaymentService)
├── Register with VisibilityService
├── Set up auth event listeners
└── Attempt initial connection
3. Authentication Events
├── auth:login → Connect WebSocket
└── auth:logout → Disconnect WebSocket
4. Connection Lifecycle
├── Connect → Update status → Listen for messages
├── Message → Process → Update balance
├── Disconnect → Attempt reconnection
└── Visibility Change → Pause/Resume
```
## Connection Management
### **Connection Lifecycle**
#### **Initial Connection**
```typescript
// Triggered by authentication events
eventBus.on('auth:login', () => {
setTimeout(() => {
this.connectIfNeeded()
}, 500) // Small delay for auth processing
})
```
#### **Connection Process**
```typescript
private async connect(walletInkey: string): Promise<void> {
// 1. Build WebSocket URL
const baseUrl = import.meta.env.VITE_LNBITS_BASE_URL
const wsProtocol = baseUrl.startsWith('https') ? 'wss:' : 'ws:'
const host = baseUrl.replace(/^https?:\/\//, '').replace(/\/$/, '')
const wsUrl = `${wsProtocol}//${host}/api/v1/ws/${walletInkey}`
// 2. Create WebSocket connection
this.ws = new WebSocket(wsUrl)
// 3. Set up event handlers
this.ws.onopen = this.handleOpen.bind(this)
this.ws.onmessage = this.handleMessage.bind(this)
this.ws.onclose = this.handleClose.bind(this)
this.ws.onerror = this.handleWebSocketError.bind(this)
}
```
### **Reconnection Strategy**
#### **Exponential Backoff**
```typescript
private scheduleReconnect(): void {
if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
this.connectionStatus.value = 'failed'
return
}
// Exponential backoff: 1s, 2s, 4s, 8s, 16s
const delay = this.config.reconnectDelay * Math.pow(2, this.reconnectAttempts)
this.reconnectAttempts++
this.reconnectTimer = setTimeout(() => {
this.connectIfNeeded()
}, delay)
}
```
#### **Connection Health Monitoring**
```typescript
// Connection states tracked
enum ConnectionStatus {
DISCONNECTED = 'disconnected',
CONNECTING = 'connecting',
CONNECTED = 'connected',
RECONNECTING = 'reconnecting',
ERROR = 'error',
FAILED = 'failed'
}
```
### **Graceful Disconnection**
```typescript
public disconnect(): void {
// Clear reconnection timer
if (this.reconnectTimer) {
clearTimeout(this.reconnectTimer)
this.reconnectTimer = null
}
// Close WebSocket with normal closure code
if (this.ws) {
this.ws.close(1000, 'Client disconnect')
this.ws = null
}
// Update reactive state
this.isConnected.value = false
this.connectionStatus.value = 'disconnected'
}
```
## Message Processing
### **Message Structure**
LNbits WebSocket sends messages in this format:
```json
{
"wallet_balance": 1000820, // Balance in sats
"payment": { // Payment details (optional)
"amount": 100000, // Amount in millisats (positive = received, negative = sent)
"payment_hash": "abc123...",
"description": "Payment description",
"time": 1694123456,
"pending": false
}
}
```
### **Message Handler**
```typescript
private handleMessage(event: MessageEvent): void {
try {
const data = JSON.parse(event.data)
// Process payment notification first
if (data.payment) {
this.handlePaymentNotification(data.payment)
}
// Process balance update
if (data.wallet_balance !== undefined) {
this.processBalanceUpdate(data)
}
} catch (error) {
console.error('Failed to parse WebSocket message:', error)
}
}
```
### **Payment Notification Processing**
```typescript
private handlePaymentNotification(payment: any): void {
// Add to transaction history via WalletService
if (this.walletService?.addTransaction) {
this.walletService.addTransaction(payment)
}
// Show toast notification for incoming payments
if (payment.amount > 0 && !payment.pending) {
const amountSats = Math.abs(payment.amount / 1000)
this.toast.success(`Received ${amountSats} sats!`)
}
}
```
## Balance Update Logic
### **LNbits WebSocket Behavior**
LNbits has different behavior for incoming vs outgoing payments:
- **Incoming payments**: WebSocket sends **post-payment balance** (already includes received amount)
- **Outgoing payments**: WebSocket sends **pre-payment balance** (before deduction)
### **Smart Balance Conversion**
```typescript
private processBalanceUpdate(data: any): void {
let finalBalance = data.wallet_balance // Balance in sats from LNbits
if (data.payment) {
if (data.payment.amount < 0) {
// Outgoing payment - LNbits sends pre-payment balance
// We need to subtract the payment amount
const paymentSats = Math.abs(data.payment.amount) / 1000
finalBalance = data.wallet_balance - paymentSats
console.log('Outgoing payment adjustment:', {
originalBalance: data.wallet_balance,
paymentSats: paymentSats,
finalBalance: finalBalance
})
} else if (data.payment.amount > 0) {
// Incoming payment - LNbits sends post-payment balance
// Use balance as-is
console.log('Incoming payment - using balance as-is:', data.wallet_balance)
}
}
// Update balance via PaymentService
this.updateWalletBalance(finalBalance)
}
```
### **Balance Update Integration**
```typescript
private updateWalletBalance(balanceSats: number): void {
// Convert sats to millisats for internal storage
const balanceMsat = balanceSats * 1000
// Get connected wallet ID
const wallet = this.paymentService?.getPreferredWallet?.()
const walletId = wallet?.id
// Update via PaymentService for consistency
if (this.paymentService?.updateWalletBalance) {
this.paymentService.updateWalletBalance(balanceMsat, walletId)
}
}
```
### **Unit Conversion Table**
| Source | Unit | Internal Storage | Display |
|--------|------|------------------|---------|
| LNbits WebSocket | sats | millisats × 1000 | sats ÷ 1000 |
| LNbits API | millisats | millisats | sats ÷ 1000 |
| Payment amounts | millisats | millisats | sats ÷ 1000 |
| UI display | sats | millisats ÷ 1000 | sats |
## Error Handling
### **Connection Errors**
```typescript
private handleWebSocketError(event: Event): void {
console.error('WebSocket error:', event)
this.connectionStatus.value = 'error'
// Log additional error details
if (this.ws) {
console.error('WebSocket state:', this.ws.readyState)
console.error('WebSocket URL:', this.ws.url)
}
}
```
### **Connection Close Handling**
```typescript
private handleClose(event: CloseEvent): void {
console.log('WebSocket closed:', event.code, event.reason)
this.isConnected.value = false
this.connectionStatus.value = 'disconnected'
this.ws = null
// Only reconnect if not a normal closure
if (event.code !== 1000) {
this.scheduleReconnect()
}
}
```
### **Error Recovery Strategies**
#### **Authentication Errors (Code 1002)**
```typescript
// Invalid wallet credentials - clear and require re-authentication
if (event.code === 1002) {
this.authService?.logout()
this.toast.error('Wallet credentials invalid. Please login again.')
}
```
#### **Network Errors**
```typescript
// Network connectivity issues - retry with backoff
if (!navigator.onLine) {
window.addEventListener('online', () => {
this.reconnectAttempts = 0
this.connectIfNeeded()
}, { once: true })
}
```
#### **Server Errors (Code 1011)**
```typescript
// Server internal error - longer backoff
if (event.code === 1011) {
this.config.reconnectDelay = 5000 // Increase delay
this.scheduleReconnect()
}
```
## Battery Optimization
### **VisibilityService Integration**
Mobile browsers suspend WebSocket connections when the app loses visibility. The WebSocket service integrates with VisibilityService to handle this efficiently:
```typescript
protected async onInitialize(): Promise<void> {
// Register with VisibilityService
if (this.visibilityService) {
this.visibilityService.registerService(
this.metadata.name,
this.onResume.bind(this),
this.onPause.bind(this)
)
}
}
```
### **Pause Behavior**
```typescript
private async onPause(): Promise<void> {
console.log('WebSocket pausing - app not visible')
// Disconnect to save battery
this.disconnect()
}
```
### **Resume Behavior**
```typescript
private async onResume(): Promise<void> {
console.log('WebSocket resuming - app visible')
// Reconnect if not already connected
if (!this.isConnected.value) {
this.reconnectAttempts = 0 // Reset attempt counter
await this.connectIfNeeded()
}
}
```
### **Visibility States**
| App State | WebSocket Action | Battery Impact |
|-----------|------------------|----------------|
| Visible | Connected | Normal |
| Hidden/Background | Disconnected | Minimal |
| Tab Switch | Disconnected | Minimal |
| Resume | Reconnect | Brief spike |
## Configuration
### **WebSocket Configuration**
Configure WebSocket behavior in module config:
```typescript
// app.config.ts
modules: {
wallet: {
enabled: true,
config: {
websocket: {
enabled: true, // Enable WebSocket functionality
reconnectDelay: 1000, // Initial reconnection delay (ms)
maxReconnectAttempts: 5 // Maximum reconnection attempts
}
}
}
}
```
### **Environment Variables**
```bash
# LNbits server URL - must be accessible for WebSocket
VITE_LNBITS_BASE_URL=https://your-lnbits-server.com
# Development mode - enables verbose WebSocket logging
VITE_DEV_MODE=true
```
### **Runtime Configuration Access**
```typescript
// Access configuration in service
const appConfig = (window as any).appConfig
if (appConfig?.modules?.wallet?.config?.websocket) {
this.config = { ...this.config, ...appConfig.modules.wallet.config.websocket }
}
```
## Troubleshooting
### **Common Issues**
#### **WebSocket Connection Fails**
**Symptoms:** Connection status shows 'error' or 'failed'
**Debugging Steps:**
1. Check LNbits server accessibility
2. Verify VITE_LNBITS_BASE_URL environment variable
3. Check browser network tab for WebSocket connection attempts
4. Verify wallet credentials (inkey) are valid
**Solutions:**
```bash
# Test LNbits server connectivity
curl https://your-lnbits-server.com/api/v1/wallet
# Check WebSocket endpoint manually
# Open browser console and test:
const ws = new WebSocket('wss://your-server/api/v1/ws/your-inkey')
```
#### **Balance Not Updating**
**Symptoms:** Payments are processed but UI balance doesn't change
**Debugging Steps:**
1. Check browser console for WebSocket messages
2. Verify PaymentService is receiving updateWalletBalance calls
3. Check if wallet ID matches between services
**Debug Logging:**
```typescript
// Enable debug logging in WalletWebSocketService
console.log('WebSocket message:', data)
console.log('Balance update:', { old: oldBalance, new: finalBalance })
```
#### **Frequent Disconnections**
**Symptoms:** WebSocket constantly reconnecting
**Potential Causes:**
- Network instability
- LNbits server restarts
- Proxy/firewall interference
- Mobile browser background throttling
**Solutions:**
- Increase reconnectDelay in configuration
- Check server logs for connection issues
- Verify VisibilityService is working correctly
### **Diagnostic Tools**
#### **Connection Status Component**
```vue
<template>
<div class="websocket-status">
<div :class="statusClass">
{{ connectionStatus }}
</div>
<div v-if="!isConnected">
<button @click="reconnect">Reconnect</button>
</div>
</div>
</template>
<script setup>
const websocketService = injectService(SERVICE_TOKENS.WALLET_WEBSOCKET_SERVICE)
const { isConnected, connectionStatus } = websocketService
const statusClass = computed(() => ({
'status-connected': connectionStatus.value === 'connected',
'status-connecting': connectionStatus.value === 'connecting',
'status-error': connectionStatus.value === 'error'
}))
const reconnect = () => websocketService.reconnect()
</script>
```
#### **Debug Console Commands**
```javascript
// Access services from browser console
const wsService = window.__DI_CONTAINER__.get('WALLET_WEBSOCKET_SERVICE')
// Check connection status
console.log('Connected:', wsService.isConnected.value)
console.log('Status:', wsService.connectionStatus.value)
// Manual reconnection
wsService.reconnect()
// View configuration
console.log('Config:', wsService.config)
```
### **Performance Monitoring**
#### **Connection Metrics**
```typescript
// Track connection performance
class ConnectionMetrics {
private connectionAttempts = 0
private successfulConnections = 0
private totalDowntime = 0
private lastConnectTime = 0
onConnectionAttempt() {
this.connectionAttempts++
this.lastConnectTime = Date.now()
}
onConnectionSuccess() {
this.successfulConnections++
const connectTime = Date.now() - this.lastConnectTime
console.log(`Connected in ${connectTime}ms`)
}
getSuccessRate(): number {
return this.successfulConnections / this.connectionAttempts
}
}
```
## See Also
### Related Documentation
- **[[index|💰 Wallet Module Overview]]** - Main wallet module documentation
- **[[../../03-core-services/visibility-service|👁️ Visibility Service]]** - Battery optimization service
- **[[../../03-core-services/payment-service|💳 Payment Service]]** - Core payment processing
### API References
- **[[../../05-api-reference/lnbits-api|⚡ LNbits API]]** - Backend API documentation
- **[[../../05-api-reference/websocket-protocol|🔌 WebSocket Protocol]]** - WebSocket message formats
### Development Guides
- **[[../../04-development/testing|🧪 Testing Guide]]** - Testing WebSocket functionality
- **[[../../04-development/debugging|🐛 Debugging]]** - Debugging WebSocket issues
---
**Tags:** #websocket #real-time #lightning #lnbits #battery-optimization #connection-management
**Last Updated:** 2025-09-18
**Author:** Development Team