feat: tx builder error handling (MetaMask#72)

Author: darioAnongba

.github/workflows/build-lint-test.yml

@@ -60,7 +60,7 @@ jobs:
         run: yarn lint
       - name: Test
         working-directory: tests/node
-        run: yarn test
+        run: yarn build && yarn test
 
   lint:
     name: Lint (fmt + clippy)

src/bitcoin/tx_builder.rs

@@ -1,12 +1,10 @@
 use std::{cell::RefCell, rc::Rc};
 
-use bdk_wallet::{bitcoin::ScriptBuf, Wallet as BdkWallet};
+use bdk_wallet::{bitcoin::ScriptBuf, error::CreateTxError, Wallet as BdkWallet};
+use serde::Serialize;
 use wasm_bindgen::prelude::wasm_bindgen;
 
-use crate::{
-    result::JsResult,
-    types::{Address, FeeRate, OutPoint, Psbt, Recipient},
-};
+use crate::types::{Address, Amount, BdkError, BdkErrorCode, FeeRate, OutPoint, Psbt, Recipient};
 
 /// A transaction builder.
 ///
@@ -113,7 +111,7 @@ impl TxBuilder {
     /// Finish building the transaction.
     ///
     /// Returns a new [`Psbt`] per [`BIP174`].
-    pub fn finish(self) -> JsResult<Psbt> {
+    pub fn finish(self) -> Result<Psbt, BdkError> {
         let mut wallet = self.wallet.borrow_mut();
         let mut builder = wallet.build_tx();
 
@@ -135,3 +133,50 @@ impl TxBuilder {
         Ok(psbt.into())
     }
 }
+
+/// Wallet's UTXO set is not enough to cover recipient's requested plus fee.
+#[wasm_bindgen]
+#[derive(Clone, Serialize)]
+pub struct InsufficientFunds {
+    /// Amount needed for the transaction
+    pub needed: Amount,
+    /// Amount available for spending
+    pub available: Amount,
+}
+
+impl From<CreateTxError> for BdkError {
+    fn from(e: CreateTxError) -> Self {
+        use CreateTxError::*;
+        match &e {
+            Descriptor(_) => BdkError::new(BdkErrorCode::Descriptor, e.to_string(), ()),
+            Policy(_) => BdkError::new(BdkErrorCode::Policy, e.to_string(), ()),
+            SpendingPolicyRequired(keychain_kind) => {
+                BdkError::new(BdkErrorCode::SpendingPolicyRequired, e.to_string(), keychain_kind)
+            }
+            Version0 => BdkError::new(BdkErrorCode::Version0, e.to_string(), ()),
+            Version1Csv => BdkError::new(BdkErrorCode::Version1Csv, e.to_string(), ()),
+            LockTime { .. } => BdkError::new(BdkErrorCode::LockTime, e.to_string(), ()),
+            RbfSequenceCsv { .. } => BdkError::new(BdkErrorCode::RbfSequenceCsv, e.to_string(), ()),
+            FeeTooLow { required } => BdkError::new(BdkErrorCode::FeeTooLow, e.to_string(), required),
+            FeeRateTooLow { required } => BdkError::new(BdkErrorCode::FeeRateTooLow, e.to_string(), required),
+            NoUtxosSelected => BdkError::new(BdkErrorCode::NoUtxosSelected, e.to_string(), ()),
+            OutputBelowDustLimit(limit) => BdkError::new(BdkErrorCode::OutputBelowDustLimit, e.to_string(), limit),
+            CoinSelection(insufficient_funds) => BdkError::new(
+                BdkErrorCode::InsufficientFunds,
+                e.to_string(),
+                InsufficientFunds {
+                    available: insufficient_funds.available.into(),
+                    needed: insufficient_funds.needed.into(),
+                },
+            ),
+            NoRecipients => BdkError::new(BdkErrorCode::NoRecipients, e.to_string(), ()),
+            Psbt(_) => BdkError::new(BdkErrorCode::Psbt, e.to_string(), ()),
+            MissingKeyOrigin(_) => BdkError::new(BdkErrorCode::MissingKeyOrigin, e.to_string(), ()),
+            UnknownUtxo => BdkError::new(BdkErrorCode::UnknownUtxo, e.to_string(), ()),
+            MissingNonWitnessUtxo(outpoint) => {
+                BdkError::new(BdkErrorCode::MissingNonWitnessUtxo, e.to_string(), outpoint)
+            }
+            MiniscriptPsbt(_) => BdkError::new(BdkErrorCode::MiniscriptPsbt, e.to_string(), ()),
+        }
+    }
+}

src/types/amount.rs

@@ -1,6 +1,7 @@
 use std::ops::Deref;
 
 use bdk_wallet::bitcoin::{Amount as BdkAmount, Denomination as BdkDenomination};
+use serde::Serialize;
 use wasm_bindgen::prelude::wasm_bindgen;
 
 use crate::result::JsResult;
@@ -10,7 +11,7 @@ use crate::result::JsResult;
 /// The [Amount] type can be used to express Bitcoin amounts that support
 /// arithmetic and conversion to various denominations.
 #[wasm_bindgen]
-#[derive(Clone, Copy)]
+#[derive(Clone, Copy, Serialize)]
 pub struct Amount(BdkAmount);
 
 #[wasm_bindgen]

src/types/error.rs

@@ -0,0 +1,86 @@
+use serde::Serialize;
+use serde_wasm_bindgen::to_value;
+use wasm_bindgen::{prelude::wasm_bindgen, JsValue};
+
+#[wasm_bindgen]
+pub struct BdkError {
+    code: BdkErrorCode,
+    message: String,
+    data: JsValue,
+}
+
+impl BdkError {
+    pub fn new<D>(code: BdkErrorCode, message: impl Into<String>, data: D) -> Self
+    where
+        D: Serialize,
+    {
+        BdkError {
+            code,
+            message: message.into(),
+            data: to_value(&data).unwrap_or(JsValue::UNDEFINED),
+        }
+    }
+}
+
+#[wasm_bindgen]
+impl BdkError {
+    #[wasm_bindgen(getter)]
+    pub fn code(&self) -> BdkErrorCode {
+        self.code
+    }
+
+    #[wasm_bindgen(getter)]
+    pub fn message(&self) -> String {
+        self.message.clone()
+    }
+
+    #[wasm_bindgen(getter)]
+    pub fn data(&self) -> JsValue {
+        self.data.clone()
+    }
+}
+
+#[wasm_bindgen]
+#[derive(Clone, Copy)]
+pub enum BdkErrorCode {
+    /// There was a problem with the descriptors passed in
+    Descriptor,
+    /// There was a problem while extracting and manipulating policies
+    Policy,
+    /// Spending policy is not compatible with this [`KeychainKind`]
+    SpendingPolicyRequired,
+    /// Requested invalid transaction version '0'
+    Version0,
+    /// Requested transaction version `1`, but at least `2` is needed to use OP_CSV
+    Version1Csv,
+    /// Requested `LockTime` is less than is required to spend from this script
+    LockTime,
+    /// Cannot enable RBF with `Sequence` given a required OP_CSV
+    RbfSequenceCsv,
+    /// When bumping a tx the absolute fee requested is lower than replaced tx absolute fee
+    FeeTooLow,
+    /// When bumping a tx the fee rate requested is lower than required
+    FeeRateTooLow,
+    /// `manually_selected_only` option is selected but no utxo has been passed
+    NoUtxosSelected,
+    /// Output created is under the dust limit, 546 satoshis
+    OutputBelowDustLimit,
+    /// Wallet's UTXO set is not enough to cover recipient's requested plus fee.
+    InsufficientFunds,
+    /// Cannot build a tx without recipients
+    NoRecipients,
+    /// Partially signed bitcoin transaction error
+    Psbt,
+    /// In order to use the [`TxBuilder::add_global_xpubs`] option every extended
+    /// key in the descriptor must either be a master key itself (having depth = 0) or have an
+    /// explicit origin provided
+    ///
+    /// [`TxBuilder::add_global_xpubs`]: crate::wallet::tx_builder::TxBuilder::add_global_xpubs
+    MissingKeyOrigin,
+    /// Happens when trying to spend an UTXO that is not in the internal database
+    UnknownUtxo,
+    /// Missing non_witness_utxo on foreign utxo for given `OutPoint`
+    MissingNonWitnessUtxo,
+    /// Miniscript PSBT error
+    MiniscriptPsbt,
+}

src/types/mod.rs

@@ -5,6 +5,7 @@ mod block;
 mod chain;
 mod changeset;
 mod checkpoint;
+mod error;
 mod fee;
 mod input;
 mod keychain;
@@ -21,6 +22,7 @@ pub use block::*;
 pub use chain::*;
 pub use changeset::*;
 pub use checkpoint::*;
+pub use error::*;
 pub use fee::*;
 pub use input::*;
 pub use keychain::*;

src/types/network.rs

@@ -6,9 +6,9 @@ use wasm_bindgen::prelude::wasm_bindgen;
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum NetworkKind {
     /// The Bitcoin mainnet network.
-    Main,
+    Main = "main",
     /// Some kind of testnet network.
-    Test,
+    Test = "test",
 }
 
 impl From<BdkNetworkKind> for NetworkKind {

tests/node/integration/esplora.test.ts

@@ -8,12 +8,14 @@ import {
   UnconfirmedTx,
   Wallet,
   SignOptions,
+  BdkError,
+  BdkErrorCode,
 } from "../../../pkg/bitcoindevkit";
 
 // Tests are expected to run in order
 describe("Esplora client", () => {
-  const stopGap = 5;
-  const parallelRequests = 1;
+  const stopGap = 2;
+  const parallelRequests = 10;
   const externalDescriptor =
     "wpkh(tprv8ZgxMBicQKsPe2qpAuh1K1Hig72LCoP4JgNxZM2ZRWHZYnpuw5oHoGBsQm7Qb8mLgPpRJVn3hceWgGQRNbPD6x1pp2Qme2YFRAPeYh7vmvE/84'/1'/0'/0/*)#a6kgzlgq";
   const internalDescriptor =
@@ -59,7 +61,7 @@ describe("Esplora client", () => {
     feeRate = new FeeRate(BigInt(Math.floor(fee)));
   });
 
-  it("sends a transaction", async () => {
+  it.skip("sends a transaction", async () => {
     const sendAmount = Amount.from_sat(BigInt(1000));
     expect(wallet.balance.trusted_spendable.to_sat()).toBeGreaterThan(
       sendAmount.to_sat()
@@ -105,4 +107,39 @@ describe("Esplora client", () => {
         .finish();
     }).toThrow();
   });
+
+  it("catches fine-grained errors and deserializes its data", () => {
+    // Amount should be too big so we fail with InsufficientFunds
+    const sendAmount = Amount.from_sat(BigInt(2000000000));
+
+    try {
+      wallet
+        .build_tx()
+        .fee_rate(new FeeRate(BigInt(1)))
+        .add_recipient(new Recipient(recipientAddress, sendAmount))
+        .finish();
+    } catch (error) {
+      expect(error).toBeInstanceOf(BdkError);
+
+      const { code, message, data } = error;
+      expect(code).toBe(BdkErrorCode.InsufficientFunds);
+      expect(message.startsWith("Insufficient funds:")).toBe(true);
+      expect(data.needed).toBe(2000000000 + 110);
+      expect(data.available).toBeDefined();
+    }
+
+    try {
+      wallet
+        .build_tx()
+        .fee_rate(new FeeRate(BigInt(1)))
+        .finish();
+    } catch (error) {
+      expect(error).toBeInstanceOf(BdkError);
+
+      const { code, message, data } = error;
+      expect(code).toBe(BdkErrorCode.NoRecipients);
+      expect(message).toBe("Cannot build tx without recipients");
+      expect(data).toBeUndefined();
+    }
+  });
 });

tests/node/package.json

@@ -3,7 +3,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "build": "wasm-pack build --target nodejs --all-features",
-    "test": "yarn build && jest"
+    "test": "jest"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",