@bitgo/wasm-utxo 1.14.1 → 1.16.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, } 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/wasm/wasm_utxo.d.ts

@@ -13,10 +13,35 @@ export class BitGoPsbt {
   private constructor();
   free(): void;
   [Symbol.dispose](): void;
+  /**
+   * Add an output to the PSBT
+   *
+   * # Arguments
+   * * `script` - The output script (scriptPubKey)
+   * * `value` - The value in satoshis
+   *
+   * # Returns
+   * The index of the newly added output
+   */
+  add_output(script: Uint8Array, value: bigint): number;
   /**
    * Deserialize a PSBT from bytes with network-specific logic
    */
   static from_bytes(bytes: Uint8Array, network: string): BitGoPsbt;
+  /**
+   * Create an empty PSBT for the given network with wallet keys
+   *
+   * # Arguments
+   * * `network` - Network name (utxolib or coin name)
+   * * `wallet_keys` - The wallet's root keys (used to set global xpubs)
+   * * `version` - Optional transaction version (default: 2)
+   * * `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
    */
@@ -41,6 +66,48 @@ export class BitGoPsbt {
    * - `Err(WasmUtxoError)` if signing fails
    */
   sign_with_xpriv(input_index: number, xpriv: WasmBIP32): void;
+  /**
+   * Add a wallet input with full PSBT metadata
+   *
+   * This is a higher-level method that adds an input and populates all required
+   * PSBT fields (scripts, derivation info, etc.) based on the wallet's chain type.
+   *
+   * # Arguments
+   * * `txid` - The transaction ID (hex string)
+   * * `vout` - The output index being spent
+   * * `value` - The value in satoshis
+   * * `chain` - The chain code (0/1=p2sh, 10/11=p2shP2wsh, 20/21=p2wsh, 30/31=p2tr, 40/41=p2trMusig2)
+   * * `index` - The derivation index
+   * * `wallet_keys` - The root wallet keys
+   * * `signer` - The key that will sign ("user", "backup", or "bitgo") - required for p2tr/p2trMusig2
+   * * `cosigner` - The key that will co-sign - required for p2tr/p2trMusig2
+   * * `sequence` - Optional sequence number (default: 0xFFFFFFFE for RBF)
+   * * `prev_tx` - Optional full previous transaction bytes (for non-segwit)
+   *
+   * # Returns
+   * 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
+   *
+   * This creates a verifiable wallet output (typically for change) with all required
+   * PSBT fields (scripts, derivation info) based on the wallet's chain type.
+   *
+   * # Arguments
+   * * `chain` - The chain code (0/1=p2sh, 10/11=p2shP2wsh, 20/21=p2wsh, 30/31=p2tr, 40/41=p2trMusig2)
+   * * `index` - The derivation index
+   * * `value` - The value in satoshis
+   * * `wallet_keys` - The root wallet keys
+   *
+   * # Returns
+   * The index of the newly added output
+   */
+  add_wallet_output(chain: number, index: number, value: bigint, wallet_keys: WasmRootWalletKeys): number;
   /**
    * Sign a single input with a raw private key
    *
@@ -61,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
    *
@@ -181,6 +264,42 @@ export class BitGoPsbt {
    * - `Err(WasmUtxoError)` if the input index is out of bounds, derivation fails, or verification fails
    */
   verify_signature_with_xpub(input_index: number, xpub: WasmBIP32): boolean;
+  /**
+   * Add a replay protection input to the PSBT
+   *
+   * Replay protection inputs are P2SH-P2PK inputs used on forked networks to prevent
+   * transaction replay attacks. They use a simple pubkey script without wallet derivation.
+   *
+   * # Arguments
+   * * `ecpair` - The ECPair containing the public key for the replay protection input
+   * * `txid` - The transaction ID (hex string) of the output being spent
+   * * `vout` - The output index being spent
+   * * `value` - The value in satoshis
+   * * `sequence` - Optional sequence number (default: 0xFFFFFFFE for RBF)
+   *
+   * # Returns
+   * 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
    *
@@ -213,6 +332,28 @@ export class BitGoPsbt {
    * Get the network of the PSBT
    */
   network(): string;
+  /**
+   * Get the transaction version
+   */
+  version(): number;
+  /**
+   * Add an input to the PSBT
+   *
+   * # Arguments
+   * * `txid` - The transaction ID (hex string) of the output being spent
+   * * `vout` - The output index being spent
+   * * `value` - The value in satoshis of the output being spent
+   * * `script` - The output script (scriptPubKey) of the output being spent
+   * * `sequence` - Optional sequence number (default: 0xFFFFFFFE for RBF)
+   *
+   * # Returns
+   * The index of the newly added input
+   */
+  add_input(txid: string, vout: number, value: bigint, script: Uint8Array, sequence?: number | null, prev_tx?: Uint8Array | null): number;
+  /**
+   * Get the transaction lock time
+   */
+  lock_time(): number;
   /**
    * Serialize the PSBT to bytes
    *