[NWC] Phase 3: Automatic hold invoice payment for sellers via NWC

[mostronator]

Summary

Adds automatic Lightning invoice payment via NWC (Nostr Wallet Connect) to the buyer/seller escrow flow. When an NWC wallet is connected, users see a "Pay with Wallet" button instead of the manual QR code flow.

Changes

New Files

• lib/shared/widgets/nwc_payment_widget.dart — Reusable NWC payment widget with progress states (idle → paying → success/failed)
• docs/NWC_PHASE3_IMPLEMENTATION.md — Detailed implementation documentation

Modified Files

• lib/features/order/screens/pay_lightning_invoice_screen.dart — Detects NWC connection, shows auto-pay or manual flow
• lib/features/wallet/providers/nwc_provider.dart — Added payInvoice() method with auto balance refresh
• lib/l10n/intl_en.arb, intl_es.arb, intl_it.arb — 11 new localization strings

Features

• Balance-aware: Disables pay button if wallet balance < invoice amount
• Error handling: INSUFFICIENT_BALANCE, PAYMENT_FAILED, RATE_LIMITED, QUOTA_EXCEEDED, timeout — all with user-friendly messages in 3 languages
• Retry: Failed payments can be retried without leaving the screen
• Manual fallback: "Pay manually" link switches to QR code flow
• No regression: Manual flow unchanged when no NWC wallet connected

Flow

1. Mostro sends PaymentRequest with Lightning invoice
2. Screen detects NWC wallet connection
3. If connected → shows "Pay with Wallet" button + balance
4. On tap → animated progress → success ✅ or failure ❌
5. On failure → retry or fall back to manual QR flow
6. If not connected → original manual flow (no change)

Screenshots

UI follows existing app theme (AppTheme colors, lucide_icons, 12px border radius cards).

Testing

Manual testing with Coinos NWC wallet. Widget is stateless-safe (each instance manages own payment state).

References

• Phase 1: [NWC] Phase 1: Core NWC protocol library integration #456 (merged)
• Phase 2: [NWC] Phase 2: Wallet connection management UI #457 (merged)
• Closes [NWC] Phase 3: Automatic hold invoice payment for sellers via NWC #458
• NIP-47 pay_invoice

Summary by CodeRabbit

• New Features

  • Added Nostr Wallet Connect (NWC) integration for automatic invoice payments when a wallet is connected
  • New payment widget with balance awareness and multiple error states (timeout, insufficient funds, rate limits)
  • Fallback to manual payment if wallet payment fails

• Documentation

  • Comprehensive NWC Phase 3 implementation guide with flow diagrams and architecture details

• Localization

  • Added wallet payment UI strings across English, Spanish, and Italian

[coderabbitai]

Warning

Rate limit exceeded

@mostronator has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 9 minutes and 50 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

Walkthrough

Adds NWC Phase 3 implementation: automatic Lightning invoice payment via connected wallet. Introduces NwcPaymentWidget for UI/state management, payInvoice method to NwcNotifier, integrates NWC auto-pay flow into PayLightningInvoiceScreen with manual fallback, and adds localization strings for payment states across EN/ES/IT.

Changes

Cohort / File(s)	Summary
Documentation docs/NWC_PHASE3_IMPLEMENTATION.md	Comprehensive guide for NWC Phase 3: Automatic Invoice Payment including flow diagrams, component architecture, NwcPaymentWidget states, edge cases, and localization details.
NWC Payment Widget lib/shared/widgets/nwc_payment_widget.dart	New stateful widget enabling automatic invoice payment with NwcPaymentStatus enum (idle, paying, success, failed), balance awareness, error handling with user-friendly messages, and fallback-to-manual option.
NWC Provider Integration lib/features/wallet/providers/nwc_provider.dart	Adds payInvoice(String invoice) method to NwcNotifier with active connection check, client call, balance refresh on success, and error propagation.
Invoice Payment Screen lib/features/order/screens/pay_lightning_invoice_screen.dart	Conditionally renders NwcPaymentWidget when NWC connected; maintains original PayLightningInvoiceWidget as fallback. Introduces _manualMode flag for flow control and success/failure navigation.
Localization lib/l10n/intl_en.arb, lib/l10n/intl_es.arb, lib/l10n/intl_it.arb	Adds 10 new translation keys covering NWC payment states: payWithWallet, nwcPaymentSending/Success/Failed/Timeout, nwcInsufficientBalance, nwcRateLimited/QuotaExceeded, nwcRetryPayment, nwcPayManually.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Screen as PayLightningInvoiceScreen
    participant Widget as NwcPaymentWidget
    participant Notifier as NwcNotifier
    participant Client as NwcClient
    participant Wallet as Lightning Wallet
    
    User->>Screen: Navigate with invoice & amount
    Screen->>Screen: Check NWC connection status
    alt NWC Connected
        Screen->>Widget: Render with invoice & sats
        User->>Widget: Tap "Pay with Wallet"
        Widget->>Widget: Set status=paying
        Widget->>Notifier: payInvoice(lnInvoice)
        Notifier->>Client: payInvoice(PayInvoiceParams)
        Client->>Wallet: Request payment via NIP-47
        Wallet->>Wallet: Process & sign invoice
        Wallet-->>Client: PayInvoiceResult with preimage
        Client-->>Notifier: Return result
        Notifier->>Notifier: Call getBalance() to refresh
        Notifier-->>Widget: Return PayInvoiceResult
        Widget->>Widget: Set status=success
        Widget-->>User: Display preimage & success
        User->>Screen: Success callback
        Screen->>Screen: Navigate home
    else NWC Not Connected
        Screen->>Screen: Render manual flow
        User->>User: Copy & pay invoice manually
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• [NWC] Phase 4: Automatic invoice generation for buyers via NWC #459 — Both modifications to NwcNotifier provider; this adds payInvoice while #459 adds makeInvoice, building complementary NWC methods.
• [NWC] Phase 5: Payment notifications and enhanced UX #460 — Overlaps with Phase 5 requirements (pre-flight balance checks, wallet balance display, periodic refresh, post-payment verification).
• [NWC] Phase 2: Wallet connection management UI #457 — Phase 2 foundation that establishes NWC connection/management; Phase 3 builds on that infrastructure with payment capabilities.

Possibly related PRs

• [NWC] Phase 1: Core NWC protocol library #461 — Implements NWC core models and exceptions (PayInvoiceResult, NwcResponseException) that Phase 3 directly consumes in the new payInvoice method and error handling.
• Add order information when displaying or requesting the invoice #156 — Modifies the same pay_lightning_invoice_screen.dart file; integration needed to ensure UI flow compatibility with order-related fields.

Suggested reviewers

• grunch

Poem

🐰 A wallet connected, invoices take flight,
Payment flows swift through the NWC light,
No more copy-paste in the darkness of night,
One tap, and the balance shines crystal bright! ✨⚡

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title references Phase 3 and NWC automatic invoice payment, which aligns with the main objective of adding NWC-based automatic payment for invoices. However, the title specifies 'sellers' while the PR implementation and documentation are focused on the buyer flow for paying Lightning invoices, not seller-initiated payments.	Revise the title to accurately reflect the buyer flow context: '[NWC] Phase 3: Automatic Lightning invoice payment via NWC (buyer flow)' or similar to clarify this enables buyers to pay invoices automatically, not sellers to receive payments.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The PR fully implements all scope items from issue #458: NWC connection detection, payment UI with 'Pay with Wallet' option, payInvoice() implementation with balance refresh, error handling for specified cases (INSUFFICIENT_BALANCE, PAYMENT_FAILED, RATE_LIMITED, timeout), fallback to manual flow, manual flow preservation, and localized messages across EN/ES/IT.
Out of Scope Changes check	✅ Passed	All changes align with issue #458 scope: documentation added explaining the implementation, NwcPaymentWidget provides reusable payment UI, payInvoice() method integrates NWC payments, PayLightningInvoiceScreen conditionally renders NWC/manual flows, and localization supports the new feature without unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/nwc-auto-payment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@lib/shared/widgets/nwc_payment_widget.dart`:
- Around line 68-79: Replace the hardcoded "Preimage:" label with a localized
string (add a new key nwcPreimageLabel in all ARB files and use your app's
localization accessor, e.g. AppLocalizations.of(context).nwcPreimageLabel) and
stop calling substring directly on the preimage; instead add a small safe helper
(e.g. _preview(String? p, [int len = 8]) that returns p==null?'' : (p.length <=
len ? p : p.substring(0, len) + '...')) and use it wherever preimage previews
are shown (references: nwc_payment_widget, the code around
nwcNotifier.payInvoice, setState where _preimage is set, and logger.i calls) so
both the 8-char and 16-char previews use the safe helper.

[grunch]

tACK