@bitgo/wasm-utxo 1.15.0 → 1.17.0

package/dist/esm/js/fixedScriptWallet/ZcashBitGoPsbt.d.ts

@@ -0,0 +1,113 @@
+import { type WalletKeysArg } from "./RootWalletKeys.js";
+import { BitGoPsbt, type CreateEmptyOptions } from "./BitGoPsbt.js";
+/** Zcash network names */
+export type ZcashNetworkName = "zcash" | "zcashTest" | "zec" | "tzec";
+/** Options for creating an empty Zcash PSBT (preferred method using block height) */
+export type CreateEmptyZcashOptions = CreateEmptyOptions & {
+    /** Block height to determine consensus branch ID automatically */
+    blockHeight: number;
+    /** Zcash version group ID (defaults to Sapling: 0x892F2085) */
+    versionGroupId?: number;
+    /** Zcash transaction expiry height */
+    expiryHeight?: number;
+};
+/** Options for creating an empty Zcash PSBT with explicit consensus branch ID (advanced use) */
+export type CreateEmptyZcashWithConsensusBranchIdOptions = CreateEmptyOptions & {
+    /** Zcash consensus branch ID (required, e.g., 0xC2D6D0B4 for NU5, 0x76B809BB for Sapling) */
+    consensusBranchId: number;
+    /** Zcash version group ID (defaults to Sapling: 0x892F2085) */
+    versionGroupId?: number;
+    /** Zcash transaction expiry height */
+    expiryHeight?: number;
+};
+/**
+ * Zcash-specific PSBT implementation
+ *
+ * This class extends BitGoPsbt with Zcash-specific functionality:
+ * - Required consensus branch ID for sighash computation
+ * - Version group ID for Zcash transaction format
+ * - Expiry height for transaction validity
+ *
+ * All Zcash-specific getters return non-optional types since they're
+ * guaranteed to be present for Zcash PSBTs.
+ *
+ * @example
+ * ```typescript
+ * // Create a new Zcash PSBT
+ * const psbt = ZcashBitGoPsbt.createEmpty("zcash", walletKeys, {
+ *   consensusBranchId: 0x76B809BB,  // Sapling
+ * });
+ *
+ * // Deserialize from bytes
+ * const psbt = ZcashBitGoPsbt.fromBytes(bytes, "zcash");
+ * ```
+ */
+export declare class ZcashBitGoPsbt extends BitGoPsbt {
+    /**
+     * Create an empty Zcash PSBT with consensus branch ID determined from block height
+     *
+     * **This is the preferred method for creating Zcash PSBTs.** It automatically determines
+     * the correct consensus branch ID based on the network and block height using Zcash
+     * network upgrade activation heights, eliminating the need to manually look up branch IDs.
+     *
+     * @param network - Zcash network name ("zcash", "zcashTest", "zec", "tzec")
+     * @param walletKeys - The wallet's root keys (sets global xpubs in the PSBT)
+     * @param options - Options including blockHeight to determine consensus rules
+     * @returns A new ZcashBitGoPsbt instance
+     * @throws Error if block height is before Overwinter activation
+     *
+     * @example
+     * ```typescript
+     * // Create PSBT for a specific block height (recommended)
+     * const psbt = ZcashBitGoPsbt.createEmpty("zcash", walletKeys, {
+     *   blockHeight: 1687104,  // Automatically uses Nu5 branch ID
+     * });
+     *
+     * // Create PSBT for current block height
+     * const currentHeight = await getBlockHeight();
+     * const psbt = ZcashBitGoPsbt.createEmpty("zcash", walletKeys, {
+     *   blockHeight: currentHeight,
+     * });
+     * ```
+     */
+    static createEmpty(network: ZcashNetworkName, walletKeys: WalletKeysArg, options: CreateEmptyZcashOptions): ZcashBitGoPsbt;
+    /**
+     * Create an empty Zcash PSBT with explicit consensus branch ID
+     *
+     * **Advanced use only.** This method requires manually specifying the consensus branch ID.
+     * In most cases, you should use `createEmpty()` instead, which automatically determines
+     * the correct branch ID from the block height.
+     *
+     * @param network - Zcash network name ("zcash", "zcashTest", "zec", "tzec")
+     * @param walletKeys - The wallet's root keys (sets global xpubs in the PSBT)
+     * @param options - Zcash-specific options including required consensusBranchId
+     * @returns A new ZcashBitGoPsbt instance
+     *
+     * @example
+     * ```typescript
+     * // Only use this if you need explicit control over the branch ID
+     * const psbt = ZcashBitGoPsbt.createEmptyWithConsensusBranchId("zcash", walletKeys, {
+     *   consensusBranchId: 0xC2D6D0B4,  // Nu5 branch ID
+     * });
+     * ```
+     */
+    static createEmptyWithConsensusBranchId(network: ZcashNetworkName, walletKeys: WalletKeysArg, options: CreateEmptyZcashWithConsensusBranchIdOptions): ZcashBitGoPsbt;
+    /**
+     * Deserialize a Zcash PSBT from bytes
+     *
+     * @param bytes - The PSBT bytes
+     * @param network - Zcash network name ("zcash", "zcashTest", "zec", "tzec")
+     * @returns A ZcashBitGoPsbt instance
+     */
+    static fromBytes(bytes: Uint8Array, network: ZcashNetworkName): ZcashBitGoPsbt;
+    /**
+     * Get the Zcash version group ID
+     * @returns The version group ID (e.g., 0x892F2085 for Sapling)
+     */
+    get versionGroupId(): number;
+    /**
+     * Get the Zcash expiry height
+     * @returns The expiry height (0 if not set)
+     */
+    get expiryHeight(): number;
+}

package/dist/esm/js/fixedScriptWallet/ZcashBitGoPsbt.js

@@ -0,0 +1,110 @@
+import { BitGoPsbt as WasmBitGoPsbt } from "../wasm/wasm_utxo.js";
+import { RootWalletKeys } from "./RootWalletKeys.js";
+import { BitGoPsbt } from "./BitGoPsbt.js";
+/**
+ * Zcash-specific PSBT implementation
+ *
+ * This class extends BitGoPsbt with Zcash-specific functionality:
+ * - Required consensus branch ID for sighash computation
+ * - Version group ID for Zcash transaction format
+ * - Expiry height for transaction validity
+ *
+ * All Zcash-specific getters return non-optional types since they're
+ * guaranteed to be present for Zcash PSBTs.
+ *
+ * @example
+ * ```typescript
+ * // Create a new Zcash PSBT
+ * const psbt = ZcashBitGoPsbt.createEmpty("zcash", walletKeys, {
+ *   consensusBranchId: 0x76B809BB,  // Sapling
+ * });
+ *
+ * // Deserialize from bytes
+ * const psbt = ZcashBitGoPsbt.fromBytes(bytes, "zcash");
+ * ```
+ */
+export class ZcashBitGoPsbt extends BitGoPsbt {
+    /**
+     * Create an empty Zcash PSBT with consensus branch ID determined from block height
+     *
+     * **This is the preferred method for creating Zcash PSBTs.** It automatically determines
+     * the correct consensus branch ID based on the network and block height using Zcash
+     * network upgrade activation heights, eliminating the need to manually look up branch IDs.
+     *
+     * @param network - Zcash network name ("zcash", "zcashTest", "zec", "tzec")
+     * @param walletKeys - The wallet's root keys (sets global xpubs in the PSBT)
+     * @param options - Options including blockHeight to determine consensus rules
+     * @returns A new ZcashBitGoPsbt instance
+     * @throws Error if block height is before Overwinter activation
+     *
+     * @example
+     * ```typescript
+     * // Create PSBT for a specific block height (recommended)
+     * const psbt = ZcashBitGoPsbt.createEmpty("zcash", walletKeys, {
+     *   blockHeight: 1687104,  // Automatically uses Nu5 branch ID
+     * });
+     *
+     * // Create PSBT for current block height
+     * const currentHeight = await getBlockHeight();
+     * const psbt = ZcashBitGoPsbt.createEmpty("zcash", walletKeys, {
+     *   blockHeight: currentHeight,
+     * });
+     * ```
+     */
+    static createEmpty(network, walletKeys, options) {
+        const keys = RootWalletKeys.from(walletKeys);
+        const wasm = WasmBitGoPsbt.create_empty_zcash_at_height(network, keys.wasm, options.blockHeight, options.version, options.lockTime, options.versionGroupId, options.expiryHeight);
+        return new ZcashBitGoPsbt(wasm);
+    }
+    /**
+     * Create an empty Zcash PSBT with explicit consensus branch ID
+     *
+     * **Advanced use only.** This method requires manually specifying the consensus branch ID.
+     * In most cases, you should use `createEmpty()` instead, which automatically determines
+     * the correct branch ID from the block height.
+     *
+     * @param network - Zcash network name ("zcash", "zcashTest", "zec", "tzec")
+     * @param walletKeys - The wallet's root keys (sets global xpubs in the PSBT)
+     * @param options - Zcash-specific options including required consensusBranchId
+     * @returns A new ZcashBitGoPsbt instance
+     *
+     * @example
+     * ```typescript
+     * // Only use this if you need explicit control over the branch ID
+     * const psbt = ZcashBitGoPsbt.createEmptyWithConsensusBranchId("zcash", walletKeys, {
+     *   consensusBranchId: 0xC2D6D0B4,  // Nu5 branch ID
+     * });
+     * ```
+     */
+    static createEmptyWithConsensusBranchId(network, walletKeys, options) {
+        const keys = RootWalletKeys.from(walletKeys);
+        const wasm = WasmBitGoPsbt.create_empty_zcash(network, keys.wasm, options.consensusBranchId, options.version, options.lockTime, options.versionGroupId, options.expiryHeight);
+        return new ZcashBitGoPsbt(wasm);
+    }
+    /**
+     * Deserialize a Zcash PSBT from bytes
+     *
+     * @param bytes - The PSBT bytes
+     * @param network - Zcash network name ("zcash", "zcashTest", "zec", "tzec")
+     * @returns A ZcashBitGoPsbt instance
+     */
+    static fromBytes(bytes, network) {
+        const wasm = WasmBitGoPsbt.from_bytes(bytes, network);
+        return new ZcashBitGoPsbt(wasm);
+    }
+    // --- Zcash-specific getters ---
+    /**
+     * Get the Zcash version group ID
+     * @returns The version group ID (e.g., 0x892F2085 for Sapling)
+     */
+    get versionGroupId() {
+        return this.wasm.version_group_id();
+    }
+    /**
+     * Get the Zcash expiry height
+     * @returns The expiry height (0 if not set)
+     */
+    get expiryHeight() {
+        return this.wasm.expiry_height();
+    }
+}

package/dist/esm/js/fixedScriptWallet/index.d.ts

@@ -1,4 +1,5 @@
 export { RootWalletKeys, type WalletKeysArg, type IWalletKeys } from "./RootWalletKeys.js";
 export { ReplayProtection, type ReplayProtectionArg } from "./ReplayProtection.js";
 export { outputScript, address } from "./address.js";
-export { BitGoPsbt, type NetworkName, type ScriptId, type InputScriptType, type ParsedInput, type ParsedOutput, type ParsedTransaction, type SignPath, } from "./BitGoPsbt.js";
+export { BitGoPsbt, type NetworkName, type ScriptId, type InputScriptType, type ParsedInput, type ParsedOutput, type ParsedTransaction, type SignPath, type CreateEmptyOptions, type AddInputOptions, type AddOutputOptions, type AddWalletInputOptions, type AddWalletOutputOptions, } from "./BitGoPsbt.js";
+export { ZcashBitGoPsbt, type ZcashNetworkName, type CreateEmptyZcashOptions, } from "./ZcashBitGoPsbt.js";

package/dist/esm/js/fixedScriptWallet/index.js

@@ -1,4 +1,7 @@
 export { RootWalletKeys } from "./RootWalletKeys.js";
 export { ReplayProtection } from "./ReplayProtection.js";
 export { outputScript, address } from "./address.js";
+// Bitcoin-like PSBT (for all non-Zcash networks)
 export { BitGoPsbt, } from "./BitGoPsbt.js";
+// Zcash-specific PSBT subclass
+export { ZcashBitGoPsbt, } from "./ZcashBitGoPsbt.js";

package/dist/esm/js/index.d.ts

@@ -39,3 +39,4 @@ declare module "./wasm/wasm_utxo.js" {
 export { WrapDescriptor as Descriptor } from "./wasm/wasm_utxo.js";
 export { WrapMiniscript as Miniscript } from "./wasm/wasm_utxo.js";
 export { WrapPsbt as Psbt } from "./wasm/wasm_utxo.js";
+export { DashTransaction, Transaction, ZcashTransaction } from "./transaction.js";

package/dist/esm/js/index.js

@@ -16,3 +16,4 @@ export { BIP32 } from "./bip32.js";
 export { WrapDescriptor as Descriptor } from "./wasm/wasm_utxo.js";
 export { WrapMiniscript as Miniscript } from "./wasm/wasm_utxo.js";
 export { WrapPsbt as Psbt } from "./wasm/wasm_utxo.js";
+export { DashTransaction, Transaction, ZcashTransaction } from "./transaction.js";

package/dist/esm/js/transaction.d.ts

@@ -0,0 +1,46 @@
+import { WasmDashTransaction, WasmTransaction, WasmZcashTransaction } from "./wasm/wasm_utxo.js";
+/**
+ * Transaction wrapper (Bitcoin-like networks)
+ *
+ * Provides a camelCase, strongly-typed API over the snake_case WASM bindings.
+ */
+export declare class Transaction {
+    private _wasm;
+    private constructor();
+    static fromBytes(bytes: Uint8Array): Transaction;
+    toBytes(): Uint8Array;
+    /**
+     * @internal
+     */
+    get wasm(): WasmTransaction;
+}
+/**
+ * Zcash Transaction wrapper
+ *
+ * Provides a camelCase, strongly-typed API over the snake_case WASM bindings.
+ */
+export declare class ZcashTransaction {
+    private _wasm;
+    private constructor();
+    static fromBytes(bytes: Uint8Array): ZcashTransaction;
+    toBytes(): Uint8Array;
+    /**
+     * @internal
+     */
+    get wasm(): WasmZcashTransaction;
+}
+/**
+ * Dash Transaction wrapper (supports EVO special transactions)
+ *
+ * Round-trip only: bytes -> parse -> bytes.
+ */
+export declare class DashTransaction {
+    private _wasm;
+    private constructor();
+    static fromBytes(bytes: Uint8Array): DashTransaction;
+    toBytes(): Uint8Array;
+    /**
+     * @internal
+     */
+    get wasm(): WasmDashTransaction;
+}

package/dist/esm/js/transaction.js

@@ -0,0 +1,70 @@
+import { WasmDashTransaction, WasmTransaction, WasmZcashTransaction } from "./wasm/wasm_utxo.js";
+/**
+ * Transaction wrapper (Bitcoin-like networks)
+ *
+ * Provides a camelCase, strongly-typed API over the snake_case WASM bindings.
+ */
+export class Transaction {
+    _wasm;
+    constructor(_wasm) {
+        this._wasm = _wasm;
+    }
+    static fromBytes(bytes) {
+        return new Transaction(WasmTransaction.from_bytes(bytes));
+    }
+    toBytes() {
+        return this._wasm.to_bytes();
+    }
+    /**
+     * @internal
+     */
+    get wasm() {
+        return this._wasm;
+    }
+}
+/**
+ * Zcash Transaction wrapper
+ *
+ * Provides a camelCase, strongly-typed API over the snake_case WASM bindings.
+ */
+export class ZcashTransaction {
+    _wasm;
+    constructor(_wasm) {
+        this._wasm = _wasm;
+    }
+    static fromBytes(bytes) {
+        return new ZcashTransaction(WasmZcashTransaction.from_bytes(bytes));
+    }
+    toBytes() {
+        return this._wasm.to_bytes();
+    }
+    /**
+     * @internal
+     */
+    get wasm() {
+        return this._wasm;
+    }
+}
+/**
+ * Dash Transaction wrapper (supports EVO special transactions)
+ *
+ * Round-trip only: bytes -> parse -> bytes.
+ */
+export class DashTransaction {
+    _wasm;
+    constructor(_wasm) {
+        this._wasm = _wasm;
+    }
+    static fromBytes(bytes) {
+        return new DashTransaction(WasmDashTransaction.from_bytes(bytes));
+    }
+    toBytes() {
+        return this._wasm.to_bytes();
+    }
+    /**
+     * @internal
+     */
+    get wasm() {
+        return this._wasm;
+    }
+}

package/dist/esm/js/wasm/wasm_utxo.d.ts

@@ -38,6 +38,10 @@ export class BitGoPsbt {
    * * `lock_time` - Optional lock time (default: 0)
    */
   static create_empty(network: string, wallet_keys: WasmRootWalletKeys, version?: number | null, lock_time?: number | null): BitGoPsbt;
+  /**
+   * Get the Zcash expiry height (returns None for non-Zcash PSBTs)
+   */
+  expiry_height(): number | undefined;
   /**
    * Get the unsigned transaction ID
    */
@@ -84,6 +88,10 @@ export class BitGoPsbt {
    * The index of the newly added input
    */
   add_wallet_input(txid: string, vout: number, value: bigint, wallet_keys: WasmRootWalletKeys, chain: number, index: number, signer?: string | null, cosigner?: string | null, sequence?: number | null, prev_tx?: Uint8Array | null): number;
+  /**
+   * Get the Zcash version group ID (returns None for non-Zcash PSBTs)
+   */
+  version_group_id(): number | undefined;
   /**
    * Add a wallet output with full PSBT metadata
    *
@@ -120,6 +128,22 @@ export class BitGoPsbt {
    * - `Err(WasmUtxoError)` if signing fails
    */
   sign_with_privkey(input_index: number, ecpair: WasmECPair): void;
+  /**
+   * Create an empty Zcash PSBT with the required consensus branch ID
+   *
+   * This method is specifically for Zcash networks which require additional
+   * parameters for sighash computation.
+   *
+   * # Arguments
+   * * `network` - Network name (must be "zcash" or "zcashTest")
+   * * `wallet_keys` - The wallet's root keys (used to set global xpubs)
+   * * `consensus_branch_id` - Zcash consensus branch ID (e.g., 0xC2D6D0B4 for NU5)
+   * * `version` - Optional transaction version (default: 4 for Zcash Sapling+)
+   * * `lock_time` - Optional lock time (default: 0)
+   * * `version_group_id` - Optional version group ID (defaults to Sapling: 0x892F2085)
+   * * `expiry_height` - Optional expiry height
+   */
+  static create_empty_zcash(network: string, wallet_keys: WasmRootWalletKeys, consensus_branch_id: number, version?: number | null, lock_time?: number | null, version_group_id?: number | null, expiry_height?: number | null): BitGoPsbt;
   /**
    * Extract the final transaction from a finalized PSBT
    *
@@ -257,6 +281,25 @@ export class BitGoPsbt {
    * The index of the newly added input
    */
   add_replay_protection_input(ecpair: WasmECPair, txid: string, vout: number, value: bigint, sequence?: number | null): number;
+  /**
+   * Create an empty Zcash PSBT with consensus branch ID determined from block height
+   *
+   * This method automatically determines the correct consensus branch ID based on
+   * the network and block height using the network upgrade activation heights.
+   *
+   * # Arguments
+   * * `network` - Network name (must be "zcash" or "zcashTest")
+   * * `wallet_keys` - The wallet's root keys (used to set global xpubs)
+   * * `block_height` - Block height to determine consensus rules
+   * * `version` - Optional transaction version (default: 4 for Zcash Sapling+)
+   * * `lock_time` - Optional lock time (default: 0)
+   * * `version_group_id` - Optional version group ID (defaults to Sapling: 0x892F2085)
+   * * `expiry_height` - Optional expiry height
+   *
+   * # Errors
+   * Returns error if block height is before Overwinter activation
+   */
+  static create_empty_zcash_at_height(network: string, wallet_keys: WasmRootWalletKeys, block_height: number, version?: number | null, lock_time?: number | null, version_group_id?: number | null, expiry_height?: number | null): BitGoPsbt;
   /**
    * Parse outputs with wallet keys to identify which outputs belong to a wallet
    *
@@ -445,6 +488,20 @@ export class WasmBIP32 {
   readonly index: number;
 }
 
+export class WasmDashTransaction {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Deserialize a Dash transaction from bytes (supports EVO special tx extra payload).
+   */
+  static from_bytes(bytes: Uint8Array): WasmDashTransaction;
+  /**
+   * Serialize the Dash transaction to bytes (preserving tx_type and extra payload).
+   */
+  to_bytes(): Uint8Array;
+}
+
 export class WasmECPair {
   private constructor();
   free(): void;
@@ -548,6 +605,58 @@ export class WasmRootWalletKeys {
   bitgo_key(): WasmBIP32;
 }
 
+export class WasmTransaction {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Deserialize a transaction from bytes
+   *
+   * # Arguments
+   * * `bytes` - The serialized transaction bytes
+   *
+   * # Returns
+   * A WasmTransaction instance
+   *
+   * # Errors
+   * Returns an error if the bytes cannot be parsed as a valid transaction
+   */
+  static from_bytes(bytes: Uint8Array): WasmTransaction;
+  /**
+   * Serialize the transaction to bytes
+   *
+   * # Returns
+   * The serialized transaction bytes
+   */
+  to_bytes(): Uint8Array;
+}
+
+export class WasmZcashTransaction {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Deserialize a Zcash transaction from bytes
+   *
+   * # Arguments
+   * * `bytes` - The serialized transaction bytes
+   *
+   * # Returns
+   * A WasmZcashTransaction instance
+   *
+   * # Errors
+   * Returns an error if the bytes cannot be parsed as a valid Zcash transaction
+   */
+  static from_bytes(bytes: Uint8Array): WasmZcashTransaction;
+  /**
+   * Serialize the transaction to bytes
+   *
+   * # Returns
+   * The serialized transaction bytes
+   */
+  to_bytes(): Uint8Array;
+}
+
 export class WrapDescriptor {
   private constructor();
   free(): void;