feat(wallet): expose finalize_psbt, cancel_tx, tx_details, descriptor_checksum, next_derivation_index

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Expand Wallet API surface ([#21](https://github.com/bitcoindevkit/bdk-wasm/issues/21)):
+  - `Wallet::finalize_psbt` for finalizing PSBTs (adding finalized script/witness to inputs)
+  - `Wallet::cancel_tx` for releasing reserved change addresses when a transaction won't be broadcast
+  - `Wallet::tx_details` for retrieving comprehensive transaction details (sent, received, fee, fee rate, balance delta, chain position)
+  - `Wallet::descriptor_checksum` for getting the descriptor checksum string for a keychain
+  - `Wallet::next_derivation_index` for getting the next unused derivation index for a keychain
+- `TxDetails` type with getters for `txid`, `sent`, `received`, `fee`, `fee_rate`, `balance_delta_sat`, `chain_position`, and `tx`
+
 ## [0.3.0] - 2026-03-16
 
 ### Added

src/bitcoin/wallet.rs

@@ -11,8 +11,8 @@ use crate::{
     result::JsResult,
     types::{
         AddressInfo, Amount, Balance, ChangeSet, CheckPoint, FeeRate, FullScanRequest, KeychainKind, LocalOutput,
-        Network, NetworkKind, OutPoint, Psbt, ScriptBuf, SentAndReceived, SpkIndexed, SyncRequest, Transaction, TxOut,
-        Txid, Update, WalletEvent,
+        Network, NetworkKind, OutPoint, Psbt, ScriptBuf, SentAndReceived, SpkIndexed, SyncRequest, Transaction,
+        TxDetails, TxOut, Txid, Update, WalletEvent,
     },
 };
 
@@ -265,6 +265,49 @@ impl Wallet {
             .map(|(keychain, index)| SpkIndexed(keychain.into(), index))
     }
 
+    /// Finalize a PSBT, putting the finalized script and witness values into the inputs.
+    ///
+    /// Returns `true` if the PSBT was fully finalized, `false` if some inputs could not
+    /// be finalized. Use `SignOptions::try_finalize` to control whether finalization is
+    /// attempted.
+    pub fn finalize_psbt(&self, psbt: &mut Psbt, options: SignOptions) -> JsResult<bool> {
+        let result = self.0.borrow().finalize_psbt(psbt, options.into())?;
+        Ok(result)
+    }
+
+    /// Inform the wallet that a transaction built from it will not be broadcast.
+    ///
+    /// This frees up the change address that was reserved when creating the transaction,
+    /// making it available for future transactions.
+    pub fn cancel_tx(&self, tx: &Transaction) {
+        self.0.borrow_mut().cancel_tx(tx);
+    }
+
+    /// Get the descriptor checksum for the given keychain.
+    ///
+    /// Returns the checksum portion of the descriptor string (the part after `#`).
+    pub fn descriptor_checksum(&self, keychain: KeychainKind) -> String {
+        self.0.borrow().descriptor_checksum(keychain.into())
+    }
+
+    /// Get the next derivation index for the given keychain.
+    ///
+    /// This is one more than the highest index that has been derived so far.
+    /// Unlike `derivation_index`, this always returns a value (0 if nothing has been derived).
+    pub fn next_derivation_index(&self, keychain: KeychainKind) -> u32 {
+        self.0.borrow().next_derivation_index(keychain.into())
+    }
+
+    /// Get detailed information about a transaction in the wallet.
+    ///
+    /// Returns `TxDetails` containing the sent/received amounts, fee, fee rate,
+    /// balance delta, chain position, and the full transaction.
+    ///
+    /// Returns `None` if the transaction is not found in the wallet.
+    pub fn tx_details(&self, txid: Txid) -> Option<TxDetails> {
+        self.0.borrow().tx_details(txid.into()).map(Into::into)
+    }
+
     pub fn apply_unconfirmed_txs(&self, unconfirmed_txs: Vec<UnconfirmedTx>) {
         self.0
             .borrow_mut()

src/types/mod.rs

@@ -16,6 +16,7 @@ mod psbt;
 mod script;
 mod slip10;
 mod transaction;
+mod tx_details;
 
 pub use address::*;
 pub use amount::*;
@@ -35,3 +36,4 @@ pub use psbt::*;
 pub use script::*;
 pub use slip10::*;
 pub use transaction::*;
+pub use tx_details::*;

src/types/tx_details.rs

@@ -0,0 +1,98 @@
+use bdk_wallet::TxDetails as BdkTxDetails;
+use wasm_bindgen::prelude::wasm_bindgen;
+
+use super::{Amount, ChainPosition, FeeRate, Transaction, Txid};
+
+/// Detailed information about a wallet transaction.
+///
+/// This type provides a comprehensive view of a transaction from the wallet's perspective,
+/// including sent/received amounts, fees, fee rate, balance delta, and chain position.
+///
+/// Obtain a `TxDetails` by calling `Wallet::tx_details(txid)`.
+#[wasm_bindgen]
+pub struct TxDetails {
+    txid: bitcoin::Txid,
+    sent: bitcoin::Amount,
+    received: bitcoin::Amount,
+    fee: Option<bitcoin::Amount>,
+    fee_rate: Option<bitcoin::FeeRate>,
+    balance_delta_sat: i64,
+    chain_position: bdk_wallet::chain::ChainPosition<bdk_wallet::chain::ConfirmationBlockTime>,
+    tx: bitcoin::Transaction,
+}
+
+#[wasm_bindgen]
+impl TxDetails {
+    /// The transaction id.
+    #[wasm_bindgen(getter)]
+    pub fn txid(&self) -> Txid {
+        self.txid.into()
+    }
+
+    /// The sum of the transaction input amounts that spend from previous outputs
+    /// tracked by this wallet.
+    #[wasm_bindgen(getter)]
+    pub fn sent(&self) -> Amount {
+        self.sent.into()
+    }
+
+    /// The sum of the transaction outputs that send to script pubkeys tracked by
+    /// this wallet.
+    #[wasm_bindgen(getter)]
+    pub fn received(&self) -> Amount {
+        self.received.into()
+    }
+
+    /// The fee paid for the transaction, if known.
+    ///
+    /// This will be `None` if the transaction has inputs not owned by this wallet
+    /// and their `TxOut` values have not been inserted via `Wallet::insert_txout`.
+    #[wasm_bindgen(getter)]
+    pub fn fee(&self) -> Option<Amount> {
+        self.fee.map(Into::into)
+    }
+
+    /// The fee rate paid for the transaction, if known.
+    ///
+    /// Same conditions as `fee` for when this is `None`.
+    #[wasm_bindgen(getter)]
+    pub fn fee_rate(&self) -> Option<FeeRate> {
+        self.fee_rate.map(Into::into)
+    }
+
+    /// The net effect of the transaction on the wallet balance, in satoshis.
+    ///
+    /// Positive values mean the wallet received more than it spent (net inflow).
+    /// Negative values mean the wallet spent more than it received (net outflow).
+    #[wasm_bindgen(getter)]
+    pub fn balance_delta_sat(&self) -> i64 {
+        self.balance_delta_sat
+    }
+
+    /// The position of the transaction in the chain (confirmed or unconfirmed).
+    #[wasm_bindgen(getter)]
+    pub fn chain_position(&self) -> ChainPosition {
+        self.chain_position.into()
+    }
+
+    /// The complete transaction.
+    #[wasm_bindgen(getter)]
+    pub fn tx(&self) -> Transaction {
+        self.tx.clone().into()
+    }
+}
+
+impl From<BdkTxDetails> for TxDetails {
+    fn from(details: BdkTxDetails) -> Self {
+        TxDetails {
+            txid: details.txid,
+            sent: details.sent,
+            received: details.received,
+            fee: details.fee,
+            fee_rate: details.fee_rate,
+            balance_delta_sat: details.balance_delta.to_sat(),
+            chain_position: details.chain_position,
+            tx: details.tx.as_ref().clone(),
+        }
+    }
+}

tests/node/integration/wallet.test.ts

@@ -302,4 +302,78 @@ describe("Wallet", () => {
       expect(data.available).toBeDefined();
     }
   });
+
+  describe("descriptor_checksum", () => {
+    it("returns a non-empty checksum string", () => {
+      const checksum = wallet.descriptor_checksum("external");
+
+      expect(typeof checksum).toBe("string");
+      expect(checksum.length).toBeGreaterThan(0);
+      // Descriptor checksums are 8 characters of bech32
+      expect(checksum.length).toBe(8);
+    });
+
+    it("returns different checksums for external and internal keychains", () => {
+      const externalChecksum = wallet.descriptor_checksum("external");
+      const internalChecksum = wallet.descriptor_checksum("internal");
+
+      expect(externalChecksum).not.toBe(internalChecksum);
+    });
+  });
+
+  describe("next_derivation_index", () => {
+    it("returns 0 for a fresh wallet with no revealed addresses", () => {
+      const freshWallet = Wallet.create(network, externalDesc, internalDesc);
+      const index = freshWallet.next_derivation_index("external");
+
+      expect(typeof index).toBe("number");
+      expect(index).toBe(0);
+    });
+
+    it("increments after revealing an address", () => {
+      const freshWallet = Wallet.create(network, externalDesc, internalDesc);
+      freshWallet.reveal_next_address("external");
+      const index = freshWallet.next_derivation_index("external");
+
+      expect(index).toBe(1);
+    });
+
+    it("is consistent with derivation_index", () => {
+      const freshWallet = Wallet.create(network, externalDesc, internalDesc);
+      freshWallet.reveal_next_address("external");
+      freshWallet.reveal_next_address("external");
+
+      const derivIndex = freshWallet.derivation_index("external");
+      const nextIndex = freshWallet.next_derivation_index("external");
+
+      // next_derivation_index should be derivation_index + 1
+      expect(nextIndex).toBe(derivIndex! + 1);
+    });
+  });
+
+  describe("cancel_tx", () => {
+    it("is callable on the wallet", () => {
+      // cancel_tx only unmarks change addresses; with an empty wallet it's a no-op.
+      // We verify the method exists and is callable.
+      expect(typeof wallet.cancel_tx).toBe("function");
+    });
+  });
+
+  describe("finalize_psbt", () => {
+    it("is callable with default SignOptions", () => {
+      expect(typeof wallet.finalize_psbt).toBe("function");
+      // Full PSBT finalization is tested in esplora integration tests
+      // where we have funded wallets
+    });
+  });
+
+  describe("tx_details", () => {
+    it("returns undefined for a non-existent txid", () => {
+      const unknownTxid = Txid.from_string(
+        "0000000000000000000000000000000000000000000000000000000000000000"
+      );
+      const details = wallet.tx_details(unknownTxid);
+      expect(details).toBeUndefined();
+    });
+  });
 });