Merge rbf_channel into splice_channel and expose prior contribution

Users previously had to choose between splice_channel (fresh splice) and
rbf_channel (fee bump) upfront. Since splice_channel already detects
pending splices and computes the minimum RBF feerate, rbf_channel was
redundant. Merging into a single API lets the user call one method and
discover from the returned FundingTemplate whether an RBF is possible.

The FundingTemplate now carries the user's prior contribution from the
previous splice negotiation when one is available. This lets users reuse
their existing contribution for an RBF without performing new coin
selection. A PriorContribution enum distinguishes whether the
contribution has been adjusted to the minimum RBF feerate (Adjusted) or
could not be adjusted due to insufficient fee buffer or max_feerate
constraints (Unadjusted).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jkczyz

lightning/src/ln/channel.rs

@@ -56,7 +56,7 @@ use crate::ln::channelmanager::{
 	MAX_LOCAL_BREAKDOWN_TIMEOUT, MIN_CLTV_EXPIRY_DELTA,
 };
 use crate::ln::funding::{
-	FeeRateAdjustmentError, FundingContribution, FundingTemplate, FundingTxInput,
+	FeeRateAdjustmentError, FundingContribution, FundingTemplate, FundingTxInput, PriorContribution,
 };
 use crate::ln::interactivetxs::{
 	AbortReason, HandleTxCompleteValue, InteractiveTxConstructor, InteractiveTxConstructorArgs,
@@ -11907,7 +11907,7 @@ where
 		}
 	}
 
-	/// Initiate splicing.
+	/// Builds a [`FundingTemplate`] for splicing or RBF, if the channel state allows it.
 	pub fn splice_channel(&self) -> Result<FundingTemplate, APIError> {
 		if self.holder_commitment_point.current_point().is_none() {
 			return Err(APIError::APIMisuseError {
@@ -11950,19 +11950,35 @@ where
 			});
 		}
 
-		// Compute the RBF feerate floor from either negotiated candidates (via
-		// can_initiate_rbf) or an in-progress funding negotiation (which will become a
-		// negotiated candidate once it completes).
-		let min_rbf_feerate = self.can_initiate_rbf().ok().flatten().or_else(|| {
-			self.pending_splice
-				.as_ref()
-				.and_then(|pending_splice| pending_splice.funding_negotiation.as_ref())
-				.map(|negotiation| {
-					let prev_feerate = negotiation.funding_feerate_sat_per_1000_weight();
-					let min_feerate_kwu = ((prev_feerate as u64) * 25).div_ceil(24);
-					FeeRate::from_sat_per_kwu(min_feerate_kwu)
-				})
-		});
+		let (min_rbf_feerate, prior_contribution) = if self.is_rbf_compatible().is_err() {
+			// Channel can never RBF (e.g., zero-conf).
+			(None, None)
+		} else if let Ok(min_rbf_feerate) = self.can_initiate_rbf() {
+			// A previous splice was negotiated but not yet locked. The user's splice
+			// will be an RBF, so provide the minimum RBF feerate and prior contribution.
+			let prior = self.build_prior_contribution();
+			(Some(min_rbf_feerate), prior)
+		} else if let Some(negotiation) = self
+			.pending_splice
+			.as_ref()
+			.and_then(|pending_splice| pending_splice.funding_negotiation.as_ref())
+		{
+			// A splice is currently being negotiated.
+			// - If the negotiation succeeds, the user's splice will need to satisfy the RBF
+			//   feerate requirement. Derive the minimum RBF feerate from the negotiation's
+			//   feerate so the user can choose an appropriate feerate.
+			// - If the negotiation fails (e.g., tx_abort), the splice will proceed as a fresh
+			//   splice instead. In this case, the min_rbf_feerate becomes stale, causing a
+			//   slightly higher feerate than necessary. Call splice_channel again after
+			//   receiving SpliceFailed to get a fresh template without the RBF constraint.
+			let prev_feerate = negotiation.funding_feerate_sat_per_1000_weight();
+			let min_feerate_kwu = ((prev_feerate as u64) * 25).div_ceil(24);
+			(Some(FeeRate::from_sat_per_kwu(min_feerate_kwu)), None)
+		} else {
+			// No RBF feerate to derive — either a fresh splice or a pending splice that
+			// can't be RBF'd (e.g., splice_locked already exchanged).
+			(None, None)
+		};
 
 		let funding_txo = self.funding.get_funding_txo().expect("funding_txo should be set");
 		let previous_utxo =
@@ -11973,63 +11989,35 @@ where
 			satisfaction_weight: EMPTY_SCRIPT_SIG_WEIGHT + FUNDING_TRANSACTION_WITNESS_WEIGHT,
 		};
 
-		Ok(FundingTemplate::new(Some(shared_input), min_rbf_feerate))
+		Ok(FundingTemplate::new(Some(shared_input), min_rbf_feerate, prior_contribution))
 	}
 
-	/// Initiate an RBF of a pending splice transaction.
-	pub fn rbf_channel(&self) -> Result<FundingTemplate, APIError> {
-		if self.holder_commitment_point.current_point().is_none() {
-			return Err(APIError::APIMisuseError {
-				err: format!(
-					"Channel {} cannot RBF until a payment is routed",
-					self.context.channel_id(),
-				),
-			});
-		}
-
-		if self.quiescent_action.is_some() {
-			return Err(APIError::APIMisuseError {
-				err: format!(
-					"Channel {} cannot RBF as one is waiting to be negotiated",
-					self.context.channel_id(),
-				),
-			});
-		}
-
-		if !self.context.is_usable() {
-			return Err(APIError::APIMisuseError {
-				err: format!(
-					"Channel {} cannot RBF as it is either pending open/close",
-					self.context.channel_id()
-				),
-			});
-		}
+	/// Clones the prior contribution and fetches the holder balance for deferred feerate
+	/// adjustment.
+	fn build_prior_contribution(&self) -> Option<PriorContribution> {
+		debug_assert!(self.pending_splice.is_some(), "can_initiate_rbf requires pending_splice");
+		let prior = self.pending_splice.as_ref()?.contributions.last()?;
+		let holder_balance = self
+			.get_holder_counterparty_balances_floor_incl_fee(&self.funding)
+			.map(|(h, _)| h)
+			.ok();
+		Some(PriorContribution::new(prior.clone(), holder_balance))
+	}
 
+	/// Returns whether this channel can ever RBF, independent of splice state.
+	fn is_rbf_compatible(&self) -> Result<(), String> {
 		if self.context.minimum_depth(&self.funding) == Some(0) {
-			return Err(APIError::APIMisuseError {
-				err: format!(
-					"Channel {} has option_zeroconf, cannot RBF splice",
-					self.context.channel_id(),
-				),
-			});
+			return Err(format!(
+				"Channel {} has option_zeroconf, cannot RBF",
+				self.context.channel_id(),
+			));
 		}
-
-		let min_rbf_feerate =
-			self.can_initiate_rbf().map_err(|err| APIError::APIMisuseError { err })?;
-
-		let funding_txo = self.funding.get_funding_txo().expect("funding_txo should be set");
-		let previous_utxo =
-			self.funding.get_funding_output().expect("funding_output should be set");
-		let shared_input = Input {
-			outpoint: funding_txo.into_bitcoin_outpoint(),
-			previous_utxo,
-			satisfaction_weight: EMPTY_SCRIPT_SIG_WEIGHT + FUNDING_TRANSACTION_WITNESS_WEIGHT,
-		};
-
-		Ok(FundingTemplate::new(Some(shared_input), min_rbf_feerate))
+		Ok(())
 	}
 
-	fn can_initiate_rbf(&self) -> Result<Option<FeeRate>, String> {
+	fn can_initiate_rbf(&self) -> Result<FeeRate, String> {
+		self.is_rbf_compatible()?;
+
 		let pending_splice = match &self.pending_splice {
 			Some(pending_splice) => pending_splice,
 			None => {
@@ -12068,13 +12056,16 @@ where
 			));
 		}
 
-		let min_rbf_feerate =
-			pending_splice.last_funding_feerate_sat_per_1000_weight.map(|prev_feerate| {
+		match pending_splice.last_funding_feerate_sat_per_1000_weight {
+			Some(prev_feerate) => {
 				let min_feerate_kwu = ((prev_feerate as u64) * 25).div_ceil(24);
-				FeeRate::from_sat_per_kwu(min_feerate_kwu)
-			});
-
-		Ok(min_rbf_feerate)
+				Ok(FeeRate::from_sat_per_kwu(min_feerate_kwu))
+			},
+			None => Err(format!(
+				"Channel {} has no prior feerate to compute RBF minimum",
+				self.context.channel_id(),
+			)),
+		}
 	}
 
 	/// Attempts to adjust the contribution's feerate to the minimum RBF feerate so the splice can
@@ -12205,7 +12196,7 @@ where
 		// If a pending splice exists with negotiated candidates, attempt to adjust the
 		// contribution's feerate to the minimum RBF feerate so it can proceed as an RBF immediately
 		// rather than waiting for the splice to lock.
-		let contribution = if let Ok(Some(min_rbf_feerate)) = self.can_initiate_rbf() {
+		let contribution = if let Ok(min_rbf_feerate) = self.can_initiate_rbf() {
 			self.maybe_adjust_for_rbf(contribution, min_rbf_feerate, logger)
 		} else {
 			contribution
@@ -12605,12 +12596,7 @@ where
 			return Err(ChannelError::WarnAndDisconnect("Quiescence needed for RBF".to_owned()));
 		}
 
-		if self.context.minimum_depth(&self.funding) == Some(0) {
-			return Err(ChannelError::WarnAndDisconnect(format!(
-				"Channel {} has option_zeroconf, cannot RBF splice",
-				self.context.channel_id(),
-			)));
-		}
+		self.is_rbf_compatible().map_err(|msg| ChannelError::WarnAndDisconnect(msg))?;
 
 		let pending_splice = match &self.pending_splice {
 			Some(pending_splice) => pending_splice,
@@ -13817,7 +13803,7 @@ where
 							);
 							return None;
 						},
-						Ok(Some(min_rbf_feerate)) if contribution.feerate() < min_rbf_feerate => {
+						Ok(min_rbf_feerate) if contribution.feerate() < min_rbf_feerate => {
 							log_given_level!(
 								logger,
 								logger_level,

lightning/src/ln/channelmanager.rs

@@ -4701,24 +4701,21 @@ impl<
 	}
 
 	/// Initiate a splice in order to add value to (splice-in) or remove value from (splice-out)
-	/// the channel. This will spend the channel's funding transaction output, effectively replacing
-	/// it with a new one.
+	/// the channel, or to RBF a pending splice transaction.
 	///
 	/// # Required Feature Flags
 	///
 	/// Initiating a splice requires that the channel counterparty supports splicing. Any
 	/// channel (no matter the type) can be spliced, as long as the counterparty is currently
 	/// connected.
 	///
-	/// Returns a [`FundingTemplate`] which should be used to build a [`FundingContribution`] via
-	/// one of its splice methods (e.g., [`FundingTemplate::splice_in_sync`]). The `min_feerate`
-	/// and `max_feerate` parameters are provided when calling those splice methods. The resulting
-	/// contribution must then be passed to [`ChannelManager::funding_contributed`].
+	/// # Return Value
 	///
-	/// When a pending splice exists with negotiated candidates (i.e., a splice that hasn't been
-	/// locked yet), [`FundingTemplate::min_rbf_feerate`] will return the minimum feerate required
-	/// for an RBF attempt (25/24 of the previous feerate). This can be used to choose an
-	/// appropriate `min_feerate` when calling the splice methods.
+	/// Returns a [`FundingTemplate`] which should be used to obtain a [`FundingContribution`]
+	/// to pass to [`ChannelManager::funding_contributed`]. If a splice has been negotiated but
+	/// not yet locked, it can be replaced with a higher feerate transaction to speed up
+	/// confirmation via Replace By Fee (RBF). See [`FundingTemplate`] for details on building
+	/// a fresh contribution or reusing a prior one for RBF.
 	#[rustfmt::skip]
 	pub fn splice_channel(
 		&self, channel_id: &ChannelId, counterparty_node_id: &PublicKey,
@@ -4765,67 +4762,6 @@ impl<
 		}
 	}
 
-	/// Initiate an RBF of a pending splice transaction for an existing channel.
-	///
-	/// This is used after a splice has been negotiated but before it has been locked, in order
-	/// to bump the feerate of the funding transaction via replace-by-fee.
-	///
-	/// # Required Feature Flags
-	///
-	/// Initiating an RBF requires that the channel counterparty supports splicing. The
-	/// counterparty must be currently connected.
-	///
-	/// Returns a [`FundingTemplate`] which should be used to build a [`FundingContribution`] via
-	/// one of its splice methods (e.g., [`FundingTemplate::splice_in_sync`]). The `min_feerate`
-	/// and `max_feerate` parameters are provided when calling those splice methods.
-	/// [`FundingTemplate::min_rbf_feerate`] returns the minimum feerate required for the RBF
-	/// (25/24 of the previous feerate). The resulting contribution must then be passed to
-	/// [`ChannelManager::funding_contributed`].
-	pub fn rbf_channel(
-		&self, channel_id: &ChannelId, counterparty_node_id: &PublicKey,
-	) -> Result<FundingTemplate, APIError> {
-		let per_peer_state = self.per_peer_state.read().unwrap();
-
-		let peer_state_mutex = match per_peer_state
-			.get(counterparty_node_id)
-			.ok_or_else(|| APIError::no_such_peer(counterparty_node_id))
-		{
-			Ok(p) => p,
-			Err(e) => return Err(e),
-		};
-
-		let mut peer_state = peer_state_mutex.lock().unwrap();
-		if !peer_state.latest_features.supports_splicing() {
-			return Err(APIError::ChannelUnavailable {
-				err: "Peer does not support splicing".to_owned(),
-			});
-		}
-		if !peer_state.latest_features.supports_quiescence() {
-			return Err(APIError::ChannelUnavailable {
-				err: "Peer does not support quiescence, a splicing prerequisite".to_owned(),
-			});
-		}
-
-		// Look for the channel
-		match peer_state.channel_by_id.entry(*channel_id) {
-			hash_map::Entry::Occupied(chan_phase_entry) => {
-				if let Some(chan) = chan_phase_entry.get().as_funded() {
-					chan.rbf_channel()
-				} else {
-					Err(APIError::ChannelUnavailable {
-						err: format!(
-							"Channel with id {} is not funded, cannot RBF splice",
-							channel_id
-						),
-					})
-				}
-			},
-			hash_map::Entry::Vacant(_) => {
-				Err(APIError::no_such_channel_for_peer(channel_id, counterparty_node_id))
-			},
-		}
-	}
-
 	#[cfg(test)]
 	pub(crate) fn abandon_splice(
 		&self, channel_id: &ChannelId, counterparty_node_id: &PublicKey,
@@ -6590,13 +6526,16 @@ impl<
 	///
 	/// If any failures occur while negotiating the funding transaction, an [`Event::SpliceFailed`]
 	/// will be emitted. Any contributed inputs no longer used will be included in an
-	/// [`Event::DiscardFunding`] and thus can be re-spent.
+	/// [`Event::DiscardFunding`] and thus can be re-spent. If a [`FundingTemplate`] was obtained
+	/// while a previous splice was still being negotiated, its
+	/// [`min_rbf_feerate`][FundingTemplate::min_rbf_feerate] may be stale after the failure.
+	/// Call this method again to get a fresh template.
 	///
 	/// After initial signatures have been exchanged, [`Event::FundingTransactionReadyForSigning`]
 	/// will be generated and [`ChannelManager::funding_transaction_signed`] should be called.
 	///
 	/// Once the splice has been locked by both counterparties, an [`Event::ChannelReady`] will be
-	/// emitted with the new funding output. At this point, a new splice can be negotiated by
+	/// emitted with the new funding output. At this point, a new (non-RBF) splice can be negotiated by
 	/// calling [`ChannelManager::splice_channel`] again on this channel.
 	///
 	/// # Errors