Enhance README and wallet module documentation with new payment features
- Updated README.md to include new capabilities for Lightning invoice creation, smart payment scanning, universal payment support, and smart amount fields. - Enhanced wallet-module documentation to reflect comprehensive Lightning Network wallet functionality, including detailed descriptions of payment processing, QR code scanning, and invoice management features. - Added new sections for QR scanner component and payment flow architecture, improving clarity and usability for developers. These changes provide clearer guidance on the application's features and improve the overall documentation quality.
This commit is contained in:
parent
b8515c4598
commit
ab1a6747ce
2 changed files with 160 additions and 49 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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<PaymentTransaction[]> // Transaction history
|
||||
payLinks: ComputedRef<PayLink[]> // Created payment links
|
||||
isCreatingPayLink: ComputedRef<boolean> // Pay link creation state
|
||||
isCreatingInvoice: ComputedRef<boolean> // Invoice 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
|
||||
- `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...')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue