web-app/docs/02-modules/wallet-module/index.md

💰 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:

// 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:

// 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:

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:

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)

// Direct invoice payment
await walletService.sendPayment({
  destination: "lnbc1000n1p3xh4v...",
  amount: 1000 // Optional if invoice has amount
})

Lightning Addresses

// Lightning address payment
await walletService.sendPayment({
  destination: "user@stacker.news",
  amount: 1000,
  comment: "Great post!"
})

LNURL Pay

// 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:

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:

# 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:

interface SendPaymentRequest {
  destination: string
  amount: number
  comment?: string
  newPaymentType?: NewPaymentParams  // Add new type
}

2. Update WalletService.sendPayment():

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:

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:

interface PaymentTransaction {
  // ... existing fields
  type: 'sent' | 'received' | 'new_type'
  metadata?: NewTypeMetadata
}

2. Update transaction mapping:

private mapPaymentToTransaction(payment: any): PaymentTransaction {
  // Add new type detection and mapping
}

Custom WebSocket Handlers

To add custom WebSocket message handling:

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

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

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 - Authentication and core services
• ../../03-core-services/payment-service - Core payment processing
• websocket-integration - Real-time update details
• payment-processing - Payment flow documentation

API References

• ../../05-api-reference/lnbits-api - Backend API integration
• ../../05-api-reference/lightning-payments - Payment protocol details

Development Guides

• ../../04-development/testing - Testing strategies
• ../../04-development/debugging - Troubleshooting guide

---

Tags: #wallet #lightning #payments #websocket #real-time #module Last Updated: 2025-09-18 Author: Development Team