Add on-chain payment fee bumping

On-chain payments can remain unconfirmed when fees rise after they
are sent. Allow operators to raise a payment's fee while preserving
its recipient amount and payment ID, so they can get the payment
confirmed without creating another payment.

AI assistance: OpenAI Codex.

Author: benthecarman

docs/api-guide.md

@@ -97,7 +97,7 @@ RPCs with no permission mapping return `UNIMPLEMENTED`, even for admin tokens.
 | ---------- | ------ |
 | `node:read` | Node information, balances, and pathfinding scores |
 | `onchain:receive` | Create on-chain receive addresses |
-| `onchain:send` | Send on-chain funds |
+| `onchain:send` | Send on-chain funds or bump an on-chain payment fee |
 | `invoices:create` | Create BOLT11/BOLT12 invoices and incoming refund requests |
 | `payments:read` | Read payments, forwarded payments, and forwarding statistics |
 | `payments:claim` | Claim or fail held BOLT11 payments |
@@ -174,6 +174,12 @@ All RPCs are unary (single request, single response) unless noted otherwise.
 |------------------|----------------------------------------------------------------------|
 | `OnchainReceive` | Generate a new on-chain funding address                              |
 | `OnchainSend`    | Send to a Bitcoin address (with optional fee rate and send-all mode) |
+| `OnchainBumpFee` | Raise the fee of an unconfirmed outbound on-chain payment using RBF  |
+
+`OnchainBumpFee` replaces a payment's transaction while preserving its payment ID and recipient
+amount. Use the `payment_id` from `ListPayments`. The optional `fee_rate_sat_per_vb` sets the new
+total fee rate in sat/vB; omit it to use an automatic rate. The response contains the replacement
+`txid`. Confirmed, inbound, Lightning, and channel funding payments are not eligible.
 
 ### BOLT11 Payments
 

e2e-tests/src/lib.rs

@@ -11,9 +11,10 @@ use std::io::{BufRead, BufReader, Write};
 use std::net::TcpListener;
 use std::path::{Path, PathBuf};
 use std::process::{Child, Command, Stdio};
-use std::time::{Duration, Instant};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use corepc_node::Node;
+use ldk_node::bitcoin::Amount;
 use ldk_server_client::client::{EventStream, LdkServerClient};
 use ldk_server_client::error::LdkServerErrorCode;
 use ldk_server_client::ldk_server_grpc::api::{GetNodeInfoRequest, GetNodeInfoResponse};
@@ -30,7 +31,7 @@ use ldk_server_grpc::types::{
 	ClaimableAwaitingConfirmations, ForwardedPayment, LightningBalance, Payment, PaymentDirection,
 	PaymentStatus,
 };
-use serde_json::Value;
+use serde_json::{json, Value};
 
 const EVENT_TIMEOUT: Duration = Duration::from_secs(15);
 
@@ -772,6 +773,81 @@ pub async fn mine_and_sync(
 	}
 }
 
+/// Wait for a transaction to enter the mempool and return its decoded details.
+pub async fn wait_for_transaction(bitcoind: &TestBitcoind, txid: &str) -> Value {
+	tokio::time::timeout(Duration::from_secs(30), async {
+		loop {
+			let mempool: Vec<String> = bitcoind.bitcoind.client.call("getrawmempool", &[]).unwrap();
+			if mempool.iter().any(|id| id == txid) {
+				return bitcoind
+					.bitcoind
+					.client
+					.call("getrawtransaction", &[json!(txid), json!(true)])
+					.unwrap();
+			}
+			tokio::time::sleep(Duration::from_millis(100)).await;
+		}
+	})
+	.await
+	.expect("transaction did not enter the mempool")
+}
+
+/// Wait for the on-chain wallet to complete another sync.
+///
+/// The pinned wallet records a replacement before its background sync sees the transaction.
+pub async fn wait_for_wallet_sync(server: &LdkServerHandle) {
+	let after = SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs();
+	tokio::time::timeout(Duration::from_secs(30), async {
+		loop {
+			let info = server.client().get_node_info(GetNodeInfoRequest {}).await.unwrap();
+			if info.latest_onchain_wallet_sync_timestamp.is_some_and(|timestamp| timestamp > after)
+			{
+				break;
+			}
+			tokio::time::sleep(Duration::from_millis(100)).await;
+		}
+	})
+	.await
+	.expect("wallet did not sync after the replacement");
+}
+
+/// Wait for a transaction to appear in the node's payment history.
+pub async fn payment_for_tx(server: &LdkServerHandle, txid: &str) -> Payment {
+	tokio::time::timeout(Duration::from_secs(30), async {
+		loop {
+			for payment in list_payments(server).await {
+				if let Some(payment_kind::Kind::Onchain(onchain)) =
+					payment.kind.as_ref().and_then(|kind| kind.kind.as_ref())
+				{
+					if onchain.txid == txid {
+						return payment;
+					}
+				}
+			}
+			tokio::time::sleep(Duration::from_millis(100)).await;
+		}
+	})
+	.await
+	.expect("payment was not recorded")
+}
+
+/// Check that a replacement preserves the recipient amount.
+pub async fn assert_replacement(
+	bitcoind: &TestBitcoind, old: &str, new: &str, address: &str, amount: Amount,
+) {
+	assert_ne!(old, new);
+	let tx = wait_for_transaction(bitcoind, new).await;
+	let recipient = tx["vout"]
+		.as_array()
+		.unwrap()
+		.iter()
+		.find(|output| output["scriptPubKey"]["address"] == address)
+		.unwrap();
+	assert_eq!(Amount::from_btc(recipient["value"].as_f64().unwrap()).unwrap(), amount);
+	let mempool: Vec<String> = bitcoind.bitcoind.client.call("getrawmempool", &[]).unwrap();
+	assert!(!mempool.iter().any(|id| id == old));
+}
+
 /// Wait until the given client has at least one usable channel,
 /// periodically mining blocks to trigger chain sync.
 pub async fn wait_for_usable_channel(

e2e-tests/tests/e2e.rs

@@ -12,32 +12,39 @@ use std::str::FromStr;
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use e2e_tests::{
-	close_channel, find_available_port, list_payments, mine_and_sync, run_cli, run_cli_raw,
-	run_cli_with_config, send_bolt11_payment, setup_funded_channel, wait_for_channels,
-	wait_for_event, wait_for_gossip, wait_for_onchain_balance, wait_for_settled_balance,
-	wait_for_usable_channel, LdkServerConfig, LdkServerHandle, TestBitcoind, TestConfigBuilder,
+	assert_replacement, close_channel, find_available_port, list_payments, mine_and_sync,
+	payment_for_tx, run_cli, run_cli_raw, run_cli_with_config, send_bolt11_payment,
+	setup_funded_channel, wait_for_channels, wait_for_event, wait_for_gossip,
+	wait_for_onchain_balance, wait_for_settled_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::bitcoin::Amount;
 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::ldk_server_grpc::api::{
-	open_channel_request, Bolt11ClaimForIdRequest, Bolt11FailForIdRequest, Bolt11ReceiveRequest,
-	Bolt12ReceiveRequest, GetChannelForwardingStatsRequest, GetForwardedPaymentDetailsRequest,
+	onchain_send_request, open_channel_request, Bolt11ClaimForIdRequest, Bolt11FailForIdRequest,
+	Bolt11ReceiveRequest, Bolt11SendRequest, Bolt12ReceiveRequest,
+	GetChannelForwardingStatsRequest, GetForwardedPaymentDetailsRequest, GetPaymentDetailsRequest,
 	ListChannelForwardingStatsRequest, ListChannelPairForwardingStatsRequest,
-	ListForwardedPaymentsRequest, OnchainReceiveRequest, OpenChannelRequest,
+	ListForwardedPaymentsRequest, OnchainBumpFeeRequest, OnchainReceiveRequest, OnchainSendRequest,
+	OpenChannelRequest,
 };
 use ldk_server_client::ldk_server_grpc::events::event_envelope::Event;
 use ldk_server_client::ldk_server_grpc::events::{
 	ChannelClosureInitiator, ChannelState, ChannelStateChangeReasonKind, PaymentFailureReason,
 };
 use ldk_server_client::ldk_server_grpc::types::{
-	bolt11_invoice_description, Bolt11InvoiceDescription, ChannelShutdownState, ReserveType,
+	bolt11_invoice_description, Bolt11InvoiceDescription, ChannelShutdownState, PaymentDirection,
+	ReserveType,
 };
 use ldk_server_grpc::types::payment_kind;
+use serde_json::json;
 
 #[tokio::test]
 async fn test_cli_get_node_info() {
@@ -411,6 +418,20 @@ async fn test_cli_onchain_send() {
 	let recv_output = run_cli(&server, &["onchain-receive"]);
 	let dest_addr = recv_output["address"].as_str().unwrap();
 
+	for rate in [0, u64::MAX / 250 + 1, u64::MAX] {
+		let error = server
+			.client()
+			.onchain_send(OnchainSendRequest {
+				address: dest_addr.into(),
+				amount: Some(onchain_send_request::Amount::AmountSats(50_000)),
+				fee_rate_sat_per_vb: Some(rate),
+			})
+			.await
+			.unwrap_err();
+		assert_eq!(error.error_code, InvalidRequestError);
+		assert_eq!(error.message, ldk_node::NodeError::InvalidFeeRate.to_string());
+	}
+
 	let output = run_cli(&server, &["onchain-send", dest_addr, "50000sat"]);
 	assert!(!output["txid"].as_str().unwrap().is_empty());
 }
@@ -435,6 +456,176 @@ async fn test_cli_onchain_send_all() {
 	wait_for_settled_balance(&server, 0, Duration::from_secs(30)).await;
 }
 
+#[tokio::test]
+async fn test_onchain_fee_bump_client_cli() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+	let address = server.client().onchain_receive(OnchainReceiveRequest {}).await.unwrap().address;
+	bitcoind.fund_address(&address, 1.0);
+	mine_and_sync(&bitcoind, &[&server], 6).await;
+	wait_for_onchain_balance(server.client(), Duration::from_secs(30)).await;
+	let destination = bitcoind.bitcoind.client.new_address().unwrap().to_string();
+	let amount = Amount::from_sat(50_000);
+	let original = server
+		.client()
+		.onchain_send(OnchainSendRequest {
+			address: destination.clone(),
+			amount: Some(onchain_send_request::Amount::AmountSats(amount.to_sat())),
+			fee_rate_sat_per_vb: Some(2),
+		})
+		.await
+		.unwrap()
+		.txid;
+	wait_for_transaction(&bitcoind, &original).await;
+	let payment = payment_for_tx(&server, &original).await;
+	assert_ne!(payment.payment_id, original, "payment IDs use a different byte order");
+
+	// A rate below the original must fail instead of selecting an automatic rate.
+	let error = server
+		.client()
+		.onchain_bump_fee(OnchainBumpFeeRequest {
+			payment_id: payment.payment_id.clone(),
+			fee_rate_sat_per_vb: Some(1),
+		})
+		.await
+		.unwrap_err();
+	assert_eq!(error.error_code, InvalidRequestError);
+
+	let replacement = server
+		.client()
+		.onchain_bump_fee(OnchainBumpFeeRequest {
+			payment_id: payment.payment_id.clone(),
+			fee_rate_sat_per_vb: Some(5),
+		})
+		.await
+		.unwrap()
+		.txid;
+	assert_replacement(&bitcoind, &original, &replacement, &destination, amount).await;
+	wait_for_wallet_sync(&server).await;
+	let cli =
+		run_cli(&server, &["onchain-bump-fee", &payment.payment_id, "--fee-rate-sat-per-vb", "10"]);
+	let cli_txid = cli["txid"].as_str().unwrap();
+	assert_replacement(&bitcoind, &replacement, cli_txid, &destination, amount).await;
+	let updated = payment_for_tx(&server, cli_txid).await;
+	assert_eq!(updated.payment_id, payment.payment_id);
+	assert_eq!(updated.amount_msat, Some(amount.to_sat() * 1000));
+	assert!(updated.fee_paid_msat > payment.fee_paid_msat);
+
+	mine_and_sync(&bitcoind, &[&server], 6).await;
+	// Wait for wallet confirmation, which can follow the Lightning tip update.
+	tokio::time::timeout(Duration::from_secs(30), async {
+		loop {
+			let details = server
+				.client()
+				.get_payment_details(GetPaymentDetailsRequest {
+					payment_id: payment.payment_id.clone(),
+				})
+				.await
+				.unwrap()
+				.payment
+				.unwrap();
+			if let Some(payment_kind::Kind::Onchain(onchain)) =
+				details.kind.and_then(|kind| kind.kind)
+			{
+				if matches!(
+					onchain.status.and_then(|status| status.status),
+					Some(ldk_server_grpc::types::confirmation_status::Status::Confirmed(_))
+				) {
+					break;
+				}
+			}
+			tokio::time::sleep(Duration::from_millis(100)).await;
+		}
+	})
+	.await
+	.unwrap();
+	let error = server
+		.client()
+		.onchain_bump_fee(OnchainBumpFeeRequest {
+			payment_id: payment.payment_id,
+			fee_rate_sat_per_vb: Some(20),
+		})
+		.await
+		.unwrap_err();
+	assert_eq!(error.error_code, InvalidRequestError);
+}
+
+#[tokio::test]
+async fn test_onchain_fee_bump_invalid_requests_and_ineligible_payments() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+	for id in [String::new(), "ab".repeat(31), "ab".repeat(33), "zz".repeat(32), "00".repeat(32)] {
+		let error = server
+			.client()
+			.onchain_bump_fee(OnchainBumpFeeRequest { payment_id: id, fee_rate_sat_per_vb: None })
+			.await
+			.unwrap_err();
+		assert_eq!(error.error_code, InvalidRequestError);
+	}
+	for rate in [0, u64::MAX / 250 + 1, u64::MAX] {
+		let error = server
+			.client()
+			.onchain_bump_fee(OnchainBumpFeeRequest {
+				payment_id: "00".repeat(32),
+				fee_rate_sat_per_vb: Some(rate),
+			})
+			.await
+			.unwrap_err();
+		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()
+		.bolt11_receive(Bolt11ReceiveRequest {
+			amount_msat: Some(100_000),
+			expiry_secs: 3600,
+			..Default::default()
+		})
+		.await
+		.unwrap()
+		.invoice;
+	// A failed send with no route still records an outbound Lightning payment.
+	let _ = server.client().bolt11_send(Bolt11SendRequest { invoice, ..Default::default() }).await;
+
+	let payments = list_payments(&server).await;
+	let lightning = payments
+		.iter()
+		.find(|p| {
+			matches!(
+				p.kind.as_ref().and_then(|k| k.kind.as_ref()),
+				Some(payment_kind::Kind::Bolt11(_))
+			)
+		})
+		.unwrap();
+	let error = server
+		.client()
+		.onchain_bump_fee(OnchainBumpFeeRequest {
+			payment_id: lightning.payment_id.clone(),
+			fee_rate_sat_per_vb: None,
+		})
+		.await
+		.unwrap_err();
+	assert_eq!(error.error_code, InvalidRequestError);
+
+	let address = server.client().onchain_receive(OnchainReceiveRequest {}).await.unwrap().address;
+	// Leave the incoming payment unconfirmed to exercise the direction guard.
+	let txid: String =
+		bitcoind.bitcoind.client.call("sendtoaddress", &[json!(address), json!(0.1)]).unwrap();
+	let incoming = payment_for_tx(&server, &txid).await;
+	assert_eq!(incoming.direction, PaymentDirection::Inbound as i32);
+	let error = server
+		.client()
+		.onchain_bump_fee(OnchainBumpFeeRequest {
+			payment_id: incoming.payment_id,
+			fee_rate_sat_per_vb: None,
+		})
+		.await
+		.unwrap_err();
+	assert_eq!(error.error_code, InvalidRequestError);
+}
+
 #[tokio::test]
 async fn test_cli_connect_peer() {
 	let bitcoind = TestBitcoind::new();

e2e-tests/tests/macaroons.rs

@@ -101,6 +101,27 @@ async fn test_scoped_macaroon_lifecycle() {
 	);
 }
 
+#[tokio::test]
+async fn test_macaroon_onchain_fee_bump_permissions() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+	// An invalid payment ID distinguishes reaching the handler from an auth rejection.
+	for (name, permission, expected_error) in [
+		("onchain-sender", "onchain:send", InvalidRequestError),
+		("lightning-sender", "payments:send", AuthorizationError),
+		("reader", "payments:read", AuthorizationError),
+		("full-admin", "admin", InvalidRequestError),
+	] {
+		let created = run_cli(&server, &["create-macaroon", name, "--permissions", permission]);
+		let scoped_client =
+			client_with_macaroon(&server, created["token"].as_str().unwrap().to_string());
+		assert_eq!(
+			scoped_client.onchain_bump_fee(Default::default()).await.unwrap_err().error_code,
+			expected_error
+		);
+	}
+}
+
 #[tokio::test]
 async fn test_macaroon_splice_permissions() {
 	let bitcoind = TestBitcoind::new();