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.
This commit is contained in:
parent
832bf4d4ca
commit
71cec00bfc
6 changed files with 1748 additions and 1 deletions
|
|
@ -80,6 +80,43 @@ interface AuthService {
|
|||
|
||||
**See:** [[authentication|📖 Authentication Service Documentation]]
|
||||
|
||||
### **PaymentService** 💳
|
||||
**Purpose:** Centralized Lightning payment processing and wallet management
|
||||
**Location:** `src/core/services/PaymentService.ts`
|
||||
**Token:** `SERVICE_TOKENS.PAYMENT_SERVICE`
|
||||
|
||||
**Key Features:**
|
||||
- **Wallet Management** - Multi-wallet support with preferred wallet selection
|
||||
- **Payment Processing** - Lightning invoices, QR code generation, and external wallet handling
|
||||
- **Balance Management** - Real-time wallet balance updates and tracking
|
||||
- **Payment Validation** - Balance checking and payment amount validation
|
||||
- **Error Handling** - Consistent payment error handling and user feedback
|
||||
|
||||
**Reactive State:**
|
||||
```typescript
|
||||
interface PaymentService {
|
||||
isProcessingPayment: ComputedRef<boolean> // Payment in progress
|
||||
paymentError: ComputedRef<string | null> // Payment error state
|
||||
totalBalance: number // Total balance across wallets (getter)
|
||||
hasWalletWithBalance: boolean // Wallet availability check (getter)
|
||||
}
|
||||
```
|
||||
|
||||
**Key Methods:**
|
||||
- `payWithWallet(paymentRequest, amount?, options?)` - Process Lightning payment
|
||||
- `generateQRCode(paymentRequest, options?)` - Generate payment QR codes
|
||||
- `openExternalWallet(paymentRequest)` - Launch external Lightning wallet
|
||||
- `updateWalletBalance(balanceMsat, walletId?)` - Update wallet balance from WebSocket
|
||||
- `getPreferredWallet()` - Get the primary wallet for operations
|
||||
- `getWalletWithBalance(requiredAmount?)` - Find wallet with sufficient balance
|
||||
|
||||
**Wallet Selection Logic:**
|
||||
- Always uses first wallet (`wallets[0]`) for consistency across modules
|
||||
- Provides helper methods for wallet selection and balance checking
|
||||
- Integrates with AuthService for wallet credentials and management
|
||||
|
||||
**See:** [[payment-service|📖 Payment Service Documentation]]
|
||||
|
||||
### **RelayHub** 🌐
|
||||
**Purpose:** Centralized Nostr relay connection management
|
||||
**Location:** `src/modules/base/nostr/relay-hub.ts`
|
||||
|
|
@ -222,6 +259,74 @@ interface EventBusEvents {
|
|||
|
||||
**See:** [[../01-architecture/event-bus|📖 Event Bus Communication Documentation]]
|
||||
|
||||
### **WalletService** 🏦
|
||||
**Purpose:** Wallet operations and transaction management
|
||||
**Location:** `src/modules/wallet/services/WalletService.ts`
|
||||
**Token:** `SERVICE_TOKENS.WALLET_SERVICE`
|
||||
|
||||
**Key Features:**
|
||||
- **Payment Operations** - Send Lightning payments to invoices, addresses, and LNURL
|
||||
- **Payment Link Management** - Create and manage LNURL payment links and Lightning addresses
|
||||
- **Transaction History** - Load and manage comprehensive transaction history
|
||||
- **Real-time Updates** - Add new transactions from WebSocket notifications
|
||||
|
||||
**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 with Lightning address
|
||||
- `deletePayLink(linkId: string)` - Remove payment link
|
||||
- `addTransaction(payment)` - Add transaction from WebSocket notification
|
||||
- `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:**
|
||||
- **Real-time Connection** - WebSocket connection to LNbits for instant updates
|
||||
- **Balance Synchronization** - Smart balance updates with unit conversion handling
|
||||
- **Payment Notifications** - Toast notifications for incoming payments
|
||||
- **Connection Management** - Automatic reconnection with exponential backoff
|
||||
- **Battery Optimization** - VisibilityService integration for mobile efficiency
|
||||
|
||||
**Reactive State:**
|
||||
```typescript
|
||||
interface WalletWebSocketService {
|
||||
isConnected: Ref<boolean> // WebSocket connection status
|
||||
connectionStatus: Ref<string> // Connection state details
|
||||
}
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
**WebSocket Integration:**
|
||||
- Connects to `wss://lnbits-server/api/v1/ws/{walletInkey}`
|
||||
- Handles incoming/outgoing payment balance differences
|
||||
- Updates PaymentService with converted balance (sats → millisats)
|
||||
- Integrates with WalletService for transaction updates
|
||||
|
||||
## Service Lifecycle
|
||||
|
||||
### **Initialization Phase**
|
||||
|
|
@ -479,9 +584,11 @@ describe('Service Integration', () => {
|
|||
|
||||
### Service Documentation
|
||||
- **[[authentication|🔐 Authentication Service]]** - User identity and session management
|
||||
- **[[payment-service|💳 Payment Service]]** - Lightning payment processing and wallet management
|
||||
- **[[storage-service|💾 Storage Service]]** - User-scoped data persistence
|
||||
- **[[toast-service|📢 Toast Service]]** - User notifications and feedback
|
||||
- **[[visibility-service|👁️ Visibility Service]]** - Dynamic UI component control
|
||||
- **[[../02-modules/wallet-module/index|💰 Wallet Services]]** - WalletService and WebSocket integration
|
||||
|
||||
### Architecture References
|
||||
- **[[../01-architecture/dependency-injection|⚙️ Dependency Injection]]** - DI container system
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue