refactor: add dynamic dispatch and Zcash hydration support

Extends BitGoPsbt.fromHalfSignedLegacyTransaction() with:
- Dynamic dispatch to detect transaction type (Bitcoin/Dash/Zcash)
- Early rejection of Zcash with helpful error message
- ITransaction parameter overload to avoid re-parsing

Adds ZcashBitGoPsbt.fromHalfSignedLegacyTransaction():
- Block height mode (recommended): auto-determines consensus_branch_id
- Explicit consensus_branch_id mode for advanced usage
- Full Sapling field restoration
- Comprehensive round-trip tests

Rust layer implements:
- from_half_signed_legacy_transaction_zcash() with block height
- from_half_signed_legacy_transaction_zcash_with_consensus_branch_id()
- Shared logic for Zcash wire format decoding

Transaction classes add supportsCoin() for dispatch routing.
WASM bindings expose both Zcash variants with unified unspent parsing.

Co-authored-by: llm-git <llm-git@ttll.de>

Author: OttoAllmendinger

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

@@ -196,18 +196,46 @@ export class BitGoPsbt extends PsbtBase<WasmBitGoPsbt> implements IPsbtWithAddre
    * with proper wallet metadata (bip32Derivation, scripts, witnessUtxo).
    * Only supports p2sh, p2shP2wsh, and p2wsh inputs (not taproot).
    *
-   * @param txBytes - The serialized half-signed legacy transaction
+   * Uses dynamic dispatch to handle different transaction types:
+   * - Bitcoin-like coins (BTC, LTC, DOGE, etc.): Fully supported
+   * - Dash (DASH): Supported (special transaction format)
+   * - Zcash (ZEC): Not supported (incompatible overwintered format; use ZcashBitGoPsbt.createEmpty instead)
+   *
+   * @param txBytesOrTx - Either serialized transaction bytes or a decoded ITransaction instance
    * @param network - Network name
    * @param walletKeys - The wallet's root keys
    * @param unspents - Chain, index, and value for each input
+   * @param options - Additional options (e.g., blockHeight for Zcash consensus branch ID)
+   * @throws Error if transaction is Zcash (use ZcashBitGoPsbt.createEmpty instead)
    */
   static fromHalfSignedLegacyTransaction(
-    txBytes: Uint8Array,
+    txBytesOrTx: Uint8Array | ITransaction,
     network: NetworkName,
     walletKeys: WalletKeysArg,
     unspents: HydrationUnspent[],
+    _options?: unknown,
   ): BitGoPsbt {
     const keys = RootWalletKeys.from(walletKeys);
+
+    // Decode transaction bytes using dynamic dispatch if needed
+    let tx: ITransaction;
+    let txBytes: Uint8Array;
+    if (txBytesOrTx instanceof Uint8Array) {
+      txBytes = txBytesOrTx;
+      // Dynamic dispatch: determine coin type and decode with correct class
+      const coinName = typeof network === "string" ? (network as CoinName) : network;
+      tx = Transaction.fromBytes(txBytes, coinName);
+    } else {
+      tx = txBytesOrTx;
+      txBytes = tx.toBytes();
+    }
+
+    // Validate that this is not a Zcash transaction
+    if (tx instanceof ZcashTransaction) {
+      throw new Error('Use ZcashBitGoPsbt.fromHalfSignedLegacyTransaction() for Zcash transactions');
+    }
+
+    // For Bitcoin-like and Dash transactions, pass to WASM layer
     const wasm = WasmBitGoPsbt.from_half_signed_legacy_transaction(
       txBytes,
       network,

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

@@ -1,7 +1,7 @@
 import { BitGoPsbt as WasmBitGoPsbt } from "../wasm/wasm_utxo.js";
 import { type WalletKeysArg, RootWalletKeys } from "./RootWalletKeys.js";
-import { BitGoPsbt, type CreateEmptyOptions } from "./BitGoPsbt.js";
-import { ZcashTransaction } from "../transaction.js";
+import { BitGoPsbt, type CreateEmptyOptions, type HydrationUnspent } from "./BitGoPsbt.js";
+import { ZcashTransaction, type ITransaction } from "../transaction.js";
 
 /** Zcash network names */
 export type ZcashNetworkName = "zcash" | "zcashTest" | "zec" | "tzec";
@@ -144,6 +144,77 @@ export class ZcashBitGoPsbt extends BitGoPsbt {
     return new ZcashBitGoPsbt(wasm);
   }
 
+  /**
+   * Reconstruct a Zcash PSBT from a half-signed legacy transaction
+   *
+   * This is the inverse of `getHalfSignedLegacyFormat()` for Zcash. It decodes the Zcash wire
+   * format (which includes version_group_id, expiry_height, and sapling fields), extracts
+   * partial signatures, and reconstructs a proper Zcash PSBT with consensus metadata.
+   *
+   * Supports two modes for determining consensus_branch_id:
+   * - **Recommended**: Pass `blockHeight` to auto-determine consensus_branch_id via network upgrade activation heights
+   * - **Advanced**: Pass `consensusBranchId` directly if you already know it (e.g., 0xC2D6D0B4 for NU5)
+   *
+   * @param txBytesOrTx - Either serialized Zcash transaction bytes or a decoded ITransaction instance
+   * @param network - Zcash network name ("zcash", "zcashTest", "zec", "tzec")
+   * @param walletKeys - The wallet's root keys
+   * @param unspents - Chain, index, and value for each input
+   * @param options - Either `{ blockHeight: number }` or `{ consensusBranchId: number }`
+   * @returns A ZcashBitGoPsbt instance
+   *
+   * @example
+   * ```typescript
+   * // Round-trip with block height (recommended)
+   * const legacyBytes = psbt.getHalfSignedLegacyFormat();
+   * const reconstructed = ZcashBitGoPsbt.fromHalfSignedLegacyTransaction(
+   *   legacyBytes,
+   *   "zec",
+   *   walletKeys,
+   *   unspents,
+   *   { blockHeight: 1687105 }  // NU5 activation height
+   * );
+   *
+   * // Or with explicit consensus branch ID
+   * const reconstructed = ZcashBitGoPsbt.fromHalfSignedLegacyTransaction(
+   *   legacyBytes,
+   *   "zec",
+   *   walletKeys,
+   *   unspents,
+   *   { consensusBranchId: 0xC2D6D0B4 }  // NU5 branch ID
+   * );
+   * ```
+   */
+  static fromHalfSignedLegacyTransaction(
+    txBytesOrTx: Uint8Array | ITransaction,
+    network: ZcashNetworkName,
+    walletKeys: WalletKeysArg,
+    unspents: HydrationUnspent[],
+    options: { blockHeight: number } | { consensusBranchId: number },
+  ): ZcashBitGoPsbt {
+    const keys = RootWalletKeys.from(walletKeys);
+    const txBytes = txBytesOrTx instanceof Uint8Array ? txBytesOrTx : txBytesOrTx.toBytes();
+
+    if ("blockHeight" in options) {
+      const wasm = WasmBitGoPsbt.from_half_signed_legacy_transaction_zcash(
+        txBytes,
+        network,
+        keys.wasm,
+        unspents,
+        options.blockHeight,
+      );
+      return new ZcashBitGoPsbt(wasm);
+    } else {
+      const wasm = WasmBitGoPsbt.from_half_signed_legacy_transaction_zcash_with_branch_id(
+        txBytes,
+        network,
+        keys.wasm,
+        unspents,
+        options.consensusBranchId,
+      );
+      return new ZcashBitGoPsbt(wasm);
+    }
+  }
+
   // --- Zcash-specific getters ---
 
   /**

packages/wasm-utxo/js/transaction.ts

@@ -30,14 +30,33 @@ export class Transaction extends TransactionBase<WasmTransaction> {
     super(wasm);
   }
 
+  /**
+   * Check if a coin is supported by this transaction class.
+   * Bitcoin-like transactions support all coins except Zcash and Dash.
+   */
+  static supportsCoin(coin: CoinName): boolean {
+    return !ZcashTransaction.supportsCoin(coin) && !DashTransaction.supportsCoin(coin);
+  }
+
   /**
    * Create an empty transaction (version 1, locktime 0)
    */
   static create(): Transaction {
     return new Transaction(WasmTransaction.create());
   }
 
-  static fromBytes(bytes: Uint8Array): Transaction {
+  static fromBytes(bytes: Uint8Array): Transaction;
+  static fromBytes(bytes: Uint8Array, coin: "zec" | "tzec"): ZcashTransaction;
+  static fromBytes(bytes: Uint8Array, coin: "dash" | "tdash"): DashTransaction;
+  static fromBytes(bytes: Uint8Array, coin: CoinName): Transaction | ZcashTransaction | DashTransaction;
+  static fromBytes(
+    bytes: Uint8Array,
+    coin?: CoinName,
+  ): Transaction | ZcashTransaction | DashTransaction {
+    if (coin !== undefined) {
+      if (ZcashTransaction.supportsCoin(coin)) return ZcashTransaction.fromBytes(bytes);
+      if (DashTransaction.supportsCoin(coin)) return DashTransaction.fromBytes(bytes);
+    }
     return new Transaction(WasmTransaction.from_bytes(bytes));
   }
 
@@ -96,6 +115,14 @@ export class ZcashTransaction extends TransactionBase<WasmZcashTransaction> {
     super(wasm);
   }
 
+  /**
+   * Check if a coin is supported by this transaction class.
+   * Zcash transactions support Zcash mainnet and testnet.
+   */
+  static supportsCoin(coin: CoinName): boolean {
+    return coin === "zec" || coin === "tzec";
+  }
+
   static fromBytes(bytes: Uint8Array): ZcashTransaction {
     return new ZcashTransaction(WasmZcashTransaction.from_bytes(bytes));
   }
@@ -121,6 +148,14 @@ export class DashTransaction extends TransactionBase<WasmDashTransaction> {
     super(wasm);
   }
 
+  /**
+   * Check if a coin is supported by this transaction class.
+   * Dash transactions support Dash mainnet and testnet.
+   */
+  static supportsCoin(coin: CoinName): boolean {
+    return coin === "dash" || coin === "tdash";
+  }
+
   static fromBytes(bytes: Uint8Array): DashTransaction {
     return new DashTransaction(WasmDashTransaction.from_bytes(bytes));
   }
@@ -135,3 +170,4 @@ export class DashTransaction extends TransactionBase<WasmDashTransaction> {
     return this._wasm;
   }
 }
+