Skip to content

Withheld channel close: fail back inflight HTLCs and free UTXOs#8943

Open
nepet wants to merge 3 commits intoElementsProject:masterfrom
nepet:lightningd/fail-back-htlcs-on-close
Open

Withheld channel close: fail back inflight HTLCs and free UTXOs#8943
nepet wants to merge 3 commits intoElementsProject:masterfrom
nepet:lightningd/fail-back-htlcs-on-close

Conversation

@nepet
Copy link
Member

@nepet nepet commented Mar 16, 2026

Important

26.04 FREEZE March 11th: Non-bugfix PRs not ready by this date will wait for 26.06.

RC1 is scheduled on March 23rd

The final release is scheduled for April 15th.

Checklist

Before submitting the PR, ensure the following tasks are completed. If an item is not applicable to your PR, please mark it as checked:

  • The changelog has been updated in the relevant commit(s) according to the guidelines.
  • Tests have been added or modified to reflect the changes.
  • Documentation has been reviewed and updated as needed.
  • Related issues have been listed and linked, including any that this PR closes.
  • Important All PRs must consider how to reverse any persistent changes for tools/lightning-downgrade

This PR improves the handling of withheld channel closes:
First, when a withheld zero-conf channel gets dropped, for example because an in-flight HTLC on a channel hits its CLTV deadline, we only freed any HTLCs on that channel withouth failing them back upstream. The upstream peer would then sit there waiting for a resolution that was never going to come, and eventually force-close its channel too. This patch iterates over offered HTLCs on the withheld channel during drop_to_chain() and fails them back with permanent_channel_failure before freeing them.

Second, the UTXOs used in the withheld funding PSBT were left reserved after the channel was torn down. They'd eventually become available again once the reservation expired, but in the meantime the wallet would behave as if those funds didn't exist. Now we explicitly unreserve them when dropping the channel.

This also slips in a convenient small addition to forward_event: also return the preimage if status is settled

@nepet nepet requested a review from rustyrussell March 16, 2026 11:35
@nepet nepet added this to the v26.04 milestone Mar 16, 2026
@nepet nepet force-pushed the lightningd/fail-back-htlcs-on-close branch 4 times, most recently from a3ab851 to e80f9cb Compare March 16, 2026 11:51
nepet added 3 commits March 16, 2026 14:02
When a withheld channel is force-closed (e.g. due to CLTV timeout),
in-flight HTLCs were being freed without failing them back to the
upstream sender. This caused the upstream peer to eventually
force-close its own channel waiting for a resolution that would
never come.

Iterate over all offered HTLCs on the withheld channel in
drop_to_chain() and fail them back upstream with
permanent_channel_failure before freeing them.

Changelog-fixed: withheld channel now fail back incoming inflight htlc
…channel

When a channel using a withheld funding PSBT is dropped, we need to
unreserve the UTXOs from the PSBT. Otherwise those funds will remain
blocked until the reservation expires, delaying their availability for
other transactions.

Changelog-Fixed: lightningd: unreserve UTXOs from withheld funding PSBT
on channel close.
Adds the preimage to the forward_event notification when status is
settled. This can be useful to gather some context when listening to
this event

Changelog-Changed: forward_event notification no has preimage set if
status is settled.

Signed-off-by: Peter Neuroth <pet.v.ne@gmail.com>
@nepet nepet force-pushed the lightningd/fail-back-htlcs-on-close branch from e80f9cb to 1984cd3 Compare March 16, 2026 13:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant