Add pending-splice funding fee bumping

Pending splices can remain unconfirmed when their funding fee is too
low. Allow operators to raise that fee while preserving the splice
amount and destination, so the channel balance change can complete.

Support only pending splices with an automatic fee rate because the
pinned LDK Node revision does not support channel-opening fee bumps
or caller-selected splice fee rates.

AI assistance: OpenAI Codex.

Author: benthecarman

docs/api-guide.md

@@ -151,15 +151,28 @@ a channel just-in-time when the invoice is paid.
 
 ### Channel Management
 
-| RPC                   | Description                                                            |
-|-----------------------|------------------------------------------------------------------------|
-| `OpenChannel`         | Open a new outbound channel (with optional push amount and fee config) |
-| `CloseChannel`        | Cooperatively close a channel                                          |
-| `ForceCloseChannel`   | Force-close a channel unilaterally                                     |
-| `SpliceIn`            | Add on-chain funds to an existing channel                              |
-| `SpliceOut`           | Remove funds from a channel back on-chain                              |
-| `UpdateChannelConfig` | Update forwarding fees and CLTV expiry delta                           |
-| `ListChannels`        | List all channels with balances and configuration                      |
+| RPC                     | Description                                                            |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `OpenChannel`           | Open a new outbound channel (with optional push amount and fee config) |
+| `CloseChannel`          | Cooperatively close a channel                                          |
+| `ForceCloseChannel`     | Force-close a channel unilaterally                                     |
+| `SpliceIn`              | Add on-chain funds to an existing channel                              |
+| `SpliceOut`             | Remove funds from a channel back on-chain                              |
+| `BumpChannelFundingFee` | Raise the fee of a pending splice transaction                          |
+| `UpdateChannelConfig`   | Update forwarding fees and CLTV expiry delta                           |
+| `ListChannels`          | List all channels with balances and configuration                      |
+
+> [!NOTE]
+> `BumpChannelFundingFee` supports pending splices only. It preserves the splice amount and
+> destination, and LDK Node selects the fee rate. General channel-opening fee bumps and
+> caller-selected splice fee rates are not supported.
+
+Call it on the node that contributed to the splice, using the channel's `user_channel_id` and
+`counterparty_node_id`. A channel with no pending splice returns an error. An empty response means
+the fee bump has started; use [channel events](#event-streaming) to follow its progress.
+
+The automatic increase can be below Bitcoin Core 29's minimum relay fee increase. Check that the
+replacement transaction reaches the mempool; a successful RPC does not guarantee relay or confirmation.
 
 ### Payment History
 

e2e-tests/src/lib.rs

@@ -52,6 +52,8 @@ impl TestBitcoind {
 
 	fn with_extra_args(extra_args: &[&str]) -> Self {
 		let mut conf = corepc_node::Conf::default();
+		// Match the pinned LDK Node splice fixtures' 0.1 sat/vB relay fee increase.
+		conf.args.push("-incrementalrelayfee=0.00000100");
 		conf.args.extend_from_slice(extra_args);
 
 		let bitcoind = match std::env::var("BITCOIND_EXE") {
@@ -547,6 +549,17 @@ pub async fn wait_for_event(
 	.expect("Timed out waiting for event")
 }
 
+/// Wait for a negotiated splice and return its funding transaction ID.
+pub async fn splice_txid(events: &mut EventStream) -> String {
+	let event = wait_for_event(events, |e| matches!(e, Event::SpliceNegotiated(_))).await;
+	match event.event.unwrap() {
+		Event::SpliceNegotiated(splice) => {
+			splice.new_funding_txo.split(':').next().unwrap().to_string()
+		},
+		_ => unreachable!(),
+	}
+}
+
 /// Poll get_node_info until the server responds successfully.
 async fn wait_for_server_ready(handle: &LdkServerHandle, timeout: Duration) -> GetNodeInfoResponse {
 	let start = std::time::Instant::now();

e2e-tests/tests/e2e.rs

@@ -13,24 +13,25 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use e2e_tests::{
 	assert_replacement, find_available_port, mine_and_sync, payment_for_tx, run_cli, run_cli_raw,
-	run_cli_with_config, setup_funded_channel, wait_for_event, wait_for_onchain_balance,
-	wait_for_transaction, wait_for_usable_channel, wait_for_wallet_sync, LdkServerConfig,
-	LdkServerHandle, TestBitcoind, TestConfigBuilder,
+	run_cli_with_config, setup_funded_channel, splice_txid, wait_for_event,
+	wait_for_onchain_balance, wait_for_transaction, wait_for_usable_channel, wait_for_wallet_sync,
+	LdkServerConfig, LdkServerHandle, TestBitcoind, TestConfigBuilder,
 };
 use hex_conservative::{DisplayHex, FromHex};
 use ldk_node::bitcoin::hashes::{sha256, Hash};
 use ldk_node::lightning::ln::msgs::SocketAddress;
 use ldk_node::lightning::offers::offer::Offer;
 use ldk_node::lightning::offers::refund::Refund;
 use ldk_node::lightning_invoice::Bolt11Invoice;
-use ldk_server_client::error::LdkServerErrorCode::InvalidRequestError;
+use ldk_server_client::error::LdkServerErrorCode::{InvalidRequestError, LightningError};
 use ldk_server_client::ldk_server_grpc::api::{
 	onchain_send_request, open_channel_request, Bolt11ClaimForIdRequest, Bolt11FailForIdRequest,
-	Bolt11ReceiveRequest, Bolt11SendRequest, Bolt12ReceiveRequest, GetBalancesRequest,
-	GetChannelForwardingStatsRequest, GetForwardedPaymentDetailsRequest, GetPaymentDetailsRequest,
-	ListChannelForwardingStatsRequest, ListChannelPairForwardingStatsRequest,
-	ListForwardedPaymentsRequest, ListPaymentsRequest, OnchainBumpFeeRequest,
-	OnchainReceiveRequest, OnchainSendRequest, OpenChannelRequest,
+	Bolt11ReceiveRequest, Bolt11SendRequest, Bolt12ReceiveRequest, BumpChannelFundingFeeRequest,
+	GetBalancesRequest, GetChannelForwardingStatsRequest, GetForwardedPaymentDetailsRequest,
+	GetPaymentDetailsRequest, ListChannelForwardingStatsRequest,
+	ListChannelPairForwardingStatsRequest, ListChannelsRequest, ListForwardedPaymentsRequest,
+	ListPaymentsRequest, OnchainBumpFeeRequest, OnchainReceiveRequest, OnchainSendRequest,
+	OpenChannelRequest,
 };
 use ldk_server_client::ldk_server_grpc::events::event_envelope::Event;
 use ldk_server_client::ldk_server_grpc::events::{
@@ -567,6 +568,7 @@ async fn test_onchain_fee_bump_invalid_requests_and_ineligible_payments() {
 		assert_eq!(error.error_code, InvalidRequestError);
 		assert_eq!(error.message, ldk_node::NodeError::InvalidFeeRate.to_string());
 	}
+
 	let peer = LdkServerHandle::start(&bitcoind).await;
 	let invoice = peer
 		.client()
@@ -618,6 +620,7 @@ async fn test_onchain_fee_bump_invalid_requests_and_ineligible_payments() {
 		.unwrap_err();
 	assert_eq!(error.error_code, InvalidRequestError);
 }
+
 #[tokio::test]
 async fn test_cli_connect_peer() {
 	let bitcoind = TestBitcoind::new();
@@ -1541,6 +1544,132 @@ async fn test_cli_splice_out() {
 	assert!(address.starts_with("bcrt1"), "Expected regtest address, got: {}", address);
 }
 
+#[tokio::test]
+async fn test_pending_splice_fee_bump_client_cli() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+	let peer = LdkServerHandle::start(&bitcoind).await;
+	let channel = setup_funded_channel(&bitcoind, &server, &peer, 100_000).await;
+	let request = BumpChannelFundingFeeRequest {
+		user_channel_id: channel.clone(),
+		counterparty_node_id: peer.node_id().into(),
+	};
+	let error = server.client().bump_channel_funding_fee(request.clone()).await.unwrap_err();
+	assert_eq!(error.error_code, LightningError);
+	let mut wrong_peer = request.clone();
+	wrong_peer.counterparty_node_id = server.node_id().into();
+	assert_eq!(
+		server.client().bump_channel_funding_fee(wrong_peer).await.unwrap_err().error_code,
+		LightningError
+	);
+
+	let mut events = server.client().subscribe_events().await.unwrap();
+	// Use the same funded channel and splice-in operation as the existing splice fixtures.
+	run_cli(&server, &["splice-in", &channel, peer.node_id(), "50000sat"]);
+	let original = splice_txid(&mut events).await;
+	let original_tx = wait_for_transaction(&bitcoind, &original).await;
+	let funding_output = original_tx["vout"]
+		.as_array()
+		.unwrap()
+		.iter()
+		.find(|output| output["scriptPubKey"]["type"] == "witness_v0_scripthash")
+		.unwrap();
+	let expected_channel_value =
+		ldk_node::bitcoin::Amount::from_btc(funding_output["value"].as_f64().unwrap())
+			.unwrap()
+			.to_sat();
+	assert!(expected_channel_value >= 150_000);
+
+	let funding = payment_for_tx(&server, &original).await;
+	let error = server
+		.client()
+		.onchain_bump_fee(OnchainBumpFeeRequest {
+			payment_id: funding.payment_id,
+			fee_rate_sat_per_vb: Some(10),
+		})
+		.await
+		.unwrap_err();
+	assert_eq!(error.error_code, InvalidRequestError);
+
+	server.client().bump_channel_funding_fee(request.clone()).await.unwrap();
+	let replacement = splice_txid(&mut events).await;
+	assert_ne!(original, replacement);
+	wait_for_transaction(&bitcoind, &replacement).await;
+	let cli = run_cli(&server, &["bump-channel-funding-fee", &channel, peer.node_id()]);
+	assert_eq!(cli, json!({}));
+	let cli_txid = splice_txid(&mut events).await;
+	assert_ne!(replacement, cli_txid);
+	let replacement_tx = wait_for_transaction(&bitcoind, &cli_txid).await;
+	let replacement_output = replacement_tx["vout"]
+		.as_array()
+		.unwrap()
+		.iter()
+		.find(|output| output["scriptPubKey"] == funding_output["scriptPubKey"])
+		.unwrap();
+	assert_eq!(replacement_output["value"], funding_output["value"]);
+	let mempool: Vec<String> = bitcoind.bitcoind.client.call("getrawmempool", &[]).unwrap();
+	for old in [&original, &replacement] {
+		assert!(!mempool.contains(old));
+	}
+	mine_and_sync(&bitcoind, &[&server, &peer], 6).await;
+	tokio::time::timeout(Duration::from_secs(30), async {
+		loop {
+			let channels = server.client().list_channels(ListChannelsRequest {}).await.unwrap();
+			if channels.channels.iter().any(|c| {
+				c.user_channel_id == channel
+					&& c.channel_value_sats == expected_channel_value
+					&& c.is_usable
+			}) {
+				break;
+			}
+			tokio::time::sleep(Duration::from_millis(100)).await;
+		}
+	})
+	.await
+	.expect("replacement splice did not confirm with the original amount");
+	assert_eq!(
+		server.client().bump_channel_funding_fee(request).await.unwrap_err().error_code,
+		LightningError
+	);
+}
+
+#[tokio::test]
+async fn test_pending_splice_fee_bump_invalid_requests() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+	for id in ["", "-1", "xyz", "340282366920938463463374607431768211456"] {
+		let error = server
+			.client()
+			.bump_channel_funding_fee(BumpChannelFundingFeeRequest {
+				user_channel_id: id.into(),
+				counterparty_node_id: server.node_id().into(),
+			})
+			.await
+			.unwrap_err();
+		assert_eq!(error.error_code, InvalidRequestError);
+	}
+	for peer in ["", "invalid", &"00".repeat(33)] {
+		let error = server
+			.client()
+			.bump_channel_funding_fee(BumpChannelFundingFeeRequest {
+				user_channel_id: "1".into(),
+				counterparty_node_id: peer.into(),
+			})
+			.await
+			.unwrap_err();
+		assert_eq!(error.error_code, InvalidRequestError);
+	}
+	let error = server
+		.client()
+		.bump_channel_funding_fee(BumpChannelFundingFeeRequest {
+			user_channel_id: u128::MAX.to_string(),
+			counterparty_node_id: server.node_id().into(),
+		})
+		.await
+		.unwrap_err();
+	assert_eq!(error.error_code, LightningError);
+}
+
 #[tokio::test]
 async fn test_cli_graph_list_channels_empty() {
 	let bitcoind = TestBitcoind::new();

e2e-tests/tests/mcp.rs

@@ -11,13 +11,14 @@ use std::str::FromStr;
 use std::time::Duration;
 
 use e2e_tests::{
-	assert_replacement, mine_and_sync, payment_for_tx, setup_funded_channel, wait_for_event,
-	wait_for_onchain_balance, wait_for_transaction, wait_for_wallet_sync, LdkServerHandle,
-	McpHandle, TestBitcoind,
+	assert_replacement, mine_and_sync, payment_for_tx, setup_funded_channel, splice_txid,
+	wait_for_event, wait_for_onchain_balance, wait_for_transaction, wait_for_wallet_sync,
+	LdkServerHandle, McpHandle, TestBitcoind,
 };
 use ldk_node::lightning::offers::refund::Refund;
 use ldk_server_client::ldk_server_grpc::api::{
-	onchain_send_request, Bolt11ReceiveRequest, OnchainReceiveRequest, OnchainSendRequest,
+	onchain_send_request, splice_in_request, Bolt11ReceiveRequest, OnchainReceiveRequest,
+	OnchainSendRequest, SpliceInRequest,
 };
 use ldk_server_client::ldk_server_grpc::events::event_envelope::Event;
 use ldk_server_client::ldk_server_grpc::types::{
@@ -251,3 +252,52 @@ async fn test_mcp_onchain_fee_bump() {
 		}
 	}
 }
+
+#[tokio::test]
+async fn test_mcp_pending_splice_fee_bump() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+	let peer = LdkServerHandle::start(&bitcoind).await;
+	let channel = setup_funded_channel(&bitcoind, &server, &peer, 100_000).await;
+	let mut events = server.client().subscribe_events().await.unwrap();
+	server
+		.client()
+		.splice_in(SpliceInRequest {
+			user_channel_id: channel.clone(),
+			counterparty_node_id: peer.node_id().into(),
+			amount: Some(splice_in_request::Amount::SpliceAmountSats(50_000)),
+		})
+		.await
+		.unwrap();
+	let original = splice_txid(&mut events).await;
+	let original_tx = wait_for_transaction(&bitcoind, &original).await;
+	let funding_output = original_tx["vout"]
+		.as_array()
+		.unwrap()
+		.iter()
+		.find(|output| output["scriptPubKey"]["type"] == "witness_v0_scripthash")
+		.unwrap();
+	let mut mcp = McpHandle::start(&server);
+	let response = mcp.call(
+		1,
+		"tools/call",
+		json!({
+			"name": "bump_channel_funding_fee",
+			"arguments": {"user_channel_id": channel, "counterparty_node_id": peer.node_id()}
+		}),
+	);
+	assert_ne!(response["result"]["isError"], true, "{response}");
+	assert_eq!(tool_result_json(&response), json!({}));
+	let replacement = splice_txid(&mut events).await;
+	assert_ne!(original, replacement);
+	let replacement_tx = wait_for_transaction(&bitcoind, &replacement).await;
+	let replacement_output = replacement_tx["vout"]
+		.as_array()
+		.unwrap()
+		.iter()
+		.find(|output| output["scriptPubKey"] == funding_output["scriptPubKey"])
+		.unwrap();
+	assert_eq!(replacement_output["value"], funding_output["value"]);
+	let mempool: Vec<String> = bitcoind.bitcoind.client.call("getrawmempool", &[]).unwrap();
+	assert!(!mempool.contains(&original));
+}

ldk-server-cli/src/main.rs

@@ -32,9 +32,10 @@ use ldk_server_client::ldk_server_grpc::api::{
 	Bolt11SendUnderpayingRequest, Bolt11SendUnderpayingResponse, Bolt12CreatePayerProofRequest,
 	Bolt12CreatePayerProofResponse, Bolt12ReceiveRefundRequest, Bolt12ReceiveRefundResponse,
 	Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRefundRequest, Bolt12SendRefundResponse,
-	Bolt12SendRequest, Bolt12SendResponse, CloseChannelRequest, CloseChannelResponse,
-	ConnectPeerRequest, ConnectPeerResponse, DecodeInvoiceRequest, DecodeInvoiceResponse,
-	DecodeOfferRequest, DecodeOfferResponse, DisconnectPeerRequest, DisconnectPeerResponse,
+	Bolt12SendRequest, Bolt12SendResponse, BumpChannelFundingFeeRequest,
+	BumpChannelFundingFeeResponse, CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest,
+	ConnectPeerResponse, DecodeInvoiceRequest, DecodeInvoiceResponse, DecodeOfferRequest,
+	DecodeOfferResponse, DisconnectPeerRequest, DisconnectPeerResponse,
 	ExportPathfindingScoresRequest, ForceCloseChannelRequest, ForceCloseChannelResponse,
 	GetBalancesRequest, GetBalancesResponse, GetChannelForwardingStatsRequest,
 	GetChannelForwardingStatsResponse, GetForwardedPaymentDetailsRequest,
@@ -546,6 +547,15 @@ enum Commands {
 		)]
 		address: Option<String>,
 	},
+	#[command(
+		about = "Bump a pending splice fee. Does not support general channel-opening fee bumping. LDK Node selects the fee rate; callers cannot set it"
+	)]
+	BumpChannelFundingFee {
+		#[arg(help = "The local user channel ID as a decimal u128 string")]
+		user_channel_id: String,
+		#[arg(help = "The hex-encoded public key of the channel's peer")]
+		counterparty_node_id: String,
+	},
 	#[command(about = "Return a list of known channels")]
 	ListChannels,
 	#[command(about = "Retrieve list of all payments")]
@@ -1225,6 +1235,16 @@ async fn main() {
 					.await,
 			);
 		},
+		Commands::BumpChannelFundingFee { user_channel_id, counterparty_node_id } => {
+			handle_response_result::<_, BumpChannelFundingFeeResponse>(
+				client
+					.bump_channel_funding_fee(BumpChannelFundingFeeRequest {
+						user_channel_id,
+						counterparty_node_id,
+					})
+					.await,
+			);
+		},
 		Commands::ListChannels => {
 			handle_response_result::<_, ListChannelsResponse>(
 				client.list_channels(ListChannelsRequest {}).await,
@@ -1621,6 +1641,28 @@ mod tests {
 		}
 	}
 
+	#[test]
+	fn bump_channel_funding_fee_arguments() {
+		let cli = Cli::try_parse_from(["ldk-server-cli", "bump-channel-funding-fee", "42", "peer"])
+			.unwrap();
+		match cli.command {
+			Commands::BumpChannelFundingFee { user_channel_id, counterparty_node_id } => {
+				assert_eq!(user_channel_id, "42");
+				assert_eq!(counterparty_node_id, "peer");
+			},
+			_ => panic!("wrong command"),
+		}
+		assert!(Cli::try_parse_from([
+			"ldk-server-cli",
+			"bump-channel-funding-fee",
+			"42",
+			"peer",
+			"--fee-rate-sat-per-vb",
+			"10"
+		])
+		.is_err());
+	}
+
 	#[tokio::test]
 	async fn fetch_paginated_collects_multiple_pages() {
 		let response = fetch_paginated(