feat: allow including received unconfirmed balance in spendable balance

Author: ben-kaufman

CHANGELOG.md

@@ -45,6 +45,12 @@
   - `Bolt11Payment::estimate_routing_fees_using_amount()`: Estimates fees for amount-less invoices.
 - Enhanced `OnchainPayment::send_to_address()` to accept optional `utxos_to_spend` parameter
   for manual UTXO selection.
+- Added `Config::include_untrusted_pending_in_spendable` option to control whether unconfirmed
+  funds from external sources are included in `spendable_onchain_balance_sats`. When set to `true`,
+  the spendable balance will include `untrusted_pending` UTXOs (unconfirmed transactions received
+  from external wallets). Default is `false` for safety, as spending unconfirmed external funds
+  carries risk of double-spending. This affects all balance reporting including `list_balances()`
+  and `BalanceChanged` events.
 
 ## Upstream v0.7.0 Release Notes
 This seventh minor release introduces numerous new features, bug fixes, and API improvements. In particular, it adds support for channel Splicing, Async Payments, as well as sourcing chain data from a Bitcoin Core REST backend.

bindings/ldk_node.udl

@@ -13,6 +13,7 @@ dictionary Config {
 	u64 probing_liquidity_limit_multiplier;
 	AnchorChannelsConfig? anchor_channels_config;
 	RouteParametersConfig? route_parameters;
+	boolean include_untrusted_pending_in_spendable;
 };
 
 dictionary AnchorChannelsConfig {

bindings/swift/Sources/LDKNode/LDKNode.swift

@@ -5080,10 +5080,11 @@ public struct Config {
     public var probingLiquidityLimitMultiplier: UInt64
     public var anchorChannelsConfig: AnchorChannelsConfig?
     public var routeParameters: RouteParametersConfig?
+    public var includeUntrustedPendingInSpendable: Bool
 
     // Default memberwise initializers are never public by default, so we
     // declare one manually.
-    public init(storageDirPath: String, network: Network, listeningAddresses: [SocketAddress]?, announcementAddresses: [SocketAddress]?, nodeAlias: NodeAlias?, trustedPeers0conf: [PublicKey], probingLiquidityLimitMultiplier: UInt64, anchorChannelsConfig: AnchorChannelsConfig?, routeParameters: RouteParametersConfig?) {
+    public init(storageDirPath: String, network: Network, listeningAddresses: [SocketAddress]?, announcementAddresses: [SocketAddress]?, nodeAlias: NodeAlias?, trustedPeers0conf: [PublicKey], probingLiquidityLimitMultiplier: UInt64, anchorChannelsConfig: AnchorChannelsConfig?, routeParameters: RouteParametersConfig?, includeUntrustedPendingInSpendable: Bool) {
         self.storageDirPath = storageDirPath
         self.network = network
         self.listeningAddresses = listeningAddresses
@@ -5093,6 +5094,7 @@ public struct Config {
         self.probingLiquidityLimitMultiplier = probingLiquidityLimitMultiplier
         self.anchorChannelsConfig = anchorChannelsConfig
         self.routeParameters = routeParameters
+        self.includeUntrustedPendingInSpendable = includeUntrustedPendingInSpendable
     }
 }
 
@@ -5127,6 +5129,9 @@ extension Config: Equatable, Hashable {
         if lhs.routeParameters != rhs.routeParameters {
             return false
         }
+        if lhs.includeUntrustedPendingInSpendable != rhs.includeUntrustedPendingInSpendable {
+            return false
+        }
         return true
     }
 
@@ -5140,6 +5145,7 @@ extension Config: Equatable, Hashable {
         hasher.combine(probingLiquidityLimitMultiplier)
         hasher.combine(anchorChannelsConfig)
         hasher.combine(routeParameters)
+        hasher.combine(includeUntrustedPendingInSpendable)
     }
 }
 
@@ -5151,16 +5157,17 @@ public struct FfiConverterTypeConfig: FfiConverterRustBuffer {
     public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> Config {
         return
             try Config(
-                storageDirPath: FfiConverterString.read(from: &buf), 
-                network: FfiConverterTypeNetwork.read(from: &buf), 
-                listeningAddresses: FfiConverterOptionSequenceTypeSocketAddress.read(from: &buf), 
-                announcementAddresses: FfiConverterOptionSequenceTypeSocketAddress.read(from: &buf), 
-                nodeAlias: FfiConverterOptionTypeNodeAlias.read(from: &buf), 
-                trustedPeers0conf: FfiConverterSequenceTypePublicKey.read(from: &buf), 
-                probingLiquidityLimitMultiplier: FfiConverterUInt64.read(from: &buf), 
-                anchorChannelsConfig: FfiConverterOptionTypeAnchorChannelsConfig.read(from: &buf), 
-                routeParameters: FfiConverterOptionTypeRouteParametersConfig.read(from: &buf)
-        )
+                storageDirPath: FfiConverterString.read(from: &buf),
+                network: FfiConverterTypeNetwork.read(from: &buf),
+                listeningAddresses: FfiConverterOptionSequenceTypeSocketAddress.read(from: &buf),
+                announcementAddresses: FfiConverterOptionSequenceTypeSocketAddress.read(from: &buf),
+                nodeAlias: FfiConverterOptionTypeNodeAlias.read(from: &buf),
+                trustedPeers0conf: FfiConverterSequenceTypePublicKey.read(from: &buf),
+                probingLiquidityLimitMultiplier: FfiConverterUInt64.read(from: &buf),
+                anchorChannelsConfig: FfiConverterOptionTypeAnchorChannelsConfig.read(from: &buf),
+                routeParameters: FfiConverterOptionTypeRouteParametersConfig.read(from: &buf),
+                includeUntrustedPendingInSpendable: FfiConverterBool.read(from: &buf)
+            )
     }
 
     public static func write(_ value: Config, into buf: inout [UInt8]) {
@@ -5173,6 +5180,7 @@ public struct FfiConverterTypeConfig: FfiConverterRustBuffer {
         FfiConverterUInt64.write(value.probingLiquidityLimitMultiplier, into: &buf)
         FfiConverterOptionTypeAnchorChannelsConfig.write(value.anchorChannelsConfig, into: &buf)
         FfiConverterOptionTypeRouteParametersConfig.write(value.routeParameters, into: &buf)
+        FfiConverterBool.write(value.includeUntrustedPendingInSpendable, into: &buf)
     }
 }
 

src/config.rs

@@ -184,6 +184,19 @@ pub struct Config {
 	/// **Note:** If unset, default parameters will be used, and you will be able to override the
 	/// parameters on a per-payment basis in the corresponding method calls.
 	pub route_parameters: Option<RouteParametersConfig>,
+	/// Whether to include unconfirmed funds from external sources in spendable balance.
+	///
+	/// If `true`, [`BalanceDetails::spendable_onchain_balance_sats`] will include
+	/// unconfirmed UTXOs received from external wallets (`untrusted_pending` in BDK terms).
+	///
+	/// Default is `false`, meaning only confirmed funds and unconfirmed change from your own
+	/// transactions are considered spendable.
+	///
+	/// **Warning:** Spending unconfirmed external funds is risky as the sender could
+	/// double-spend, causing your transaction to fail.
+	///
+	/// [`BalanceDetails::spendable_onchain_balance_sats`]: crate::BalanceDetails::spendable_onchain_balance_sats
+	pub include_untrusted_pending_in_spendable: bool,
 }
 
 impl Default for Config {
@@ -198,6 +211,7 @@ impl Default for Config {
 			anchor_channels_config: Some(AnchorChannelsConfig::default()),
 			route_parameters: None,
 			node_alias: None,
+			include_untrusted_pending_in_spendable: false,
 		}
 	}
 }

src/wallet/mod.rs

@@ -876,9 +876,15 @@ impl Wallet {
 	fn get_balances_inner(
 		&self, balance: Balance, total_anchor_channels_reserve_sats: u64,
 	) -> Result<(u64, u64), Error> {
+		let spendable_base = if self.config.include_untrusted_pending_in_spendable {
+			balance.trusted_spendable().to_sat() + balance.untrusted_pending.to_sat()
+		} else {
+			balance.trusted_spendable().to_sat()
+		};
+
 		let (total, spendable) = (
 			balance.total().to_sat(),
-			balance.trusted_spendable().to_sat().saturating_sub(total_anchor_channels_reserve_sats),
+			spendable_base.saturating_sub(total_anchor_channels_reserve_sats),
 		);
 
 		Ok((total, spendable))