feat(webln): support Lightning Addresses in sendPayment

[naveenkumar29052006]

Describe the changes you have made in this PR

This PR extends window.webln.sendPayment() to support Lightning Addresses (e.g. alice@getalby.com) in addition to BOLT11 invoices.

When a Lightning Address is detected, it is resolved via LNURL-pay to obtain an invoice, after which the existing payment flow continues unchanged. Invoice-based payments behave exactly as before.

This improves WebLN developer experience and enables simpler Value-for-Value integrations (e.g. RSS readers, blogs, tipping flows) without requiring developers to manually resolve Lightning Addresses.

---

A clear and concise description of what you want to happen

Allow websites to call webln.sendPayment() with either:

• a BOLT11 invoice, or
• a Lightning Address

and have both work seamlessly and consistently.

---

Link this PR to an issue / bounty [optional]

Related bounty:
https://guides.getalby.com/developer-guide/bounties/alby-browser-extension-bounties#add-value-4-value-to-a-rss-reader

---

Type of change

• feat: New feature (non-breaking change which adds functionality)

---

Screenshots of the changes [optional]

N/A (no UI changes)

---

How has this been tested?

Manual testing with the Alby browser extension:

1. Tested webln.sendPayment(<bolt11_invoice>)

   • Payment flow works unchanged.

2. Tested webln.sendPayment(<lightning_address>)

   • Lightning Address is resolved via LNURL-pay.
   • Payment prompt opens and payment completes successfully.

3. Tested invalid Lightning Address input

   • A clear error is returned without crashing.

---

Checklist

• Self-review of changed code
• Manual testing
• Added automated tests where applicable
• Update Docs & Guides

---

For UI-related changes

N/A

Screen.Recording.2026-01-26.at.10.41.25.PM.mov

Summary by CodeRabbit

• New Features

  • Added support for Lightning addresses in payment requests.

• Bug Fixes

  • Improved error handling for payment request failures with clearer error messages.
  • Enhanced reliability when processing various payment request formats.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds LNURL Lightning address support to payment request handling, enabling resolution of Lightning addresses alongside existing Bolt11 decoding, with comprehensive error handling and conditional payment routing based on decoded payment details.

Changes

Cohort / File(s)	Summary
LNURL and Bolt11 Payment Resolution src/extension/background-script/actions/webln/sendPaymentOrPrompt.ts	Adds LNURL handling to detect and resolve Lightning addresses via lnurlLib; replaces direct Bolt11 decoding with guarded try/catch flow; introduces error handling for both LNURL resolution and Bolt11 decoding with descriptive error messages; implements conditional payment routing based on allowance checks and decoded payment details

Sequence Diagram

sequenceDiagram
    participant User as Payment Request<br/>Input
    participant Handler as sendPaymentOrPrompt<br/>Handler
    participant LNURL as LNURL<br/>Resolver
    participant Decoder as Bolt11<br/>Decoder
    participant Router as Payment<br/>Router
    
    User->>Handler: Payment Request (address/bolt11)
    
    alt Is Lightning Address
        Handler->>LNURL: Resolve LNURL
        alt Resolution Success
            LNURL-->>Handler: Payment Details
            Handler->>Handler: Check Detail Tag
            alt Tag is "payRequest"
                Handler->>Router: Route to lnurlPayWithPrompt
            else Other Tag
                Handler-->>User: Error Response
            end
        else Resolution Failure
            LNURL-->>Handler: Error
            Handler-->>User: "Failed to resolve<br/>Lightning Address"
        end
    else Is Bolt11
        Handler->>Decoder: Decode Bolt11
        alt Decode Success
            Decoder-->>Handler: Payment Details
            Handler->>Handler: Check Allowance
            alt Allowance OK
                Handler->>Router: Route to sendPaymentWithAllowance
            else No Allowance
                Handler->>Router: Route to payWithPrompt
            end
        else Decode Failure
            Decoder-->>Handler: Error
            Handler-->>User: Error Message
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 A lightning address now hops through the air,
LNURL resolves with a magical flare,
Bolt11 decodes with error's great care,
Payments now route with conditional flair—
More paths for the coins, more features to share! ⚡✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding Lightning Address support to the sendPayment function.
Description check	✅ Passed	The description comprehensively covers the required template sections including clear change description, issue link, feature type, testing approach, and completed checklist items.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

• 📝 Generate docstrings

---

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

[naveenkumar29052006]

@rolznz
Hi, I’ve created this PR as part of the Value-4-Value RSS Reader bounty to improve WebLN support for Lightning Addresses in sendPayment().

Whenever you have time, could you please take a look and let me know:

if the approach looks okay, and

if there are any changes or adjustments you’d like me to make.

Thanks a lot!

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/extension/background-script/actions/webln/sendPaymentOrPrompt.ts`:
- Around line 44-51: The try/catch around lightningPayReq.decode in
sendPaymentOrPrompt currently only handles Error instances and leaves non-Error
throws to be swallowed, so change the catch to always return an error when
decode fails (e.g., return { error: String(e) } for any thrown value) and
optionally add a guard that paymentRequestDetails is defined before calling
payWithPrompt; locate lightningPayReq.decode, the paymentRequestDetails variable
and the later call to payWithPrompt in sendPaymentOrPrompt to implement this
consistent error-return behavior.
- Around line 29-41: The code currently returns a generic "Failed to resolve
Lightning Address" when lnurlDetails resolves but has a tag other than
"payRequest", which is misleading; update the logic in sendPaymentOrPrompt so
that after resolving lnurlDetails you explicitly handle unsupported tags by
returning a clear error (e.g., return { error: `Unsupported LNURL type:
${lnurlDetails.tag}` }) when lnurlDetails.tag exists but !== "payRequest", keep
the existing path that calls lnurlPayWithPrompt for "payRequest", and also
ensure the catch block handles non-Error throws by returning a safe generic
error if e is not an instance of Error.