Implement Lightning Payment Operations

[CodeByMAB]

Epic Reference

Part of Epic: Breez SDK Integration for Expo App (epic:97fd7dcb-10ec-46a8-b681-b2805eb0eb56)
SRS Spec: spec:97fd7dcb-10ec-46a8-b681-b2805eb0eb56/a8f8bef7-d1c5-4113-a9ad-6092120bfe76

Overview

Implement Lightning payment operations: create invoice (receivePayment), pay invoice (sendPayment), decode invoice (parseInvoice), list payments. Support Bolt11, optional LNURL and Lightning address resolution via Breez SDK.

Related SRS Requirements: FR-PAY-002, FR-PAY-003, FR-PAY-004, FR-PAY-005, FR-PAY-006, Section 7.5.1

Tasks

• Create Lightning invoice: receivePayment({ amountMsat?, description? }); display as text and QR; copy/share
• Pay Lightning invoice: decode with parseInvoice; sendPayment({ bolt11, amountMsat? }); show fee estimate; confirm; complete within 10s
• List payments: listPayments({ filter?, fromTimestamp?, toTimestamp? }); show in history
• Handle LNURL-Pay and LNURL-Withdraw (Breez SDK built-in); detect LNURL in QR
• Support Lightning address ([user@domain.com]): validate format, resolve to LNURL-Pay, send payment
• Error handling: insufficient funds, invoice expired, route not found, invalid input; user-friendly messages and retry where appropriate
• Monitor payment status via SDK events; update balance and UI immediately

Acceptance Criteria

• AC-PAY-002-01 to 06: Create invoice, display QR/text, copy, monitor, notification within 1s, balance updates
• AC-PAY-003-01 to 06: Amount/description, Bolt11, QR/copy, expiry (default 1h), monitor
• AC-PAY-004-01 to 06: Scan/paste invoice, decode, show fee, confirm, complete <10s, show result
• AC-PAY-005-01 to 05: LNURL detect, LNURL-Pay amount in range, LNURL-Withdraw, metadata, <15s
• AC-PAY-006-01 to 05: Lightning address validation, resolve, amount/message, <15s, cache 24h

Payment Flow (conceptual)

• Receive: Create invoice → Show QR/Copy → Payment received event → Update balance & notify
• Send: Scan/Paste → Decode → Confirm amount & fee → Send → Success/Failure UI

Dependencies

• Setup Expo Project with Breez SDK Integration #1 Setup Expo Project with Breez SDK Integration
• Implement Wallet Creation and Restoration #2 Implement Wallet Creation and Restoration
• Initialize Breez SDK and Lightning Node #3 Initialize Breez SDK and Lightning Node

---

Ticket ID: ticket:97fd7dcb-10ec-46a8-b681-b2805eb0eb56/8381c733-0d5e-4870-b95a-235c33662eba

[traycerai]

Plan

Observations

The project is a Lightning-only Bitcoin wallet using Breez SDK Spark (Nodeless) with Expo/React Native. Currently, only documentation exists (file:docs/BRS.md and file:docs/SRS.md). The SRS defines comprehensive requirements for payment operations (FR-PAY-002 through FR-PAY-006) with detailed acceptance criteria, UI wireframes, and Breez SDK integration specifications. Dependencies include tickets #1 (Expo setup), #2 (wallet creation), and #3 (SDK initialization), which must be completed first. The Breez SDK provides native support for Lightning payments, LNURL, and Lightning addresses through methods like receivePayment(), sendPayment(), parseInvoice(), and listPayments().

Approach

The implementation follows an event-driven architecture leveraging Breez SDK's built-in capabilities. Create service layer abstractions for payment operations that wrap SDK methods with error handling and state management. Build React Native UI components matching the SRS wireframes for send/receive/history screens. Implement real-time payment monitoring through SDK event listeners (paymentReceived, paymentSent, paymentFailed) that trigger immediate UI updates and balance refreshes. Use native Expo modules for QR code generation/scanning and clipboard operations. Structure the code to handle LNURL and Lightning addresses transparently through Breez SDK's automatic detection and resolution.

Implementation Steps

1. Project Structure Setup

Create the following directory structure for payment operations:

src/
├── services/
│   ├── payment/
│   │   ├── PaymentService.ts
│   │   ├── InvoiceService.ts
│   │   ├── LNURLService.ts
│   │   └── types.ts
├── components/
│   ├── payment/
│   │   ├── ReceivePayment.tsx
│   │   ├── SendPayment.tsx
│   │   ├── PaymentHistory.tsx
│   │   ├── InvoiceDisplay.tsx
│   │   ├── QRCodeScanner.tsx
│   │   └── PaymentConfirmation.tsx
├── hooks/
│   ├── usePayments.ts
│   ├── useInvoice.ts
│   └── usePaymentEvents.ts
├── store/
│   └── paymentSlice.ts
└── utils/
    ├── paymentValidation.ts
    └── errorMessages.ts

2. Install Required Dependencies

Add the following packages to support payment operations:

• react-native-qrcode-svg and react-native-svg for QR code generation
• expo-camera for QR code scanning (already in SRS config)
• expo-clipboard for copy functionality
• expo-sharing for share functionality
• expo-haptics for tactile feedback on payment events

Update app.json to include camera and biometric permissions as specified in SRS section 8.1.1.

3. Payment Service Layer

3.1 Create PaymentService (file:src/services/payment/PaymentService.ts)

Implement core payment operations wrapping Breez SDK methods:

receivePayment()

• Accept parameters: { amountMsat?: number, description?: string, expiry?: number }
• Call Breez SDK receivePayment() method
• Return invoice object with bolt11, paymentHash, expiresAt
• Handle errors: network failures, SDK not initialized
• Default expiry: 3600 seconds (1 hour) per FR-PAY-003-05

sendPayment()

• Accept parameters: { bolt11: string, amountMsat?: number }
• First call parseInvoice() to decode and validate
• Call prepareSendPayment() to get fee estimate
• Execute sendPayment() with confirmation
• Monitor payment status via SDK events
• Timeout after 10 seconds per AC-PAY-004-05
• Return payment result with paymentHash, feeMsat, status

parseInvoice()

• Accept Bolt11 invoice string
• Call Breez SDK parseInvoice() method
• Return decoded invoice details: amount, description, payee, expiry
• Validate invoice format and expiration
• Handle errors: invalid format, expired invoice

listPayments()

• Accept filter parameters: { filter?: PaymentType[], fromTimestamp?: number, toTimestamp?: number, offset?: number, limit?: number }
• Call Breez SDK listPayments() method
• Default limit: 50 transactions per page (per SRS section 4.5)
• Return array of payment objects with type, amount, timestamp, status
• Support pagination for infinite scroll

3.2 Create InvoiceService (file:src/services/payment/InvoiceService.ts)

Handle invoice-specific operations:

createInvoice()

• Wrapper around receivePayment() with additional validation
• Validate amount is positive if provided
• Sanitize description (max 639 bytes per FR-PAY-003)
• Generate QR code data (uppercase Bolt11 string)
• Store invoice in local state for monitoring

monitorInvoice()

• Register listener for paymentReceived event
• Match incoming payment to invoice by paymentHash
• Trigger callback when payment received
• Update balance immediately per AC-PAY-002-06
• Show notification within 1 second per AC-PAY-002-05
• Clean up listener after payment or expiry

validateInvoice()

• Check invoice format (Bolt11 regex)
• Verify not expired
• Decode and validate amount if present
• Return validation result with error messages

3.3 Create LNURLService (file:src/services/payment/LNURLService.ts)

Handle LNURL and Lightning address operations:

detectPaymentType()

• Accept input string (invoice, LNURL, Lightning address, Bitcoin address)
• Use regex patterns to detect type:
  • Bolt11: starts with lnbc, lntb
  • LNURL: starts with lnurl or lightning:
  • Lightning address: matches ^[a-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,}$
  • Bitcoin address: bech32, P2SH, P2PKH formats
• Return payment type enum

resolveLightningAddress()

• Validate Lightning address format per FR-PAY-006-01
• Call Breez SDK to resolve address to LNURL-Pay endpoint
• Cache resolved endpoint for 24 hours per AC-PAY-006-05
• Return LNURL-Pay request object
• Handle errors: invalid format, resolution failure, network timeout

handleLNURLPay()

• Parse LNURL using Breez SDK parseLnurl()
• Display metadata (description, images) per AC-PAY-005-04
• Validate amount within min/max range per AC-PAY-005-02
• Call lnurlPay() with amount and optional comment
• Complete within 15 seconds per AC-PAY-005-05
• Return payment result

handleLNURLWithdraw()

• Parse LNURL-Withdraw request
• Automatically withdraw available amount per AC-PAY-005-03
• Create invoice via receivePayment()
• Submit invoice to LNURL service
• Monitor for incoming payment
• Complete within 15 seconds

4. Payment Event Handling

4.1 Create usePaymentEvents Hook (file:src/hooks/usePaymentEvents.ts)

Implement real-time payment monitoring:

Setup Event Listeners

• Register listeners on component mount for:
  • paymentReceived: Update balance, show notification, add to history
  • paymentSent: Update balance, show confirmation, add to history
  • paymentFailed: Show error message, log details, enable retry
• Clean up listeners on unmount

Event Processing

• Process events asynchronously
• Update UI within 500ms per SRS section 7.4.2
• Persist events to local database
• Trigger haptic feedback for payment events
• Update Redux store with new payment data

Balance Updates

• Listen to nodeStateChanged event
• Extract channelsBalanceMsat from node state
• Update balance display immediately
• Refresh inbound/outbound liquidity indicators

5. UI Components

5.1 ReceivePayment Component (file:src/components/payment/ReceivePayment.tsx)

Based on SRS wireframe at lines 1154-1221:

Layout

• Header with back button and "Receive Payment" title
• Amount input section (optional) with unit toggle (sats/BTC)
• QR code display section using react-native-qrcode-svg
• Invoice text display (monospace font, scrollable)
• Action buttons: Copy and Share
• Info box with expiry information
• Countdown timer showing remaining validity

Functionality

• Call InvoiceService.createInvoice() when amount entered or on mount
• Generate QR code from Bolt11 invoice (200x200px)
• Copy invoice to clipboard using expo-clipboard
• Share invoice using expo-sharing
• Monitor invoice status via usePaymentEvents
• Show success animation when payment received
• Auto-navigate back to dashboard after successful payment

State Management

• Local state: amount, description, invoice, QR data, expiry timer
• Redux state: payment status, balance updates

5.2 SendPayment Component (file:src/components/payment/SendPayment.tsx)

Based on SRS wireframe at lines 1044-1134:

Layout

• Header with back button and "Send Payment" title
• Recipient input field with Paste and Scan QR buttons
• Amount input section with unit toggle
• Payment details card showing type, network fee, total
• Warning box about irreversibility
• Send Payment button (disabled until valid input)

Functionality

• Accept input via paste or QR scan using expo-camera
• Auto-detect payment type using LNURLService.detectPaymentType()
• For Bolt11: decode using parseInvoice(), display details
• For LNURL: resolve and show amount range
• For Lightning address: resolve to LNURL-Pay
• Call prepareSendPayment() to estimate fees
• Show confirmation dialog with all details
• Execute sendPayment() on confirmation
• Display loading state during payment (max 10s)
• Show success/failure result with appropriate messaging

Error Handling

• Insufficient funds: Show balance, suggest amount adjustment
• Invoice expired: Prompt to request new invoice
• Route not found: Suggest retry or on-chain alternative
• Invalid input: Clear field, show validation message
• Network error: Enable retry with exponential backoff

5.3 PaymentHistory Component (file:src/components/payment/PaymentHistory.tsx)

Based on SRS wireframe at lines 1369-1500:

Layout

• Header with "Transaction History" title
• Search bar for filtering transactions
• Filter chips: All, Lightning Sent, Lightning Received, Withdrawals
• Transaction list with infinite scroll
• Each item shows: icon, description, date, amount (colored by type)
• Pull-to-refresh functionality

Functionality

• Load initial 50 transactions using listPayments()
• Implement infinite scroll with pagination (offset/limit)
• Filter by payment type using filter chips
• Search by description or amount
• Pull-to-refresh to sync latest transactions
• Tap transaction to navigate to detail view
• Display relative timestamps ("2 hours ago", "Yesterday")

Transaction Item

• Icon: ⚡ for Lightning, ↓ for received, 🔗 for withdrawal
• Description from invoice or auto-generated
• Timestamp with relative formatting
• Amount with + (green) for received, - (red) for sent
• Status indicator for pending transactions

5.4 InvoiceDisplay Component (file:src/components/payment/InvoiceDisplay.tsx)

Reusable component for displaying invoices:

Props

• invoice: Bolt11 string
• amount: Amount in msats
• description: Invoice description
• expiresAt: Expiration timestamp
• onCopy: Callback for copy action
• onShare: Callback for share action

Features

• QR code generation using react-native-qrcode-svg
• Configurable QR size (default 200x200)
• Invoice text with copy button
• Expiry countdown timer
• Visual feedback on copy/share actions

5.5 QRCodeScanner Component (file:src/components/payment/QRCodeScanner.tsx)

Modal component for scanning QR codes:

Implementation

• Use expo-camera with CameraView component
• Configure barcodeScannerSettings for QR codes
• Request camera permissions using useCameraPermissions
• Handle onBarcodeScanned event
• Validate scanned data before returning
• Show scanning overlay with targeting frame
• Provide manual input fallback option
• Close modal after successful scan

5.6 PaymentConfirmation Component (file:src/components/payment/PaymentConfirmation.tsx)

Modal dialog for confirming payments:

Display

• Payment type (Lightning, LNURL, Lightning Address)
• Recipient information (truncated invoice or address)
• Amount in selected unit
• Estimated network fee
• Total amount to be sent
• Warning about irreversibility

Actions

• Cancel button (dismiss modal)
• Confirm button (execute payment)
• Loading state during payment execution
• Success/failure result display

6. State Management

6.1 Payment Redux Slice (file:src/store/paymentSlice.ts)

Create Redux slice for payment state:

State Shape

{
  payments: Payment[],
  pendingPayments: Payment[],
  balance: {
    totalMsat: number,
    inboundMsat: number,
    outboundMsat: number
  },
  activeInvoice: Invoice | null,
  loading: boolean,
  error: string | null
}

Actions

• addPayment: Add new payment to history
• updatePayment: Update payment status
• setBalance: Update wallet balance
• setActiveInvoice: Set currently monitored invoice
• clearActiveInvoice: Clear after payment received
• setLoading: Toggle loading state
• setError: Set error message

Selectors

• selectPayments: Get all payments
• selectPendingPayments: Get pending payments
• selectBalance: Get current balance
• selectRecentPayments: Get last 5 payments for dashboard

7. Validation and Error Handling

7.1 Payment Validation (file:src/utils/paymentValidation.ts)

Implement validation functions:

validateBolt11()

• Check format using regex
• Verify checksum
• Validate not expired
• Return validation result

validateLightningAddress()

• Match regex pattern per FR-PAY-006-01
• Check domain validity
• Return validation result

validateAmount()

• Check positive value
• Verify sufficient balance
• Validate within LNURL min/max range if applicable
• Return validation result

validateBitcoinAddress()

• Support bech32, P2SH, P2PKH formats
• Verify checksum
• Return validation result

7.2 Error Messages (file:src/utils/errorMessages.ts)

Map SDK errors to user-friendly messages per SRS section 7.6.1:

• NetworkError → "Connection lost. Please check your internet."
• InsufficientFunds → "Insufficient balance for this payment."
• InvoiceExpired → "This invoice has expired."
• RouteNotFound → "Unable to find payment route. Try again."
• InvalidInput → "Invalid address or invoice."
• LspError → "Service temporarily unavailable."

Include recovery suggestions and retry options where appropriate.

8. Integration with Existing Components

8.1 Dashboard Integration

Update dashboard screen to:

• Display recent payments using selectRecentPayments selector
• Show quick action buttons: Send, Receive, Withdraw, Scan
• Display current balance from Redux store
• Navigate to payment screens on button press

8.2 Navigation Setup

Add navigation routes:

• /send → SendPayment screen
• /receive → ReceivePayment screen
• /history → PaymentHistory screen
• /payment/:id → Payment detail screen

Configure deep linking for Lightning URIs and LNURL.

9. Testing Considerations

Unit Tests

• Test payment service methods with mocked Breez SDK
• Test validation functions with various inputs
• Test error message mapping
• Test state management actions and reducers

Integration Tests

• Test payment flow end-to-end on testnet
• Test LNURL-Pay and LNURL-Withdraw flows
• Test Lightning address resolution
• Test event handling and UI updates

Performance Tests

• Verify payment creation < 2 seconds
• Verify payment execution < 10 seconds
• Verify UI updates < 500ms after events
• Verify list rendering with 1000+ transactions

10. Performance Optimizations

Caching

• Cache Lightning address resolutions for 24 hours
• Cache payment history (last 1000 transactions)
• Implement virtual scrolling for long payment lists

Debouncing

• Debounce amount input to reduce re-renders
• Debounce search input in payment history

Memoization

• Memoize payment list filtering and sorting
• Memoize QR code generation
• Use React.memo for list items

Architecture Diagram

sequenceDiagram
    participant User
    participant UI
    participant Service
    participant BreezSDK
    participant Events
    participant Store

    Note over User,Store: Receive Payment Flow
    User->>UI: Enter amount & description
    UI->>Service: createInvoice(amount, desc)
    Service->>BreezSDK: receivePayment()
    BreezSDK-->>Service: Invoice (bolt11, hash)
    Service-->>UI: Invoice data
    UI->>UI: Display QR & text
    User->>UI: Copy/Share invoice
    
    Note over Events,Store: Payment Monitoring
    BreezSDK->>Events: paymentReceived event
    Events->>Store: addPayment()
    Events->>Store: updateBalance()
    Store-->>UI: State update
    UI->>UI: Show notification
    UI->>UI: Update balance

    Note over User,Store: Send Payment Flow
    User->>UI: Scan/Paste invoice
    UI->>Service: detectPaymentType(input)
    Service-->>UI: Type (Bolt11/LNURL/Address)
    UI->>Service: parseInvoice(bolt11)
    Service->>BreezSDK: parseInvoice()
    BreezSDK-->>Service: Invoice details
    Service-->>UI: Amount, description, fee
    UI->>UI: Show confirmation
    User->>UI: Confirm payment
    UI->>Service: sendPayment(bolt11)
    Service->>BreezSDK: sendPayment()
    BreezSDK->>Events: paymentSent event
    Events->>Store: addPayment()
    Events->>Store: updateBalance()
    BreezSDK-->>Service: Payment result
    Service-->>UI: Success/Failure
    UI->>UI: Show result

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The project is a Lightning-only Bitcoin wallet using Breez SDK Spark (Nodeless) with Expo/React Native. Currently, only documentation exists (file:docs/BRS.md and file:docs/SRS.md). The SRS defines comprehensive requirements for payment operations (FR-PAY-002 through FR-PAY-006) with detailed acceptance criteria, UI wireframes, and Breez SDK integration specifications. Dependencies include tickets #1 (Expo setup), #2 (wallet creation), and #3 (SDK initialization), which must be completed first. The Breez SDK provides native support for Lightning payments, LNURL, and Lightning addresses through methods like `receivePayment()`, `sendPayment()`, `parseInvoice()`, and `listPayments()`.

## Approach

The implementation follows an event-driven architecture leveraging Breez SDK's built-in capabilities. Create service layer abstractions for payment operations that wrap SDK methods with error handling and state management. Build React Native UI components matching the SRS wireframes for send/receive/history screens. Implement real-time payment monitoring through SDK event listeners (`paymentReceived`, `paymentSent`, `paymentFailed`) that trigger immediate UI updates and balance refreshes. Use native Expo modules for QR code generation/scanning and clipboard operations. Structure the code to handle LNURL and Lightning addresses transparently through Breez SDK's automatic detection and resolution.

## Implementation Steps

### 1. Project Structure Setup

Create the following directory structure for payment operations:

```
src/
├── services/
│   ├── payment/
│   │   ├── PaymentService.ts
│   │   ├── InvoiceService.ts
│   │   ├── LNURLService.ts
│   │   └── types.ts
├── components/
│   ├── payment/
│   │   ├── ReceivePayment.tsx
│   │   ├── SendPayment.tsx
│   │   ├── PaymentHistory.tsx
│   │   ├── InvoiceDisplay.tsx
│   │   ├── QRCodeScanner.tsx
│   │   └── PaymentConfirmation.tsx
├── hooks/
│   ├── usePayments.ts
│   ├── useInvoice.ts
│   └── usePaymentEvents.ts
├── store/
│   └── paymentSlice.ts
└── utils/
    ├── paymentValidation.ts
    └── errorMessages.ts
```

### 2. Install Required Dependencies

Add the following packages to support payment operations:

- `react-native-qrcode-svg` and `react-native-svg` for QR code generation
- `expo-camera` for QR code scanning (already in SRS config)
- `expo-clipboard` for copy functionality
- `expo-sharing` for share functionality
- `expo-haptics` for tactile feedback on payment events

Update `app.json` to include camera and biometric permissions as specified in SRS section 8.1.1.

### 3. Payment Service Layer

#### 3.1 Create PaymentService (file:src/services/payment/PaymentService.ts)

Implement core payment operations wrapping Breez SDK methods:

**receivePayment()**
- Accept parameters: `{ amountMsat?: number, description?: string, expiry?: number }`
- Call Breez SDK `receivePayment()` method
- Return invoice object with `bolt11`, `paymentHash`, `expiresAt`
- Handle errors: network failures, SDK not initialized
- Default expiry: 3600 seconds (1 hour) per FR-PAY-003-05

**sendPayment()**
- Accept parameters: `{ bolt11: string, amountMsat?: number }`
- First call `parseInvoice()` to decode and validate
- Call `prepareSendPayment()` to get fee estimate
- Execute `sendPayment()` with confirmation
- Monitor payment status via SDK events
- Timeout after 10 seconds per AC-PAY-004-05
- Return payment result with `paymentHash`, `feeMsat`, `status`

**parseInvoice()**
- Accept Bolt11 invoice string
- Call Breez SDK `parseInvoice()` method
- Return decoded invoice details: amount, description, payee, expiry
- Validate invoice format and expiration
- Handle errors: invalid format, expired invoice

**listPayments()**
- Accept filter parameters: `{ filter?: PaymentType[], fromTimestamp?: number, toTimestamp?: number, offset?: number, limit?: number }`
- Call Breez SDK `listPayments()` method
- Default limit: 50 transactions per page (per SRS section 4.5)
- Return array of payment objects with type, amount, timestamp, status
- Support pagination for infinite scroll

#### 3.2 Create InvoiceService (file:src/services/payment/InvoiceService.ts)

Handle invoice-specific operations:

**createInvoice()**
- Wrapper around `receivePayment()` with additional validation
- Validate amount is positive if provided
- Sanitize description (max 639 bytes per FR-PAY-003)
- Generate QR code data (uppercase Bolt11 string)
- Store invoice in local state for monitoring

**monitorInvoice()**
- Register listener for `paymentReceived` event
- Match incoming payment to invoice by `paymentHash`
- Trigger callback when payment received
- Update balance immediately per AC-PAY-002-06
- Show notification within 1 second per AC-PAY-002-05
- Clean up listener after payment or expiry

**validateInvoice()**
- Check invoice format (Bolt11 regex)
- Verify not expired
- Decode and validate amount if present
- Return validation result with error messages

#### 3.3 Create LNURLService (file:src/services/payment/LNURLService.ts)

Handle LNURL and Lightning address operations:

**detectPaymentType()**
- Accept input string (invoice, LNURL, Lightning address, Bitcoin address)
- Use regex patterns to detect type:
  - Bolt11: starts with `lnbc`, `lntb`
  - LNURL: starts with `lnurl` or `lightning:`
  - Lightning address: matches `^[a-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,}$`
  - Bitcoin address: bech32, P2SH, P2PKH formats
- Return payment type enum

**resolveLightningAddress()**
- Validate Lightning address format per FR-PAY-006-01
- Call Breez SDK to resolve address to LNURL-Pay endpoint
- Cache resolved endpoint for 24 hours per AC-PAY-006-05
- Return LNURL-Pay request object
- Handle errors: invalid format, resolution failure, network timeout

**handleLNURLPay()**
- Parse LNURL using Breez SDK `parseLnurl()`
- Display metadata (description, images) per AC-PAY-005-04
- Validate amount within min/max range per AC-PAY-005-02
- Call `lnurlPay()` with amount and optional comment
- Complete within 15 seconds per AC-PAY-005-05
- Return payment result

**handleLNURLWithdraw()**
- Parse LNURL-Withdraw request
- Automatically withdraw available amount per AC-PAY-005-03
- Create invoice via `receivePayment()`
- Submit invoice to LNURL service
- Monitor for incoming payment
- Complete within 15 seconds

### 4. Payment Event Handling

#### 4.1 Create usePaymentEvents Hook (file:src/hooks/usePaymentEvents.ts)

Implement real-time payment monitoring:

**Setup Event Listeners**
- Register listeners on component mount for:
  - `paymentReceived`: Update balance, show notification, add to history
  - `paymentSent`: Update balance, show confirmation, add to history
  - `paymentFailed`: Show error message, log details, enable retry
- Clean up listeners on unmount

**Event Processing**
- Process events asynchronously
- Update UI within 500ms per SRS section 7.4.2
- Persist events to local database
- Trigger haptic feedback for payment events
- Update Redux store with new payment data

**Balance Updates**
- Listen to `nodeStateChanged` event
- Extract `channelsBalanceMsat` from node state
- Update balance display immediately
- Refresh inbound/outbound liquidity indicators

### 5. UI Components

#### 5.1 ReceivePayment Component (file:src/components/payment/ReceivePayment.tsx)

Based on SRS wireframe at lines 1154-1221:

**Layout**
- Header with back button and "Receive Payment" title
- Amount input section (optional) with unit toggle (sats/BTC)
- QR code display section using `react-native-qrcode-svg`
- Invoice text display (monospace font, scrollable)
- Action buttons: Copy and Share
- Info box with expiry information
- Countdown timer showing remaining validity

**Functionality**
- Call `InvoiceService.createInvoice()` when amount entered or on mount
- Generate QR code from Bolt11 invoice (200x200px)
- Copy invoice to clipboard using `expo-clipboard`
- Share invoice using `expo-sharing`
- Monitor invoice status via `usePaymentEvents`
- Show success animation when payment received
- Auto-navigate back to dashboard after successful payment

**State Management**
- Local state: amount, description, invoice, QR data, expiry timer
- Redux state: payment status, balance updates

#### 5.2 SendPayment Component (file:src/components/payment/SendPayment.tsx)

Based on SRS wireframe at lines 1044-1134:

**Layout**
- Header with back button and "Send Payment" title
- Recipient input field with Paste and Scan QR buttons
- Amount input section with unit toggle
- Payment details card showing type, network fee, total
- Warning box about irreversibility
- Send Payment button (disabled until valid input)

**Functionality**
- Accept input via paste or QR scan using `expo-camera`
- Auto-detect payment type using `LNURLService.detectPaymentType()`
- For Bolt11: decode using `parseInvoice()`, display details
- For LNURL: resolve and show amount range
- For Lightning address: resolve to LNURL-Pay
- Call `prepareSendPayment()` to estimate fees
- Show confirmation dialog with all details
- Execute `sendPayment()` on confirmation
- Display loading state during payment (max 10s)
- Show success/failure result with appropriate messaging

**Error Handling**
- Insufficient funds: Show balance, suggest amount adjustment
- Invoice expired: Prompt to request new invoice
- Route not found: Suggest retry or on-chain alternative
- Invalid input: Clear field, show validation message
- Network error: Enable retry with exponential backoff

#### 5.3 PaymentHistory Component (file:src/components/payment/PaymentHistory.tsx)

Based on SRS wireframe at lines 1369-1500:

**Layout**
- Header with "Transaction History" title
- Search bar for filtering transactions
- Filter chips: All, Lightning Sent, Lightning Received, Withdrawals
- Transaction list with infinite scroll
- Each item shows: icon, description, date, amount (colored by type)
- Pull-to-refresh functionality

**Functionality**
- Load initial 50 transactions using `listPayments()`
- Implement infinite scroll with pagination (offset/limit)
- Filter by payment type using filter chips
- Search by description or amount
- Pull-to-refresh to sync latest transactions
- Tap transaction to navigate to detail view
- Display relative timestamps ("2 hours ago", "Yesterday")

**Transaction Item**
- Icon: ⚡ for Lightning, ↓ for received, 🔗 for withdrawal
- Description from invoice or auto-generated
- Timestamp with relative formatting
- Amount with + (green) for received, - (red) for sent
- Status indicator for pending transactions

#### 5.4 InvoiceDisplay Component (file:src/components/payment/InvoiceDisplay.tsx)

Reusable component for displaying invoices:

**Props**
- `invoice`: Bolt11 string
- `amount`: Amount in msats
- `description`: Invoice description
- `expiresAt`: Expiration timestamp
- `onCopy`: Callback for copy action
- `onShare`: Callback for share action

**Features**
- QR code generation using `react-native-qrcode-svg`
- Configurable QR size (default 200x200)
- Invoice text with copy button
- Expiry countdown timer
- Visual feedback on copy/share actions

#### 5.5 QRCodeScanner Component (file:src/components/payment/QRCodeScanner.tsx)

Modal component for scanning QR codes:

**Implementation**
- Use `expo-camera` with `CameraView` component
- Configure `barcodeScannerSettings` for QR codes
- Request camera permissions using `useCameraPermissions`
- Handle `onBarcodeScanned` event
- Validate scanned data before returning
- Show scanning overlay with targeting frame
- Provide manual input fallback option
- Close modal after successful scan

#### 5.6 PaymentConfirmation Component (file:src/components/payment/PaymentConfirmation.tsx)

Modal dialog for confirming payments:

**Display**
- Payment type (Lightning, LNURL, Lightning Address)
- Recipient information (truncated invoice or address)
- Amount in selected unit
- Estimated network fee
- Total amount to be sent
- Warning about irreversibility

**Actions**
- Cancel button (dismiss modal)
- Confirm button (execute payment)
- Loading state during payment execution
- Success/failure result display

### 6. State Management

#### 6.1 Payment Redux Slice (file:src/store/paymentSlice.ts)

Create Redux slice for payment state:

**State Shape**
```typescript
{
  payments: Payment[],
  pendingPayments: Payment[],
  balance: {
    totalMsat: number,
    inboundMsat: number,
    outboundMsat: number
  },
  activeInvoice: Invoice | null,
  loading: boolean,
  error: string | null
}
```

**Actions**
- `addPayment`: Add new payment to history
- `updatePayment`: Update payment status
- `setBalance`: Update wallet balance
- `setActiveInvoice`: Set currently monitored invoice
- `clearActiveInvoice`: Clear after payment received
- `setLoading`: Toggle loading state
- `setError`: Set error message

**Selectors**
- `selectPayments`: Get all payments
- `selectPendingPayments`: Get pending payments
- `selectBalance`: Get current balance
- `selectRecentPayments`: Get last 5 payments for dashboard

### 7. Validation and Error Handling

#### 7.1 Payment Validation (file:src/utils/paymentValidation.ts)

Implement validation functions:

**validateBolt11()**
- Check format using regex
- Verify checksum
- Validate not expired
- Return validation result

**validateLightningAddress()**
- Match regex pattern per FR-PAY-006-01
- Check domain validity
- Return validation result

**validateAmount()**
- Check positive value
- Verify sufficient balance
- Validate within LNURL min/max range if applicable
- Return validation result

**validateBitcoinAddress()**
- Support bech32, P2SH, P2PKH formats
- Verify checksum
- Return validation result

#### 7.2 Error Messages (file:src/utils/errorMessages.ts)

Map SDK errors to user-friendly messages per SRS section 7.6.1:

- `NetworkError` → "Connection lost. Please check your internet."
- `InsufficientFunds` → "Insufficient balance for this payment."
- `InvoiceExpired` → "This invoice has expired."
- `RouteNotFound` → "Unable to find payment route. Try again."
- `InvalidInput` → "Invalid address or invoice."
- `LspError` → "Service temporarily unavailable."

Include recovery suggestions and retry options where appropriate.

### 8. Integration with Existing Components

#### 8.1 Dashboard Integration

Update dashboard screen to:
- Display recent payments using `selectRecentPayments` selector
- Show quick action buttons: Send, Receive, Withdraw, Scan
- Display current balance from Redux store
- Navigate to payment screens on button press

#### 8.2 Navigation Setup

Add navigation routes:
- `/send` → SendPayment screen
- `/receive` → ReceivePayment screen
- `/history` → PaymentHistory screen
- `/payment/:id` → Payment detail screen

Configure deep linking for Lightning URIs and LNURL.

### 9. Testing Considerations

**Unit Tests**
- Test payment service methods with mocked Breez SDK
- Test validation functions with various inputs
- Test error message mapping
- Test state management actions and reducers

**Integration Tests**
- Test payment flow end-to-end on testnet
- Test LNURL-Pay and LNURL-Withdraw flows
- Test Lightning address resolution
- Test event handling and UI updates

**Performance Tests**
- Verify payment creation < 2 seconds
- Verify payment execution < 10 seconds
- Verify UI updates < 500ms after events
- Verify list rendering with 1000+ transactions

### 10. Performance Optimizations

**Caching**
- Cache Lightning address resolutions for 24 hours
- Cache payment history (last 1000 transactions)
- Implement virtual scrolling for long payment lists

**Debouncing**
- Debounce amount input to reduce re-renders
- Debounce search input in payment history

**Memoization**
- Memoize payment list filtering and sorting
- Memoize QR code generation
- Use React.memo for list items

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant UI
    participant Service
    participant BreezSDK
    participant Events
    participant Store

    Note over User,Store: Receive Payment Flow
    User->>UI: Enter amount & description
    UI->>Service: createInvoice(amount, desc)
    Service->>BreezSDK: receivePayment()
    BreezSDK-->>Service: Invoice (bolt11, hash)
    Service-->>UI: Invoice data
    UI->>UI: Display QR & text
    User->>UI: Copy/Share invoice
    
    Note over Events,Store: Payment Monitoring
    BreezSDK->>Events: paymentReceived event
    Events->>Store: addPayment()
    Events->>Store: updateBalance()
    Store-->>UI: State update
    UI->>UI: Show notification
    UI->>UI: Update balance

    Note over User,Store: Send Payment Flow
    User->>UI: Scan/Paste invoice
    UI->>Service: detectPaymentType(input)
    Service-->>UI: Type (Bolt11/LNURL/Address)
    UI->>Service: parseInvoice(bolt11)
    Service->>BreezSDK: parseInvoice()
    BreezSDK-->>Service: Invoice details
    Service-->>UI: Amount, description, fee
    UI->>UI: Show confirmation
    User->>UI: Confirm payment
    UI->>Service: sendPayment(bolt11)
    Service->>BreezSDK: sendPayment()
    BreezSDK->>Events: paymentSent event
    Events->>Store: addPayment()
    Events->>Store: updateBalance()
    BreezSDK-->>Service: Payment result
    Service-->>UI: Success/Failure
    UI->>UI: Show result
```

---

Execution Information

Branch: main
Commit: 342104b

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

The project is a Lightning-only Bitcoin wallet using Breez SDK Spark (Nodeless) with Expo/React Native. Currently, only documentation exists (file:docs/BRS.md and file:docs/SRS.md). The SRS defines comprehensive requirements for payment operations (FR-PAY-002 through FR-PAY-006) with detailed acceptance criteria, UI wireframes, and Breez SDK integration specifications. Dependencies include tickets #1 (Expo setup), #2 (wallet creation), and #3 (SDK initialization), which must be completed first. The Breez SDK provides native support for Lightning payments, LNURL, and Lightning addresses through methods like receivePayment(), sendPayment(), parseInvoice(), and listPayments().

Approach

The implementation follows an event-driven architecture leveraging Breez SDK's built-in capabilities. Create service layer abstractions for payment operations that wrap SDK methods with error handling and state management. Build React Native UI components matching the SRS wireframes for send/receive/history screens. Implement real-time payment monitoring through SDK event listeners (paymentReceived, paymentSent, paymentFailed) that trigger immediate UI updates and balance refreshes. Use native Expo modules for QR code generation/scanning and clipboard operations. Structure the code to handle LNURL and Lightning addresses transparently through Breez SDK's automatic detection and resolution.

Implementation Steps

1. Project Structure Setup

Create the following directory structure for payment operations:

src/
├── services/
│   ├── payment/
│   │   ├── PaymentService.ts
│   │   ├── InvoiceService.ts
│   │   ├── LNURLService.ts
│   │   └── types.ts
├── components/
│   ├── payment/
│   │   ├── ReceivePayment.tsx
│   │   ├── SendPayment.tsx
│   │   ├── PaymentHistory.tsx
│   │   ├── InvoiceDisplay.tsx
│   │   ├── QRCodeScanner.tsx
│   │   └── PaymentConfirmation.tsx
├── hooks/
│   ├── usePayments.ts
│   ├── useInvoice.ts
│   └── usePaymentEvents.ts
├── store/
│   └── paymentSlice.ts
└── utils/
    ├── paymentValidation.ts
    └── errorMessages.ts

2. Install Required Dependencies

Add the following packages to support payment operations:

• react-native-qrcode-svg and react-native-svg for QR code generation
• expo-camera for QR code scanning (already in SRS config)
• expo-clipboard for copy functionality
• expo-sharing for share functionality
• expo-haptics for tactile feedback on payment events

Update app.json to include camera and biometric permissions as specified in SRS section 8.1.1.

3. Payment Service Layer

3.1 Create PaymentService (file:src/services/payment/PaymentService.ts)

Implement core payment operations wrapping Breez SDK methods:

receivePayment()

• Accept parameters: { amountMsat?: number, description?: string, expiry?: number }
• Call Breez SDK receivePayment() method
• Return invoice object with bolt11, paymentHash, expiresAt
• Handle errors: network failures, SDK not initialized
• Default expiry: 3600 seconds (1 hour) per FR-PAY-003-05

sendPayment()

• Accept parameters: { bolt11: string, amountMsat?: number }
• First call parseInvoice() to decode and validate
• Call prepareSendPayment() to get fee estimate
• Execute sendPayment() with confirmation
• Monitor payment status via SDK events
• Timeout after 10 seconds per AC-PAY-004-05
• Return payment result with paymentHash, feeMsat, status

parseInvoice()

• Accept Bolt11 invoice string
• Call Breez SDK parseInvoice() method
• Return decoded invoice details: amount, description, payee, expiry
• Validate invoice format and expiration
• Handle errors: invalid format, expired invoice

listPayments()

• Accept filter parameters: { filter?: PaymentType[], fromTimestamp?: number, toTimestamp?: number, offset?: number, limit?: number }
• Call Breez SDK listPayments() method
• Default limit: 50 transactions per page (per SRS section 4.5)
• Return array of payment objects with type, amount, timestamp, status
• Support pagination for infinite scroll

3.2 Create InvoiceService (file:src/services/payment/InvoiceService.ts)

Handle invoice-specific operations:

createInvoice()

• Wrapper around receivePayment() with additional validation
• Validate amount is positive if provided
• Sanitize description (max 639 bytes per FR-PAY-003)
• Generate QR code data (uppercase Bolt11 string)
• Store invoice in local state for monitoring

monitorInvoice()

• Register listener for paymentReceived event
• Match incoming payment to invoice by paymentHash
• Trigger callback when payment received
• Update balance immediately per AC-PAY-002-06
• Show notification within 1 second per AC-PAY-002-05
• Clean up listener after payment or expiry

validateInvoice()

• Check invoice format (Bolt11 regex)
• Verify not expired
• Decode and validate amount if present
• Return validation result with error messages

3.3 Create LNURLService (file:src/services/payment/LNURLService.ts)

Handle LNURL and Lightning address operations:

detectPaymentType()

• Accept input string (invoice, LNURL, Lightning address, Bitcoin address)
• Use regex patterns to detect type:
  • Bolt11: starts with lnbc, lntb
  • LNURL: starts with lnurl or lightning:
  • Lightning address: matches ^[a-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,}$
  • Bitcoin address: bech32, P2SH, P2PKH formats
• Return payment type enum

resolveLightningAddress()

• Validate Lightning address format per FR-PAY-006-01
• Call Breez SDK to resolve address to LNURL-Pay endpoint
• Cache resolved endpoint for 24 hours per AC-PAY-006-05
• Return LNURL-Pay request object
• Handle errors: invalid format, resolution failure, network timeout

handleLNURLPay()

• Parse LNURL using Breez SDK parseLnurl()
• Display metadata (description, images) per AC-PAY-005-04
• Validate amount within min/max range per AC-PAY-005-02
• Call lnurlPay() with amount and optional comment
• Complete within 15 seconds per AC-PAY-005-05
• Return payment result

handleLNURLWithdraw()

• Parse LNURL-Withdraw request
• Automatically withdraw available amount per AC-PAY-005-03
• Create invoice via receivePayment()
• Submit invoice to LNURL service
• Monitor for incoming payment
• Complete within 15 seconds

4. Payment Event Handling

4.1 Create usePaymentEvents Hook (file:src/hooks/usePaymentEvents.ts)

Implement real-time payment monitoring:

Setup Event Listeners

• Register listeners on component mount for:
  • paymentReceived: Update balance, show notification, add to history
  • paymentSent: Update balance, show confirmation, add to history
  • paymentFailed: Show error message, log details, enable retry
• Clean up listeners on unmount

Event Processing

• Process events asynchronously
• Update UI within 500ms per SRS section 7.4.2
• Persist events to local database
• Trigger haptic feedback for payment events
• Update Redux store with new payment data

Balance Updates

• Listen to nodeStateChanged event
• Extract channelsBalanceMsat from node state
• Update balance display immediately
• Refresh inbound/outbound liquidity indicators

5. UI Components

5.1 ReceivePayment Component (file:src/components/payment/ReceivePayment.tsx)

Based on SRS wireframe at lines 1154-1221:

Layout

• Header with back button and "Receive Payment" title
• Amount input section (optional) with unit toggle (sats/BTC)
• QR code display section using react-native-qrcode-svg
• Invoice text display (monospace font, scrollable)
• Action buttons: Copy and Share
• Info box with expiry information
• Countdown timer showing remaining validity

Functionality

• Call InvoiceService.createInvoice() when amount entered or on mount
• Generate QR code from Bolt11 invoice (200x200px)
• Copy invoice to clipboard using expo-clipboard
• Share invoice using expo-sharing
• Monitor invoice status via usePaymentEvents
• Show success animation when payment received
• Auto-navigate back to dashboard after successful payment

State Management

• Local state: amount, description, invoice, QR data, expiry timer
• Redux state: payment status, balance updates

5.2 SendPayment Component (file:src/components/payment/SendPayment.tsx)

Based on SRS wireframe at lines 1044-1134:

Layout

• Header with back button and "Send Payment" title
• Recipient input field with Paste and Scan QR buttons
• Amount input section with unit toggle
• Payment details card showing type, network fee, total
• Warning box about irreversibility
• Send Payment button (disabled until valid input)

Functionality

• Accept input via paste or QR scan using expo-camera
• Auto-detect payment type using LNURLService.detectPaymentType()
• For Bolt11: decode using parseInvoice(), display details
• For LNURL: resolve and show amount range
• For Lightning address: resolve to LNURL-Pay
• Call prepareSendPayment() to estimate fees
• Show confirmation dialog with all details
• Execute sendPayment() on confirmation
• Display loading state during payment (max 10s)
• Show success/failure result with appropriate messaging

Error Handling

• Insufficient funds: Show balance, suggest amount adjustment
• Invoice expired: Prompt to request new invoice
• Route not found: Suggest retry or on-chain alternative
• Invalid input: Clear field, show validation message
• Network error: Enable retry with exponential backoff

5.3 PaymentHistory Component (file:src/components/payment/PaymentHistory.tsx)

Based on SRS wireframe at lines 1369-1500:

Layout

• Header with "Transaction History" title
• Search bar for filtering transactions
• Filter chips: All, Lightning Sent, Lightning Received, Withdrawals
• Transaction list with infinite scroll
• Each item shows: icon, description, date, amount (colored by type)
• Pull-to-refresh functionality

Functionality

• Load initial 50 transactions using listPayments()
• Implement infinite scroll with pagination (offset/limit)
• Filter by payment type using filter chips
• Search by description or amount
• Pull-to-refresh to sync latest transactions
• Tap transaction to navigate to detail view
• Display relative timestamps ("2 hours ago", "Yesterday")

Transaction Item

• Icon: ⚡ for Lightning, ↓ for received, 🔗 for withdrawal
• Description from invoice or auto-generated
• Timestamp with relative formatting
• Amount with + (green) for received, - (red) for sent
• Status indicator for pending transactions

5.4 InvoiceDisplay Component (file:src/components/payment/InvoiceDisplay.tsx)

Reusable component for displaying invoices:

Props

• invoice: Bolt11 string
• amount: Amount in msats
• description: Invoice description
• expiresAt: Expiration timestamp
• onCopy: Callback for copy action
• onShare: Callback for share action

Features

• QR code generation using react-native-qrcode-svg
• Configurable QR size (default 200x200)
• Invoice text with copy button
• Expiry countdown timer
• Visual feedback on copy/share actions

5.5 QRCodeScanner Component (file:src/components/payment/QRCodeScanner.tsx)

Modal component for scanning QR codes:

Implementation

• Use expo-camera with CameraView component
• Configure barcodeScannerSettings for QR codes
• Request camera permissions using useCameraPermissions
• Handle onBarcodeScanned event
• Validate scanned data before returning
• Show scanning overlay with targeting frame
• Provide manual input fallback option
• Close modal after successful scan

5.6 PaymentConfirmation Component (file:src/components/payment/PaymentConfirmation.tsx)

Modal dialog for confirming payments:

Display

• Payment type (Lightning, LNURL, Lightning Address)
• Recipient information (truncated invoice or address)
• Amount in selected unit
• Estimated network fee
• Total amount to be sent
• Warning about irreversibility

Actions

• Cancel button (dismiss modal)
• Confirm button (execute payment)
• Loading state during payment execution
• Success/failure result display

6. State Management

6.1 Payment Redux Slice (file:src/store/paymentSlice.ts)

Create Redux slice for payment state:

State Shape

{
  payments: Payment[],
  pendingPayments: Payment[],
  balance: {
    totalMsat: number,
    inboundMsat: number,
    outboundMsat: number
  },
  activeInvoice: Invoice | null,
  loading: boolean,
  error: string | null
}

Actions

• addPayment: Add new payment to history
• updatePayment: Update payment status
• setBalance: Update wallet balance
• setActiveInvoice: Set currently monitored invoice
• clearActiveInvoice: Clear after payment received
• setLoading: Toggle loading state
• setError: Set error message

Selectors

• selectPayments: Get all payments
• selectPendingPayments: Get pending payments
• selectBalance: Get current balance
• selectRecentPayments: Get last 5 payments for dashboard

7. Validation and Error Handling

7.1 Payment Validation (file:src/utils/paymentValidation.ts)

Implement validation functions:

validateBolt11()

• Check format using regex
• Verify checksum
• Validate not expired
• Return validation result

validateLightningAddress()

• Match regex pattern per FR-PAY-006-01
• Check domain validity
• Return validation result

validateAmount()

• Check positive value
• Verify sufficient balance
• Validate within LNURL min/max range if applicable
• Return validation result

validateBitcoinAddress()

• Support bech32, P2SH, P2PKH formats
• Verify checksum
• Return validation result

7.2 Error Messages (file:src/utils/errorMessages.ts)

Map SDK errors to user-friendly messages per SRS section 7.6.1:

• NetworkError → "Connection lost. Please check your internet."
• InsufficientFunds → "Insufficient balance for this payment."
• InvoiceExpired → "This invoice has expired."
• RouteNotFound → "Unable to find payment route. Try again."
• InvalidInput → "Invalid address or invoice."
• LspError → "Service temporarily unavailable."

Include recovery suggestions and retry options where appropriate.

8. Integration with Existing Components

8.1 Dashboard Integration

Update dashboard screen to:

• Display recent payments using selectRecentPayments selector
• Show quick action buttons: Send, Receive, Withdraw, Scan
• Display current balance from Redux store
• Navigate to payment screens on button press

8.2 Navigation Setup

Add navigation routes:

• /send → SendPayment screen
• /receive → ReceivePayment screen
• /history → PaymentHistory screen
• /payment/:id → Payment detail screen

Configure deep linking for Lightning URIs and LNURL.

9. Testing Considerations

Unit Tests

• Test payment service methods with mocked Breez SDK
• Test validation functions with various inputs
• Test error message mapping
• Test state management actions and reducers

Integration Tests

• Test payment flow end-to-end on testnet
• Test LNURL-Pay and LNURL-Withdraw flows
• Test Lightning address resolution
• Test event handling and UI updates

Performance Tests

• Verify payment creation < 2 seconds
• Verify payment execution < 10 seconds
• Verify UI updates < 500ms after events
• Verify list rendering with 1000+ transactions

10. Performance Optimizations

Caching

• Cache Lightning address resolutions for 24 hours
• Cache payment history (last 1000 transactions)
• Implement virtual scrolling for long payment lists

Debouncing

• Debounce amount input to reduce re-renders
• Debounce search input in payment history

Memoization

• Memoize payment list filtering and sorting
• Memoize QR code generation
• Use React.memo for list items

Architecture Diagram

sequenceDiagram
    participant User
    participant UI
    participant Service
    participant BreezSDK
    participant Events
    participant Store

    Note over User,Store: Receive Payment Flow
    User->>UI: Enter amount & description
    UI->>Service: createInvoice(amount, desc)
    Service->>BreezSDK: receivePayment()
    BreezSDK-->>Service: Invoice (bolt11, hash)
    Service-->>UI: Invoice data
    UI->>UI: Display QR & text
    User->>UI: Copy/Share invoice
    
    Note over Events,Store: Payment Monitoring
    BreezSDK->>Events: paymentReceived event
    Events->>Store: addPayment()
    Events->>Store: updateBalance()
    Store-->>UI: State update
    UI->>UI: Show notification
    UI->>UI: Update balance

    Note over User,Store: Send Payment Flow
    User->>UI: Scan/Paste invoice
    UI->>Service: detectPaymentType(input)
    Service-->>UI: Type (Bolt11/LNURL/Address)
    UI->>Service: parseInvoice(bolt11)
    Service->>BreezSDK: parseInvoice()
    BreezSDK-->>Service: Invoice details
    Service-->>UI: Amount, description, fee
    UI->>UI: Show confirmation
    User->>UI: Confirm payment
    UI->>Service: sendPayment(bolt11)
    Service->>BreezSDK: sendPayment()
    BreezSDK->>Events: paymentSent event
    Events->>Store: addPayment()
    Events->>Store: updateBalance()
    BreezSDK-->>Service: Payment result
    Service-->>UI: Success/Failure
    UI->>UI: Show result

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The project is a Lightning-only Bitcoin wallet using Breez SDK Spark (Nodeless) with Expo/React Native. Currently, only documentation exists (file:docs/BRS.md and file:docs/SRS.md). The SRS defines comprehensive requirements for payment operations (FR-PAY-002 through FR-PAY-006) with detailed acceptance criteria, UI wireframes, and Breez SDK integration specifications. Dependencies include tickets #1 (Expo setup), #2 (wallet creation), and #3 (SDK initialization), which must be completed first. The Breez SDK provides native support for Lightning payments, LNURL, and Lightning addresses through methods like `receivePayment()`, `sendPayment()`, `parseInvoice()`, and `listPayments()`.

## Approach

The implementation follows an event-driven architecture leveraging Breez SDK's built-in capabilities. Create service layer abstractions for payment operations that wrap SDK methods with error handling and state management. Build React Native UI components matching the SRS wireframes for send/receive/history screens. Implement real-time payment monitoring through SDK event listeners (`paymentReceived`, `paymentSent`, `paymentFailed`) that trigger immediate UI updates and balance refreshes. Use native Expo modules for QR code generation/scanning and clipboard operations. Structure the code to handle LNURL and Lightning addresses transparently through Breez SDK's automatic detection and resolution.

## Implementation Steps

### 1. Project Structure Setup

Create the following directory structure for payment operations:

```
src/
├── services/
│   ├── payment/
│   │   ├── PaymentService.ts
│   │   ├── InvoiceService.ts
│   │   ├── LNURLService.ts
│   │   └── types.ts
├── components/
│   ├── payment/
│   │   ├── ReceivePayment.tsx
│   │   ├── SendPayment.tsx
│   │   ├── PaymentHistory.tsx
│   │   ├── InvoiceDisplay.tsx
│   │   ├── QRCodeScanner.tsx
│   │   └── PaymentConfirmation.tsx
├── hooks/
│   ├── usePayments.ts
│   ├── useInvoice.ts
│   └── usePaymentEvents.ts
├── store/
│   └── paymentSlice.ts
└── utils/
    ├── paymentValidation.ts
    └── errorMessages.ts
```

### 2. Install Required Dependencies

Add the following packages to support payment operations:

- `react-native-qrcode-svg` and `react-native-svg` for QR code generation
- `expo-camera` for QR code scanning (already in SRS config)
- `expo-clipboard` for copy functionality
- `expo-sharing` for share functionality
- `expo-haptics` for tactile feedback on payment events

Update `app.json` to include camera and biometric permissions as specified in SRS section 8.1.1.

### 3. Payment Service Layer

#### 3.1 Create PaymentService (file:src/services/payment/PaymentService.ts)

Implement core payment operations wrapping Breez SDK methods:

**receivePayment()**
- Accept parameters: `{ amountMsat?: number, description?: string, expiry?: number }`
- Call Breez SDK `receivePayment()` method
- Return invoice object with `bolt11`, `paymentHash`, `expiresAt`
- Handle errors: network failures, SDK not initialized
- Default expiry: 3600 seconds (1 hour) per FR-PAY-003-05

**sendPayment()**
- Accept parameters: `{ bolt11: string, amountMsat?: number }`
- First call `parseInvoice()` to decode and validate
- Call `prepareSendPayment()` to get fee estimate
- Execute `sendPayment()` with confirmation
- Monitor payment status via SDK events
- Timeout after 10 seconds per AC-PAY-004-05
- Return payment result with `paymentHash`, `feeMsat`, `status`

**parseInvoice()**
- Accept Bolt11 invoice string
- Call Breez SDK `parseInvoice()` method
- Return decoded invoice details: amount, description, payee, expiry
- Validate invoice format and expiration
- Handle errors: invalid format, expired invoice

**listPayments()**
- Accept filter parameters: `{ filter?: PaymentType[], fromTimestamp?: number, toTimestamp?: number, offset?: number, limit?: number }`
- Call Breez SDK `listPayments()` method
- Default limit: 50 transactions per page (per SRS section 4.5)
- Return array of payment objects with type, amount, timestamp, status
- Support pagination for infinite scroll

#### 3.2 Create InvoiceService (file:src/services/payment/InvoiceService.ts)

Handle invoice-specific operations:

**createInvoice()**
- Wrapper around `receivePayment()` with additional validation
- Validate amount is positive if provided
- Sanitize description (max 639 bytes per FR-PAY-003)
- Generate QR code data (uppercase Bolt11 string)
- Store invoice in local state for monitoring

**monitorInvoice()**
- Register listener for `paymentReceived` event
- Match incoming payment to invoice by `paymentHash`
- Trigger callback when payment received
- Update balance immediately per AC-PAY-002-06
- Show notification within 1 second per AC-PAY-002-05
- Clean up listener after payment or expiry

**validateInvoice()**
- Check invoice format (Bolt11 regex)
- Verify not expired
- Decode and validate amount if present
- Return validation result with error messages

#### 3.3 Create LNURLService (file:src/services/payment/LNURLService.ts)

Handle LNURL and Lightning address operations:

**detectPaymentType()**
- Accept input string (invoice, LNURL, Lightning address, Bitcoin address)
- Use regex patterns to detect type:
  - Bolt11: starts with `lnbc`, `lntb`
  - LNURL: starts with `lnurl` or `lightning:`
  - Lightning address: matches `^[a-z0-9._-]+@[a-z0-9.-]+\.[a-z]{2,}$`
  - Bitcoin address: bech32, P2SH, P2PKH formats
- Return payment type enum

**resolveLightningAddress()**
- Validate Lightning address format per FR-PAY-006-01
- Call Breez SDK to resolve address to LNURL-Pay endpoint
- Cache resolved endpoint for 24 hours per AC-PAY-006-05
- Return LNURL-Pay request object
- Handle errors: invalid format, resolution failure, network timeout

**handleLNURLPay()**
- Parse LNURL using Breez SDK `parseLnurl()`
- Display metadata (description, images) per AC-PAY-005-04
- Validate amount within min/max range per AC-PAY-005-02
- Call `lnurlPay()` with amount and optional comment
- Complete within 15 seconds per AC-PAY-005-05
- Return payment result

**handleLNURLWithdraw()**
- Parse LNURL-Withdraw request
- Automatically withdraw available amount per AC-PAY-005-03
- Create invoice via `receivePayment()`
- Submit invoice to LNURL service
- Monitor for incoming payment
- Complete within 15 seconds

### 4. Payment Event Handling

#### 4.1 Create usePaymentEvents Hook (file:src/hooks/usePaymentEvents.ts)

Implement real-time payment monitoring:

**Setup Event Listeners**
- Register listeners on component mount for:
  - `paymentReceived`: Update balance, show notification, add to history
  - `paymentSent`: Update balance, show confirmation, add to history
  - `paymentFailed`: Show error message, log details, enable retry
- Clean up listeners on unmount

**Event Processing**
- Process events asynchronously
- Update UI within 500ms per SRS section 7.4.2
- Persist events to local database
- Trigger haptic feedback for payment events
- Update Redux store with new payment data

**Balance Updates**
- Listen to `nodeStateChanged` event
- Extract `channelsBalanceMsat` from node state
- Update balance display immediately
- Refresh inbound/outbound liquidity indicators

### 5. UI Components

#### 5.1 ReceivePayment Component (file:src/components/payment/ReceivePayment.tsx)

Based on SRS wireframe at lines 1154-1221:

**Layout**
- Header with back button and "Receive Payment" title
- Amount input section (optional) with unit toggle (sats/BTC)
- QR code display section using `react-native-qrcode-svg`
- Invoice text display (monospace font, scrollable)
- Action buttons: Copy and Share
- Info box with expiry information
- Countdown timer showing remaining validity

**Functionality**
- Call `InvoiceService.createInvoice()` when amount entered or on mount
- Generate QR code from Bolt11 invoice (200x200px)
- Copy invoice to clipboard using `expo-clipboard`
- Share invoice using `expo-sharing`
- Monitor invoice status via `usePaymentEvents`
- Show success animation when payment received
- Auto-navigate back to dashboard after successful payment

**State Management**
- Local state: amount, description, invoice, QR data, expiry timer
- Redux state: payment status, balance updates

#### 5.2 SendPayment Component (file:src/components/payment/SendPayment.tsx)

Based on SRS wireframe at lines 1044-1134:

**Layout**
- Header with back button and "Send Payment" title
- Recipient input field with Paste and Scan QR buttons
- Amount input section with unit toggle
- Payment details card showing type, network fee, total
- Warning box about irreversibility
- Send Payment button (disabled until valid input)

**Functionality**
- Accept input via paste or QR scan using `expo-camera`
- Auto-detect payment type using `LNURLService.detectPaymentType()`
- For Bolt11: decode using `parseInvoice()`, display details
- For LNURL: resolve and show amount range
- For Lightning address: resolve to LNURL-Pay
- Call `prepareSendPayment()` to estimate fees
- Show confirmation dialog with all details
- Execute `sendPayment()` on confirmation
- Display loading state during payment (max 10s)
- Show success/failure result with appropriate messaging

**Error Handling**
- Insufficient funds: Show balance, suggest amount adjustment
- Invoice expired: Prompt to request new invoice
- Route not found: Suggest retry or on-chain alternative
- Invalid input: Clear field, show validation message
- Network error: Enable retry with exponential backoff

#### 5.3 PaymentHistory Component (file:src/components/payment/PaymentHistory.tsx)

Based on SRS wireframe at lines 1369-1500:

**Layout**
- Header with "Transaction History" title
- Search bar for filtering transactions
- Filter chips: All, Lightning Sent, Lightning Received, Withdrawals
- Transaction list with infinite scroll
- Each item shows: icon, description, date, amount (colored by type)
- Pull-to-refresh functionality

**Functionality**
- Load initial 50 transactions using `listPayments()`
- Implement infinite scroll with pagination (offset/limit)
- Filter by payment type using filter chips
- Search by description or amount
- Pull-to-refresh to sync latest transactions
- Tap transaction to navigate to detail view
- Display relative timestamps ("2 hours ago", "Yesterday")

**Transaction Item**
- Icon: ⚡ for Lightning, ↓ for received, 🔗 for withdrawal
- Description from invoice or auto-generated
- Timestamp with relative formatting
- Amount with + (green) for received, - (red) for sent
- Status indicator for pending transactions

#### 5.4 InvoiceDisplay Component (file:src/components/payment/InvoiceDisplay.tsx)

Reusable component for displaying invoices:

**Props**
- `invoice`: Bolt11 string
- `amount`: Amount in msats
- `description`: Invoice description
- `expiresAt`: Expiration timestamp
- `onCopy`: Callback for copy action
- `onShare`: Callback for share action

**Features**
- QR code generation using `react-native-qrcode-svg`
- Configurable QR size (default 200x200)
- Invoice text with copy button
- Expiry countdown timer
- Visual feedback on copy/share actions

#### 5.5 QRCodeScanner Component (file:src/components/payment/QRCodeScanner.tsx)

Modal component for scanning QR codes:

**Implementation**
- Use `expo-camera` with `CameraView` component
- Configure `barcodeScannerSettings` for QR codes
- Request camera permissions using `useCameraPermissions`
- Handle `onBarcodeScanned` event
- Validate scanned data before returning
- Show scanning overlay with targeting frame
- Provide manual input fallback option
- Close modal after successful scan

#### 5.6 PaymentConfirmation Component (file:src/components/payment/PaymentConfirmation.tsx)

Modal dialog for confirming payments:

**Display**
- Payment type (Lightning, LNURL, Lightning Address)
- Recipient information (truncated invoice or address)
- Amount in selected unit
- Estimated network fee
- Total amount to be sent
- Warning about irreversibility

**Actions**
- Cancel button (dismiss modal)
- Confirm button (execute payment)
- Loading state during payment execution
- Success/failure result display

### 6. State Management

#### 6.1 Payment Redux Slice (file:src/store/paymentSlice.ts)

Create Redux slice for payment state:

**State Shape**
```typescript
{
  payments: Payment[],
  pendingPayments: Payment[],
  balance: {
    totalMsat: number,
    inboundMsat: number,
    outboundMsat: number
  },
  activeInvoice: Invoice | null,
  loading: boolean,
  error: string | null
}
```

**Actions**
- `addPayment`: Add new payment to history
- `updatePayment`: Update payment status
- `setBalance`: Update wallet balance
- `setActiveInvoice`: Set currently monitored invoice
- `clearActiveInvoice`: Clear after payment received
- `setLoading`: Toggle loading state
- `setError`: Set error message

**Selectors**
- `selectPayments`: Get all payments
- `selectPendingPayments`: Get pending payments
- `selectBalance`: Get current balance
- `selectRecentPayments`: Get last 5 payments for dashboard

### 7. Validation and Error Handling

#### 7.1 Payment Validation (file:src/utils/paymentValidation.ts)

Implement validation functions:

**validateBolt11()**
- Check format using regex
- Verify checksum
- Validate not expired
- Return validation result

**validateLightningAddress()**
- Match regex pattern per FR-PAY-006-01
- Check domain validity
- Return validation result

**validateAmount()**
- Check positive value
- Verify sufficient balance
- Validate within LNURL min/max range if applicable
- Return validation result

**validateBitcoinAddress()**
- Support bech32, P2SH, P2PKH formats
- Verify checksum
- Return validation result

#### 7.2 Error Messages (file:src/utils/errorMessages.ts)

Map SDK errors to user-friendly messages per SRS section 7.6.1:

- `NetworkError` → "Connection lost. Please check your internet."
- `InsufficientFunds` → "Insufficient balance for this payment."
- `InvoiceExpired` → "This invoice has expired."
- `RouteNotFound` → "Unable to find payment route. Try again."
- `InvalidInput` → "Invalid address or invoice."
- `LspError` → "Service temporarily unavailable."

Include recovery suggestions and retry options where appropriate.

### 8. Integration with Existing Components

#### 8.1 Dashboard Integration

Update dashboard screen to:
- Display recent payments using `selectRecentPayments` selector
- Show quick action buttons: Send, Receive, Withdraw, Scan
- Display current balance from Redux store
- Navigate to payment screens on button press

#### 8.2 Navigation Setup

Add navigation routes:
- `/send` → SendPayment screen
- `/receive` → ReceivePayment screen
- `/history` → PaymentHistory screen
- `/payment/:id` → Payment detail screen

Configure deep linking for Lightning URIs and LNURL.

### 9. Testing Considerations

**Unit Tests**
- Test payment service methods with mocked Breez SDK
- Test validation functions with various inputs
- Test error message mapping
- Test state management actions and reducers

**Integration Tests**
- Test payment flow end-to-end on testnet
- Test LNURL-Pay and LNURL-Withdraw flows
- Test Lightning address resolution
- Test event handling and UI updates

**Performance Tests**
- Verify payment creation < 2 seconds
- Verify payment execution < 10 seconds
- Verify UI updates < 500ms after events
- Verify list rendering with 1000+ transactions

### 10. Performance Optimizations

**Caching**
- Cache Lightning address resolutions for 24 hours
- Cache payment history (last 1000 transactions)
- Implement virtual scrolling for long payment lists

**Debouncing**
- Debounce amount input to reduce re-renders
- Debounce search input in payment history

**Memoization**
- Memoize payment list filtering and sorting
- Memoize QR code generation
- Use React.memo for list items

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant UI
    participant Service
    participant BreezSDK
    participant Events
    participant Store

    Note over User,Store: Receive Payment Flow
    User->>UI: Enter amount & description
    UI->>Service: createInvoice(amount, desc)
    Service->>BreezSDK: receivePayment()
    BreezSDK-->>Service: Invoice (bolt11, hash)
    Service-->>UI: Invoice data
    UI->>UI: Display QR & text
    User->>UI: Copy/Share invoice
    
    Note over Events,Store: Payment Monitoring
    BreezSDK->>Events: paymentReceived event
    Events->>Store: addPayment()
    Events->>Store: updateBalance()
    Store-->>UI: State update
    UI->>UI: Show notification
    UI->>UI: Update balance

    Note over User,Store: Send Payment Flow
    User->>UI: Scan/Paste invoice
    UI->>Service: detectPaymentType(input)
    Service-->>UI: Type (Bolt11/LNURL/Address)
    UI->>Service: parseInvoice(bolt11)
    Service->>BreezSDK: parseInvoice()
    BreezSDK-->>Service: Invoice details
    Service-->>UI: Amount, description, fee
    UI->>UI: Show confirmation
    User->>UI: Confirm payment
    UI->>Service: sendPayment(bolt11)
    Service->>BreezSDK: sendPayment()
    BreezSDK->>Events: paymentSent event
    Events->>Store: addPayment()
    Events->>Store: updateBalance()
    BreezSDK-->>Service: Payment result
    Service-->>UI: Success/Failure
    UI->>UI: Show result
```

---

Execution Information

Branch: main
Commit: 342104b