Avoid duplicate on-chain HTLC claims after replay by joostjager · Pull Request #4583 · lightningdevkit/rust-lightning

joostjager · 2026-04-30T13:57:15Z

ldk-reviews-bot · 2026-04-30T13:57:18Z

👋 I see @valentinewallace was un-assigned.
If you'd like another reviewer assignment, please click here.

codecov · 2026-04-30T15:13:17Z

Codecov Report

❌ Patch coverage is 99.08537% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.16%. Comparing base (42e198c) to head (37d6b77).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	93.54%	2 Missing ⚠️
lightning/src/chain/onchaintx.rs	99.55%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4583      +/-   ##
==========================================
+ Coverage   87.15%   87.16%   +0.01%     
==========================================
  Files         161      161              
  Lines      109251   109512     +261     
  Branches   109251   109512     +261     
==========================================
+ Hits        95215    95459     +244     
- Misses      11560    11575      +15     
- Partials     2476     2478       +2

Flag	Coverage Δ
fuzzing-fake-hashes	`31.17% <55.29%> (+0.01%)`	⬆️
fuzzing-real-hashes	`22.92% <0.00%> (-0.01%)`	⬇️
tests	`86.23% <99.08%> (+0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-claude-review-bot · 2026-05-01T11:38:46Z

I've completed a thorough re-review of the entire PR diff, including deep analysis of:

ClaimId::from_htlcs sorting change: Verified that from_htlcs is only called for NEW claims (line 922 in generate_claim), never to recompute existing stored ClaimIds. Deserialized ClaimIds in pending_claim_requests and claimable_outpoints are used as raw bytes and never regenerated. No serialization compatibility issue.
is_htlc_output_spent_on_chain: Confirmed that commitment_tx_output_idx in htlcs_resolved_on_chain and htlc.transaction_output_index both refer to the commitment transaction output index. Since only one commitment transaction can confirm per funding output, indices are unambiguous.
Three-layer dedup in update_claims_view_from_requests: The ordering (is_outpoint_spend_waiting_threshold_conf → claimable_outpoints → locktimed_packages) is correct because ContentiousOutpoint events remove their outpoints from claimable_outpoints, so there's no overlap between checks 1 and 2.
contains_outpoint vs old exact match: The change from locked_package.outpoints() == req.outpoints() to locked_package.contains_outpoint(outpoint) is intentional — a single-outpoint ClaimRequest should be detected as already covered by a multi-outpoint aggregated timelocked package.
CSV delay window behavior: Verified that between ANTI_REORG_DELAY (OnchainTxHandler cleanup) and BREAKDOWN_TIMEOUT (ChannelMonitor HTLCSpendConfirmation threshold), replayed preimage claims intentionally create live conflicting claims (kept as retry state in case of reorg). After CSV delay passes, htlcs_resolved_on_chain provides final suppression. The test correctly covers this with a reload step to verify persisted state.
Integration test do_test_duplicate_delayed_holder_htlc_claims_after_claim_funds_replay: Verified provide_payment_preimage_unsafe_legacy exists and is an appropriate test API. The reload-then-replay pattern correctly verifies persisted resolution state.

No issues found.

TheBlueMatt · 2026-05-01T13:17:51Z

 		requests.retain(|req| {
 			let outpoint = req.outpoint();
-			if self.claimable_outpoints.get(outpoint).is_some() {
+			if self.is_outpoint_spend_waiting_threshold_conf(outpoint) {


Does this break for reorgs where a counterparty's transaction gets unconfirmed? ie if we have a event awaiting confirmations for the counterparty claiming an outpoint, but then that gets reorg'd out and not replayed, do we still manage to broadcast our own claim (and RBF it)?

I assume that this case is only reachable if we receive a preimage after a counterparty's timeout claim is confirming?

I think on a reorg the item in onchain_events_awaiting_threshold_conf is revived again? Basically the claim is passed around to different data structures, but never lost?

TheBlueMatt · 2026-05-01T13:23:04Z


+	fn is_htlc_output_spent_on_chain(&self, htlc: &HTLCOutputInCommitment) -> bool {
+		if let Some(transaction_output_index) = htlc.transaction_output_index {
+			// This is a monitor-level HTLC generation filter. OnchainTxHandler


So why exactly do we need the duplicate?

It stems from OnchainTxHandler not persisting state

TheBlueMatt · 2026-05-01T13:23:21Z

+			// still guards package state for outpoints split out by confirmed
+			// spends; here we avoid recreating HTLC claim requests once the
+			// monitor has observed resolution.
+			self.onchain_events_awaiting_threshold_conf.iter().any(|entry| match entry.event {


Same issue as the previous commit - does this break broadcasting our conflicting claim on reorg?

Hm, here indeed a claim is never submitted and also cannot be resurrected.

Now only checking for deeply confirmed outpoints, but need to look at the consequences of that.

Have ChannelMonitor hand singular ClaimRequests to OnchainTxHandler. Convert them to PackageTemplates only after duplicate filtering. This makes the single-outpoint invariant explicit at that boundary.

Move repeated OnchainTxHandler setup into shared test helpers so the claim-replay coverage can focus on the behavior under test.

A replayed holder HTLC claim may arrive as a single-outpoint request after earlier requests were merged into a delayed package. Check whether an existing delayed package already covers the new request instead of requiring exact outpoint-set equality. Add focused OnchainTxHandler coverage and a ChannelMonitor regression through claim_funds for both current anchor variants.

When a transaction spends one outpoint from a delayed package, the split outpoint is tracked as a ContentiousOutpoint while it awaits anti-reorg confirmation. Reject replayed claim requests for those pending-spent outpoints so they are not added back before the spend either matures or reorgs out. Add an OnchainTxHandler regression that replays a holder claim during that pending-spent window and verifies reorg resurrection still works.

Filter regenerated HTLC claim requests only after ChannelMonitor has persisted final HTLC resolution for the commitment output. This keeps replayed preimage updates from recreating claims once the monitor has durable resolution state, while preserving live conflicting claims before final resolution so they can be retried if a counterparty spend reorgs out.

Hash HTLC claim outpoints in canonical order so the same logical HTLC set produces the same ClaimId regardless of descriptor order. Add a unit test covering reversed descriptor order.

joostjager self-assigned this Apr 30, 2026

joostjager added this to Weekly Goals Apr 30, 2026

joostjager force-pushed the onchain-claim-replay-fixes branch 2 times, most recently from 531576d to 9e0f886 Compare May 1, 2026 11:06

joostjager marked this pull request as ready for review May 1, 2026 11:22

ldk-reviews-bot requested a review from valentinewallace May 1, 2026 11:23

joostjager changed the title ~~Onchain claim replay fixes~~ Avoid duplicate on-chain HTLC claims after replay May 1, 2026

joostjager removed the request for review from valentinewallace May 1, 2026 11:24

TheBlueMatt reviewed May 1, 2026

View reviewed changes

joostjager force-pushed the onchain-claim-replay-fixes branch from 9e0f886 to 37d6b77 Compare May 1, 2026 15:07

joostjager added 6 commits May 1, 2026 20:26

lightning: introduce singular claim requests

2493b57

Have ChannelMonitor hand singular ClaimRequests to OnchainTxHandler. Convert them to PackageTemplates only after duplicate filtering. This makes the single-outpoint invariant explicit at that boundary.

lightning: refactor onchain tx handler tests

bcfd69d

Move repeated OnchainTxHandler setup into shared test helpers so the claim-replay coverage can focus on the behavior under test.

lightning: canonicalize htlc claim ids

1c3b725

Hash HTLC claim outpoints in canonical order so the same logical HTLC set produces the same ClaimId regardless of descriptor order. Add a unit test covering reversed descriptor order.

joostjager force-pushed the onchain-claim-replay-fixes branch from 37d6b77 to 1c3b725 Compare May 1, 2026 18:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Avoid duplicate on-chain HTLC claims after replay#4583

Avoid duplicate on-chain HTLC claims after replay#4583
joostjager wants to merge 6 commits intolightningdevkit:mainfrom
joostjager:onchain-claim-replay-fixes

joostjager commented Apr 30, 2026 •

edited

Loading

Uh oh!

ldk-reviews-bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

ldk-claude-review-bot commented May 1, 2026 •

edited

Loading

Uh oh!

TheBlueMatt May 1, 2026

Uh oh!

joostjager May 1, 2026

Uh oh!

TheBlueMatt May 1, 2026

Uh oh!

joostjager May 1, 2026

Uh oh!

TheBlueMatt May 1, 2026

Uh oh!

joostjager May 1, 2026

Uh oh!

joostjager May 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

joostjager commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ldk-claude-review-bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TheBlueMatt May 1, 2026

Choose a reason for hiding this comment

Uh oh!

joostjager May 1, 2026

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt May 1, 2026

Choose a reason for hiding this comment

Uh oh!

joostjager May 1, 2026

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt May 1, 2026

Choose a reason for hiding this comment

Uh oh!

joostjager May 1, 2026

Choose a reason for hiding this comment

Uh oh!

joostjager May 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

joostjager commented Apr 30, 2026 •

edited

Loading

ldk-reviews-bot commented Apr 30, 2026 •

edited

Loading

codecov Bot commented Apr 30, 2026 •

edited

Loading

ldk-claude-review-bot commented May 1, 2026 •

edited

Loading