@bitgo/wasm-utxo 4.40.0 → 5.0.0

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

@@ -1,3 +1,4 @@
+import { WasmDimensions } from "../wasm/wasm_utxo.js";
 import type { BitGoPsbt, InputScriptType, SignPath } from "./BitGoPsbt.js";
 import type { CoinName } from "../coinName.js";
 import type { OutputScriptType } from "./scriptType.js";
@@ -17,16 +18,6 @@ export type FromInputOptions = {
      */
     utxolibCompat?: boolean;
 };
-/**
- * Options for output dimension calculation
- */
-export type FromOutputOptions = {
-    /**
-     * Set when `address` may be a ZIP-316 Unified Address whose Orchard receiver should be sized
-     * as a shielded output. Forwarded to `toOutputScriptWithCoin`'s `canBeShieldedOutput`.
-     */
-    isShielded?: boolean;
-};
 /**
  * Dimensions class for estimating transaction virtual size.
  *
@@ -37,7 +28,7 @@ export type FromOutputOptions = {
  */
 export declare class Dimensions {
     private _wasm;
-    private constructor();
+    protected constructor(_wasm: WasmDimensions);
     /**
      * Create empty dimensions (zero weight)
      */
@@ -62,12 +53,10 @@ export declare class Dimensions {
      */
     static fromOutput(script: Uint8Array): Dimensions;
     /**
-     * Create dimensions for a single output from an address.
-     *
-     * Pass `{ isShielded: true }` when `address` may be a ZIP-316 Unified Address whose Orchard
-     * receiver should be sized as a shielded output
+     * Create dimensions for a single output from an address, decoded as an ordinary transparent
+     * address for `network`.
      */
-    static fromOutput(address: string, network: CoinName, options?: FromOutputOptions): Dimensions;
+    static fromOutput(address: string, network: CoinName): Dimensions;
     /**
      * Create dimensions for a single output from script length only
      */

package/dist/esm/js/fixedScriptWallet/Dimensions.js

@@ -42,12 +42,12 @@ export class Dimensions {
         }
         return new Dimensions(WasmDimensions.from_input(params.chain, params.signPath?.signer, params.signPath?.cosigner, compat));
     }
-    static fromOutput(params, network, options) {
+    static fromOutput(params, network) {
         if (typeof params === "string") {
             if (network === undefined) {
                 throw new Error("network is required when passing an address string");
             }
-            const script = toOutputScriptWithCoin(params, network, options?.isShielded);
+            const script = toOutputScriptWithCoin(params, network);
             return new Dimensions(WasmDimensions.from_output_script_length(script.length));
         }
         if (typeof params === "object" && "scriptType" in params) {

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

@@ -0,0 +1,45 @@
+import type { CoinName } from "../coinName.js";
+import type { OutputScriptType } from "./scriptType.js";
+import { Dimensions } from "./Dimensions.js";
+/**
+ * Options for {@link ZcashDimensions.fromOutput}.
+ */
+export type ZcashFromOutputOptions = {
+    /**
+     * Set when `address` may be a ZIP-316 Unified Address whose Orchard receiver should be sized
+     * as a shielded output. Forwarded to `zcashAddress.toShieldedReceiverWithCoin`; when unset,
+     * `zcashAddress.toTransparentReceiverWithCoin` is used instead.
+     */
+    isShielded?: boolean;
+};
+/**
+ * Zcash-specific dimensions: resolves ZIP-316 Unified Addresses (transparent or Orchard/Ironwood
+ * shielded receiver) instead of the plain transparent-only decoding {@link Dimensions.fromOutput}
+ * does for every other coin.
+ */
+export declare class ZcashDimensions extends Dimensions {
+    /**
+     * Create dimensions for a single output from script bytes
+     */
+    static fromOutput(script: Uint8Array): Dimensions;
+    /**
+     * Create dimensions for a single output from a Zcash address for `network`.
+     *
+     * Pass `{ isShielded: true }` when `address` may be a ZIP-316 Unified Address whose Orchard
+     * receiver should be sized as a shielded output; otherwise its transparent receiver is
+     * resolved (a UA with no transparent receiver throws rather than falling back to Orchard).
+     */
+    static fromOutput(address: string, network: CoinName, options?: ZcashFromOutputOptions): Dimensions;
+    /**
+     * Create dimensions for a single output from script length only
+     */
+    static fromOutput(params: {
+        length: number;
+    }): Dimensions;
+    /**
+     * Create dimensions for a single output from script type
+     */
+    static fromOutput(params: {
+        scriptType: OutputScriptType;
+    }): Dimensions;
+}

package/dist/esm/js/fixedScriptWallet/ZcashDimensions.js

@@ -0,0 +1,26 @@
+import { WasmDimensions } from "../wasm/wasm_utxo.js";
+import { toShieldedReceiverWithCoin, toTransparentReceiverWithCoin } from "../zcashAddress.js";
+import { Dimensions } from "./Dimensions.js";
+/**
+ * Zcash-specific dimensions: resolves ZIP-316 Unified Addresses (transparent or Orchard/Ironwood
+ * shielded receiver) instead of the plain transparent-only decoding {@link Dimensions.fromOutput}
+ * does for every other coin.
+ */
+export class ZcashDimensions extends Dimensions {
+    static fromOutput(params, network, options) {
+        if (typeof params === "string") {
+            if (network === undefined) {
+                throw new Error("network is required when passing an address string");
+            }
+            const receiver = options?.isShielded
+                ? toShieldedReceiverWithCoin(params, network)
+                : toTransparentReceiverWithCoin(params, network);
+            return new ZcashDimensions(WasmDimensions.from_output_script_length(receiver.length));
+        }
+        if (typeof params === "object" && "scriptType" in params) {
+            return Dimensions.fromOutput(params);
+        }
+        // Both Uint8Array and { length: number } have .length
+        return Dimensions.fromOutput(params);
+    }
+}

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

@@ -0,0 +1,31 @@
+import { IronwoodWitness as WasmIronwoodWitness } 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 declare class ZcashIronwoodWitness {
+    private _wasm;
+    private constructor();
+    /**
+     * 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;
+    /** The leaf's position in the note commitment tree. */
+    get position(): number;
+    /**
+     * The 32 sibling hashes (leaf-to-root order), flattened into a single 1024-byte array
+     * (32 hashes × 32 bytes each).
+     */
+    get authPath(): Uint8Array;
+    /** @internal */
+    get wasm(): WasmIronwoodWitness;
+}

package/dist/esm/js/fixedScriptWallet/ZcashIronwoodWitness.js

@@ -0,0 +1,41 @@
+import { 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 {
+    _wasm;
+    constructor(_wasm) {
+        this._wasm = _wasm;
+    }
+    /**
+     * 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, position, authPath, anchor) {
+        return new ZcashIronwoodWitness(ironwood_build_witness(cmx, position, authPath, anchor));
+    }
+    /** The leaf's position in the note commitment tree. */
+    get position() {
+        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() {
+        return this._wasm.auth_path;
+    }
+    /** @internal */
+    get wasm() {
+        return this._wasm;
+    }
+}

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

@@ -15,6 +15,8 @@ import type { ZcashNetworkName } from "./ZcashBitGoPsbt.js";
  * const ua = ZcashUnifiedAddress.parse(uaString, "zec");
  * const ironwood = ua.orchardReceiver;      // 43 bytes, or undefined
  * const script = ua.transparentScript;      // scriptPubKey bytes, or undefined
+ * ua.hasOrchardReceiver;                    // true iff orchardReceiver is present
+ * ua.hasTransparentReceiver;                // true iff transparentScript is present
  * ua.contains(transparentAddress);          // is it one of this UA's receivers?
  * ```
  */
@@ -43,6 +45,20 @@ export declare class ZcashUnifiedAddress {
      * a `TxOut.scriptPubKey`, or `undefined` if the UA has no transparent receiver.
      */
     get transparentScript(): Uint8Array | undefined;
+    /**
+     * Whether this Unified Address carries an Orchard/Ironwood receiver.
+     *
+     * Equivalent to `orchardReceiver !== undefined`; prefer this when only presence
+     * matters, since it avoids copying the receiver bytes.
+     */
+    get hasOrchardReceiver(): boolean;
+    /**
+     * Whether this Unified Address carries a transparent (P2PKH/P2SH) receiver.
+     *
+     * Equivalent to `transparentScript !== undefined`; prefer this when only presence
+     * matters, since it avoids copying the script bytes.
+     */
+    get hasTransparentReceiver(): boolean;
     /**
      * Whether `candidate` is a receiver of this unified address.
      *

package/dist/esm/js/fixedScriptWallet/ZcashUnifiedAddress.js

@@ -14,6 +14,8 @@ import { ZcashUnifiedAddress as WasmZcashUnifiedAddress } from "../wasm/wasm_utx
  * const ua = ZcashUnifiedAddress.parse(uaString, "zec");
  * const ironwood = ua.orchardReceiver;      // 43 bytes, or undefined
  * const script = ua.transparentScript;      // scriptPubKey bytes, or undefined
+ * ua.hasOrchardReceiver;                    // true iff orchardReceiver is present
+ * ua.hasTransparentReceiver;                // true iff transparentScript is present
  * ua.contains(transparentAddress);          // is it one of this UA's receivers?
  * ```
  */
@@ -52,6 +54,24 @@ export class ZcashUnifiedAddress {
     get transparentScript() {
         return this._wasm.transparentScript;
     }
+    /**
+     * Whether this Unified Address carries an Orchard/Ironwood receiver.
+     *
+     * Equivalent to `orchardReceiver !== undefined`; prefer this when only presence
+     * matters, since it avoids copying the receiver bytes.
+     */
+    get hasOrchardReceiver() {
+        return this._wasm.hasOrchardReceiver;
+    }
+    /**
+     * Whether this Unified Address carries a transparent (P2PKH/P2SH) receiver.
+     *
+     * Equivalent to `transparentScript !== undefined`; prefer this when only presence
+     * matters, since it avoids copying the script bytes.
+     */
+    get hasTransparentReceiver() {
+        return this._wasm.hasTransparentReceiver;
+    }
     /**
      * Whether `candidate` is a receiver of this unified address.
      *

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

@@ -12,6 +12,7 @@ export { ZcashBitGoPsbt, type ZcashNetworkName, type ZcashParsedOutput, type Cre
 export { ZcashIronwoodBitGoPsbt, zip302NoMemo, type CreateEmptyIronwoodOptions, type CreateEmptyIronwoodWithConsensusBranchIdOptions, } from "./ZcashIronwoodBitGoPsbt.js";
 export { ZcashUnifiedAddress } from "./ZcashUnifiedAddress.js";
 export { ZcashV6Transaction } from "./ZcashV6Transaction.js";
+export { ZcashIronwoodWitness } from "./ZcashIronwoodWitness.js";
 import type { ScriptType } from "./scriptType.js";
 /**
  * Check if a network supports a given fixed-script wallet script type

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

@@ -18,6 +18,8 @@ export { ZcashIronwoodBitGoPsbt, zip302NoMemo, } from "./ZcashIronwoodBitGoPsbt.
 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";
 /**
  * Check if a network supports a given fixed-script wallet script type
  *

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

@@ -1,4 +1,5 @@
 export * as address from "./address.js";
+export * as zcashAddress from "./zcashAddress.js";
 export * as ast from "./ast/index.js";
 export * as bip322 from "./bip322/index.js";
 export * as inscriptions from "./inscriptions.js";
@@ -11,6 +12,7 @@ export * as ecpair from "./ecpair.js";
 export { ECPair } from "./ecpair.js";
 export { BIP32 } from "./bip32.js";
 export { Dimensions } from "./fixedScriptWallet/Dimensions.js";
+export { ZcashDimensions } from "./fixedScriptWallet/ZcashDimensions.js";
 export type WasmUtxoVersionInfo = {
     version: string;
     gitHash: string;

package/dist/esm/js/index.js

@@ -6,6 +6,7 @@ void wasm;
 // Most exports are namespaced to avoid polluting the top-level namespace
 // and to make imports more explicit (e.g., `import { address } from '@bitgo/wasm-utxo'`)
 export * as address from "./address.js";
+export * as zcashAddress from "./zcashAddress.js";
 export * as ast from "./ast/index.js";
 export * as bip322 from "./bip322/index.js";
 export * as inscriptions from "./inscriptions.js";
@@ -19,6 +20,7 @@ export * as ecpair from "./ecpair.js";
 export { ECPair } from "./ecpair.js";
 export { BIP32 } from "./bip32.js";
 export { Dimensions } from "./fixedScriptWallet/Dimensions.js";
+export { ZcashDimensions } from "./fixedScriptWallet/ZcashDimensions.js";
 export function getWasmUtxoVersion() {
     return WasmUtxoNamespace.get_wasm_utxo_version();
 }

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

@@ -7,12 +7,9 @@ export class AddressNamespace {
     [Symbol.dispose](): void;
     static from_output_script_with_coin(script: Uint8Array, coin: string, format?: string | null): string;
     /**
-     * `can_be_shielded_output`: when set and `address` is a ZIP-316 unified address carrying an
-     * Orchard/Ironwood receiver, returns that raw 43-byte receiver instead of a transparent
-     * scriptPubKey. See [`to_output_script_or_shielded_receiver_with_coin`] for the exact
-     * fallback/error rules.
+     * Convert `address` to its scriptPubKey bytes for `coin`.
      */
-    static to_output_script_with_coin(address: string, coin: string, can_be_shielded_output?: boolean | null): Uint8Array;
+    static to_output_script_with_coin(address: string, coin: string): Uint8Array;
 }
 
 /**
@@ -984,6 +981,27 @@ export class InscriptionsNamespace {
     static sign_reveal_transaction(private_key: Uint8Array, tap_leaf_script: any, commit_tx: WasmTransaction, commit_output_script: Uint8Array, recipient_output_script: Uint8Array, output_value_sats: bigint): Uint8Array;
 }
 
+/**
+ * A validated Merkle witness for an Ironwood/Orchard note commitment, from
+ * [`ironwood_build_witness`].
+ *
+ * Not yet installed anywhere — see [`ironwood_build_witness`]'s docs.
+ */
+export class IronwoodWitness {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The 32 sibling hashes (leaf-to-root order), flattened into a single 1024-byte array
+     * (32 hashes × 32 bytes each).
+     */
+    readonly auth_path: Uint8Array;
+    /**
+     * The leaf's position in the note commitment tree.
+     */
+    readonly position: number;
+}
+
 export class MessageNamespace {
     private constructor();
     free(): void;
@@ -1777,6 +1795,20 @@ export class ZcashUnifiedAddress {
      * below are infallible. Throws if the address is malformed or on the wrong network.
      */
     static parse(address: string, network: string): ZcashUnifiedAddress;
+    /**
+     * Whether this Unified Address carries an Orchard/Ironwood receiver.
+     *
+     * Equivalent to `orchardReceiver !== undefined`, without cloning the receiver bytes
+     * when the caller only needs presence.
+     */
+    readonly hasOrchardReceiver: boolean;
+    /**
+     * Whether this Unified Address carries a transparent (P2PKH/P2SH) receiver.
+     *
+     * Equivalent to `transparentScript !== undefined`, without cloning the script bytes
+     * when the caller only needs presence.
+     */
+    readonly hasTransparentReceiver: boolean;
     /**
      * The Orchard/Ironwood receiver's raw 43 bytes (diversifier + pk_d), or `undefined`.
      */
@@ -1861,6 +1893,19 @@ export class ZcashV6Transaction {
     readonly ironwoodValueBalance: bigint;
 }
 
+/**
+ * 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.
+ */
+export function ironwood_build_witness(cmx: Uint8Array, position: number, auth_path: Uint8Array[], anchor: Uint8Array): IronwoodWitness;
+
 /**
  * Check if the inspect feature is enabled.
  *
@@ -1932,6 +1977,43 @@ export function parsePsbtToJson(psbt_bytes: Uint8Array, coin_name: string): stri
  */
 export function parseTxToJson(tx_bytes: Uint8Array, coin_name: string): string;
 
+/**
+ * Whether `address` is a ZIP-316 unified address for `coin`'s network carrying an
+ * Orchard/Ironwood receiver. `false` (never throws) for a malformed/wrong-network unified
+ * address, an ordinary address, or a UA with no Orchard/Ironwood receiver.
+ */
+export function zcashHasOrchardReceiver(address: string, coin: string): boolean;
+
+/**
+ * Whether `address` has a usable transparent receiver for `coin`'s network: either it's a
+ * unified address carrying a transparent receiver, or it's itself a valid transparent address
+ * for `coin`. `false` (never throws) otherwise.
+ */
+export function zcashHasTransparentReceiver(address: string, coin: string): boolean;
+
+export function zcashToShieldedReceiverWithCoin(address: string, coin: string): Uint8Array;
+
+/**
+ * Resolve the Orchard/Ironwood receiver of a ZIP-316 unified address for `coin`'s network, as
+ * its raw 43 bytes (diversifier + `pk_d`) — there is no scriptPubKey for a shielded output, so
+ * this can't return script bytes uniformly and returns raw receiver bytes instead.
+ *
+ * A UA that has no Orchard/Ironwood receiver (e.g. Sapling-only) throws rather than falling back
+ * to the transparent receiver. If `address` merely looks like a unified address for this coin's
+ * network (right Bech32m HRP) but is malformed, this also throws. `address` must be a unified
+ * address — an ordinary transparent address is rejected, since it can never carry a shielded
+ * receiver; use {@link toOutputScriptWithCoin} in `js/address.ts` for the transparent case.
+ * Resolve the transparent receiver of an `address` for `coin`'s network, as its scriptPubKey
+ * bytes. When `address` is a ZIP-316 unified address, resolves its transparent receiver rather
+ * than rejecting the UA string outright — a UA with no transparent receiver (e.g. Orchard-only)
+ * throws rather than falling back to a shielded one. An ordinary (non-UA) address falls through
+ * to the same transparent codec path as any other coin.
+ *
+ * This is the zcash-aware counterpart of `toOutputScriptWithCoin` in `js/address.ts`, which
+ * dispatches here for zcash/tzec so that non-zcash coins never pay for a unified-address check.
+ */
+export function zcashToTransparentReceiverWithCoin(address: string, coin: string): Uint8Array;
+
 /**
  * Return the Zcash consensus branch ID active at `height` on `network`.
  *

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

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./wasm_utxo_bg.js";
 __wbg_set_wasm(wasm);
 
 export {
-    AddressNamespace, Bip322Namespace, BitGoPsbt, FixedScriptWalletNamespace, InscriptionsNamespace, MessageNamespace, UtxolibCompatNamespace, WasmBIP32, WasmDashTransaction, WasmDimensions, WasmECPair, WasmReplayProtection, WasmRootWalletKeys, WasmTransaction, WasmUtxoNamespace, WasmZcashTransaction, WrapDescriptor, WrapMiniscript, WrapPsbt, ZcashUnifiedAddress, ZcashV6Transaction, isInspectEnabled, parsePsbtRawToJson, parsePsbtToJson, parseTxToJson, zcash_branch_id_for_height, zcash_ironwood_version_group_id
+    AddressNamespace, Bip322Namespace, BitGoPsbt, FixedScriptWalletNamespace, InscriptionsNamespace, IronwoodWitness, MessageNamespace, UtxolibCompatNamespace, WasmBIP32, WasmDashTransaction, WasmDimensions, WasmECPair, WasmReplayProtection, WasmRootWalletKeys, WasmTransaction, WasmUtxoNamespace, WasmZcashTransaction, WrapDescriptor, WrapMiniscript, WrapPsbt, ZcashUnifiedAddress, ZcashV6Transaction, ironwood_build_witness, isInspectEnabled, parsePsbtRawToJson, parsePsbtToJson, parseTxToJson, zcashHasOrchardReceiver, zcashHasTransparentReceiver, zcashToShieldedReceiverWithCoin, zcashToTransparentReceiverWithCoin, zcash_branch_id_for_height, zcash_ironwood_version_group_id
 } from "./wasm_utxo_bg.js";