CSHLD-1573: Build and validate Merkle witness path for Zcash Ironwood shielded notes

packages/wasm-utxo/Cargo.toml

@@ -85,6 +85,10 @@ hex = "0.4"
 wasm-bindgen-test = "0.3"
 rstest = "0.26.1"
 pastey = "0.1"
+# Pallas field arithmetic, used only in the ironwood_build witness tests to synthesize arbitrary
+# canonical field elements (leaf/sibling hashes) without needing a real note-commitment tree.
+# Version pinned to match orchard 0.15's own dependency (see Cargo.lock).
+pasta_curves = "0.5"
 
 [target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
 # 11.2 is the first release with the `Transaction::V6` / Ironwood (`ironwood_shielded_data`)

packages/wasm-utxo/js/fixedScriptWallet/ZcashIronwoodWitness.ts

@@ -0,0 +1,51 @@
+import {
+  IronwoodWitness as WasmIronwoodWitness,
+  ironwood_build_witness,
+} from "../wasm/wasm_utxo.js";
+
+/**
+ * A validated Merkle witness for an Ironwood/Orchard note commitment.
+ *
+ * Build with {@link ZcashIronwoodWitness.build}: `cmx` is the note commitment being
+ * witnessed, `authPath` must be exactly 32 sibling hashes (32 bytes each, leaf-to-root
+ * order), and `anchor` is the expected note-commitment-tree root. Throws if any input
+ * isn't a canonical field element, or if the witness doesn't recompute to `anchor`.
+ *
+ * wasm-utxo has no chain state, so the raw sibling-hash path must be supplied by the
+ * caller (typically BitGo's backend, querying a Zcash-aware service).
+ */
+export class ZcashIronwoodWitness {
+  private constructor(private _wasm: WasmIronwoodWitness) {}
+
+  /**
+   * Build and validate a Merkle witness for an Ironwood/Orchard note commitment.
+   * @throws If any input isn't a canonical field element, or the witness doesn't
+   *   recompute to `anchor`
+   */
+  static build(
+    cmx: Uint8Array,
+    position: number,
+    authPath: Uint8Array[],
+    anchor: Uint8Array,
+  ): ZcashIronwoodWitness {
+    return new ZcashIronwoodWitness(ironwood_build_witness(cmx, position, authPath, anchor));
+  }
+
+  /** The leaf's position in the note commitment tree. */
+  get position(): number {
+    return this._wasm.position;
+  }
+
+  /**
+   * The 32 sibling hashes (leaf-to-root order), flattened into a single 1024-byte array
+   * (32 hashes × 32 bytes each).
+   */
+  get authPath(): Uint8Array {
+    return this._wasm.auth_path;
+  }
+
+  /** @internal */
+  get wasm(): WasmIronwoodWitness {
+    return this._wasm;
+  }
+}

packages/wasm-utxo/js/fixedScriptWallet/index.ts

@@ -62,6 +62,9 @@ export { ZcashUnifiedAddress } from "./ZcashUnifiedAddress.js";
 // Zcash v6 (Ironwood / NU6.3) transaction
 export { ZcashV6Transaction } from "./ZcashV6Transaction.js";
 
+// Zcash v6 (Ironwood / NU6.3) Merkle witness
+export { ZcashIronwoodWitness } from "./ZcashIronwoodWitness.js";
+
 import type { ScriptType } from "./scriptType.js";
 
 /**

packages/wasm-utxo/src/error.rs

@@ -25,6 +25,7 @@ pub enum WasmUtxoError {
     Parse(ParseTransactionError),
     UnifiedAddress(crate::zcash::unified_address::UnifiedAddressError),
     ZcashV6(crate::zcash::v6::ZcashV6Error),
+    Ironwood(crate::zcash::ironwood_build::IronwoodBuildError),
 }
 
 impl std::error::Error for WasmUtxoError {}
@@ -36,6 +37,7 @@ impl fmt::Display for WasmUtxoError {
             WasmUtxoError::Parse(e) => write!(f, "{}", e),
             WasmUtxoError::UnifiedAddress(e) => write!(f, "{}", e),
             WasmUtxoError::ZcashV6(e) => write!(f, "{}", e),
+            WasmUtxoError::Ironwood(e) => write!(f, "{}", e),
         }
     }
 }
@@ -47,6 +49,7 @@ impl WasmErrorCode for WasmUtxoError {
             WasmUtxoError::Parse(e) => e.code(),
             WasmUtxoError::UnifiedAddress(e) => e.code(),
             WasmUtxoError::ZcashV6(e) => e.code(),
+            WasmUtxoError::Ironwood(e) => e.code(),
         }
     }
 }
@@ -99,6 +102,12 @@ impl From<crate::zcash::v6::ZcashV6Error> for WasmUtxoError {
     }
 }
 
+impl From<crate::zcash::ironwood_build::IronwoodBuildError> for WasmUtxoError {
+    fn from(err: crate::zcash::ironwood_build::IronwoodBuildError) -> Self {
+        WasmUtxoError::Ironwood(err)
+    }
+}
+
 impl WasmUtxoError {
     pub fn new(s: &str) -> WasmUtxoError {
         WasmUtxoError::StringError(s.to_string())

packages/wasm-utxo/src/wasm/zcash.rs

@@ -42,6 +42,78 @@ pub fn zcash_ironwood_version_group_id() -> u32 {
     crate::zcash::transaction::ZCASH_IRONWOOD_VERSION_GROUP_ID
 }
 
+/// A validated Merkle witness for an Ironwood/Orchard note commitment, from
+/// [`ironwood_build_witness`].
+///
+/// Not yet installed anywhere — see [`ironwood_build_witness`]'s docs.
+#[wasm_bindgen]
+pub struct IronwoodWitness {
+    inner: crate::zcash::ironwood_build::IronwoodWitness,
+}
+
+#[wasm_bindgen]
+impl IronwoodWitness {
+    /// The leaf's position in the note commitment tree.
+    #[wasm_bindgen(getter)]
+    pub fn position(&self) -> u32 {
+        self.inner.position
+    }
+
+    /// The 32 sibling hashes (leaf-to-root order), flattened into a single 1024-byte array
+    /// (32 hashes × 32 bytes each).
+    #[wasm_bindgen(getter)]
+    pub fn auth_path(&self) -> Vec<u8> {
+        self.inner.auth_path.concat()
+    }
+}
+
+/// Build and validate a Merkle witness for an Ironwood/Orchard note commitment.
+///
+/// `cmx` is the note commitment being witnessed; `auth_path` must be exactly 32 sibling hashes (32
+/// bytes each), leaf-to-root order; `anchor` is the expected note-commitment-tree root. Throws if
+/// any input isn't a canonical field element, or if the witness doesn't recompute to `anchor`.
+///
+/// This crate has no chain state, so the raw sibling-hash path must be supplied by the caller
+/// (typically BitGo's backend, querying a Zcash-aware service). The returned witness is not yet
+/// installed anywhere — hook it into a spend once real-spend construction exists.
+#[wasm_bindgen]
+pub fn ironwood_build_witness(
+    cmx: &[u8],
+    position: u32,
+    auth_path: Vec<js_sys::Uint8Array>,
+    anchor: &[u8],
+) -> Result<IronwoodWitness, WasmUtxoError> {
+    use crate::zcash::ironwood_build::{build_ironwood_witness, IRONWOOD_MERKLE_DEPTH};
+
+    let cmx: [u8; 32] = cmx
+        .try_into()
+        .map_err(|_| WasmUtxoError::new(&format!("cmx must be 32 bytes, got {}", cmx.len())))?;
+    let anchor: [u8; 32] = anchor.try_into().map_err(|_| {
+        WasmUtxoError::new(&format!("anchor must be 32 bytes, got {}", anchor.len()))
+    })?;
+    if auth_path.len() != IRONWOOD_MERKLE_DEPTH {
+        return Err(WasmUtxoError::new(&format!(
+            "authPath must have exactly {} entries, got {}",
+            IRONWOOD_MERKLE_DEPTH,
+            auth_path.len()
+        )));
+    }
+    let mut path = [[0u8; 32]; IRONWOOD_MERKLE_DEPTH];
+    for (i, entry) in auth_path.iter().enumerate() {
+        let bytes = entry.to_vec();
+        path[i] = bytes.try_into().map_err(|_| {
+            WasmUtxoError::new(&format!(
+                "authPath[{i}] must be 32 bytes, got {}",
+                entry.length()
+            ))
+        })?;
+    }
+
+    Ok(IronwoodWitness {
+        inner: build_ironwood_witness(&cmx, position, &path, &anchor)?,
+    })
+}
+
 /// A parsed ZIP-316 Unified Address.
 ///
 /// Decode once with [`ZcashUnifiedAddress::parse`], then read each component through