fix: offload bolt11_decode in list_transactions to worker thread

[BenGWeeks]

Take the proposed fix with a pinch of salt — drafted quickly with AI assistance. The diagnosis (synchronous bolt11_decode blocking the event loop) is grounded in reading the handler code, but the exact fix shape deserves maintainer review.

Summary

Fixes #35

_on_list_transactions in tasks.py calls the synchronous bolt11_decode() inside a Python for loop in an async handler. On wallets with non-trivial history this blocks the asyncio event loop long enough that:

• NWC clients hit their reply timeout (~60s) and see list_transactions fail
• Relay keep-alives, publish tasks, and concurrent NWC requests are starved
• LNbits logs show nothing useful — the handler is simply still running

Other NWC methods (get_info, get_balance, make_invoice, lookup_invoice) are unaffected because they don't do per-record synchronous CPU work in a loop.

Status

Draft — currently testing this fix in production (LNbits v1.5.3, LNDRest). Will mark ready for review once verified over a sustained period.

Fix

Offload each bolt11_decode call to a worker thread via asyncio.to_thread, so the event loop can keep running while each invoice is parsed. This is the same pattern used in lnbits/lnbits#3925 for analogous synchronous websocket calls in send_nostr_dm.

# before
invoice_data = bolt11_decode(p.bolt11)

# after
invoice_data = await asyncio.to_thread(bolt11_decode, p.bolt11)

asyncio is already imported; no new dependencies.

Why this matters

Together with the other two fixes that are already in production testing, this closes the last of three event-loop-starvation paths that collectively rendered NWC unusable on busy LNDRest-backed wallets:

Fix	Repo	Path
IN_FLIGHT polling hot-loop	lnbits/lnbits#3918	lnbits/core/services/payments.py
Blocking relay publishes	lnbits/lnbits#3925	lnbits/core/services/nostr.py
This PR	lnbits/nwcprovider	nwcprovider/tasks.py

Alternatives considered

• Defer decode to the client: pass raw bolt11 through and let the client decode. Smaller payload, no server CPU. But it changes the response schema (fields description, description_hash, and the invoice_data.date fallback for timestamp) and would break clients that rely on the current shape. Rejected for backward compatibility.
• Periodic asyncio.sleep(0) yields: works, but still runs all the CPU on the event-loop thread. asyncio.to_thread is cleaner and scales better.

Related

• Fixes [BUG] list_transactions blocks asyncio event loop in synchronous bolt11_decode loop #35
• Sibling fixes: fix: exponential backoff for IN_FLIGHT payment polling lnbits#3918, fix: non-blocking relay publishes in send_nostr_dm lnbits#3925
• Symptom: nostr client extension becomes temporarily unresponsive nostrclient#40 (nostrclient unresponsive — same event-loop starvation class)

Changes

• tasks.py: wrap bolt11_decode in asyncio.to_thread inside _on_list_transactions

🤖 Generated with Claude Code

[motorina0]

please drop the AI slop description

This is not a blocker operation, it runs in constant time.

invoice_data = bolt11_decode(p.bolt11)

Starting a new thread for each decode might actually degrade the overall performance.

invoice_data = await asyncio.to_thread(bolt11_decode, p.bolt11)

Is there a before/after performance test done?

[BenGWeeks]

Feel free to fix how ever you guys see fit - you know your solution better than I do.

The issue was that list_transactions would timeout and fail.

[riccardobl]

I see, the TL;DR is basically that you want to yield the event loop, not to make _on_list_transactions faster.
Actually makes sense. But as @motorina0 said, spamming threads is not the right solution, the proposed alternative await asyncio.sleep(0) is the right approach.

Could you please change the PR to reflect that? Or if you prefer i can commit the fix to main branch.

Thanks