Merge pull request #4706 from TheBlueMatt/2026-06-0.2-backports-2

[0.2] Another round of backports + initial release notes

Author: TheBlueMatt

CHANGELOG.md

@@ -1,3 +1,89 @@
+# 0.2.3 - Jun 18, 2026 - "Through the Loupe"
+
+## API Updates
+ * `DefaultMessageRouter` will now always generate blinded message paths that
+   provide no privacy (where our node is the introduction node) for nodes with
+   public channels. This works around an issue which will appear for any nodes
+   with LND peers that enable onion messaging - such peers will refuse to
+   forward BOLT 12 messages from unknown third parties, which most BOLT 12
+   payers rely on today (#4647).
+ * Explicit `amount_msats` of 0 is rejected in BOLT 12 `Offer`s; `OfferBuilder`
+   now maps 0-amounts to an amount of `None` (#4324).
+
+## Bug Fixes
+ * `Features::supports_zero_conf` no longer clears the `ZeroConf` features and
+   `Features::requires_zero_conf` now correctly reports required, rather than
+   supported, status (#4517).
+ * If an MPP payment is claimed but `ChannelMonitorUpdate`s for some parts are
+   still being completed asynchronously, further channel updates (e.g.
+   forwarding another payment) are pending and the node restarts, the channel
+   could have become stuck (#4520).
+ * The presence of unconfirmed transactions actually no longer causes
+   `ElectrumSyncClient` to spuriously fail to sync (#4590).
+ * LSPS1, LSPS2, and LSPS5 persistence will no longer get stuck and refuse to
+   persist again after a single failure from the KVStore (#4597, #4282).
+ * Dropping the future returned by
+   `OutputSweeper::regenerate_and_broadcast_spend_if_necessary` no longer
+   results in future calls to the same method being spuriously ignored (#4598).
+ * Used async-receive offers are no longer refreshed on every timer tick once
+   their refresh time is reached (#4672).
+ * `FilesystemStore::list_all_keys` will no longer fail if there are stale
+   intermediate files lying around from a previous unclean shutdown (#4618).
+ * When forwarding an HTLC while in a blinded path with proportional fees over
+   200%, LDK will no longer spuriously allow a forward that pays us 1 msat too
+   little in fees (#4697).
+ * Fixed a rare case where a channel could get stuck on reconnect when using
+   both async `ChannelMonitorUpdate` persistence and async signing (#4684).
+ * If we had exactly zero balance in a zero-fee-commitment channel, the
+   counterparty was able to splice all of their balance out, violating the
+   reserve requirements they'd otherwise be forced to keep (#4580).
+ * Providing an `Event::HTLCIntercepted` to the `LSPS2ServiceHandler` twice no
+   longer results in spuriously opening a channel early (#4656).
+ * `Event::PaymentSent::fee_paid_msat` is no longer `None` in cases where
+   `ChannelManager::abandon_payment` was called before the payment ultimately
+   completes anyway (#4651).
+ * `AnchorDescriptor::previous_utxo` now provides the correct `script_pubkey`
+   for non-zero-commitment-fee anchor channels (#4669).
+ * Syncing a `ChainMonitor` using the `Confirm` trait will no longer write some
+   full `ChannelMonitor`s to disk several times per block (#4544).
+ * `OMDomainResolver` now correctly accounts for failed queries when rate
+   limiting, ensuring we continue to respond to queries after failures (#4591).
+ * Calling `ChannelManager::send_payment_with_route` without a `route_params`
+   and with an invalid `Route` will no longer panic (#4707).
+ * `LSPS2ServiceHandler::channel_open_failed` now correctly fails intercepted
+   HTLCs rather than allowing them to fail just before expiry (#4677).
+ * `StaticInvoice::is_offer_expired` was corrected to check offer, rather than
+   static invoice, expiry (#4594).
+ * `lightning-custom-message`'s handling of `peer_connected` events now ensures
+   that sub-handlers will see a `peer_disconnected` event if a different
+   sub-handler refused the connection by `Err`ing `peer_connected` (#4595).
+ * Replay protection for LSPS5 signatures now detects replays which are only
+   different in the encoded signature's case (#4701).
+ * When `lightning-liquidity` is configured in the background processor, there
+   is no longer a stream of `Persisting LiquidityManager...` log spam (#4246).
+ * Incomplete MPP keysend payments will no longer see their HTLCs held until
+   expiry (#4558).
+ * `InvoiceRequestBuilder` will no longer accept a `quantity` of `0` for a
+   BOLT 12 `Offer`, allowing any quantity up to a bound (#4667).
+ * `lightning-custom-message` handlers that return `Ok(None)` when asked to
+   deserialize a message in their defined range no longer cause panics (#4709).
+ * Several spurious debug assertions were fixed (#4537, #4618, #4026)
+
+## Security
+0.2.3 fixes several underestimates of the anchor reserves required to ensure we
+can reliably close channels and a sanitization issue.
+ * When using the `anchor_channel_reserves` module to calculate reserves
+   required to pay for fees when closing anchor channels, zero-fee-commitment
+   channels were not considered. This could allow a counterparty to open many
+   channels, leaving us unable to properly force-close (#4592).
+ * The `anchor_channel_reserves` module overestimated the value of `Utxo`s in
+   the wallet by ignoring the `TxIn` cost to spend them (#4670).
+ * `PrintableString` did not properly sanitize unicode format characters,
+   allowing an attacker to corrupt the rendering of logs or UI (#4593, #4605).
+
+Thanks to Project Loupe for reporting most of the issues fixed in this release.
+
+
 # 0.2.2 - Feb 6, 2025 - "An Async Splicing Production"
 
 ## API Updates

lightning-custom-message/src/lib.rs

@@ -358,7 +358,12 @@ macro_rules! composite_custom_message_handler {
 				match message_type {
 					$(
 						$pattern => match <$type>::read(&self.$field, message_type, buffer)? {
-							None => unreachable!(),
+							// A sub-handler returns `None` for a `message_type` it doesn't
+							// recognize. The composite's pattern can be broader than the types
+							// the sub-handler decodes (e.g. a range), and `message_type` is
+							// peer-provided, so report the message as unknown rather than
+							// treating this as unreachable and panicking.
+							None => Ok(None),
 							Some(message) => Ok(Some($message::$variant(message))),
 						},
 					)*
@@ -501,6 +506,71 @@ mod tests {
 		}
 	);
 
+	struct ReservedBlockHandler;
+	impl CustomMessageReader for ReservedBlockHandler {
+		type CustomMessage = Foo;
+		fn read<R: LengthLimitedRead>(
+			&self, message_type: u16, _b: &mut R,
+		) -> Result<Option<Foo>, DecodeError> {
+			// This build defines only the message at 32768; the rest of the block its
+			// protocol reserved (32768..=32777) is for types future versions may add.
+			// A not-yet-defined type is unknown to this build, so per the
+			// `CustomMessageReader` contract it returns `Ok(None)` -- a newer peer can
+			// send one and this older node will treat it as an unknown message.
+			match message_type {
+				32768 => Ok(Some(Foo)),
+				_ => Ok(None),
+			}
+		}
+	}
+	impl CustomMessageHandler for ReservedBlockHandler {
+		fn handle_custom_message(&self, _msg: Foo, _: PublicKey) -> Result<(), LightningError> {
+			Ok(())
+		}
+		fn get_and_clear_pending_msg(&self) -> Vec<(PublicKey, Foo)> {
+			vec![]
+		}
+		fn peer_disconnected(&self, _: PublicKey) {}
+		fn peer_connected(&self, _: PublicKey, _: &Init, _: bool) -> Result<(), ()> {
+			Ok(())
+		}
+		fn provided_node_features(&self) -> NodeFeatures {
+			NodeFeatures::empty()
+		}
+		fn provided_init_features(&self, _: PublicKey) -> InitFeatures {
+			InitFeatures::empty()
+		}
+	}
+
+	composite_custom_message_handler!(
+		struct ReservedBlockComposite {
+			proto: ReservedBlockHandler,
+		}
+
+		enum ReservedBlockMessage {
+			Proto(32768..=32777),
+		}
+	);
+
+	#[test]
+	fn read_treats_a_reserved_in_range_type_as_unknown() {
+		// A sub-handler may own a block of type ids (declared here as a range) yet only
+		// decode the subset its build defines, returning `Ok(None)` for reserved or
+		// not-yet-defined types in the block -- exactly what a node does on receiving a
+		// newer peer's message. `read` must surface that as an unknown message, not
+		// panic.
+		let composite = ReservedBlockComposite { proto: ReservedBlockHandler };
+		let mut buffer: &[u8] = &[];
+		// The message this build defines decodes to its variant.
+		assert!(matches!(
+			composite.read(32768, &mut buffer),
+			Ok(Some(ReservedBlockMessage::Proto(_)))
+		));
+		// A reserved type from the same block is reported unknown, not panicked
+		// (pre-fix the matched arm hit `unreachable!()`).
+		assert!(matches!(composite.read(32770, &mut buffer), Ok(None)));
+	}
+
 	#[test]
 	fn peer_connected_failure_does_not_leak_subhandler_state() {
 		let composite = CompositeHandler {

lightning-liquidity/src/lsps2/payment_queue.rs

@@ -26,21 +26,29 @@ impl PaymentQueue {
 		PaymentQueue { payments: Vec::new() }
 	}
 
+	fn payment_status(entry: &PaymentQueueEntry) -> (u64, usize) {
+		let total_expected_outbound_amount_msat =
+			entry.htlcs.iter().map(|htlc| htlc.expected_outbound_amount_msat).sum();
+		(total_expected_outbound_amount_msat, entry.htlcs.len())
+	}
+
 	pub(crate) fn add_htlc(&mut self, new_htlc: InterceptedHTLC) -> (u64, usize) {
+		if let Some(entry) = self
+			.payments
+			.iter()
+			.find(|entry| entry.htlcs.iter().any(|htlc| htlc.intercept_id == new_htlc.intercept_id))
+		{
+			debug_assert_eq!(entry.payment_hash, new_htlc.payment_hash);
+			return Self::payment_status(entry);
+		}
+
 		let payment =
 			self.payments.iter_mut().find(|entry| entry.payment_hash == new_htlc.payment_hash);
 		if let Some(entry) = payment {
 			// HTLCs within a payment should have the same payment hash.
 			debug_assert!(entry.htlcs.iter().all(|htlc| htlc.payment_hash == entry.payment_hash));
-			// The given HTLC should not already be present.
-			debug_assert!(entry
-				.htlcs
-				.iter()
-				.all(|htlc| htlc.intercept_id != new_htlc.intercept_id));
 			entry.htlcs.push(new_htlc);
-			let total_expected_outbound_amount_msat =
-				entry.htlcs.iter().map(|htlc| htlc.expected_outbound_amount_msat).sum();
-			(total_expected_outbound_amount_msat, entry.htlcs.len())
+			Self::payment_status(entry)
 		} else {
 			let expected_outbound_amount_msat = new_htlc.expected_outbound_amount_msat;
 			let entry =
@@ -127,6 +135,15 @@ mod tests {
 			(500_000_000, 2),
 		);
 
+		assert_eq!(
+			payment_queue.add_htlc(InterceptedHTLC {
+				intercept_id: InterceptId([2; 32]),
+				expected_outbound_amount_msat: 300_000_000,
+				payment_hash: PaymentHash([100; 32]),
+			}),
+			(500_000_000, 2),
+		);
+
 		let expected_entry = PaymentQueueEntry {
 			payment_hash: PaymentHash([100; 32]),
 			htlcs: vec![

lightning-liquidity/src/lsps2/service.rs

@@ -1257,6 +1257,8 @@ where
 	/// This removes the intercept SCID, any outbound channel state, and associated
 	/// channel‐ID mappings for the specified `user_channel_id`, but only while no payment
 	/// has been forwarded yet and no channel has been opened on-chain.
+	/// Any held HTLCs for the pending flow are failed backwards before the local state
+	/// is removed.
 	///
 	/// Returns an error if:
 	///  - there is no channel matching `user_channel_id`, or
@@ -1292,25 +1294,27 @@ where
 
 			let jit_channel = peer_state
 				.outbound_channels_by_intercept_scid
-				.get(&intercept_scid)
+				.get_mut(&intercept_scid)
 				.ok_or_else(|| APIError::APIMisuseError {
-				err: format!(
-					"Failed to map intercept_scid {} for user_channel_id {} to a channel.",
-					intercept_scid, user_channel_id,
-				),
-			})?;
+					err: format!(
+						"Failed to map intercept_scid {} for user_channel_id {} to a channel.",
+						intercept_scid, user_channel_id,
+					),
+				})?;
 
-			let is_pending = matches!(
-				jit_channel.state,
-				OutboundJITChannelState::PendingInitialPayment { .. }
-					| OutboundJITChannelState::PendingChannelOpen { .. }
-			);
+			let intercepted_htlcs = match &mut jit_channel.state {
+				OutboundJITChannelState::PendingInitialPayment { payment_queue }
+				| OutboundJITChannelState::PendingChannelOpen { payment_queue, .. } => payment_queue.clear(),
+				_ => {
+					return Err(APIError::APIMisuseError {
+						err: "Cannot abandon channel open after channel creation or payment forwarding"
+							.to_string(),
+					});
+				},
+			};
 
-			if !is_pending {
-				return Err(APIError::APIMisuseError {
-					err: "Cannot abandon channel open after channel creation or payment forwarding"
-						.to_string(),
-				});
+			for htlc in intercepted_htlcs {
+				let _ = self.channel_manager.get_cm().fail_intercepted_htlc(htlc.intercept_id);
 			}
 
 			peer_state.intercept_scid_by_user_channel_id.remove(&user_channel_id);
@@ -1784,14 +1788,22 @@ where
 		// TODO: We should eventually persist in parallel, however, when we do, we probably want to
 		// introduce some batching to upper-bound the number of requests inflight at any given
 		// time.
-		let mut did_persist = false;
 
 		if self.persistence_in_flight.fetch_add(1, Ordering::AcqRel) > 0 {
 			// If we're not the first event processor to get here, just return early, the increment
 			// we just did will be treated as "go around again" at the end.
-			return Ok(did_persist);
+			return Ok(false);
 		}
 
+		let res = self.do_persist().await;
+		debug_assert!(res.is_err() || self.persistence_in_flight.load(Ordering::Acquire) == 0);
+		self.persistence_in_flight.store(0, Ordering::Release);
+		res
+	}
+
+	async fn do_persist(&self) -> Result<bool, lightning::io::Error> {
+		let mut did_persist = false;
+
 		loop {
 			let mut need_remove = Vec::new();
 			let mut need_persist = Vec::new();
@@ -1853,6 +1865,7 @@ where
 					did_persist = true;
 				} else {
 					self.persist_peer_state(counterparty_node_id).await?;
+					did_persist = true;
 				}
 			}
 
@@ -2353,6 +2366,8 @@ mod tests {
 
 	use bitcoin::{absolute::LockTime, transaction::Version};
 	use core::str::FromStr;
+	use lightning::io::Cursor;
+	use lightning::util::ser::{Readable, Writeable};
 
 	const MAX_VALUE_MSAT: u64 = 21_000_000_0000_0000_000;
 
@@ -2760,6 +2775,52 @@ mod tests {
 		}
 	}
 
+	#[test]
+	fn replayed_intercepted_htlc_after_persist_is_idempotent() {
+		let payment_size_msat = Some(500_000_000);
+		let opening_fee_params = LSPS2OpeningFeeParams {
+			min_fee_msat: 10_000_000,
+			proportional: 10_000,
+			valid_until: LSPSDateTime::from_str("2035-05-20T08:30:45Z").unwrap(),
+			min_lifetime: 4032,
+			max_client_to_self_delay: 2016,
+			min_payment_size_msat: 10_000_000,
+			max_payment_size_msat: 1_000_000_000,
+			promise: "ignore".to_string(),
+		};
+		let intercept_scid = 42;
+		let user_channel_id = 43;
+		let htlc = InterceptedHTLC {
+			intercept_id: InterceptId([1; 32]),
+			expected_outbound_amount_msat: 500_000_000,
+			payment_hash: PaymentHash([2; 32]),
+		};
+
+		let mut jit_channel =
+			OutboundJITChannel::new(payment_size_msat, opening_fee_params, user_channel_id, false);
+		assert!(matches!(
+			jit_channel.htlc_intercepted(htlc).unwrap(),
+			Some(HTLCInterceptedAction::OpenChannel(_))
+		));
+
+		let mut peer_state = PeerState::new();
+		peer_state.intercept_scid_by_user_channel_id.insert(user_channel_id, intercept_scid);
+		peer_state.insert_outbound_channel(intercept_scid, jit_channel);
+
+		let encoded_peer_state = peer_state.encode();
+		let mut decoded_peer_state = PeerState::read(&mut Cursor::new(encoded_peer_state)).unwrap();
+		let decoded_jit_channel = decoded_peer_state
+			.outbound_channels_by_intercept_scid
+			.get_mut(&intercept_scid)
+			.unwrap();
+
+		assert!(decoded_jit_channel.htlc_intercepted(htlc).unwrap().is_none());
+
+		let ForwardPaymentAction(_, fee_payment) =
+			decoded_jit_channel.channel_ready(ChannelId([3; 32])).unwrap();
+		assert_eq!(fee_payment.htlcs, vec![htlc]);
+	}
+
 	#[test]
 	fn broadcast_not_allowed_after_non_paying_fee_payment_claimed() {
 		let min_fee_msat: u64 = 12345;

lightning-liquidity/src/lsps5/service.rs

@@ -339,6 +339,7 @@ where
 				did_persist = true;
 			} else {
 				self.persist_peer_state(client_id).await?;
+				did_persist = true;
 			}
 		}