Expose wallet get_transaction_details

ben-kaufman · ben-kaufman · commit 634ce3e4a612 · 2025-11-25T07:21:16.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,8 @@
   transaction information in onchain events, including inputs and outputs. This enables
   applications to analyze transaction data themselves to detect channel funding, closures,
   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 `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
@@ -114,6 +114,25 @@ The `TransactionDetails` struct provides comprehensive information about transac
 
 **Note**: You can analyze transaction inputs and outputs to detect channel funding, channel closures, and other transaction types. This provides more flexibility than the previous `TransactionContext` enum.
 
+#### Retrieving Transaction Details
+
+You can also retrieve transaction details directly using `Node::get_transaction_details()`:
+
+```swift
+// Get transaction details for a specific transaction ID
+if let details = node.getTransactionDetails(txid: txid) {
+    // Analyze the transaction details
+    print("Transaction amount: \(details.amountSats) sats")
+    print("Number of inputs: \(details.inputs.count)")
+    print("Number of outputs: \(details.outputs.count)")
+} else {
+    // Transaction not found in wallet
+    print("Transaction not found")
+}
+```
+
+This method returns `nil` if the transaction is not found in the wallet.
+
 ---
 
 ## iOS/Swift Implementation
@@ -544,6 +563,11 @@ class TransactionNotificationManager(private val context: Context) {
         }
     }
 
+    // Retrieve transaction details directly
+    fun getTransactionDetails(txid: String): TransactionDetails? {
+        return node.getTransactionDetails(txid = txid)
+    }
+
     // Helper functions to analyze transaction details
     private fun isChannelFundingTransaction(details: TransactionDetails): Boolean {
         // Analyze inputs/outputs to detect channel funding
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
@@ -1345,6 +1345,8 @@ internal typealias UniffiVTableCallbackInterfaceVssHeaderProviderUniffiByValue =
 
 
 
+
+
 
 
 
@@ -1918,6 +1920,11 @@ internal interface UniffiLib : Library {
         `reason`: RustBufferByValue,
         uniffiCallStatus: UniffiRustCallStatus,
     ): Unit
+    fun uniffi_ldk_node_fn_method_node_get_transaction_details(
+        `ptr`: Pointer?,
+        `txid`: RustBufferByValue,
+        uniffiCallStatus: UniffiRustCallStatus,
+    ): RustBufferByValue
     fun uniffi_ldk_node_fn_method_node_list_balances(
         `ptr`: Pointer?,
         uniffiCallStatus: UniffiRustCallStatus,
@@ -2547,6 +2554,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_transaction_details(
+    ): Short
     fun uniffi_ldk_node_checksum_method_node_list_balances(
     ): Short
     fun uniffi_ldk_node_checksum_method_node_list_channels(
@@ -2899,6 +2908,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_transaction_details() != 65000.toShort()) {
+        throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
+    }
     if (lib.uniffi_ldk_node_checksum_method_node_list_balances() != 57528.toShort()) {
         throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     }
@@ -5601,6 +5613,18 @@ open class Node: Disposable, NodeInterface {
         }
     }
 
+    override fun `getTransactionDetails`(`txid`: Txid): TransactionDetails? {
+        return FfiConverterOptionalTypeTransactionDetails.lift(callWithPointer {
+            uniffiRustCall { uniffiRustCallStatus ->
+                UniffiLib.INSTANCE.uniffi_ldk_node_fn_method_node_get_transaction_details(
+                    it,
+                    FfiConverterTypeTxid.lower(`txid`),
+                    uniffiRustCallStatus,
+                )
+            }
+        })
+    }
+
     override fun `listBalances`(): BalanceDetails {
         return FfiConverterTypeBalanceDetails.lift(callWithPointer {
             uniffiRustCall { uniffiRustCallStatus ->
@@ -10344,6 +10368,35 @@ object FfiConverterOptionalTypeSendingParameters: FfiConverterRustBuffer<Sending
 
 
 
+object FfiConverterOptionalTypeTransactionDetails: FfiConverterRustBuffer<TransactionDetails?> {
+    override fun read(buf: ByteBuffer): TransactionDetails? {
+        if (buf.get().toInt() == 0) {
+            return null
+        }
+        return FfiConverterTypeTransactionDetails.read(buf)
+    }
+
+    override fun allocationSize(value: TransactionDetails?): ULong {
+        if (value == null) {
+            return 1UL
+        } else {
+            return 1UL + FfiConverterTypeTransactionDetails.allocationSize(value)
+        }
+    }
+
+    override fun write(value: TransactionDetails?, buf: ByteBuffer) {
+        if (value == null) {
+            buf.put(0)
+        } else {
+            buf.put(1)
+            FfiConverterTypeTransactionDetails.write(value, buf)
+        }
+    }
+}
+
+
+
+
 object FfiConverterOptionalTypeClosureReason: FfiConverterRustBuffer<ClosureReason?> {
     override fun read(buf: ByteBuffer): ClosureReason? {
         if (buf.get().toInt() == 0) {
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,8 @@ interface NodeInterface {
     @Throws(NodeException::class)
     fun `forceCloseChannel`(`userChannelId`: UserChannelId, `counterpartyNodeId`: PublicKey, `reason`: kotlin.String?)
     
+    fun `getTransactionDetails`(`txid`: Txid): TransactionDetails?
+    
     fun `listBalances`(): BalanceDetails
     
     fun `listChannels`(): List<ChannelDetails>
@@ -1909,6 +1911,8 @@ sealed class VssHeaderProviderException(message: String): kotlin.Exception(messa
 
 
 
+
+
 
 
 
diff --git a/bindings/ldk_node.udl b/bindings/ldk_node.udl
@@ -126,6 +126,7 @@ interface Node {
 	Bolt12Payment bolt12_payment();
 	SpontaneousPayment spontaneous_payment();
 	OnchainPayment onchain_payment();
+	TransactionDetails? get_transaction_details([ByRef]Txid txid);
 	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 getTransactionDetails(txid: Txid) -> TransactionDetails?
+
     func listBalances() -> BalanceDetails
 
     func listChannels() -> [ChannelDetails]
@@ -2094,6 +2096,13 @@ open class Node:
     }
     }
 
+    open func getTransactionDetails(txid: Txid) -> TransactionDetails? {
+        return try! FfiConverterOptionTypeTransactionDetails.lift(try! rustCall {
+            uniffi_ldk_node_fn_method_node_get_transaction_details(self.uniffiClonePointer(),
+                                                                   FfiConverterTypeTxid.lower(txid), $0)
+        })
+    }
+
     open func listBalances() -> BalanceDetails {
         return try! FfiConverterTypeBalanceDetails.lift(try! rustCall {
             uniffi_ldk_node_fn_method_node_list_balances(self.uniffiClonePointer(), $0)
@@ -7821,6 +7830,27 @@ private struct FfiConverterOptionTypeSendingParameters: FfiConverterRustBuffer {
     }
 }
 
+private struct FfiConverterOptionTypeTransactionDetails: FfiConverterRustBuffer {
+    typealias SwiftType = TransactionDetails?
+
+    static func write(_ value: SwiftType, into buf: inout [UInt8]) {
+        guard let value = value else {
+            writeInt(&buf, Int8(0))
+            return
+        }
+        writeInt(&buf, Int8(1))
+        FfiConverterTypeTransactionDetails.write(value, into: &buf)
+    }
+
+    static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> SwiftType {
+        switch try readInt(&buf) as Int8 {
+        case 0: return nil
+        case 1: return try FfiConverterTypeTransactionDetails.read(from: &buf)
+        default: throw UniffiInternalError.unexpectedOptionalTag
+        }
+    }
+}
+
 private struct FfiConverterOptionTypeClosureReason: FfiConverterRustBuffer {
     typealias SwiftType = ClosureReason?
 
@@ -9568,6 +9598,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_transaction_details() != 65000 {
+        return InitializationResult.apiChecksumMismatch
+    }
     if uniffi_ldk_node_checksum_method_node_list_balances() != 57528 {
         return InitializationResult.apiChecksumMismatch
     }
diff --git a/src/lib.rs b/src/lib.rs
@@ -1012,6 +1012,14 @@ impl Node {
 		))
 	}
 
+	/// Returns transaction details for the given transaction ID, if available in the wallet.
+	///
+	/// Returns `None` if the transaction is not found in the wallet.
+	pub fn get_transaction_details(&self, txid: &bitcoin::Txid) -> Option<TransactionDetails> {
+		let (amount_sats, inputs, outputs) = self.wallet.get_tx_details(txid)?;
+		Some(TransactionDetails { amount_sats, inputs, outputs })
+	}
+
 	/// 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
@@ -34,6 +34,7 @@ use bitcoin::address::NetworkUnchecked;
 use bitcoin::hashes::Hash;
 use bitcoin::Address;
 use bitcoin::Amount;
+use bitcoin::Txid;
 use log::LevelFilter;
 
 use std::str::FromStr;
@@ -2039,3 +2040,105 @@ fn onchain_transaction_evicted_event() {
 
 	node.stop().unwrap();
 }
+
+#[test]
+fn get_transaction_details() {
+	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 the node
+	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();
+
+	// Clear any existing events
+	while node.next_event().is_some() {
+		node.event_handled().unwrap();
+	}
+
+	// Wait a bit for events to be processed
+	std::thread::sleep(Duration::from_millis(100));
+
+	// Get the transaction ID from the confirmed event
+	let mut funding_txid = None;
+	for _ in 0..5 {
+		if let Some(event) = node.next_event() {
+			match event {
+				Event::OnchainTransactionConfirmed { txid, details, .. } => {
+					funding_txid = Some(txid);
+					// Verify we can access the details from the event
+					assert!(!details.inputs.is_empty());
+					assert!(!details.outputs.is_empty());
+					node.event_handled().unwrap();
+					break;
+				},
+				_ => {
+					node.event_handled().unwrap();
+				},
+			}
+		}
+		std::thread::sleep(Duration::from_millis(100));
+	}
+
+	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");
+
+	// Verify the details match what we expect
+	assert!(!details.inputs.is_empty(), "Transaction should have inputs");
+	assert!(!details.outputs.is_empty(), "Transaction should have outputs");
+	assert_eq!(details.amount_sats, fund_amount as i64, "Amount should match funding amount");
+
+	// Verify input structure
+	for input in &details.inputs {
+		assert!(!input.txid.to_string().is_empty(), "Input should have a txid");
+		assert!(!input.scriptsig.is_empty(), "Input should have a scriptsig");
+	}
+
+	// Verify output structure
+	for output in &details.outputs {
+		assert!(output.value > 0, "Output should have a positive value");
+		assert!(!output.scriptpubkey.is_empty(), "Output should have a scriptpubkey");
+	}
+
+	// Test with a non-existent transaction
+	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();
+
+	// Sync to include the new transaction
+	node.sync_wallets().unwrap();
+
+	// Wait a bit
+	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");
+
+	// Verify the send transaction details
+	assert!(!send_details.inputs.is_empty());
+	assert!(!send_details.outputs.is_empty());
+	// The amount should be negative (outgoing) or positive depending on change
+	// But the absolute value should be at least the send amount
+	assert!(send_details.amount_sats.abs() >= send_amount as i64 || send_details.amount_sats < 0);
+
+	node.stop().unwrap();
+}
