feat(wasm-utxo): expose structured error codes derived from Rust enum variant names

Add a `WasmErrorCode` trait and `impl_wasm_error_code!` macro that derive
stable dotted error codes (e.g. `ParseTransactionError.Input/ParseInputError.WalletValidation`)
from Rust enum variant names via `strum::IntoStaticStr`.

The single `From<WasmUtxoError> for JsValue` bridge now attaches a `code`
string property to every thrown `Error` via `Reflect::set`, so callers can
dispatch on `err.code` instead of substring-matching `err.message`.

New variant names are exposed automatically — zero JS-side boilerplate per
error type.  Existing `WasmUtxoError::new()` call sites fall back to the
`WasmUtxoError.StringError` code unchanged.

The TS surface adds an `isWasmUtxoError` type guard and `WasmUtxoError`
interface exported from the package root.

Refs: T1-3475

Author: OttoAllmendinger

packages/wasm-utxo/Cargo.lock

@@ -27,6 +27,7 @@ inspect = ["dep:num-bigint", "dep:serde", "dep:serde_json", "dep:hex"]
 [dependencies]
 wasm-bindgen = "0.2"
 js-sys = "0.3"
+strum = { version = "0.27", features = ["derive"] }
 miniscript = { git = "https://github.com/BitGo/rust-miniscript", tag = "miniscript-13.0.0-bitgo.5" }
 bech32 = "0.11"
 musig2 = { version = "0.3.1", default-features = false, features = ["k256"] }

packages/wasm-utxo/Cargo.toml

@@ -144,6 +144,14 @@ declare module "./wasm/wasm_utxo.js" {
   }
 }
 
+export interface WasmUtxoError extends Error {
+  code: string;
+}
+
+export function isWasmUtxoError(e: unknown): e is WasmUtxoError {
+  return e instanceof Error && typeof (e as { code?: unknown }).code === "string";
+}
+
 export { WrapDescriptor as Descriptor } from "./wasm/wasm_utxo.js";
 export { WrapMiniscript as Miniscript } from "./wasm/wasm_utxo.js";
 export { Psbt } from "./descriptorWallet/Psbt.js";

packages/wasm-utxo/js/index.ts

@@ -49,7 +49,7 @@ pub use networks::{
 use crate::bitcoin::{Script, ScriptBuf};
 use std::fmt;
 
-#[derive(Debug)]
+#[derive(Debug, strum::IntoStaticStr)]
 pub enum AddressError {
     InvalidScript(String),
     InvalidAddress(String),
@@ -75,6 +75,7 @@ impl fmt::Display for AddressError {
 }
 
 impl std::error::Error for AddressError {}
+crate::impl_wasm_error_code!(AddressError);
 
 type Result<T> = std::result::Result<T, AddressError>;
 

packages/wasm-utxo/src/address/mod.rs

@@ -1,15 +1,46 @@
 use core::fmt;
 
-#[derive(Debug, Clone)]
+use crate::fixed_script_wallet::bitgo_psbt::ParseTransactionError;
+
+pub trait WasmErrorCode {
+    fn code(&self) -> String;
+}
+
+/// Derives `WasmErrorCode` for leaf error enums (no nested error variants).
+/// Requires `#[derive(strum::IntoStaticStr)]` on the enum.
+#[macro_export]
+macro_rules! impl_wasm_error_code {
+    ($t:ty) => {
+        impl $crate::error::WasmErrorCode for $t {
+            fn code(&self) -> String {
+                format!("{}.{}", stringify!($t), <&'static str>::from(self))
+            }
+        }
+    };
+}
+
+#[derive(Debug, strum::IntoStaticStr)]
 pub enum WasmUtxoError {
     StringError(String),
+    Parse(ParseTransactionError),
 }
 
 impl std::error::Error for WasmUtxoError {}
+
 impl fmt::Display for WasmUtxoError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             WasmUtxoError::StringError(s) => write!(f, "{}", s),
+            WasmUtxoError::Parse(e) => write!(f, "{}", e),
+        }
+    }
+}
+
+impl WasmErrorCode for WasmUtxoError {
+    fn code(&self) -> String {
+        match self {
+            WasmUtxoError::StringError(_) => "WasmUtxoError.StringError".to_string(),
+            WasmUtxoError::Parse(e) => e.code(),
         }
     }
 }
@@ -38,6 +69,18 @@ impl From<miniscript::descriptor::NonDefiniteKeyError> for WasmUtxoError {
     }
 }
 
+impl From<crate::address::AddressError> for WasmUtxoError {
+    fn from(err: crate::address::AddressError) -> Self {
+        WasmUtxoError::StringError(err.to_string())
+    }
+}
+
+impl From<ParseTransactionError> for WasmUtxoError {
+    fn from(err: ParseTransactionError) -> Self {
+        WasmUtxoError::Parse(err)
+    }
+}
+
 impl WasmUtxoError {
     pub fn new(s: &str) -> WasmUtxoError {
         WasmUtxoError::StringError(s.to_string())
@@ -53,8 +96,77 @@ impl WasmUtxoError {
     }
 }
 
-impl From<crate::address::AddressError> for WasmUtxoError {
-    fn from(err: crate::address::AddressError) -> Self {
-        WasmUtxoError::StringError(err.to_string())
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::fixed_script_wallet::bitgo_psbt::{
+        psbt_wallet_input::{OutputScriptError, ParseInputError},
+        psbt_wallet_output::ParseOutputError,
+        ParseTransactionError,
+    };
+
+    #[test]
+    fn string_error_code() {
+        let e = WasmUtxoError::new("oops");
+        assert_eq!(e.code(), "WasmUtxoError.StringError");
+    }
+
+    #[test]
+    fn parse_input_wallet_validation_code() {
+        let inner = ParseInputError::WalletValidation("no script type matches".to_string());
+        let e = WasmUtxoError::Parse(ParseTransactionError::Input {
+            index: 0,
+            error: inner,
+        });
+        assert_eq!(
+            e.code(),
+            "ParseTransactionError.Input/ParseInputError.WalletValidation"
+        );
+    }
+
+    #[test]
+    fn parse_input_utxo_code() {
+        let inner = ParseInputError::Utxo(OutputScriptError::NoUtxoFields);
+        let e = WasmUtxoError::Parse(ParseTransactionError::Input {
+            index: 0,
+            error: inner,
+        });
+        assert_eq!(
+            e.code(),
+            "ParseTransactionError.Input/ParseInputError.Utxo/OutputScriptError.NoUtxoFields"
+        );
+    }
+
+    #[test]
+    fn parse_output_code() {
+        let inner = ParseOutputError::WalletMatch("bad".to_string());
+        let e = WasmUtxoError::Parse(ParseTransactionError::Output {
+            index: 0,
+            error: inner,
+        });
+        assert_eq!(
+            e.code(),
+            "ParseTransactionError.Output/ParseOutputError.WalletMatch"
+        );
+    }
+
+    #[test]
+    fn leaf_variants_code() {
+        assert_eq!(
+            ParseInputError::ValueOverflow.code(),
+            "ParseInputError.ValueOverflow"
+        );
+        assert_eq!(
+            ParseInputError::Derivation("x".into()).code(),
+            "ParseInputError.Derivation"
+        );
+        assert_eq!(
+            ParseInputError::ScriptTypeDetection("x".into()).code(),
+            "ParseInputError.ScriptTypeDetection"
+        );
+        assert_eq!(
+            OutputScriptError::OutputIndexOutOfBounds { vout: 0 }.code(),
+            "OutputScriptError.OutputIndexOutOfBounds"
+        );
     }
 }

packages/wasm-utxo/src/error.rs

@@ -27,7 +27,7 @@ pub use zcash_psbt::{
     ZCASH_SAPLING_VERSION_GROUP_ID,
 };
 
-#[derive(Debug)]
+#[derive(Debug, strum::IntoStaticStr)]
 pub enum DeserializeError {
     /// Standard bitcoin consensus decoding error
     Consensus(miniscript::bitcoin::consensus::encode::Error),
@@ -48,6 +48,7 @@ impl std::fmt::Display for DeserializeError {
 }
 
 impl std::error::Error for DeserializeError {}
+crate::impl_wasm_error_code!(DeserializeError);
 
 impl From<miniscript::bitcoin::consensus::encode::Error> for DeserializeError {
     fn from(e: miniscript::bitcoin::consensus::encode::Error) -> Self {
@@ -61,7 +62,7 @@ impl From<miniscript::bitcoin::psbt::Error> for DeserializeError {
     }
 }
 
-#[derive(Debug)]
+#[derive(Debug, strum::IntoStaticStr)]
 pub enum SerializeError {
     /// Standard bitcoin consensus encoding error
     Consensus(std::io::Error),
@@ -79,6 +80,7 @@ impl std::fmt::Display for SerializeError {
 }
 
 impl std::error::Error for SerializeError {}
+crate::impl_wasm_error_code!(SerializeError);
 
 impl From<std::io::Error> for SerializeError {
     fn from(e: std::io::Error) -> Self {
@@ -136,7 +138,7 @@ pub struct ParsedTransaction {
 }
 
 /// Error type for transaction parsing
-#[derive(Debug)]
+#[derive(Debug, strum::IntoStaticStr)]
 pub enum ParseTransactionError {
     /// Failed to parse input
     Input {
@@ -185,6 +187,21 @@ impl std::fmt::Display for ParseTransactionError {
 
 impl std::error::Error for ParseTransactionError {}
 
+impl crate::error::WasmErrorCode for ParseTransactionError {
+    fn code(&self) -> String {
+        let variant: &str = self.into();
+        match self {
+            Self::Input { error, .. } => {
+                format!("ParseTransactionError.{}/{}", variant, error.code())
+            }
+            Self::Output { error, .. } => {
+                format!("ParseTransactionError.{}/{}", variant, error.code())
+            }
+            _ => format!("ParseTransactionError.{}", variant),
+        }
+    }
+}
+
 /// Get the default sighash type for a network and chain type
 fn get_default_sighash_type(
     network: Network,

packages/wasm-utxo/src/fixed_script_wallet/bitgo_psbt/mod.rs

@@ -71,7 +71,7 @@ pub fn derive_xpub_for_input_tap(
 }
 
 /// Error types for MuSig2 parsing
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, strum::IntoStaticStr)]
 pub enum Musig2Error {
     /// Missing participants
     MissingParticipants,
@@ -143,6 +143,7 @@ impl std::fmt::Display for Musig2Error {
 }
 
 impl std::error::Error for Musig2Error {}
+crate::impl_wasm_error_code!(Musig2Error);
 
 /// MuSig2 participant data
 ///

packages/wasm-utxo/src/fixed_script_wallet/bitgo_psbt/p2tr_musig2_input.rs

@@ -416,7 +416,7 @@ pub fn parse_shared_chain_and_index(input: &Input) -> Result<(u32, u32), String>
     Ok((chain, index))
 }
 
-#[derive(Debug)]
+#[derive(Debug, strum::IntoStaticStr)]
 pub enum OutputScriptError {
     OutputIndexOutOfBounds { vout: u32 },
     NoUtxoFields,
@@ -436,6 +436,7 @@ impl std::fmt::Display for OutputScriptError {
 }
 
 impl std::error::Error for OutputScriptError {}
+crate::impl_wasm_error_code!(OutputScriptError);
 
 /// Identifies a key in the wallet triple (user, backup, bitgo)
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -627,7 +628,7 @@ impl ParsedInput {
 }
 
 /// Error type for parsing a single PSBT input
-#[derive(Debug)]
+#[derive(Debug, strum::IntoStaticStr)]
 pub enum ParseInputError {
     /// Failed to extract output script or value from input
     Utxo(OutputScriptError),
@@ -670,6 +671,17 @@ impl std::fmt::Display for ParseInputError {
 
 impl std::error::Error for ParseInputError {}
 
+impl crate::error::WasmErrorCode for ParseInputError {
+    fn code(&self) -> String {
+        let variant: &str = self.into();
+        match self {
+            Self::Utxo(e) => format!("ParseInputError.{}/{}", variant, e.code()),
+            Self::Address(e) => format!("ParseInputError.{}/{}", variant, e.code()),
+            _ => format!("ParseInputError.{}", variant),
+        }
+    }
+}
+
 /// Get both output script and value from a PSBT input
 pub fn get_output_script_and_value(
     input: &Input,
@@ -697,7 +709,7 @@ fn get_output_script_from_input(
     get_output_script_and_value(input, prevout).map(|(script, _value)| script)
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, strum::IntoStaticStr)]
 pub enum InputValidationErrorKind {
     /// Failed to extract output script from input
     InvalidOutputScript(String),
@@ -739,7 +751,15 @@ impl std::fmt::Display for InputValidationError {
     }
 }
 
-#[derive(Debug, PartialEq, Eq)]
+crate::impl_wasm_error_code!(InputValidationErrorKind);
+
+impl crate::error::WasmErrorCode for InputValidationError {
+    fn code(&self) -> String {
+        self.kind.code()
+    }
+}
+
+#[derive(Debug, PartialEq, Eq, strum::IntoStaticStr)]
 pub enum PsbtValidationError {
     /// Number of prevouts does not match number of PSBT inputs
     InputLengthMismatch {
@@ -776,6 +796,19 @@ impl std::fmt::Display for PsbtValidationError {
 
 impl std::error::Error for PsbtValidationError {}
 
+impl crate::error::WasmErrorCode for PsbtValidationError {
+    fn code(&self) -> String {
+        let variant: &str = self.into();
+        match self {
+            Self::InvalidInputs(errors) => {
+                let inner = errors.first().map(|e| e.code()).unwrap_or_default();
+                format!("PsbtValidationError.{}/{}", variant, inner)
+            }
+            _ => format!("PsbtValidationError.{}", variant),
+        }
+    }
+}
+
 /// Validates that all inputs in a PSBT belong to the wallet
 pub fn validate_psbt_wallet_inputs(
     psbt: &Psbt,

packages/wasm-utxo/src/fixed_script_wallet/bitgo_psbt/psbt_wallet_input.rs

@@ -69,7 +69,7 @@ impl ParsedOutput {
 }
 
 /// Error type for parsing a single PSBT output
-#[derive(Debug)]
+#[derive(Debug, strum::IntoStaticStr)]
 pub enum ParseOutputError {
     /// Failed to match output to wallet (corruption or validation error)
     WalletMatch(String),
@@ -89,3 +89,4 @@ impl std::fmt::Display for ParseOutputError {
 }
 
 impl std::error::Error for ParseOutputError {}
+crate::impl_wasm_error_code!(ParseOutputError);

packages/wasm-utxo/src/fixed_script_wallet/bitgo_psbt/psbt_wallet_output.rs

@@ -987,7 +987,7 @@ impl BitGoPsbt {
         let parsed_tx = self
             .psbt
             .parse_transaction_with_wallet_keys(wallet_keys, replay_protection, &pubkeys)
-            .map_err(|e| WasmUtxoError::new(&format!("Failed to parse transaction: {}", e)))?;
+            .map_err(WasmUtxoError::from)?;
 
         // Convert to JsValue directly using TryIntoJsValue
         parsed_tx.try_to_js_value()