Merge PR '`MonitorEvent`s resolve outbound payment claims' (#4545)
What changed, and why it matters
This commit changes how Lightning Dev Kit handles payment claims when an outbound HTLC is resolved. Previously, off-chain payment claims were tied to a specific message-handling flow (RAA release) and could get out of sync with the channel monitor's durable events. The patch makes monitor events the durable source of truth for resolving outbound payments, adds tracking so the same HTLC can have both an off-chain and an on-chain claim event, and ensures older LDK versions (0.3 and earlier) don't misinterpret off-chain events as on-chain ones. It also fixes edge cases around restarts, upgrades, downgrades, and replayed events. The primary risk is not a remote exploit but a correctness/consensus bug that could, in edge cases, lead to stuck payments, phantom balances, or premature payment completion.
Review the new monitor-event acking logic carefully, especially the conditions under which `ack_monitor_event` is called and the duplicate-detection logic for `PaymentSent` events. Run the new upgrade/downgrade and on-chain-after-off-chain tests under fault injection (e.g., simulated persistence failures and restarts) to confirm no double-ack or missed-ack cases. Verify that the `from_onchain` default of `true` for newly-serialized events preserves downgrade safety. Consider whether any downstream consumers of `PaymentForwarded::claim_from_onchain_tx` need updates.
Security signals we found
Changes durable persistence format (`HTLCUpdate` adds `from_onchain` TLV field)
Changes monitor event ID generation to distinguish on-chain vs off-chain resolutions
Adds backward-compatibility guard to avoid writing off-chain HTLC events for LDK 0.3-
Refactors event completion actions to ack monitor events only after user processes PaymentSent
Adds startup replay path that re-creates outbound payments from monitor events
Adds tests for upgrade/downgrade and replayed claim scenarios
Evidence from the diff
The PR refactors outbound payment resolution to be driven by MonitorEvent::HTLCEvent rather than only by the ReleaseRAAChannelMonitorUpdate completion action. Key changes: (1) HTLCUpdate gains a from_onchain field so on-chain and off-chain resolutions get distinct monitor event IDs and off-chain events are not persisted for pre-0.4 compatibility. (2) ChannelMonitor now queues an HTLCEvent when the counterparty’s commitment dance claims an outbound HTLC off-chain. (3) EventCompletionAction carries a monitor_event_source and a new for_outbound_claim constructor that chooses between ReleaseRAAChannelMonitorUpdate (channel open) and ReleasePaymentCompleteChannelMonitorUpdate (channel closed). (4) ChannelManager::process_pending_monitor_events now handles outbound claims by updating pending PaymentSent actions and only calling claim_funds_internal when the channel is closed, while acking the monitor event once the event is handled. (5) Startup replay logic re-adds payments from monitor events when the ChannelManager is stale. (6) Tests cover upgrade/downgrade between 0.3 and current, replayed claims, and on-chain claim after off-chain claim.
Changed components
lightning/src/chain/channelmonitor.rslightning/src/ln/channelmanager.rslightning/src/ln/outbound_payment.rslightning/src/ln/functional_test_utils.rslightning/src/ln/monitor_tests.rslightning/src/ln/chanmon_update_fail_tests.rslightning/src/ln/shutdown_tests.rslightning-tests/src/upgrade_downgrade_tests.rsInspect captured patch +819 / −155
### lightning-tests/Cargo.toml
@@ -15,6 +15,7 @@ lightning-types = { path = "../lightning-types", features = ["_test_utils"] }
lightning-invoice = { path = "../lightning-invoice", default-features = false }
lightning-macros = { path = "../lightning-macros" }
lightning = { path = "../lightning", features = ["_test_utils"] }
+lightning_0_3 = { package = "lightning", version = "0.3.0-rc1", features = ["_test_utils"] }
lightning_0_2 = { package = "lightning", version = "0.2.0", features = ["_test_utils"] }
lightning_0_1 = { package = "lightning", version = "0.1.7", features = ["_test_utils"] }
### lightning-tests/src/upgrade_downgrade_tests.rs
@@ -10,6 +10,15 @@
//! Tests which test upgrading from previous versions of LDK or downgrading to previous versions of
//! LDK.
+use lightning_0_3::chain::ChannelMonitorUpdateStatus as ChannelMonitorUpdateStatus_0_3;
+use lightning_0_3::expect_payment_claimed as expect_payment_claimed_0_3;
+use lightning_0_3::get_monitor as get_monitor_0_3;
+use lightning_0_3::ln::functional_test_utils as lightning_0_3_utils;
+use lightning_0_3::ln::msgs::ChannelMessageHandler as _;
+use lightning_0_3::reload_node as reload_node_0_3;
+use lightning_0_3::types::payment::PaymentPreimage as PaymentPreimage_0_3;
+use lightning_0_3::util::ser::Writeable as _;
+
use lightning_0_2::chain::chaininterface::FEERATE_FLOOR_SATS_PER_KW as FEERATE_FLOOR_0_2;
use lightning_0_2::commitment_signed_dance as commitment_signed_dance_0_2;
use lightning_0_2::events::bump_transaction::sync::WalletSourceSync as WalletSourceSync_0_2;
@@ -42,8 +51,12 @@ use lightning_0_1::util::ser::Writeable as _;
use lightning::blinded_path::message::NextMessageHop;
use lightning::chain::chaininterface::FEERATE_FLOOR_SATS_PER_KW;
use lightning::chain::channelmonitor::{ANTI_REORG_DELAY, HTLC_FAIL_BACK_BUFFER};
-use lightning::events::{ClosureReason, Event, HTLCHandlingFailureType, NegotiationFailureReason};
+use lightning::events::{
+ ClosureReason, Event, EventsProvider, HTLCHandlingFailureType, NegotiationFailureReason,
+ ReplayEvent,
+};
use lightning::ln::channel_state::SpliceCandidateStatus;
+use lightning::ln::channelmanager::ClaimFundsOptions;
use lightning::ln::channelmanager::SpliceContributionError;
use lightning::ln::functional_test_utils::*;
use lightning::ln::funding::FundingContribution;
@@ -115,6 +128,160 @@ fn simple_upgrade() {
claim_payment(&nodes[0], &[&nodes[1]], preimage);
}
+#[test]
+fn test_0_3_pending_payment_sent_upgrade_replayed_claim() {
+ // A pending PaymentSent from 0.3 carries a legacy RAA-release action. Replaying an
+ // unfinished claim monitor update on upgrade must retain its MonitorEvent until the
+ // application accepts PaymentSent, including when the handler requests event replay.
+ let (manager_ser, monitor_ser, chan_id_bytes, preimage_bytes);
+ {
+ let chanmon_cfgs = lightning_0_3_utils::create_chanmon_cfgs(2);
+ let node_cfgs = lightning_0_3_utils::create_node_cfgs(2, &chanmon_cfgs);
+ let node_chanmgrs = lightning_0_3_utils::create_node_chanmgrs(2, &node_cfgs, &[None, None]);
+ let nodes = lightning_0_3_utils::create_network(2, &node_cfgs, &node_chanmgrs);
+ let node_a_id = nodes[0].node.get_our_node_id();
+ let node_b_id = nodes[1].node.get_our_node_id();
+ let chan_id = lightning_0_3_utils::create_announced_chan_between_nodes(&nodes, 0, 1).2;
+ chan_id_bytes = chan_id.0;
+
+ let (preimage, payment_hash, ..) =
+ lightning_0_3_utils::route_payment(&nodes[0], &[&nodes[1]], 1_000_000);
+ preimage_bytes = preimage.0;
+ monitor_ser = get_monitor_0_3!(nodes[0], chan_id).encode();
+ nodes[1].node.claim_funds(preimage);
+ lightning_0_3_utils::check_added_monitors(&nodes[1], 1);
+ expect_payment_claimed_0_3!(nodes[1], payment_hash, 1_000_000);
+ let mut updates = lightning_0_3_utils::get_htlc_update_msgs(&nodes[1], &node_a_id);
+ nodes[0].node.handle_update_fulfill_htlc(node_b_id, updates.update_fulfill_htlcs.remove(0));
+
+ // Persist the manager while the claim's monitor update is still in progress. The
+ // monitor snapshot above predates that update, so it must be replayed after reload.
+ chanmon_cfgs[0].persister.set_update_ret(ChannelMonitorUpdateStatus_0_3::InProgress);
+ nodes[0].node.handle_commitment_signed_batch_test(node_b_id, &updates.commitment_signed);
+ lightning_0_3_utils::check_added_monitors(&nodes[0], 1);
+ manager_ser = nodes[0].node.encode();
+
+ // Finish the original nodes' claim flow so their end-of-scope checks pass.
+ chanmon_cfgs[0].persister.set_update_ret(ChannelMonitorUpdateStatus_0_3::Completed);
+ let (_, update_id) = lightning_0_3_utils::get_latest_mon_update_id(&nodes[0], chan_id);
+ nodes[0].chain_monitor.chain_monitor.channel_monitor_updated(chan_id, update_id).unwrap();
+ let extra_msg = lightning_0_3_utils::commitment_signed_dance_through_cp_raa(
+ &nodes[0], &nodes[1], false, true,
+ );
+ assert!(extra_msg.is_none(), "{extra_msg:?}");
+ lightning_0_3_utils::expect_payment_sent(&nodes[0], preimage, Some(Some(0)), true, true);
+ }
+
+ let chanmon_cfgs = create_chanmon_cfgs(2);
+ let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+ let (persister, chain_monitor);
+ let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
+ let channel_manager;
+ let mut nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+ reload_node!(nodes[0], manager_ser, &[&monitor_ser], persister, chain_monitor, channel_manager);
+ assert_eq!(nodes[0].node.list_channels().len(), 1);
+
+ let preimage = PaymentPreimage(preimage_bytes);
+ let saw_payment_sent = core::cell::Cell::new(false);
+ nodes[0].node.process_pending_events(&|event| {
+ assert!(
+ matches!(event, Event::PaymentSent { payment_preimage, .. } if payment_preimage == preimage),
+ "{event:?}",
+ );
+ assert!(!saw_payment_sent.replace(true));
+ Err(ReplayEvent())
+ });
+ assert!(saw_payment_sent.get());
+ check_added_monitors(&nodes[0], 1);
+
+ let chan_id = ChannelId(chan_id_bytes);
+ let pending = get_monitor!(nodes[0], chan_id).list_unacked_monitor_events();
+ assert_eq!(pending.len(), 1, "claim acknowledged before PaymentSent was handled: {pending:?}");
+
+ // Accepting the replayed PaymentSent must acknowledge its monitor event.
+ expect_payment_sent(&nodes[0], preimage, Some(Some(0)), false, false);
+ assert!(get_monitor!(nodes[0], chan_id).list_unacked_monitor_events().is_empty());
+ assert!(nodes[0].node.get_and_clear_pending_msg_events().is_empty());
+ check_added_monitors(&nodes[0], 0);
+}
+
+#[test]
+fn test_0_3_pending_payment_sent_downgrade() {
+ // Test that an off-chain claim's `MonitorEvent` which 0.4 queued in a `ChannelMonitor` but whose
+ // `ChannelManager` never processed it is properly handled after a downgrade to LDK 0.3.
+ // 0.3 must ignore such events on monitor read.
+ let (mgr_ser, mon_ser);
+ let preimage_bytes;
+ {
+ let chanmon_cfgs = create_chanmon_cfgs(2);
+ let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+ let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
+ let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+
+ let node_a_id = nodes[0].node.get_our_node_id();
+ let node_b_id = nodes[1].node.get_our_node_id();
+
+ let chan_id = create_announced_chan_between_nodes(&nodes, 0, 1).2;
+
+ let (preimage, payment_hash, ..) = route_payment(&nodes[0], &[&nodes[1]], 1_000_000);
+ preimage_bytes = preimage.0;
+
+ // Claim the payment and deliver B's `update_fulfill_htlc` and `commitment_signed` to A,
+ // queueing A's `PaymentSent` event and pushing the claim's `MonitorEvent` into the
+ // monitor, then serialize immediately: the state written below is that of a node which
+ // crashed right after persisting the `commitment_signed`'s `ChannelMonitorUpdate`,
+ // before the `ChannelManager` processed the `MonitorEvent`.
+ nodes[1].node.claim_funds(preimage, ClaimFundsOptions::default());
+ check_added_monitors(&nodes[1], 1);
+ expect_payment_claimed!(nodes[1], payment_hash, 1_000_000);
+
+ let mut updates = get_htlc_update_msgs(&nodes[1], &node_a_id);
+ nodes[0].node.handle_update_fulfill_htlc(node_b_id, updates.update_fulfill_htlcs.remove(0));
+ nodes[0].node.handle_commitment_signed_batch_test(node_b_id, &updates.commitment_signed);
+ check_added_monitors(&nodes[0], 1);
+
+ mgr_ser = nodes[0].node.encode();
+ mon_ser = {
+ let mon = get_monitor!(nodes[0], chan_id);
+ assert_eq!(mon.list_unacked_monitor_events().len(), 1);
+ mon.encode()
+ };
+
+ // Complete the commitment dance and process `PaymentSent` now so the end-of-scope test
+ // checks pass; the state serialized above still has the event pending and the
+ // `MonitorEvent` queued in the monitor. Passing `includes_claim` asserts that A's RAA
+ // `ChannelMonitorUpdate` is held until the `PaymentSent` event is processed.
+ let extra_msg = commitment_signed_dance_through_cp_raa(&nodes[0], &nodes[1], false, true);
+ assert!(extra_msg.is_none(), "{extra_msg:?}");
+ expect_payment_sent(&nodes[0], preimage, None, true, true);
+ }
+
+ // Downgrade node A to 0.3, reloading with the manager and monitor written by the current
+ // version while `PaymentSent` was pending.
+ let chanmon_cfgs = lightning_0_3_utils::create_chanmon_cfgs(2);
+ let node_cfgs = lightning_0_3_utils::create_node_cfgs(2, &chanmon_cfgs);
+ let (persister_1, chain_mon_1);
+ let node_chanmgrs = lightning_0_3_utils::create_node_chanmgrs(2, &node_cfgs, &[None, None]);
+ let node_a_1;
+ let mut nodes = lightning_0_3_utils::create_network(2, &node_cfgs, &node_chanmgrs);
+
+ let config = lightning_0_3_utils::test_default_channel_config();
+ let mons = &[&mon_ser[..]];
+ reload_node_0_3!(nodes[0], config, &mgr_ser, mons, persister_1, chain_mon_1, node_a_1);
+
+ // The channel is still open on 0.3.
+ assert_eq!(nodes[0].node.list_channels().len(), 1);
+
+ // Processing the pending events must surface `PaymentSent` exactly once and must not panic
+ // on any startup `MonitorEvent`s re-delivered for the (open) channel.
+ let preimage = PaymentPreimage_0_3(preimage_bytes);
+ let (_, path_events) =
+ lightning_0_3_utils::expect_payment_sent(&nodes[0], preimage, None, false, false);
+ assert!(path_events.is_empty(), "{path_events:?}");
+
+ assert!(nodes[0].node.get_and_clear_pending_events().is_empty());
+}
+
#[test]
fn test_0_1_legacy_remote_key_derivation() {
// Test that a channel opened with a v1/legacy `remote_key` derivation will be properly spent
### lightning/src/chain/channelmonitor.rs
@@ -193,11 +193,12 @@ pub(super) fn monitor_event_id(event: &MonitorEvent) -> u128 {
let mut engine = Sha256::engine();
match event {
MonitorEvent::HTLCEvent(upd) => {
- 0u8.write(&mut engine).unwrap();
- SentHTLCId::from_source(&upd.source).write(&mut engine).unwrap();
- // A claim and a failure of the same HTLC must not share an ID, so that acking one never
- // removes the other.
- engine.input(&[upd.payment_preimage.is_some() as u8]);
+ let htlc_id = SentHTLCId::from_source(&upd.source);
+ return htlc_monitor_event_id(
+ htlc_id,
+ upd.payment_preimage.is_some(),
+ upd.from_onchain,
+ );
},
MonitorEvent::HolderForceClosed(outpoint)
| MonitorEvent::HolderForceClosedWithInfo { outpoint, .. } => {
@@ -212,6 +213,25 @@ pub(super) fn monitor_event_id(event: &MonitorEvent) -> u128 {
engine.input(&monitor_update_id.to_be_bytes());
},
}
+ monitor_event_id_from_engine(engine)
+}
+
+/// Derives the [`monitor_event_id`] of the [`MonitorEvent::HTLCEvent`] that would be generated for
+/// the given HTLC.
+pub(crate) fn htlc_monitor_event_id(
+ htlc_id: SentHTLCId, is_claim: bool, from_onchain: bool,
+) -> u128 {
+ let mut engine = Sha256::engine();
+ 0u8.write(&mut engine).unwrap();
+ htlc_id.write(&mut engine).unwrap();
+ // A claim and a failure of the same HTLC, or an on-chain and an off-chain resolution of it, must
+ // not share an ID, so that acking one never removes the other.
+ engine.input(&[is_claim as u8]);
+ engine.input(&[from_onchain as u8]);
+ monitor_event_id_from_engine(engine)
+}
+
+fn monitor_event_id_from_engine(engine: bitcoin::hashes::sha256::HashEngine) -> u128 {
let mut id_bytes = [0u8; 16];
id_bytes.copy_from_slice(&Sha256::from_engine(engine).to_byte_array()[..16]);
u128::from_be_bytes(id_bytes)
@@ -284,21 +304,29 @@ impl_writeable_tlv_based_enum_upgradable_legacy!(MonitorEvent,
// 6 was `UpdateFailed` until LDK 0.0.117
);
-/// Simple structure sent back by `chain::Watch` when an HTLC from a forward channel is detected on
-/// chain. Used to update the corresponding HTLC in the backward channel. Failing to pass the
-/// preimage claim backward will lead to loss of funds.
+/// Simple structure sent back by `chain::Watch` when an outbound HTLC is durably resolved. If the
+/// HTLC was a forward, use this to update the corresponding HTLC in the backward channel. Failing
+/// to pass the preimage claim backward will lead to loss of funds.
#[derive(Clone, PartialEq, Eq, Debug)]
pub struct HTLCUpdate {
pub(crate) payment_hash: PaymentHash,
pub(crate) payment_preimage: Option<PaymentPreimage>,
pub(crate) source: HTLCSource,
pub(crate) htlc_value_satoshis: u64,
+ /// Whether the HTLC resolution was observed on-chain, as opposed to being irrevocably
+ /// committed off-chain via the commitment dance. Useful for setting
+ /// [`Event::PaymentForwarded::claim_from_onchain_tx`].
+ ///
+ /// Also used to decide whether to persist this update's [`MonitorEvent::HTLCEvent`], since
+ /// off-chain HTLC events should not be persisted for LDK 0.3-.
+ pub(crate) from_onchain: bool,
}
impl_ser_tlv_based!(HTLCUpdate, {
(0, payment_hash, required),
(1, htlc_value_satoshis, required),
(2, source, required),
(4, payment_preimage, option),
+ (11, from_onchain, (default_value, true)), // Added in 0.4
});
/// If an output goes from claimable only by us to claimable by us or our counterparty within this
@@ -1740,7 +1768,9 @@ pub(crate) fn write_chanmon_internal<Signer: EcdsaChannelSigner, W: Writer>(
.pending_monitor_events
.iter()
.filter(|(_, ev)| match ev {
- MonitorEvent::HTLCEvent(_) => true,
+ // LDK versions prior to 0.4 treat any `HTLCEvent` as an on-chain event, which may lead to
+ // incorrect behavior, so don't write off-chain `HTLCEvent`s for those versions.
+ MonitorEvent::HTLCEvent(upd) => upd.from_onchain,
MonitorEvent::HolderForceClosed(_) => true,
MonitorEvent::HolderForceClosedWithInfo { .. } => true,
_ => false,
@@ -1750,6 +1780,9 @@ pub(crate) fn write_chanmon_internal<Signer: EcdsaChannelSigner, W: Writer>(
)?;
for (_, event) in channel_monitor.pending_monitor_events.iter() {
match event {
+ // LDK versions prior to 0.4 treat any `HTLCEvent` as an on-chain event, which may lead to
+ // incorrect behavior, so don't write off-chain `HTLCEvent`s for those versions.
+ MonitorEvent::HTLCEvent(upd) if !upd.from_onchain => {},
MonitorEvent::HTLCEvent(upd) => {
0u8.write(writer)?;
upd.write(writer)?;
@@ -1808,6 +1841,12 @@ pub(crate) fn write_chanmon_internal<Signer: EcdsaChannelSigner, W: Writer>(
.pending_monitor_events
.iter()
.map(|(_, ev)| ev)
+ // LDK versions prior to 0.4 treat any `HTLCEvent` as an on-chain event, which may lead to
+ // incorrect behavior, so don't write off-chain `HTLCEvent`s for those versions.
+ .filter(|ev| match ev {
+ MonitorEvent::HTLCEvent(upd) => upd.from_onchain,
+ _ => true,
+ })
.chain(holder_force_closed_compat.as_ref()),
));
let pending_mon_evs_with_ids = Some(Iterable(
@@ -3321,6 +3360,24 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitor<Signer> {
res
}
+ /// Returns the ID of an unacked [`MonitorEvent`] that resolves the given outbound HTLC via claim,
+ /// if any. Such an HTLC may no longer appear in [`Self::get_all_current_outbound_htlcs`] if the
+ /// commitment transactions it was a part of have since been revoked.
+ pub(crate) fn pending_claim_event_id(&self, htlc_id: SentHTLCId) -> Option<u128> {
+ let us = self.inner.lock().unwrap();
+ us.pending_monitor_events.iter().chain(us.provided_monitor_events.iter()).find_map(
+ |(id, ev)| match ev {
+ MonitorEvent::HTLCEvent(upd)
+ if upd.payment_preimage.is_some()
+ && htlc_id == SentHTLCId::from_source(&upd.source) =>
+ {
+ Some(*id)
+ },
+ _ => None,
+ },
+ )
+ }
+
/// Gets the set of outbound HTLCs which hit the chain and ultimately were claimed by us via
/// the timeout path and reached [`ANTI_REORG_DELAY`] confirmations. This is used to determine
/// if an HTLC has failed without the `ChannelManager` having seen it prior to being persisted.
@@ -3920,20 +3977,39 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitorImpl<Signer> {
self.prev_holder_htlc_data = Some(htlc_data);
for (claimed_htlc_id, claimed_preimage) in claimed_htlcs {
- #[cfg(debug_assertions)]
- {
- let cur_counterparty_htlcs = self
- .funding
- .counterparty_claimable_outpoints
- .get(&self.funding.current_counterparty_commitment_txid.unwrap())
- .unwrap();
- assert!(cur_counterparty_htlcs.iter().any(|(_, source_opt)| {
+ let htlc_opt = self
+ .funding
+ .counterparty_claimable_outpoints
+ .get(&self.funding.current_counterparty_commitment_txid.unwrap())
+ .unwrap()
+ .iter()
+ .find_map(|(htlc, source_opt)| {
if let Some(source) = source_opt {
- SentHTLCId::from_source(source) == *claimed_htlc_id
- } else {
- false
+ if SentHTLCId::from_source(source) == *claimed_htlc_id {
+ return Some((htlc, source));
+ }
}
- }));
+ None
+ });
+ debug_assert!(htlc_opt.is_some());
+ if let Some((htlc, source)) = htlc_opt {
+ let event = MonitorEvent::HTLCEvent(HTLCUpdate {
+ payment_hash: htlc.payment_hash,
+ payment_preimage: Some(*claimed_preimage),
+ source: *source.clone(),
+ htlc_value_satoshis: htlc.amount_msat / 1000,
+ from_onchain: false,
+ });
+ let event_id = monitor_event_id(&event);
+ // A replayed update must not queue the same event twice.
+ let already_queued = self
+ .pending_monitor_events
+ .iter()
+ .chain(self.provided_monitor_events.iter())
+ .any(|(id, _)| *id == event_id);
+ if !already_queued {
+ self.pending_monitor_events.push((event_id, event));
+ }
}
self.counterparty_fulfilled_htlcs.insert(*claimed_htlc_id, *claimed_preimage);
}
@@ -4686,6 +4762,10 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitorImpl<Signer> {
payment_preimage: None,
payment_hash: *payment_hash,
htlc_value_satoshis,
+ // Even though the HTLC was originally failed off-chain, mark it as on-chain failed
+ // because the channel is now closed and we want LDK 0.3- to read this event (see
+ // `HTLCUpdate::from_onchain`).
+ from_onchain: true,
}),
);
}
@@ -4775,6 +4855,7 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitorImpl<Signer> {
payment_preimage: None,
source: source.clone(),
htlc_value_satoshis,
+ from_onchain: true,
}),
);
self.htlcs_resolved_on_chain.push(IrrevocablyResolvedHTLC {
@@ -6115,6 +6196,7 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitorImpl<Signer> {
payment_preimage: None,
source,
htlc_value_satoshis,
+ from_onchain: true,
}));
self.htlcs_resolved_on_chain.push(IrrevocablyResolvedHTLC {
commitment_tx_output_idx,
@@ -6224,6 +6306,7 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitorImpl<Signer> {
payment_preimage: None,
payment_hash: htlc.payment_hash,
htlc_value_satoshis: htlc.amount_msat / 1000,
+ from_onchain: true,
}));
}
}
@@ -6702,14 +6785,23 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitorImpl<Signer> {
};
self.pending_monitor_events.retain(not_htlc_fail);
self.provided_monitor_events.retain(not_htlc_fail);
- if !self.pending_monitor_events.iter().chain(self.provided_monitor_events.iter()).any(
- |(_, update)| if let &MonitorEvent::HTLCEvent(ref upd) = update { upd.source == source } else { false }) {
- push_monitor_event(&mut self.pending_monitor_events, MonitorEvent::HTLCEvent(HTLCUpdate {
- source,
- payment_preimage: Some(payment_preimage),
- payment_hash,
- htlc_value_satoshis: amount_msat / 1000,
- }));
+ let update = HTLCUpdate {
+ source,
+ payment_preimage: Some(payment_preimage),
+ payment_hash,
+ htlc_value_satoshis: amount_msat / 1000,
+ from_onchain: true,
+ };
+ // Note that we compare the entire `HTLCUpdate` here when deciding whether the new event
+ // is a duplicate: this allows us to queue an on-chain HTLC update even if an off-chain
+ // update for the same HTLC is already pending unacked. Otherwise, if an outbound HTLC
+ // was first fulfilled off-chain then later fulfilled on-chain, we would only surface
+ // `PaymentPathSuccessful` + delete its outbound payments entry entry after a restart,
+ // since for off-chain claims those are only done after RAA.
+ let already_queued = self.pending_monitor_events.iter().chain(self.provided_monitor_events.iter()).any(
+ |(_, ev)| matches!(ev, MonitorEvent::HTLCEvent(upd) if *upd == update));
+ if !already_queued {
+ push_monitor_event(&mut self.pending_monitor_events, MonitorEvent::HTLCEvent(update));
}
} else {
self.onchain_events_awaiting_threshold_conf.retain(|ref entry| {
### lightning/src/ln/chanmon_update_fail_tests.rs
@@ -3803,6 +3803,9 @@ fn do_test_durable_preimages_on_closed_channel(
check_added_monitors(&nodes[1], 1);
let _ = get_revoke_commit_msgs(&nodes[1], &node_c_id);
+ // Process the off-chain claim while B<->C is open. The A<->B preimage update is
+ // still in flight, so `PaymentForwarded` must remain blocked.
+ assert!(nodes[1].node.get_and_clear_pending_events().is_empty());
let mon_bc = get_monitor!(nodes[1], chan_id_bc).encode();
if close_chans_before_reload {
@@ -5055,7 +5058,10 @@ fn native_async_persist() {
assert_eq!(update_status, ChannelMonitorUpdateStatus::InProgress);
persist_futures.poll_futures();
- assert_eq!(async_chain_monitor.release_pending_monitor_events().len(), 0);
+ let mon_evs = async_chain_monitor.release_pending_monitor_events();
+ assert_eq!(mon_evs.len(), 1, "{mon_evs:?}");
+ assert_eq!(mon_evs[0].2.len(), 1);
+ assert!(matches!(mon_evs[0].2[0].1, MonitorEvent::HTLCEvent(..)));
let pending_writes = kv_store.list_pending_async_writes(
CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
### lightning/src/ln/channelmanager.rs
@@ -44,8 +44,8 @@ use crate::chain::chaininterface::{
};
use crate::chain::chainmonitor::MonitorEventSource;
use crate::chain::channelmonitor::{
- ChannelMonitor, ChannelMonitorUpdate, ChannelMonitorUpdateStep, MonitorEvent,
- WithChannelMonitor, ANTI_REORG_DELAY, CLTV_CLAIM_BUFFER, HTLC_FAIL_BACK_BUFFER,
+ htlc_monitor_event_id, ChannelMonitor, ChannelMonitorUpdate, ChannelMonitorUpdateStep,
+ MonitorEvent, WithChannelMonitor, ANTI_REORG_DELAY, CLTV_CLAIM_BUFFER, HTLC_FAIL_BACK_BUFFER,
LATENCY_GRACE_PERIOD_BLOCKS, MAX_BLOCKS_FOR_CONF,
};
use crate::chain::transaction::{OutPoint, TransactionData};
@@ -1758,13 +1758,17 @@ pub(crate) struct PaymentCompleteUpdate {
channel_funding_outpoint: OutPoint,
channel_id: ChannelId,
htlc_id: SentHTLCId,
+ /// The [`MonitorEvent`] which reported the HTLC resolution behind the event this action is
+ /// attached to, if any. It is acknowledged once the event has been handled.
+ monitor_event_source: Option<MonitorEventSource>,
}
impl_ser_tlv_based!(PaymentCompleteUpdate, {
(1, channel_funding_outpoint, required),
(3, counterparty_node_id, required),
(5, channel_id, required),
(7, htlc_id, required),
+ (9, monitor_event_source, option),
});
#[derive(Clone, Debug, PartialEq, Eq)]
@@ -1774,6 +1778,9 @@ pub(crate) enum EventCompletionAction {
// Was required until LDK 0.2. Always filled in as `Some`.
channel_funding_outpoint: Option<OutPoint>,
channel_id: ChannelId,
+ /// The [`MonitorEvent`] which reported the HTLC resolution behind the event this action
+ /// is attached to, if any. It is acknowledged once the event has been handled.
+ monitor_event_source: Option<MonitorEventSource>,
},
/// When a payment's resolution is communicated to the downstream logic via
@@ -1792,10 +1799,63 @@ impl_ser_tlv_based_enum!(EventCompletionAction,
}
ChannelId::v1_from_funding_outpoint(channel_funding_outpoint.unwrap())
})),
+ (5, monitor_event_source, option),
}
{1, ReleasePaymentCompleteChannelMonitorUpdate} => (),
);
+impl EventCompletionAction {
+ fn channel_id(&self) -> ChannelId {
+ match self {
+ Self::ReleaseRAAChannelMonitorUpdate { channel_id, .. } => *channel_id,
+ Self::ReleasePaymentCompleteChannelMonitorUpdate(update) => update.channel_id,
+ }
+ }
+
+ fn htlc_id(&self) -> Option<SentHTLCId> {
+ match self {
+ Self::ReleaseRAAChannelMonitorUpdate { .. } => None,
+ Self::ReleasePaymentCompleteChannelMonitorUpdate(update) => Some(update.htlc_id),
+ }
+ }
+
+ /// The [`MonitorEvent`] to acknowledge once the event this action is attached to has been
+ /// handled, if any.
+ fn monitor_event_source(&self) -> Option<MonitorEventSource> {
+ match self {
+ Self::ReleaseRAAChannelMonitorUpdate { monitor_event_source, .. } => {
+ *monitor_event_source
+ },
+ Self::ReleasePaymentCompleteChannelMonitorUpdate(update) => update.monitor_event_source,
+ }
+ }
+
+ /// The action to attach to the [`Event`] resulting from a claim of an outbound HTLC.
+ fn for_outbound_claim(
+ htlc_id: SentHTLCId, channel_id: ChannelId, channel_funding_outpoint: OutPoint,
+ counterparty_node_id: PublicKey, channel_is_closed: bool, from_onchain: bool,
+ ) -> Self {
+ let event_id = htlc_monitor_event_id(htlc_id, true, from_onchain);
+ let monitor_event_source = Some(MonitorEventSource { event_id, channel_id });
+ if channel_is_closed {
+ Self::ReleasePaymentCompleteChannelMonitorUpdate(PaymentCompleteUpdate {
+ counterparty_node_id,
+ channel_funding_outpoint,
+ channel_id,
+ htlc_id,
+ monitor_event_source,
+ })
+ } else {
+ Self::ReleaseRAAChannelMonitorUpdate {
+ counterparty_node_id,
+ channel_funding_outpoint: Some(channel_funding_outpoint),
+ channel_id,
+ monitor_event_source,
+ }
+ }
+ }
+}
+
/// The source argument which is passed to [`ChannelManager::claim_mpp_part`].
///
/// This is identical to [`MPPClaimHTLCSource`] except that [`Self::counterparty_node_id`] is an
@@ -10874,6 +10934,7 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
next_channel_counterparty_node_id: PublicKey, next_channel_outpoint: OutPoint,
next_channel_id: ChannelId, next_user_channel_id: Option<u128>,
attribution_data: Option<AttributionData>, send_timestamp: Option<Duration>,
+ from_monitor_event: bool,
) {
let startup_replay =
!self.background_events_processed_since_startup.load(Ordering::Acquire);
@@ -10886,35 +10947,34 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
"We don't support claim_htlc claims during startup - monitors may not be available yet");
debug_assert_eq!(next_channel_counterparty_node_id, path.hops[0].pubkey);
- let mut ev_completion_action = if from_onchain {
- let release = PaymentCompleteUpdate {
- counterparty_node_id: next_channel_counterparty_node_id,
- channel_funding_outpoint: next_channel_outpoint,
- channel_id: next_channel_id,
- htlc_id,
- };
- Some(EventCompletionAction::ReleasePaymentCompleteChannelMonitorUpdate(release))
- } else {
- Some(EventCompletionAction::ReleaseRAAChannelMonitorUpdate {
- channel_funding_outpoint: Some(next_channel_outpoint),
- channel_id: next_channel_id,
- counterparty_node_id: path.hops[0].pubkey,
- })
+ let channel_is_closed = from_onchain || {
+ self.channel_is_closed(&next_channel_id, &next_channel_counterparty_node_id)
};
+ let mut ev_completion_action = Some(EventCompletionAction::for_outbound_claim(
+ htlc_id,
+ next_channel_id,
+ next_channel_outpoint,
+ next_channel_counterparty_node_id,
+ channel_is_closed,
+ from_onchain,
+ ));
let logger = WithContext::for_payment(
&self.logger,
path.hops.first().map(|hop| hop.pubkey),
None,
Some(payment_preimage.into()),
payment_id,
);
+ let best_block_height = self.best_block.read().unwrap().height;
self.pending_outbound_payments.claim_htlc(
payment_id,
payment_preimage,
bolt12_invoice,
session_priv,
path,
- from_onchain,
+ channel_is_closed,
+ from_monitor_event,
+ best_block_height,
&mut ev_completion_action,
&self.pending_events,
&logger,
@@ -11227,6 +11287,7 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
channel_funding_outpoint: Some(outpoint),
counterparty_node_id,
channel_id,
+ monitor_event_source: None,
})
} else {
None
@@ -13525,6 +13586,7 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
Some(next_user_channel_id),
msg.attribution_data,
send_timestamp,
+ false,
);
Ok(())
@@ -13747,7 +13809,8 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
if let Some(EventCompletionAction::ReleaseRAAChannelMonitorUpdate {
channel_funding_outpoint: _,
channel_id: ev_channel_id,
- counterparty_node_id: ev_counterparty_node_id
+ counterparty_node_id: ev_counterparty_node_id,
+ monitor_event_source: _,
}) = action {
*ev_channel_id == channel_id && *ev_counterparty_node_id == counterparty_node_id
} else {
@@ -14531,6 +14594,13 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
})
}
+ fn channel_is_closed(&self, channel_id: &ChannelId, counterparty_node_id: &PublicKey) -> bool {
+ let per_peer_state = self.per_peer_state.read().unwrap();
+ per_peer_state
+ .get(counterparty_node_id)
+ .is_some_and(|peer| !peer.lock().unwrap().channel_by_id.contains_key(channel_id))
+ }
+
/// Process pending events from the [`chain::Watch`], returning the appropriate
/// [`NotifyOption`] for persistence and event handling.
fn process_pending_monitor_events(&self) -> NotifyOption {
@@ -14557,26 +14627,86 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
Some(htlc_update.payment_hash),
);
if let Some(preimage) = htlc_update.payment_preimage {
- log_trace!(
- logger,
- "Claiming HTLC with preimage {} from our monitor",
- preimage
- );
- // Claim the funds from the previous hop, if there is one. Because this is in response to a
- // chain event, no attribution data is available.
- self.claim_funds_internal(
- htlc_update.source,
- preimage,
- htlc_update.htlc_value_satoshis * 1000,
- None,
- true,
- counterparty_node_id,
- funding_outpoint,
- channel_id,
- None,
- None,
- None,
- );
+ let is_channel_closed = htlc_update.from_onchain
+ // This check is racy, but that's ok because the worst that can happen if the
+ // channel closes later on is that we've queued the wrong EventCompletionAction
+ // below, which could leave the payment dangling until the next restart.
+ || self.channel_is_closed(&channel_id, &counterparty_node_id);
+ let htlc_id = SentHTLCId::from_source(&htlc_update.source);
+
+ if let HTLCSource::OutboundRoute { payment_id, .. } =
+ &htlc_update.source
+ {
+ // If this is a redundant claim of an outbound payment and an Event is already
+ // queued, refresh the Event's completion action in case it needs updating due to
+ // e.g. a channel closure or an upgrade/downgrade.
+ let mut pending_events = self.pending_events.lock().unwrap();
+ let pending_event_opt = pending_events.iter_mut().find(
+ |(event, _)| matches!(event, Event::PaymentSent { payment_id: Some(id), .. } if id == payment_id),
+ );
+ if let Some((_, action_opt)) = pending_event_opt {
+ let mut should_update_action = true;
+
+ // Avoid updating the completion action if it already corresponds to a different
+ // monitor event or HTLC.
+ if let Some(action) = action_opt {
+ if action
+ .monitor_event_source()
+ .is_some_and(|src| src != monitor_event_source)
+ {
+ should_update_action = false;
+ }
+ if action.channel_id() != channel_id
+ || action.htlc_id().is_some_and(|id| id != htlc_id)
+ {
+ should_update_action = false;
+ }
+ }
+
+ if should_update_action {
+ *action_opt =
+ Some(EventCompletionAction::for_outbound_claim(
+ htlc_id,
+ channel_id,
+ funding_outpoint,
+ counterparty_node_id,
+ is_channel_closed,
+ htlc_update.from_onchain,
+ ));
+ }
+ }
+ }
+
+ if is_channel_closed {
+ log_trace!(
+ logger,
+ "Claiming HTLC with preimage {} from our monitor",
+ preimage
+ );
+ // Claim the funds from the previous hop, if there is one. Because this is in response to a
+ // chain event, no attribution data is available.
+ self.claim_funds_internal(
+ htlc_update.source,
+ preimage,
+ htlc_update.htlc_value_satoshis * 1000,
+ None,
+ htlc_update.from_onchain,
+ counterparty_node_id,
+ funding_outpoint,
+ channel_id,
+ None,
+ None,
+ None,
+ true,
+ );
+ }
+
+ if !self.pending_events.lock().unwrap().iter().any(|(_, action)| {
+ action.as_ref().and_then(|action| action.monitor_event_source())
+ == Some(monitor_event_source)
+ }) {
+ self.chain_monitor.ack_monitor_event(monitor_event_source);
+ }
} else {
log_trace!(logger, "Failing HTLC from our monitor");
let failure_reason = LocalHTLCFailureReason::OnChainTimeout;
@@ -14588,6 +14718,7 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
channel_funding_outpoint: funding_outpoint,
channel_id,
htlc_id: SentHTLCId::from_source(&htlc_update.source),
+ monitor_event_source: None,
});
self.fail_htlc_backwards_internal(
&htlc_update.source,
@@ -14596,8 +14727,8 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
failure_type,
completion_update,
);
+ self.chain_monitor.ack_monitor_event(monitor_event_source);
}
- self.chain_monitor.ack_monitor_event(monitor_event_source);
},
MonitorEvent::HolderForceClosed(_)
| MonitorEvent::HolderForceClosedWithInfo { .. } => {
@@ -16397,11 +16528,15 @@ impl<
LockHeldState::NotHeldByThread
);
for action in actions.into_iter() {
+ if let Some(source) = action.monitor_event_source() {
+ self.chain_monitor.ack_monitor_event(source);
+ }
match action {
EventCompletionAction::ReleaseRAAChannelMonitorUpdate {
channel_funding_outpoint: _,
channel_id,
counterparty_node_id,
+ monitor_event_source: _,
} => {
let startup_complete =
self.background_events_processed_since_startup.load(Ordering::Acquire);
@@ -16414,6 +16549,7 @@ impl<
channel_funding_outpoint,
channel_id,
htlc_id,
+ monitor_event_source: _,
},
) => {
let per_peer_state = self.per_peer_state.read().unwrap();
@@ -20235,6 +20371,12 @@ impl<
break;
}
}
+ // If we have a monitor event resolving this HTLC, don't fail it backwards and wait for
+ // the monitor event to drive its resolution instead.
+ let htlc_id = SentHTLCId::from_source(channel_htlc_source);
+ if monitor.pending_claim_event_id(htlc_id).is_some() {
+ found_htlc = true;
+ }
if !found_htlc {
// If we have some HTLCs in the channel which are not present in the newer
// ChannelMonitor, they have been removed and should be failed back to
@@ -20869,11 +21011,22 @@ impl<
} => {
if let Some(preimage) = preimage_opt {
let pending_events = Mutex::new(pending_events_read);
+ // The preimage may have been learned either on- or off-chain, so use
+ // the ID of whichever claim event is pending, if any. Otherwise, as
+ // the channel is closed, any later claim event will be from on-chain.
+ let event_id =
+ monitor.pending_claim_event_id(htlc_id).unwrap_or_else(
+ || htlc_monitor_event_id(htlc_id, true, true),
+ );
let update = PaymentCompleteUpdate {
counterparty_node_id: monitor.get_counterparty_node_id(),
channel_funding_outpoint: monitor.get_funding_txo(),
channel_id: monitor.channel_id(),
htlc_id,
+ monitor_event_source: Some(MonitorEventSource {
+ event_id,
+ channel_id: monitor.channel_id(),
+ }),
};
let mut compl_action = Some(
EventCompletionAction::ReleasePaymentCompleteChannelMonitorUpdate(update)
@@ -20885,6 +21038,8 @@ impl<
session_priv,
path,
true,
+ false,
+ best_block.height,
&mut compl_action,
&pending_events,
&logger,
@@ -20953,6 +21108,7 @@ impl<
channel_funding_outpoint: monitor.get_funding_txo(),
channel_id: monitor.channel_id(),
htlc_id: SentHTLCId::from_source(&htlc_source),
+ monitor_event_source: None,
});
failed_htlcs.push((
@@ -21699,6 +21855,7 @@ impl<
downstream_user_channel_id,
None,
None,
+ false,
);
}
@@ -21869,6 +22026,7 @@ mod tests {
None,
Some(downstream_attribution),
None,
+ false,
);
check_added_monitors(&nodes[1], 1);
### lightning/src/ln/functional_test_utils.rs
@@ -13,7 +13,7 @@
use crate::blinded_path::payment::{
BlindedPaymentPath, DummyTlvs, ForwardNode, PaymentContext, ReceiveTlvs, TrampolineForwardTlvs,
};
-use crate::chain::channelmonitor::{ChannelMonitor, HTLC_FAIL_BACK_BUFFER};
+use crate::chain::channelmonitor::{ChannelMonitor, MonitorEvent, HTLC_FAIL_BACK_BUFFER};
use crate::chain::transaction::OutPoint;
use crate::chain::{BlockLocator, ChannelMonitorUpdateStatus, Confirm, Listen, Watch};
use crate::events::bump_transaction::sync::BumpTransactionEventHandlerSync;
@@ -1328,7 +1328,20 @@ pub fn check_added_monitors<CM: AChannelManager, H: NodeHolder<CM = CM>>(node: &
if let Some(chain_monitor) = node.chain_monitor() {
let mut added_monitors = chain_monitor.added_monitors.lock().unwrap();
let n = added_monitors.len();
- assert_eq!(n, count, "expected {} monitors to be added, not {}", count, n);
+ if n != count {
+ let recent = chain_monitor.recent_monitor_updates.lock().unwrap();
+ let mut desc = String::new();
+ for (i, (chan_id, update)) in recent.iter().take(n).enumerate() {
+ desc += &format!(
+ "\n [{}] chan={} update_id={} steps={:?}",
+ i, chan_id, update.update_id, update.updates
+ );
+ }
+ panic!(
+ "expected {} monitors to be added, not {}. Last {} updates (most recent first):{}",
+ count, n, n, desc
+ );
+ }
added_monitors.clear();
}
}
@@ -3048,6 +3061,32 @@ macro_rules! expect_payment_claimed {
};
}
+/// Returns the number of unacked [`MonitorEvent::HTLCEvent`]s for the given payment hash across
+/// all of `node`'s channel monitors.
+fn count_unacked_htlc_monitor_events<CM: AChannelManager, H: NodeHolder<CM = CM>>(
+ node: &H, payment_hash: &PaymentHash,
+) -> usize {
+ node.chain_monitor()
+ .map(|chain_monitor| {
+ chain_monitor
+ .chain_monitor
+ .list_monitors()
+ .iter()
+ .map(|channel_id| {
+ let monitor = chain_monitor.chain_monitor.get_monitor(*channel_id).unwrap();
+ monitor
+ .list_unacked_monitor_events()
+ .iter()
+ .filter(
+ |(_, ev)| matches!(ev, MonitorEvent::HTLCEvent(upd) if upd.payment_hash == *payment_hash),
+ )
+ .count()
+ })
+ .sum()
+ })
+ .unwrap_or(0)
+}
+
/// Inspect events to assert that a payment was sent. If this was a BOLT 12 payment, the BOLT 12 invoice is returned. If
/// per-path claims are expected, the events for each path are returned as well.
pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM = CM>>(
@@ -3070,6 +3109,10 @@ pub fn expect_payment_sent<CM: AChannelManager, H: NodeHolder<CM = CM>>(
if expect_post_ev_mon_update {
check_added_monitors(node, 1);
}
+ // Releasing the `PaymentSent` event should have acked the claimed HTLC(s)' `MonitorEvent`s.
+ let mon_ev_count = count_unacked_htlc_monitor_events(node, &expected_payment_hash);
+ assert_eq!(0, mon_ev_count, "expected no HTLC monitor events after the PaymentSent event");
+
// We return the invoice because some test may want to check the invoice details.
let invoice;
let mut path_events = Vec::new();
@@ -4330,6 +4373,7 @@ pub fn pass_claimed_payment_along_route_from_ev(
};
let commitment = &next_msgs.as_ref().unwrap().1;
do_commitment_signed_dance($node, $prev_node, commitment, false, false);
+ assert!($node.node.get_and_clear_pending_events().is_empty());
next_msgs = new_next_msgs;
}};
}
@@ -4363,6 +4407,18 @@ pub fn pass_claimed_payment_along_route_from_ev(
}
}
+ if !skip_last {
+ // Each fulfilled path has an unacked `MonitorEvent` until the origin processes its
+ // events. Processing `PaymentSent` must acknowledge all of these claims.
+ let payment_hash = PaymentHash(Sha256::hash(&our_payment_preimage.0).to_byte_array());
+ let mon_ev_count = count_unacked_htlc_monitor_events(origin_node, &payment_hash);
+ assert_eq!(
+ expected_paths.len(),
+ mon_ev_count,
+ "expected an HTLC monitor event per fulfilled path prior to PaymentSent event"
+ );
+ }
+
// Ensure that claim_funds is idempotent.
expected_paths[0].last().unwrap().node.claim_funds(our_payment_preimage, Default::default());
assert!(expected_paths[0].last().unwrap().node.get_and_clear_pending_msg_events().is_empty());
### lightning/src/ln/monitor_tests.rs
@@ -13,11 +13,11 @@
use crate::sign::{ecdsa::EcdsaChannelSigner, OutputSpender, SignerProvider, SpendableOutputDescriptor};
use crate::chain::{BlockLocator, Watch};
-use crate::chain::channelmonitor::{Balance, BalanceSource, ChannelMonitor, ChannelMonitorUpdateStep, HolderCommitmentTransactionBalance, ANTI_REORG_DELAY, ARCHIVAL_DELAY_BLOCKS, CLTV_CLAIM_BUFFER, COUNTERPARTY_CLAIMABLE_WITHIN_BLOCKS_PINNABLE, LATENCY_GRACE_PERIOD_BLOCKS};
+use crate::chain::channelmonitor::{Balance, BalanceSource, ChannelMonitor, ChannelMonitorUpdateStep, HolderCommitmentTransactionBalance, MonitorEvent, ANTI_REORG_DELAY, ARCHIVAL_DELAY_BLOCKS, CLTV_CLAIM_BUFFER, COUNTERPARTY_CLAIMABLE_WITHIN_BLOCKS_PINNABLE, LATENCY_GRACE_PERIOD_BLOCKS};
use crate::chain::transaction::OutPoint;
use crate::chain::chaininterface::{ConfirmationTarget, LowerBoundedFeeEstimator, compute_feerate_sat_per_1000_weight};
use crate::events::bump_transaction::BumpTransactionEvent;
-use crate::events::{Event, ClosureReason, HTLCHandlingFailureType};
+use crate::events::{Event, EventsProvider, ClosureReason, HTLCHandlingFailureType, ReplayEvent};
use crate::ln::channel;
use crate::ln::types::ChannelId;
use crate::ln::chan_utils;
@@ -3868,3 +3868,125 @@ fn test_onchain_preimage_after_fail_back_before_backwards_timeout() {
do_commitment_signed_dance(&nodes[0], &nodes[1], &htlc_updates.commitment_signed, false, false);
expect_payment_sent(&nodes[0], payment_preimage, None, true, true);
}
+
+#[test]
+fn test_onchain_claim_of_offchain_claimed_htlc_balance() {
+ // Tests that if our counterparty claims an outbound HTLC off-chain (i.e. we've handled their
+ // `update_fulfill_htlc` and `commitment_signed`, generating a `PaymentSent` event which the
+ // user has not yet processed) and then force-closes with a commitment transaction which still
+ // contains the HTLC, sweeping it on-chain with an HTLC-success transaction, our
+ // `ChannelMonitor` still records the on-chain HTLC spend once it reaches `ANTI_REORG_DELAY`
+ // confirmations. Failing to do so would leave a phantom `Balance` for the swept HTLC output
+ // around forever, preventing the monitor from ever being archived.
+ //
+ // Also tests that the on-chain claim is still surfaced to the `ChannelManager` despite the
+ // off-chain claim's `MonitorEvent` being unacked, so that the payment's path is resolved at
+ // runtime rather than only on the next restart.
+ let chanmon_cfgs = create_chanmon_cfgs(2);
+ let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+ let legacy_cfg = test_legacy_channel_config();
+ let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[Some(legacy_cfg.clone()), Some(legacy_cfg)]);
+ let mut nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+
+ let node_a_id = nodes[0].node.get_our_node_id();
+ let node_b_id = nodes[1].node.get_our_node_id();
+
+ let (_, _, chan_id, funding_tx) =
+ create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 500_000_000);
+
+ let (preimage, payment_hash, ..) = route_payment(&nodes[0], &[&nodes[1]], 10_000_000);
+
+ nodes[1].node.claim_funds(preimage, Default::default());
+ check_added_monitors(&nodes[1], 1);
+ expect_payment_claimed!(nodes[1], payment_hash, 10_000_000);
+
+ // Deliver B's `update_fulfill_htlc` and `commitment_signed` to A, but withhold A's responding
+ // RAA and CS, leaving the HTLC present in B's latest holder commitment transaction. A now has
+ // a `PaymentSent` event pending as well as an unacked `MonitorEvent` for the off-chain claim.
+ let mut updates = get_htlc_update_msgs(&nodes[1], &node_a_id);
+ nodes[0].node.handle_update_fulfill_htlc(node_b_id, updates.update_fulfill_htlcs.remove(0));
+ nodes[0].node.handle_commitment_signed_batch_test(node_b_id, &updates.commitment_signed);
+ check_added_monitors(&nodes[0], 1);
+ let _a_raa_cs = get_revoke_commit_msgs(&nodes[0], &node_b_id);
+ // Process the off-chain monitor event while keeping `PaymentSent` unhandled.
+ nodes[0].node.process_pending_events(&|_: Event| Err(ReplayEvent()));
+
+ let unacked_events = get_monitor!(nodes[0], chan_id).list_unacked_monitor_events();
+ assert!(
+ unacked_events.iter().any(|(_, ev)| matches!(ev, MonitorEvent::HTLCEvent(..))),
+ "expected an unacked off-chain claim MonitorEvent: {unacked_events:?}",
+ );
+
+ // B force-closes, broadcasting its latest commitment transaction, which contains the HTLC.
+ let message = "Closed".to_owned();
+ nodes[1].node.force_close_broadcasting_latest_txn(&chan_id, &node_a_id, message.clone()).unwrap();
+ check_added_monitors(&nodes[1], 1);
+ let reason = ClosureReason::HolderForceClosed { broadcasted_latest_txn: Some(true), message };
+ check_closed_event(&nodes[1], 1, reason, &[node_a_id], 1_000_000);
+ check_closed_broadcast(&nodes[1], 1, true);
+
+ // B's monitor broadcasts its commitment transaction along with the HTLC-success transaction
+ // sweeping the HTLC (it already has the preimage).
+ let (commitment_tx, htlc_success_tx) = {
+ let mut txn = nodes[1].tx_broadcaster.txn_broadcast();
+ assert_eq!(txn.len(), 2);
+ let commitment_tx = txn.remove(0);
+ check_spends!(commitment_tx, funding_tx);
+ assert_eq!(commitment_tx.output.len(), 3); // to_self, to_remote, and the HTLC
+ let htlc_success_tx = txn.remove(0);
+ check_spends!(htlc_success_tx, commitment_tx);
+ (commitment_tx, htlc_success_tx)
+ };
+
+ // Confirm B's commitment and HTLC-success transactions on B, discarding any rebroadcasts.
+ mine_transaction(&nodes[1], &commitment_tx);
+ mine_transaction(&nodes[1], &htlc_success_tx);
+ let _ = nodes[1].tx_broadcaster.txn_broadcast();
+
+ // Confirm B's commitment and HTLC-success transactions on A.
+ mine_transaction(&nodes[0], &commitment_tx);
+ nodes[0].node.process_pending_events(&|_: Event| Err(ReplayEvent()));
+ check_closed_broadcast(&nodes[0], 1, true);
+ check_added_monitors(&nodes[0], 1);
+ mine_transaction(&nodes[0], &htlc_success_tx);
+ connect_blocks(&nodes[0], ANTI_REORG_DELAY - 1);
+
+ // The HTLC-success spend of the HTLC output has now been irrevocably confirmed, so A must not
+ // report a `Balance` for the swept HTLC output.
+ let balances = get_monitor!(nodes[0], chan_id).get_claimable_balances();
+ assert!(
+ !balances.iter().any(|bal| matches!(bal, Balance::MaybeTimeoutClaimableHTLC { .. })),
+ "the counterparty's on-chain HTLC claim should have resolved the HTLC balance: {balances:?}",
+ );
+
+ let unacked_events = get_monitor!(nodes[0], chan_id).list_unacked_monitor_events();
+ let claims: Vec<_> = unacked_events.iter().filter_map(|(_, ev)| match ev {
+ MonitorEvent::HTLCEvent(upd) if upd.payment_hash == payment_hash => Some(upd),
+ _ => None,
+ }).collect();
+ assert_eq!(claims.len(), 2, "{unacked_events:?}");
+ assert_eq!(claims.iter().filter(|upd| upd.from_onchain).count(), 1);
+
+ // Finally, process A's pending events. In addition to `PaymentSent` and `ChannelClosed`, the
+ // counterparty's on-chain claim must have resolved the payment's path even though the
+ // off-chain claim's `MonitorEvent` was still unacked when the HTLC-success transaction
+ // confirmed: a `PaymentPathSuccessful` event is generated and, once it is processed, a
+ // `ReleasePaymentComplete` monitor update is issued for the swept HTLC.
+ let events = nodes[0].node.get_and_clear_pending_events();
+ assert_eq!(events.len(), 3, "{events:?}");
+ assert!(
+ events.iter().any(|ev| matches!(ev, Event::PaymentSent { .. })),
+ "{events:?}",
+ );
+ assert!(
+ events.iter().any(|ev| matches!(ev, Event::PaymentPathSuccessful { .. })),
+ "{events:?}",
+ );
+ assert!(
+ events.iter().any(|ev| matches!(ev, Event::ChannelClosed { .. })),
+ "{events:?}",
+ );
+ check_added_monitors(&nodes[0], 1);
+ // Processing the events acks the claim's `MonitorEvent`s.
+ assert!(get_monitor!(nodes[0], chan_id).list_unacked_monitor_events().is_empty());
+}
### lightning/src/ln/outbound_payment.rs
@@ -261,7 +261,8 @@ impl PendingOutboundPayment {
// invoice but have not locked in HTLCs for the payment yet.
fn is_pre_htlc_lock_in(&self) -> bool {
match self {
- PendingOutboundPayment::AwaitingInvoice { .. }
+ PendingOutboundPayment::AwaitingOffer { .. }
+ | PendingOutboundPayment::AwaitingInvoice { .. }
| PendingOutboundPayment::InvoiceReceived { .. }
| PendingOutboundPayment::StaticInvoiceReceived { .. } => true,
_ => false,
@@ -2407,53 +2408,88 @@ impl OutboundPayments {
}
}
- #[rustfmt::skip]
pub(super) fn claim_htlc<L: Logger>(
- &self, payment_id: PaymentId, payment_preimage: PaymentPreimage, bolt12_invoice: Option<PaidBolt12Invoice>,
- session_priv: SecretKey, path: Path, from_onchain: bool, ev_completion_action: &mut Option<EventCompletionAction>,
+ &self, payment_id: PaymentId, payment_preimage: PaymentPreimage,
+ bolt12_invoice: Option<PaidBolt12Invoice>, session_priv: SecretKey, path: Path,
+ channel_is_closed: bool, from_monitor_event: bool, best_block_height: u32,
+ ev_completion_action: &mut Option<EventCompletionAction>,
pending_events: &Mutex<VecDeque<(events::Event, Option<EventCompletionAction>)>>,
logger: &WithContext<L>,
- )
- where
- {
+ ) {
let mut session_priv_bytes = [0; 32];
session_priv_bytes.copy_from_slice(&session_priv[..]);
let mut outbounds = self.pending_outbound_payments.lock().unwrap();
let mut pending_events = pending_events.lock().unwrap();
+
+ if outbounds.get(&payment_id).map_or(true, |payment| payment.is_pre_htlc_lock_in()) {
+ let payment_sent_pending = pending_events.iter().any(|(ev, _)| {
+ matches!(ev, events::Event::PaymentSent { payment_id: ev_id, .. } if *ev_id == Some(payment_id))
+ });
+ if !payment_sent_pending {
+ // If a `ChannelMonitor` resolved an HTLC we have no record of locking in HTLCs for, it's
+ // possible we were deserialized from a stale `ChannelManager` that predates the payment.
+ // Re-add the payment to ensure we don't fail to surface the payment's resolution to the
+ // user, even though it's possible that a duplicate `PaymentSent` event may result if the
+ // manager or the monitor is not persisted in between the user processing the event and a
+ // node restart.
+ debug_assert!(from_monitor_event);
+ insert_from_monitor_on_startup(
+ &mut outbounds,
+ payment_id,
+ payment_preimage.into(),
+ session_priv_bytes,
+ &path,
+ best_block_height,
+ logger,
+ );
+ }
+ }
+
if let hash_map::Entry::Occupied(mut payment) = outbounds.entry(payment_id) {
if !payment.get().is_fulfilled() {
let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0).to_byte_array());
log_info!(logger, "Payment with id {} and hash {} sent!", payment_id, payment_hash);
let fee_paid_msat = payment.get().get_pending_fee_msat();
let amount_msat = payment.get().total_msat();
- pending_events.push_back((events::Event::PaymentSent {
- payment_id: Some(payment_id),
- payment_preimage,
- payment_hash,
- amount_msat,
- fee_paid_msat,
- bolt12_invoice: bolt12_invoice,
- }, ev_completion_action.take()));
+ pending_events.push_back((
+ events::Event::PaymentSent {
+ payment_id: Some(payment_id),
+ payment_preimage,
+ payment_hash,
+ amount_msat,
+ fee_paid_msat,
+ bolt12_invoice,
+ },
+ ev_completion_action.take(),
+ ));
payment.get_mut().mark_fulfilled();
}
- if from_onchain {
- // We currently immediately remove HTLCs which were fulfilled on-chain.
+ if channel_is_closed {
+ // We currently immediately remove HTLCs sent over closed channels.
// This could potentially lead to removing a pending payment too early,
// with a reorg of one block causing us to re-add the fulfilled payment on
// restart.
if payment.get_mut().remove(&session_priv_bytes, Some(&path)) {
- let payment_hash = Some(PaymentHash(Sha256::hash(&payment_preimage.0).to_byte_array()));
- pending_events.push_back((events::Event::PaymentPathSuccessful {
- payment_id,
- payment_hash,
- path,
- hold_times: Vec::new(),
- }, ev_completion_action.take()));
+ let payment_hash =
+ Some(PaymentHash(Sha256::hash(&payment_preimage.0).to_byte_array()));
+ pending_events.push_back((
+ events::Event::PaymentPathSuccessful {
+ payment_id,
+ payment_hash,
+ path,
+ hold_times: Vec::new(),
+ },
+ ev_completion_action.take(),
+ ));
}
}
} else {
- log_trace!(logger, "Received duplicative fulfill for HTLC with payment_preimage {}", &payment_preimage);
+ log_trace!(
+ logger,
+ "Received duplicative fulfill for HTLC with payment_preimage {}",
+ &payment_preimage
+ );
}
}
@@ -2812,64 +2848,79 @@ impl OutboundPayments {
&self, payment_id: PaymentId, payment_hash: PaymentHash, session_priv_bytes: [u8; 32],
path: &Path, best_block_height: u32, logger: &WithContext<L>,
) {
- let path_amt = path.final_value_msat();
- let path_fee = path.fee_msat();
-
- macro_rules! new_retryable {
- () => {
- PendingOutboundPayment::Retryable {
- retry_strategy: None,
- attempts: PaymentAttempts::new(),
- payment_params: None,
- session_privs: hash_set_from_iter([session_priv_bytes]),
- payment_hash,
- payment_secret: None, // only used for retries, and we'll never retry on startup
- payment_metadata: None, // only used for retries, and we'll never retry on startup
- keysend_preimage: None, // only used for retries, and we'll never retry on startup
- invoice_request: None, // only used for retries, and we'll never retry on startup
- bolt12_invoice: None, // only used for retries, and we'll never retry on startup!
- custom_tlvs: Vec::new(), // only used for retries, and we'll never retry on startup
- pending_amt_msat: path_amt,
- pending_fee_msat: Some(path_fee),
- total_msat: path_amt,
- onion_total_msat: path_amt,
- starting_block_height: best_block_height,
- remaining_max_total_routing_fee_msat: None, // only used for retries, and we'll never retry on startup
- }
+ let mut outbounds = self.pending_outbound_payments.lock().unwrap();
+ insert_from_monitor_on_startup(
+ &mut outbounds,
+ payment_id,
+ payment_hash,
+ session_priv_bytes,
+ path,
+ best_block_height,
+ logger,
+ )
+ }
+}
+
+fn insert_from_monitor_on_startup<L: Logger>(
+ outbounds: &mut HashMap<PaymentId, PendingOutboundPayment>, payment_id: PaymentId,
+ payment_hash: PaymentHash, session_priv_bytes: [u8; 32], path: &Path, best_block_height: u32,
+ logger: &WithContext<L>,
+) {
+ let path_amt = path.final_value_msat();
+ let path_fee = path.fee_msat();
+
+ macro_rules! new_retryable {
+ () => {
+ PendingOutboundPayment::Retryable {
+ retry_strategy: None,
+ attempts: PaymentAttempts::new(),
+ payment_params: None,
+ session_privs: hash_set_from_iter([session_priv_bytes]),
+ payment_hash,
+ payment_secret: None, // only used for retries, and we'll never retry on startup
+ payment_metadata: None, // only used for retries, and we'll never retry on startup
+ keysend_preimage: None, // only used for retries, and we'll never retry on startup
+ invoice_request: None, // only used for retries, and we'll never retry on startup
+ bolt12_invoice: None, // only used for retries, and we'll never retry on startup!
+ custom_tlvs: Vec::new(), // only used for retries, and we'll never retry on startup
+ pending_amt_msat: path_amt,
+ pending_fee_msat: Some(path_fee),
+ total_msat: path_amt,
+ onion_total_msat: path_amt,
+ starting_block_height: best_block_height,
+ remaining_max_total_routing_fee_msat: None, // only used for retries, and we'll never retry on startup
}
}
+ }
- match self.pending_outbound_payments.lock().unwrap().entry(payment_id) {
- hash_map::Entry::Occupied(mut entry) => {
- let newly_added = match entry.get() {
- PendingOutboundPayment::AwaitingOffer { .. }
- | PendingOutboundPayment::AwaitingInvoice { .. }
- | PendingOutboundPayment::InvoiceReceived { .. }
- | PendingOutboundPayment::StaticInvoiceReceived { .. } => {
- // If we've reached this point, it means we initiated a payment to a BOLT 12 invoice and
- // locked the htlc(s) into the `ChannelMonitor`(s), but failed to persist the
- // `ChannelManager` after transitioning from this state to `Retryable` prior to shutdown.
- // Therefore, we need to move this payment to `Retryable` now to avoid double-paying if
- // the recipient sends a duplicate invoice or release_held_htlc onion message.
- *entry.get_mut() = new_retryable!();
- true
- },
- PendingOutboundPayment::Legacy { .. }
- | PendingOutboundPayment::Retryable { .. }
- | PendingOutboundPayment::Fulfilled { .. }
- | PendingOutboundPayment::Abandoned { .. } => {
- entry.get_mut().insert(session_priv_bytes, &path)
- },
- };
- log_info!(logger, "{} a pending payment path for {} msat for session priv {} on an existing pending payment with payment hash {}",
- if newly_added { "Added" } else { "Had" }, path_amt, log_bytes!(session_priv_bytes), payment_hash);
- },
- hash_map::Entry::Vacant(entry) => {
- entry.insert(new_retryable!());
- log_info!(logger, "Added a pending payment for {} msat with payment hash {} for path with session priv {}",
- path_amt, payment_hash, log_bytes!(session_priv_bytes));
- },
- }
+ match outbounds.entry(payment_id) {
+ hash_map::Entry::Occupied(mut entry) => {
+ let newly_added = match entry.get() {
+ PendingOutboundPayment::AwaitingOffer { .. }
+ | PendingOutboundPayment::AwaitingInvoice { .. }
+ | PendingOutboundPayment::InvoiceReceived { .. }
+ | PendingOutboundPayment::StaticInvoiceReceived { .. } => {
+ // If we've reached this point, it means we initiated a payment to a BOLT 12 invoice and
+ // locked the htlc(s) into the `ChannelMonitor`(s), but failed to persist the
+ // `ChannelManager` after transitioning from this state to `Retryable` prior to shutdown.
+ // Therefore, we need to move this payment to `Retryable` now to avoid double-paying if
+ // the recipient sends a duplicate invoice or release_held_htlc onion message.
+ *entry.get_mut() = new_retryable!();
+ true
+ },
+ PendingOutboundPayment::Legacy { .. }
+ | PendingOutboundPayment::Retryable { .. }
+ | PendingOutboundPayment::Fulfilled { .. }
+ | PendingOutboundPayment::Abandoned { .. } => entry.get_mut().insert(session_priv_bytes, &path),
+ };
+ log_info!(logger, "{} a pending payment path for {} msat for session priv {} on an existing pending payment with payment hash {}",
+ if newly_added { "Added" } else { "Had" }, path_amt, log_bytes!(session_priv_bytes), payment_hash);
+ },
+ hash_map::Entry::Vacant(entry) => {
+ entry.insert(new_retryable!());
+ log_info!(logger, "Added a pending payment for {} msat with payment hash {} for path with session priv {}",
+ path_amt, payment_hash, log_bytes!(session_priv_bytes));
+ },
}
}
### lightning/src/ln/shutdown_tests.rs
@@ -1933,7 +1933,7 @@ fn test_pending_htlcs_arent_lost_on_mon_delay() {
check_added_monitors(&nodes[1], 1);
let events = nodes[1].node.get_and_clear_pending_events();
- assert_eq!(events.len(), 3, "{events:?}");
+ assert_eq!(events.len(), 4, "{events:?}");
assert!(events.iter().any(|ev| {
if let Event::PaymentSent { payment_preimage: ev_preimage, .. } = ev {
assert_eq!(*ev_preimage, preimage_a);
@@ -1943,6 +1943,7 @@ fn test_pending_htlcs_arent_lost_on_mon_delay() {
}
}));
assert!(events.iter().any(|ev| matches!(ev, Event::ChannelClosed { .. })));
+ assert!(events.iter().any(|ev| matches!(ev, Event::PaymentPathSuccessful { payment_hash: Some(hash), .. } if *hash == payment_hash_a)));
assert!(events.iter().any(|ev| {
if let Event::HTLCHandlingFailed { failure_type, failure_reason, .. } = ev {
assert!(matches!(failure_type, HTLCHandlingFailureType::Forward { .. }));
@@ -1956,6 +1957,7 @@ fn test_pending_htlcs_arent_lost_on_mon_delay() {
false
}
}));
+ check_added_monitors(&nodes[1], 2);
nodes[1].node.process_pending_htlc_forwards();
check_added_monitors(&nodes[1], 1);
### lightning/src/util/test_utils.rs
@@ -537,6 +537,8 @@ pub struct TestChainMonitor<'a> {
/// deferred operations. This allows tests to control exactly when queued monitor updates
/// are applied to the in-memory monitor.
pub pause_flush: AtomicBool,
+ /// Buffer of the last 20 monitor updates, most recent first.
+ pub recent_monitor_updates: Mutex<Vec<(ChannelId, ChannelMonitorUpdate)>>,
}
impl<'a> TestChainMonitor<'a> {
pub fn new(
@@ -597,6 +599,7 @@ impl<'a> TestChainMonitor<'a> {
#[cfg(feature = "std")]
write_blocker: Mutex::new(None),
pause_flush: AtomicBool::new(false),
+ recent_monitor_updates: Mutex::new(Vec::new()),
}
}
@@ -695,6 +698,12 @@ impl<'a> chain::Watch<TestChannelSigner> for TestChainMonitor<'a> {
.or_insert(Vec::new())
.push(update.clone());
+ {
+ let mut recent = self.recent_monitor_updates.lock().unwrap();
+ recent.insert(0, (channel_id, update.clone()));
+ recent.truncate(20);
+ }
+
if let Some(exp) = self.expect_channel_force_closed.lock().unwrap().take() {
assert_eq!(channel_id, exp.0);
assert_eq!(update.updates.len(), 1);Why this scored 52/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.