feat: add get_address_balance

ben-kaufman · ben-kaufman · commit dbe2ada07f88 · 2025-11-25T09:01:56.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,6 +21,11 @@
   and other transaction types.
 - Added `Node::get_transaction_details()` method to retrieve transaction details for any
   transaction ID that exists in the wallet, returning `None` if the transaction is not found.
+- Added `Node::get_address_balance()` method to retrieve the current balance (in satoshis) for
+  any Bitcoin address. This queries the chain source (Esplora or Electrum) to get the balance.
+  Throws `InvalidAddress` if the address string cannot be parsed or doesn't match the node's
+  network. Returns 0 if the balance cannot be queried (e.g., chain source unavailable). Note: This
+  method is not available for BitcoindRpc chain source.
 - Added `SyncType` enum to distinguish between onchain wallet sync, Lightning
   wallet sync, and fee rate cache updates.
 - Balance tracking is now persisted in `NodeMetrics` to detect changes across restarts.
diff --git a/MOBILE_DEVELOPER_GUIDE.md b/MOBILE_DEVELOPER_GUIDE.md
@@ -133,6 +133,34 @@ if let details = node.getTransactionDetails(txid: txid) {
 
 This method returns `nil` if the transaction is not found in the wallet.
 
+#### Retrieving Address Balance
+
+You can retrieve the current balance for any Bitcoin address using `Node::get_address_balance()`:
+
+```swift
+// Get balance for a Bitcoin address
+do {
+    let balance = try node.getAddressBalance(addressStr: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh")
+    print("Address balance: \(balance) sats")
+} catch {
+    // Invalid address or network mismatch
+    print("Error: \(error)")
+}
+```
+
+```kotlin
+// Get balance for a Bitcoin address
+try {
+    val balance = node.getAddressBalance("bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh")
+    println("Address balance: $balance sats")
+} catch (e: Exception) {
+    // Invalid address or network mismatch
+    println("Error: ${e.message}")
+}
+```
+
+**Note**: This method queries the chain source directly and returns the balance in satoshis. It throws an error if the address string cannot be parsed or doesn't match the node's network. It returns `0` if the balance cannot be queried (e.g., chain source unavailable). This method is not available when using BitcoindRpc as the chain source.
+
 ---
 
 ## iOS/Swift Implementation
diff --git a/bindings/kotlin/ldk-node-android/lib/src/main/jniLibs/arm64-v8a/libldk_node.so b/bindings/kotlin/ldk-node-android/lib/src/main/jniLibs/arm64-v8a/libldk_node.so
diff --git a/bindings/kotlin/ldk-node-android/lib/src/main/jniLibs/armeabi-v7a/libldk_node.so b/bindings/kotlin/ldk-node-android/lib/src/main/jniLibs/armeabi-v7a/libldk_node.so
diff --git a/bindings/kotlin/ldk-node-android/lib/src/main/jniLibs/x86_64/libldk_node.so b/bindings/kotlin/ldk-node-android/lib/src/main/jniLibs/x86_64/libldk_node.so
diff --git a/bindings/kotlin/ldk-node-android/lib/src/main/kotlin/org/lightningdevkit/ldknode/ldk_node.android.kt b/bindings/kotlin/ldk-node-android/lib/src/main/kotlin/org/lightningdevkit/ldknode/ldk_node.android.kt
@@ -1347,6 +1347,8 @@ internal typealias UniffiVTableCallbackInterfaceVssHeaderProviderUniffiByValue =
 
 
 
+
+
 
 
 
@@ -1920,6 +1922,11 @@ internal interface UniffiLib : Library {
         `reason`: RustBufferByValue,
         uniffiCallStatus: UniffiRustCallStatus,
     ): Unit
+    fun uniffi_ldk_node_fn_method_node_get_address_balance(
+        `ptr`: Pointer?,
+        `addressStr`: RustBufferByValue,
+        uniffiCallStatus: UniffiRustCallStatus,
+    ): Long
     fun uniffi_ldk_node_fn_method_node_get_transaction_details(
         `ptr`: Pointer?,
         `txid`: RustBufferByValue,
@@ -2554,6 +2561,8 @@ internal interface UniffiLib : Library {
     ): Short
     fun uniffi_ldk_node_checksum_method_node_force_close_channel(
     ): Short
+    fun uniffi_ldk_node_checksum_method_node_get_address_balance(
+    ): Short
     fun uniffi_ldk_node_checksum_method_node_get_transaction_details(
     ): Short
     fun uniffi_ldk_node_checksum_method_node_list_balances(
@@ -2908,6 +2917,9 @@ private fun uniffiCheckApiChecksums(lib: UniffiLib) {
     if (lib.uniffi_ldk_node_checksum_method_node_force_close_channel() != 48831.toShort()) {
         throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     }
+    if (lib.uniffi_ldk_node_checksum_method_node_get_address_balance() != 45284.toShort()) {
+        throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
+    }
     if (lib.uniffi_ldk_node_checksum_method_node_get_transaction_details() != 65000.toShort()) {
         throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     }
@@ -5613,6 +5625,19 @@ open class Node: Disposable, NodeInterface {
         }
     }
 
+    @Throws(NodeException::class)
+    override fun `getAddressBalance`(`addressStr`: kotlin.String): kotlin.ULong {
+        return FfiConverterULong.lift(callWithPointer {
+            uniffiRustCallWithError(NodeExceptionErrorHandler) { uniffiRustCallStatus ->
+                UniffiLib.INSTANCE.uniffi_ldk_node_fn_method_node_get_address_balance(
+                    it,
+                    FfiConverterString.lower(`addressStr`),
+                    uniffiRustCallStatus,
+                )
+            }
+        })
+    }
+
     override fun `getTransactionDetails`(`txid`: Txid): TransactionDetails? {
         return FfiConverterOptionalTypeTransactionDetails.lift(callWithPointer {
             uniffiRustCall { uniffiRustCallStatus ->
diff --git a/bindings/kotlin/ldk-node-android/lib/src/main/kotlin/org/lightningdevkit/ldknode/ldk_node.common.kt b/bindings/kotlin/ldk-node-android/lib/src/main/kotlin/org/lightningdevkit/ldknode/ldk_node.common.kt
@@ -364,6 +364,9 @@ interface NodeInterface {
     @Throws(NodeException::class)
     fun `forceCloseChannel`(`userChannelId`: UserChannelId, `counterpartyNodeId`: PublicKey, `reason`: kotlin.String?)
     
+    @Throws(NodeException::class)
+    fun `getAddressBalance`(`addressStr`: kotlin.String): kotlin.ULong
+    
     fun `getTransactionDetails`(`txid`: Txid): TransactionDetails?
     
     fun `listBalances`(): BalanceDetails
diff --git a/bindings/ldk_node.udl b/bindings/ldk_node.udl
@@ -127,6 +127,8 @@ interface Node {
 	SpontaneousPayment spontaneous_payment();
 	OnchainPayment onchain_payment();
 	TransactionDetails? get_transaction_details([ByRef]Txid txid);
+	[Throws=NodeError]
+	u64 get_address_balance([ByRef]string address_str);
 	UnifiedQrPayment unified_qr_payment();
 	LSPS1Liquidity lsps1_liquidity();
 	[Throws=NodeError]
diff --git a/bindings/swift/Sources/LDKNode/LDKNode.swift b/bindings/swift/Sources/LDKNode/LDKNode.swift
@@ -1937,6 +1937,8 @@ public protocol NodeProtocol: AnyObject {
 
     func forceCloseChannel(userChannelId: UserChannelId, counterpartyNodeId: PublicKey, reason: String?) throws
 
+    func getAddressBalance(addressStr: String) throws -> UInt64
+
     func getTransactionDetails(txid: Txid) -> TransactionDetails?
 
     func listBalances() -> BalanceDetails
@@ -2096,6 +2098,13 @@ open class Node:
     }
     }
 
+    open func getAddressBalance(addressStr: String) throws -> UInt64 {
+        return try FfiConverterUInt64.lift(rustCallWithError(FfiConverterTypeNodeError.lift) {
+            uniffi_ldk_node_fn_method_node_get_address_balance(self.uniffiClonePointer(),
+                                                               FfiConverterString.lower(addressStr), $0)
+        })
+    }
+
     open func getTransactionDetails(txid: Txid) -> TransactionDetails? {
         return try! FfiConverterOptionTypeTransactionDetails.lift(try! rustCall {
             uniffi_ldk_node_fn_method_node_get_transaction_details(self.uniffiClonePointer(),
@@ -9598,6 +9607,9 @@ private var initializationResult: InitializationResult {
     if uniffi_ldk_node_checksum_method_node_force_close_channel() != 48831 {
         return InitializationResult.apiChecksumMismatch
     }
+    if uniffi_ldk_node_checksum_method_node_get_address_balance() != 45284 {
+        return InitializationResult.apiChecksumMismatch
+    }
     if uniffi_ldk_node_checksum_method_node_get_transaction_details() != 65000 {
         return InitializationResult.apiChecksumMismatch
     }
diff --git a/src/chain/electrum.rs b/src/chain/electrum.rs
@@ -82,6 +82,31 @@ impl ElectrumRuntimeClient {
 		Ok(Self { electrum_client, bdk_electrum_client, tx_sync, runtime, config, logger })
 	}
 
+	pub(crate) async fn get_address_balance(&self, address: &bitcoin::Address) -> Option<u64> {
+		use electrum_client::ElectrumApi;
+
+		let script = address.script_pubkey();
+		let electrum_client = Arc::clone(&self.electrum_client);
+		let script_clone = script.clone();
+		let balance_result = self
+			.runtime
+			.spawn_blocking(move || {
+				electrum_client
+					.script_get_balance(&script_clone)
+					.map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, format!("{}", e)))
+			})
+			.await;
+
+		match balance_result {
+			Ok(Ok(balance)) => {
+				let confirmed = balance.confirmed.max(0) as u64;
+				let unconfirmed = balance.unconfirmed.max(0) as u64;
+				Some(confirmed + unconfirmed)
+			},
+			_ => None,
+		}
+	}
+
 	pub(crate) async fn sync_confirmables(
 		&self, confirmables: Vec<Arc<dyn Confirm + Sync + Send>>,
 	) -> Result<(), Error> {
diff --git a/src/chain/mod.rs b/src/chain/mod.rs
@@ -1964,6 +1964,49 @@ impl Filter for ChainSource {
 	}
 }
 
+impl ChainSource {
+	/// Get the current balance for an address from the chain source.
+	pub(crate) async fn get_address_balance(&self, address: &bitcoin::Address) -> Option<u64> {
+		match self {
+			Self::Esplora { esplora_client, .. } => {
+				let script = address.script_pubkey();
+				match esplora_client.scripthash_txs(&script, None).await {
+					Ok(txs) => {
+						let mut balance = 0i64;
+						for tx in txs {
+							for output in &tx.vout {
+								if output.scriptpubkey == script {
+									balance += output.value as i64;
+								}
+							}
+							for input in &tx.vin {
+								if let Some(prevout) = &input.prevout {
+									if prevout.scriptpubkey == script {
+										balance -= prevout.value as i64;
+									}
+								}
+							}
+						}
+						Some(balance.max(0) as u64)
+					},
+					Err(_) => None,
+				}
+			},
+			Self::Electrum { electrum_runtime_status, .. } => {
+				if let Some(client) = electrum_runtime_status.read().unwrap().client().as_ref() {
+					client.get_address_balance(address).await
+				} else {
+					None
+				}
+			},
+			Self::BitcoindRpc { .. } => {
+				// BitcoindRpc doesn't have a direct address balance query API
+				None
+			},
+		}
+	}
+}
+
 fn periodically_archive_fully_resolved_monitors(
 	channel_manager: Arc<ChannelManager>, chain_monitor: Arc<ChainMonitor>,
 	kv_store: Arc<DynStore>, logger: Arc<Logger>, node_metrics: Arc<RwLock<NodeMetrics>>,
diff --git a/src/lib.rs b/src/lib.rs
@@ -1020,6 +1020,36 @@ impl Node {
 		Some(TransactionDetails { amount_sats, inputs, outputs })
 	}
 
+	/// Gets the current balance (in satoshis) for a Bitcoin address.
+	///
+	/// This queries the chain source (Esplora or Electrum) to get the current balance of the
+	/// address. Returns 0 if the balance cannot be queried (e.g., chain source unavailable).
+	///
+	/// Returns [`Error::InvalidAddress`] if the address string cannot be parsed or doesn't match
+	/// the node's network.
+	pub fn get_address_balance(&self, address_str: &str) -> Result<u64, Error> {
+		use bitcoin::address::NetworkUnchecked;
+		use std::str::FromStr;
+
+		let addr_unchecked = bitcoin::Address::<NetworkUnchecked>::from_str(address_str)
+			.map_err(|_| Error::InvalidAddress)?;
+
+		let addr_checked = addr_unchecked
+			.require_network(self.config.network)
+			.map_err(|_| Error::InvalidAddress)?;
+
+		if let Ok(runtime_guard) = self.runtime.read() {
+			if let Some(runtime) = runtime_guard.as_ref() {
+				let chain_source = Arc::clone(&self.chain_source);
+				let balance = runtime
+					.block_on(async move { chain_source.get_address_balance(&addr_checked).await });
+				return Ok(balance.unwrap_or(0));
+			}
+		}
+
+		Ok(0)
+	}
+
 	/// Returns a payment handler allowing to create [BIP 21] URIs with an on-chain, [BOLT 11],
 	/// and [BOLT 12] payment options.
 	///
diff --git a/tests/integration_tests_rust.rs b/tests/integration_tests_rust.rs
@@ -2095,7 +2095,8 @@ fn get_transaction_details() {
 	let txid = funding_txid.expect("Should have received OnchainTransactionConfirmed event");
 
 	// Test get_transaction_details with the funding transaction
-	let details = node.get_transaction_details(&txid).expect("Transaction should be found in wallet");
+	let details =
+		node.get_transaction_details(&txid).expect("Transaction should be found in wallet");
 
 	// Verify the details match what we expect
 	assert!(!details.inputs.is_empty(), "Transaction should have inputs");
@@ -2115,14 +2116,16 @@ fn get_transaction_details() {
 	}
 
 	// Test with a non-existent transaction
-	let fake_txid = Txid::from_str("0000000000000000000000000000000000000000000000000000000000000000").unwrap();
+	let fake_txid =
+		Txid::from_str("0000000000000000000000000000000000000000000000000000000000000000").unwrap();
 	let result = node.get_transaction_details(&fake_txid);
 	assert!(result.is_none(), "Non-existent transaction should return None");
 
 	// Create a new transaction and verify we can get its details
 	let recipient_addr = node.onchain_payment().new_address().unwrap();
 	let send_amount = 20_000;
-	let send_txid = node.onchain_payment().send_to_address(&recipient_addr, send_amount, None, None).unwrap();
+	let send_txid =
+		node.onchain_payment().send_to_address(&recipient_addr, send_amount, None, None).unwrap();
 
 	// Sync to include the new transaction
 	node.sync_wallets().unwrap();
@@ -2131,7 +2134,8 @@ fn get_transaction_details() {
 	std::thread::sleep(Duration::from_millis(500));
 
 	// Get details for the send transaction
-	let send_details = node.get_transaction_details(&send_txid).expect("Send transaction should be found");
+	let send_details =
+		node.get_transaction_details(&send_txid).expect("Send transaction should be found");
 
 	// Verify the send transaction details
 	assert!(!send_details.inputs.is_empty());
@@ -2142,3 +2146,81 @@ fn get_transaction_details() {
 
 	node.stop().unwrap();
 }
+
+#[test]
+fn get_address_balance_esplora() {
+	use std::time::Duration;
+
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+	let chain_source = TestChainSource::Esplora(&electrsd);
+	let config = random_config(false);
+	let node = setup_node(&chain_source, config, None);
+
+	// Fund an address
+	let addr = node.onchain_payment().new_address().unwrap();
+	let fund_amount = 100_000;
+	premine_and_distribute_funds(
+		&bitcoind.client,
+		&electrsd.client,
+		vec![addr.clone()],
+		Amount::from_sat(fund_amount),
+	);
+
+	// Sync to get the funds
+	node.sync_wallets().unwrap();
+
+	// Wait a bit for the chain source to index the transaction
+	std::thread::sleep(Duration::from_millis(500));
+
+	// Test get_address_balance with the funded address
+	let balance = node.get_address_balance(&addr.to_string()).unwrap();
+	assert_eq!(balance, fund_amount, "Balance should match funded amount");
+
+	// Test with an unfunded address
+	let unfunded_addr = node.onchain_payment().new_address().unwrap();
+	let unfunded_balance = node.get_address_balance(&unfunded_addr.to_string()).unwrap();
+	assert_eq!(unfunded_balance, 0, "Unfunded address should have zero balance");
+
+	// Test with an invalid address
+	let invalid_result = node.get_address_balance("invalid_address");
+	assert!(invalid_result.is_err(), "Invalid address should return error");
+}
+
+#[test]
+fn get_address_balance_electrum() {
+	use std::time::Duration;
+
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+	let chain_source = TestChainSource::Electrum(&electrsd);
+	let config = random_config(false);
+	let node = setup_node(&chain_source, config, None);
+
+	// Fund an address
+	let addr = node.onchain_payment().new_address().unwrap();
+	let fund_amount = 100_000;
+	premine_and_distribute_funds(
+		&bitcoind.client,
+		&electrsd.client,
+		vec![addr.clone()],
+		Amount::from_sat(fund_amount),
+	);
+
+	// Sync to get the funds
+	node.sync_wallets().unwrap();
+
+	// Wait a bit for the chain source to index the transaction
+	std::thread::sleep(Duration::from_millis(500));
+
+	// Test get_address_balance with the funded address
+	let balance = node.get_address_balance(&addr.to_string()).unwrap();
+	assert_eq!(balance, fund_amount, "Balance should match funded amount");
+
+	// Test with an unfunded address
+	let unfunded_addr = node.onchain_payment().new_address().unwrap();
+	let unfunded_balance = node.get_address_balance(&unfunded_addr.to_string()).unwrap();
+	assert_eq!(unfunded_balance, 0, "Unfunded address should have zero balance");
+
+	// Test with an invalid address
+	let invalid_result = node.get_address_balance("invalid_address");
+	assert!(invalid_result.is_err(), "Invalid address should return error");
+}
