Allow to override fee rates for onchain payments

We allow to override our fee estimator in the `send_to_address` and
`send_all_to_address` API methods. To this end, we implement a
bindings-compatible wrapper around `bitcoin::FeeRate`.

Author: tnull

bindings/ldk_node.udl

@@ -161,9 +161,26 @@ interface OnchainPayment {
 	[Throws=NodeError]
 	Address new_address();
 	[Throws=NodeError]
-	Txid send_to_address([ByRef]Address address, u64 amount_sats);
+	Txid send_to_address([ByRef]Address address, u64 amount_sats, FeeRate? fee_rate);
 	[Throws=NodeError]
-	Txid send_all_to_address([ByRef]Address address, boolean retain_reserve);
+	Txid send_all_to_address([ByRef]Address address, boolean retain_reserve, FeeRate? fee_rate);
+};
+
+interface FeeRate {
+	[Name=from_sat_per_kwu]
+	constructor(u64 sat_kwu);
+	[Name=from_sat_per_vb, Throws=FeeRateError]
+	constructor(u64 sat_vb);
+	[Name=from_sat_per_vb_unchecked]
+	constructor(u64 sat_vb);
+	u64 as_sat_per_kwu();
+	u64 as_sat_per_vb_floor();
+	u64 as_sat_per_vb_ceil();
+};
+
+[Error]
+enum FeeRateError {
+	"ConversionError",
 };
 
 interface UnifiedQrPayment {

src/payment/onchain.rs

@@ -17,6 +17,11 @@ use bitcoin::{Address, Txid};
 
 use std::sync::{Arc, RwLock};
 
+#[cfg(not(feature = "uniffi"))]
+type FeeRate = bitcoin::FeeRate;
+#[cfg(feature = "uniffi")]
+type FeeRate = crate::uniffi_types::FeeRate;
+
 /// A payment handler allowing to send and receive on-chain payments.
 ///
 /// Should be retrieved by calling [`Node::onchain_payment`].
@@ -50,9 +55,13 @@ impl OnchainPayment {
 	/// This will respect any on-chain reserve we need to keep, i.e., won't allow to cut into
 	/// [`BalanceDetails::total_anchor_channels_reserve_sats`].
 	///
+	/// If `fee_rate` is set it will used on the resulting transaction. Otherwise a reasonable
+	/// we'll retrieve an estimate from the configured chain source.
+	///
 	/// [`BalanceDetails::total_anchor_channels_reserve_sats`]: crate::BalanceDetails::total_anchor_channels_reserve_sats
+	#[cfg(not(feature = "uniffi"))]
 	pub fn send_to_address(
-		&self, address: &bitcoin::Address, amount_sats: u64,
+		&self, address: &bitcoin::Address, amount_sats: u64, fee_rate: Option<FeeRate>,
 	) -> Result<Txid, Error> {
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
@@ -63,7 +72,32 @@ impl OnchainPayment {
 			crate::total_anchor_channels_reserve_sats(&self.channel_manager, &self.config);
 		let send_amount =
 			OnchainSendAmount::ExactRetainingReserve { amount_sats, cur_anchor_reserve_sats };
-		self.wallet.send_to_address(address, send_amount)
+		self.wallet.send_to_address(address, send_amount, fee_rate)
+	}
+
+	/// Send an on-chain payment to the given address.
+	///
+	/// This will respect any on-chain reserve we need to keep, i.e., won't allow to cut into
+	/// [`BalanceDetails::total_anchor_channels_reserve_sats`].
+	///
+	/// If `fee_rate` is set it will used on the resulting transaction. Otherwise a reasonable
+	/// we'll retrieve an estimate from the configured chain source.
+	///
+	/// [`BalanceDetails::total_anchor_channels_reserve_sats`]: crate::BalanceDetails::total_anchor_channels_reserve_sats
+	#[cfg(feature = "uniffi")]
+	pub fn send_to_address(
+		&self, address: &bitcoin::Address, amount_sats: u64, fee_rate: Option<Arc<FeeRate>>,
+	) -> Result<Txid, Error> {
+		let rt_lock = self.runtime.read().unwrap();
+		if rt_lock.is_none() {
+			return Err(Error::NotRunning);
+		}
+
+		let cur_anchor_reserve_sats =
+			crate::total_anchor_channels_reserve_sats(&self.channel_manager, &self.config);
+		let send_amount =
+			OnchainSendAmount::ExactRetainingReserve { amount_sats, cur_anchor_reserve_sats };
+		self.wallet.send_to_address(address, send_amount, fee_rate.map(|f| f.0))
 	}
 
 	/// Send an on-chain payment to the given address, draining the available funds.
@@ -77,9 +111,48 @@ impl OnchainPayment {
 	/// will try to send all spendable onchain funds, i.e.,
 	/// [`BalanceDetails::spendable_onchain_balance_sats`].
 	///
+	/// If `fee_rate` is set it will be used on the resulting transaction. Otherwise a reasonable
+	/// we'll retrieve an estimate from the configured chain source.
+	///
+	/// [`BalanceDetails::spendable_onchain_balance_sats`]: crate::balance::BalanceDetails::spendable_onchain_balance_sats
+	#[cfg(not(feature = "uniffi"))]
+	pub fn send_all_to_address(
+		&self, address: &bitcoin::Address, retain_reserves: bool, fee_rate: Option<FeeRate>,
+	) -> Result<Txid, Error> {
+		let rt_lock = self.runtime.read().unwrap();
+		if rt_lock.is_none() {
+			return Err(Error::NotRunning);
+		}
+
+		let send_amount = if retain_reserves {
+			let cur_anchor_reserve_sats =
+				crate::total_anchor_channels_reserve_sats(&self.channel_manager, &self.config);
+			OnchainSendAmount::AllRetainingReserve { cur_anchor_reserve_sats }
+		} else {
+			OnchainSendAmount::AllDrainingReserve
+		};
+
+		self.wallet.send_to_address(address, send_amount, fee_rate)
+	}
+
+	/// Send an on-chain payment to the given address, draining the available funds.
+	///
+	/// This is useful if you have closed all channels and want to migrate funds to another
+	/// on-chain wallet.
+	///
+	/// Please note that if `retain_reserves` is set to `false` this will **not** retain any on-chain reserves, which might be potentially
+	/// dangerous if you have open Anchor channels for which you can't trust the counterparty to
+	/// spend the Anchor output after channel closure. If `retain_reserves` is set to `true`, this
+	/// will try to send all spendable onchain funds, i.e.,
+	/// [`BalanceDetails::spendable_onchain_balance_sats`].
+	///
+	/// If `fee_rate` is set it will be used on the resulting transaction. Otherwise a reasonable
+	/// we'll retrieve an estimate from the configured chain source.
+	///
 	/// [`BalanceDetails::spendable_onchain_balance_sats`]: crate::balance::BalanceDetails::spendable_onchain_balance_sats
+	#[cfg(feature = "uniffi")]
 	pub fn send_all_to_address(
-		&self, address: &bitcoin::Address, retain_reserves: bool,
+		&self, address: &bitcoin::Address, retain_reserves: bool, fee_rate: Option<Arc<FeeRate>>,
 	) -> Result<Txid, Error> {
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
@@ -94,6 +167,6 @@ impl OnchainPayment {
 			OnchainSendAmount::AllDrainingReserve
 		};
 
-		self.wallet.send_to_address(address, send_amount)
+		self.wallet.send_to_address(address, send_amount, fee_rate.map(|f| f.0))
 	}
 }

src/payment/unified_qr.rs

@@ -156,8 +156,11 @@ impl UnifiedQrPayment {
 			},
 		};
 
-		let txid =
-			self.onchain_payment.send_to_address(&uri_network_checked.address, amount.to_sat())?;
+		let txid = self.onchain_payment.send_to_address(
+			&uri_network_checked.address,
+			amount.to_sat(),
+			None,
+		)?;
 
 		Ok(QrPaymentResult::Onchain { txid })
 	}

src/uniffi_types.rs

@@ -51,6 +51,7 @@ use lightning::util::ser::Writeable;
 use lightning_invoice::SignedRawBolt11Invoice;
 
 use std::convert::TryInto;
+use std::fmt;
 use std::str::FromStr;
 
 impl UniffiCustomTypeConverter for PublicKey {
@@ -345,3 +346,61 @@ impl UniffiCustomTypeConverter for NodeAlias {
 		obj.to_string()
 	}
 }
+
+/// Represents fee rate.
+///
+/// This is a simple wrapper around [`bitcoin::FeeRate`], only used for UniFFI bindings.
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub struct FeeRate(pub(crate) bitcoin::FeeRate);
+
+impl FeeRate {
+	/// Constructs `FeeRate` from satoshis per 1000 weight units.
+	pub const fn from_sat_per_kwu(sat_kwu: u64) -> Self {
+		Self(bitcoin::FeeRate::from_sat_per_kwu(sat_kwu))
+	}
+
+	/// Constructs `FeeRate` from satoshis per virtual bytes.
+	///
+	/// # Errors
+	///
+	/// Returns `None` on arithmetic overflow.
+	pub fn from_sat_per_vb(sat_vb: u64) -> Result<Self, FeeRateError> {
+		Ok(Self(bitcoin::FeeRate::from_sat_per_vb(sat_vb).ok_or(FeeRateError::ConversionError)?))
+	}
+
+	/// Constructs `FeeRate` from satoshis per virtual bytes without overflow check.
+	pub const fn from_sat_per_vb_unchecked(sat_vb: u64) -> Self {
+		Self(bitcoin::FeeRate::from_sat_per_vb_unchecked(sat_vb))
+	}
+
+	/// Returns raw fee rate as satoshis per 1000 weight units.
+	pub const fn as_sat_per_kwu(&self) -> u64 {
+		self.0.to_sat_per_kwu()
+	}
+
+	/// Converts to sat/vB rounding down.
+	pub const fn as_sat_per_vb_floor(&self) -> u64 {
+		self.0.to_sat_per_vb_floor()
+	}
+
+	/// Converts to sat/vB rounding up.
+	pub const fn as_sat_per_vb_ceil(self) -> u64 {
+		self.0.to_sat_per_vb_ceil()
+	}
+}
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+/// A fee rate error that possibly needs to be handled by the user.
+pub enum FeeRateError {
+	ConversionError,
+}
+
+impl std::error::Error for FeeRateError {}
+
+impl fmt::Display for FeeRateError {
+	fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+		match self {
+			Self::ConversionError => write!(f, "Fee-rate conversion failed."),
+		}
+	}
+}

src/wallet/mod.rs

@@ -39,7 +39,8 @@ use bitcoin::secp256k1::ecdh::SharedSecret;
 use bitcoin::secp256k1::ecdsa::{RecoverableSignature, Signature};
 use bitcoin::secp256k1::{PublicKey, Scalar, Secp256k1, SecretKey, Signing};
 use bitcoin::{
-	Amount, ScriptBuf, Transaction, TxOut, Txid, WPubkeyHash, WitnessProgram, WitnessVersion,
+	Amount, FeeRate, ScriptBuf, Transaction, TxOut, Txid, WPubkeyHash, WitnessProgram,
+	WitnessVersion,
 };
 
 use std::ops::Deref;
@@ -239,9 +240,12 @@ where
 
 	pub(crate) fn send_to_address(
 		&self, address: &bitcoin::Address, send_amount: OnchainSendAmount,
+		fee_rate: Option<FeeRate>,
 	) -> Result<Txid, Error> {
+		// Use the set fee_rate or default to fee estimation.
 		let confirmation_target = ConfirmationTarget::OnchainPayment;
-		let fee_rate = self.fee_estimator.estimate_fee_rate(confirmation_target);
+		let fee_rate =
+			fee_rate.unwrap_or(self.fee_estimator.estimate_fee_rate(confirmation_target));
 
 		let tx = {
 			let mut locked_wallet = self.inner.lock().unwrap();

tests/integration_tests_rust.rs

@@ -315,11 +315,12 @@ fn onchain_spend_receive() {
 
 	assert_eq!(
 		Err(NodeError::InsufficientFunds),
-		node_a.onchain_payment().send_to_address(&addr_b, expected_node_a_balance + 1)
+		node_a.onchain_payment().send_to_address(&addr_b, expected_node_a_balance + 1, None)
 	);
 
 	let amount_to_send_sats = 1000;
-	let txid = node_b.onchain_payment().send_to_address(&addr_a, amount_to_send_sats).unwrap();
+	let txid =
+		node_b.onchain_payment().send_to_address(&addr_a, amount_to_send_sats, None).unwrap();
 	generate_blocks_and_wait(&bitcoind.client, &electrsd.client, 6);
 	wait_for_tx(&electrsd.client, txid);
 
@@ -334,7 +335,7 @@ fn onchain_spend_receive() {
 	assert!(node_b.list_balances().spendable_onchain_balance_sats < expected_node_b_balance_upper);
 
 	let addr_b = node_b.onchain_payment().new_address().unwrap();
-	let txid = node_a.onchain_payment().send_all_to_address(&addr_b, true).unwrap();
+	let txid = node_a.onchain_payment().send_all_to_address(&addr_b, true, None).unwrap();
 	generate_blocks_and_wait(&bitcoind.client, &electrsd.client, 6);
 	wait_for_tx(&electrsd.client, txid);
 
@@ -350,7 +351,7 @@ fn onchain_spend_receive() {
 	assert!(node_b.list_balances().spendable_onchain_balance_sats < expected_node_b_balance_upper);
 
 	let addr_b = node_b.onchain_payment().new_address().unwrap();
-	let txid = node_a.onchain_payment().send_all_to_address(&addr_b, false).unwrap();
+	let txid = node_a.onchain_payment().send_all_to_address(&addr_b, false, None).unwrap();
 	generate_blocks_and_wait(&bitcoind.client, &electrsd.client, 6);
 	wait_for_tx(&electrsd.client, txid);