AI-generated analysisPublished automatically and not human-verified. Validated context appears in community notes below.
← Watch feed
Moderate 68 Bitcoin

Fail HTLCs from late counterparty commitment updates after funding spend

Public commit record

What the developer wrote

Authored by Joost Jager

73/100 · Adequate
Fail HTLCs from late counterparty commitment updates after funding spend

When a ChannelMonitorUpdate containing a new counterparty commitment is
dispatched (e.g. via deferred writes) before a channel force-closes but
only applied to the in-memory monitor after the commitment transaction
has already confirmed on-chain, the outbound HTLCs in that update must
be failed back.

Add fail_htlcs_from_update_after_funding_spend to ChannelMonitorImpl
which detects this race condition during update_monitor. When a
LatestCounterpartyCommitmentTXInfo or LatestCounterpartyCommitment
update is applied and the funding output has already been spent, the
function iterates all outbound HTLCs from the update and creates
OnchainEvent::HTLCUpdate entries for those that need to be failed back.
These entries mature after ANTI_REORG_DELAY blocks, giving time for the
peer to potentially broadcast the newer commitment.

HTLCs that appear as non-dust outputs in the confirmed commitment
(whether counterparty or holder) are skipped, as they will be resolved
on-chain via the normal HTLC timeout/success path. HTLCs already
fulfilled by the counterparty (tracked in counterparty_fulfilled_htlcs)
are also skipped. Duplicate failures from previously-known counterparty
commitments are handled gracefully by the ChannelManager.

AI tools were used in preparing this commit.
✓ Specific, descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context
The short version

What changed, and why it matters

This commit fixes a race condition in the Lightning Dev Kit's channel monitoring code. In simple terms, when a Lightning channel is force-closed, the software must correctly fail back any outstanding payments that are stuck. Previously, if a monitor update containing new payment information was queued but only applied after the channel's funding transaction was already spent on-chain, those payments might not be properly failed back. The patch adds logic to detect this situation and create the necessary failure events, while skipping payments that already have on-chain outputs or were already fulfilled. It also ensures the event processor is notified after flushing monitor updates.

Recommended action

Reviewers should verify that the new fail_htlcs_from_update_after_funding_spend logic correctly identifies truly new outbound HTLCs and does not inadvertently fail back HTLCs that are already resolvable on-chain. Confirm that the event notifier wake covers all deferred-write paths and that the added tests exercise both the pending and fully-confirmed funding spend branches, including dust HTLC handling. Consider whether any serialization concerns exist for failed_back_htlc_ids, which is intentionally in-memory only.

Security signals we found

01

Fixes a race condition between deferred ChannelMonitorUpdate application and on-chain funding spend confirmation

02

Prevents stuck outbound HTLCs from not being failed back after channel force-close

03

Adds duplicate-prevention via failed_back_htlcs_ids and relies on ChannelManager to handle duplicate failures gracefully

04

Skips HTLCs with on-chain outputs to avoid double-resolution

05

Skips counterparty-fulfilled HTLCs

06

Wakes event processor after monitor flush to ensure generated events are handled

07

Adds regression tests simulating the exact race condition

Risk score

Why this scored 68/100

Our methodology →
Potential impact 22/30
Exploitability 12/25
Stealth signal 10/15
Affected reach 12/15
Confidence 8/10
Evidence quality 4/5
Human-validated context

Community notes

Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.

No validated notes yet.

The AI analysis stands alone for now. Submit a note if you can add evidence or important context.