Merge PR 'Document that TokioSpawner requires all of LDK in a tokio context' (#5621)
What changed, and why it matters
This change only adds documentation comments to a Rust struct. It does not modify any executable code, so it cannot by itself introduce or fix a security vulnerability. The new text warns developers that using TokioSpawner incorrectly can cause their program to panic (crash) if LDK runs outside a Tokio runtime. It is a documentation-only clarification, not a code patch.
No security action required. Treat as a normal documentation update. Developers using TokioSpawner should review the new guidance to avoid runtime panics, but this is operational guidance, not a vulnerability fix.
Security signals we found
Documentation-only change
No code logic modified
No unsafe blocks added
No new dependencies or features
No panic handling or runtime behavior changed
Evidence from the diff
The commit adds an 11-line doc comment to TokioSpawner in lightning-block-sync/src/gossip.rs. It explains that tokio::spawn panics outside a Tokio runtime context and that LDK may call FutureSpawner::spawn from threads such as the BackgroundProcessor thread, so users must either run all of LDK inside a Tokio runtime or use a spawner that holds a tokio::runtime::Handle. No code behavior changes.
Changed components
lightning-block-sync/src/gossip.rs documentationInspect captured patch +11 / −0
### lightning-block-sync/src/gossip.rs
@@ -44,6 +44,17 @@ pub trait UtxoSource: BlockSource + 'static {
#[cfg(feature = "tokio")]
/// A trivial [`FutureSpawner`] which delegates to `tokio::spawn`.
+///
+/// `tokio::spawn` panics when called from a thread which is not in the context of a `tokio`
+/// runtime, and LDK may call [`FutureSpawner::spawn`] on any thread which calls into LDK,
+/// including the plain `std::thread` run by `BackgroundProcessor::start`, which handles peer
+/// messages (and thus any UTXO lookups a [`GossipVerifier`] performs for them) in
+/// `PeerManager::process_events`.
+///
+/// Thus, users of this spawner must either ensure that *all* parts of LDK run inside the
+/// context of a `tokio` runtime (e.g. by polling `process_events_async` on the runtime rather
+/// than using `BackgroundProcessor::start`), or use a [`FutureSpawner`] implementation which
+/// stores a `tokio::runtime::Handle` and spawns on it instead.
pub struct TokioSpawner;
#[cfg(feature = "tokio")]
impl FutureSpawner for TokioSpawner {Why this scored 19/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.