feat: expose detailed try_finalize_psbt outcomes

Author: reez

src/wallet/mod.rs

@@ -184,6 +184,55 @@ impl fmt::Display for AddressInfo {
 /// A `CanonicalTx` managed by a `Wallet`.
 pub type WalletTx<'a> = CanonicalTx<'a, Arc<Transaction>, ConfirmationBlockTime>;
 
+/// The finalization status for a single PSBT input.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FinalizePsbtInputResult {
+    /// The input was already finalized before this call.
+    AlreadyFinalized,
+    /// The input was successfully finalized during this call.
+    Finalized,
+    /// The wallet could not derive a descriptor for the input.
+    MissingDescriptor,
+    /// The wallet found the descriptor but could not construct the input satisfaction.
+    CouldNotSatisfy,
+}
+
+impl FinalizePsbtInputResult {
+    /// Whether the input is finalized after this call.
+    pub fn is_finalized(&self) -> bool {
+        matches!(self, Self::AlreadyFinalized | Self::Finalized)
+    }
+}
+
+/// Holds per-input PSBT finalization results.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FinalizePsbtResult {
+    results: BTreeMap<usize, FinalizePsbtInputResult>,
+}
+
+impl FinalizePsbtResult {
+    fn new(results: BTreeMap<usize, FinalizePsbtInputResult>) -> Self {
+        Self { results }
+    }
+
+    /// Whether all inputs are finalized after this call.
+    pub fn is_finalized(&self) -> bool {
+        self.results
+            .values()
+            .all(FinalizePsbtInputResult::is_finalized)
+    }
+
+    /// Borrow the per-input finalization results.
+    pub fn results(&self) -> &BTreeMap<usize, FinalizePsbtInputResult> {
+        &self.results
+    }
+
+    /// Consume the result and return the per-input finalization results.
+    pub fn into_results(self) -> BTreeMap<usize, FinalizePsbtInputResult> {
+        self.results
+    }
+}
+
 impl Wallet {
     /// Build a new single descriptor [`Wallet`].
     ///
@@ -1842,6 +1891,19 @@ impl Wallet {
         psbt: &mut Psbt,
         sign_options: SignOptions,
     ) -> Result<bool, SignerError> {
+        Ok(self.try_finalize_psbt(psbt, sign_options)?.is_finalized())
+    }
+
+    /// Finalize a PSBT and return per-input finalization results. Use this method when you need to
+    /// inspect why a specific input could not be finalized.
+    ///
+    /// The method should only return `Err` when the PSBT is malformed, for example if its inputs
+    /// are out of bounds.
+    pub fn try_finalize_psbt(
+        &self,
+        psbt: &mut Psbt,
+        sign_options: SignOptions,
+    ) -> Result<FinalizePsbtResult, SignerError> {
         let tx = &psbt.unsigned_tx;
         let chain_tip = self.chain.tip().block_id();
         let prev_txids = tx
@@ -1867,14 +1929,15 @@ impl Wallet {
             })
             .collect::<HashMap<Txid, u32>>();
 
-        let mut finished = true;
+        let mut results = BTreeMap::new();
 
         for (n, input) in tx.input.iter().enumerate() {
             let psbt_input = &psbt
                 .inputs
                 .get(n)
                 .ok_or(IndexOutOfBoundsError::new(n, psbt.inputs.len()))?;
             if psbt_input.final_script_sig.is_some() || psbt_input.final_script_witness.is_some() {
+                results.insert(n, FinalizePsbtInputResult::AlreadyFinalized);
                 continue;
             }
             let confirmation_height = confirmation_heights
@@ -1927,23 +1990,29 @@ impl Wallet {
                             if !tmp_input.witness.is_empty() {
                                 psbt_input.final_script_witness = Some(tmp_input.witness);
                             }
+                            results.insert(n, FinalizePsbtInputResult::Finalized);
+                        }
+                        Err(_) => {
+                            results.insert(n, FinalizePsbtInputResult::CouldNotSatisfy);
                         }
-                        Err(_) => finished = false,
                     }
                 }
-                None => finished = false,
+                None => {
+                    results.insert(n, FinalizePsbtInputResult::MissingDescriptor);
+                }
             }
         }
 
         // Clear derivation paths from outputs.
-        if finished {
+        let finalized = FinalizePsbtResult::new(results);
+        if finalized.is_finalized() {
             for output in &mut psbt.outputs {
                 output.bip32_derivation.clear();
                 output.tap_key_origins.clear();
             }
         }
 
-        Ok(finished)
+        Ok(finalized)
     }
 
     /// Return the secp256k1 context used for all signing operations.

tests/wallet.rs

@@ -10,7 +10,9 @@ use bdk_wallet::psbt::PsbtUtils;
 use bdk_wallet::signer::{SignOptions, SignerError};
 use bdk_wallet::test_utils::*;
 use bdk_wallet::KeychainKind;
-use bdk_wallet::{AddressInfo, Balance, PersistedWallet, Update, Wallet, WalletTx};
+use bdk_wallet::{
+    AddressInfo, Balance, FinalizePsbtInputResult, PersistedWallet, Update, Wallet, WalletTx,
+};
 use bitcoin::constants::COINBASE_MATURITY;
 use bitcoin::hashes::Hash;
 use bitcoin::script::PushBytesBuf;
@@ -1526,6 +1528,119 @@ fn test_signing_only_one_of_multiple_inputs() {
     )
 }
 
+#[test]
+fn test_finalize_psbt_reports_per_input_results() {
+    let (mut wallet, _) = get_funded_wallet_wpkh();
+    let addr = Address::from_str("2N1Ffz3WaNzbeLFBb51xyFMHYSEUXcbiSoX")
+        .unwrap()
+        .assume_checked();
+    let mut builder = wallet.build_tx();
+    builder.add_recipient(addr.script_pubkey(), Amount::from_sat(45_000));
+    let mut psbt = builder.finish().unwrap();
+
+    let dud_input = bitcoin::psbt::Input {
+        witness_utxo: Some(TxOut {
+            value: Amount::from_sat(100_000),
+            script_pubkey: miniscript::Descriptor::<bitcoin::PublicKey>::from_str(
+                "wpkh(025476c2e83188368da1ff3e292e7acafcdb3566bb0ad253f62fc70f07aeee6357)",
+            )
+            .unwrap()
+            .script_pubkey(),
+        }),
+        ..Default::default()
+    };
+
+    psbt.inputs.push(dud_input);
+    psbt.unsigned_tx.input.push(bitcoin::TxIn::default());
+
+    wallet
+        .sign(
+            &mut psbt,
+            SignOptions {
+                try_finalize: false,
+                trust_witness_utxo: true,
+                ..Default::default()
+            },
+        )
+        .unwrap();
+
+    let results = wallet
+        .try_finalize_psbt(&mut psbt, SignOptions::default())
+        .unwrap()
+        .into_results();
+
+    assert_eq!(results.get(&0), Some(&FinalizePsbtInputResult::Finalized));
+    assert_eq!(
+        results.get(&1),
+        Some(&FinalizePsbtInputResult::MissingDescriptor)
+    );
+    assert!(psbt.inputs[0].final_script_witness.is_some());
+}
+
+#[test]
+fn test_finalize_psbt_reports_could_not_satisfy() {
+    let (mut wallet, _) = get_funded_wallet_single("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
+    let addr = wallet.next_unused_address(KeychainKind::External);
+    let mut builder = wallet.build_tx();
+    builder.drain_to(addr.script_pubkey()).drain_wallet();
+    let mut psbt = builder.finish().unwrap();
+
+    let result = wallet
+        .try_finalize_psbt(&mut psbt, SignOptions::default())
+        .unwrap();
+
+    assert!(!result.is_finalized());
+    assert_eq!(
+        result.results().get(&0),
+        Some(&FinalizePsbtInputResult::CouldNotSatisfy)
+    );
+    assert!(psbt.inputs[0].final_script_witness.is_none());
+}
+
+#[test]
+fn test_finalize_psbt_reports_already_finalized_inputs() {
+    let (mut wallet, _) = get_funded_wallet_single("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
+    let addr = wallet.next_unused_address(KeychainKind::External);
+    let mut builder = wallet.build_tx();
+    builder.drain_to(addr.script_pubkey()).drain_wallet();
+    let mut psbt = builder.finish().unwrap();
+
+    assert!(wallet.sign(&mut psbt, SignOptions::default()).unwrap());
+
+    let result = wallet
+        .try_finalize_psbt(&mut psbt, SignOptions::default())
+        .unwrap();
+
+    assert!(result.is_finalized());
+    assert_eq!(
+        result.results().get(&0),
+        Some(&FinalizePsbtInputResult::AlreadyFinalized)
+    );
+}
+
+#[test]
+fn test_finalize_psbt_preserves_bool_api() {
+    let (mut wallet, _) = get_funded_wallet_single("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");
+    let addr = wallet.next_unused_address(KeychainKind::External);
+    let mut builder = wallet.build_tx();
+    builder.drain_to(addr.script_pubkey()).drain_wallet();
+    let mut psbt = builder.finish().unwrap();
+
+    wallet
+        .sign(
+            &mut psbt,
+            SignOptions {
+                try_finalize: false,
+                ..Default::default()
+            },
+        )
+        .unwrap();
+
+    assert!(wallet
+        .finalize_psbt(&mut psbt, SignOptions::default())
+        .unwrap());
+}
+
 #[test]
 fn test_try_finalize_sign_option() {
     let (mut wallet, _) = get_funded_wallet_single("wpkh(tprv8ZgxMBicQKsPd3EupYiPRhaMooHKUHJxNsTfYuScep13go8QFfHdtkG9nRkFGb7busX4isf6X9dURGCoKgitaApQ6MupRhZMcELAxTBRJgS/*)");