@bitgo/wasm-utxo 1.21.0 → 1.23.0

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

@@ -0,0 +1,56 @@
+import type { OutputScriptType } from "./scriptType.js";
+/** All valid chain codes as a const tuple */
+export declare const chainCodes: readonly [0, 1, 10, 11, 20, 21, 30, 31, 40, 41];
+/** A valid chain code value */
+export type ChainCode = (typeof chainCodes)[number];
+/** Whether a chain is for receiving (external) or change (internal) addresses */
+export type Scope = "internal" | "external";
+/**
+ * ChainCode namespace with utility functions for working with chain codes.
+ */
+export declare const ChainCode: {
+    /**
+     * Check if a value is a valid chain code.
+     *
+     * @example
+     * ```typescript
+     * if (ChainCode.is(maybeChain)) {
+     *   // maybeChain is now typed as ChainCode
+     *   const scope = ChainCode.scope(maybeChain);
+     * }
+     * ```
+     */
+    is(n: unknown): n is ChainCode;
+    /**
+     * Get the chain code for a script type and scope.
+     *
+     * @example
+     * ```typescript
+     * const externalP2wsh = ChainCode.value("p2wsh", "external"); // 20
+     * const internalP2tr = ChainCode.value("p2trLegacy", "internal"); // 31
+     * ```
+     */
+    value(scriptType: OutputScriptType | "p2tr", scope: Scope): ChainCode;
+    /**
+     * Get the scope (external/internal) for a chain code.
+     *
+     * @example
+     * ```typescript
+     * ChainCode.scope(0);  // "external"
+     * ChainCode.scope(1);  // "internal"
+     * ChainCode.scope(20); // "external"
+     * ```
+     */
+    scope(chainCode: ChainCode): Scope;
+    /**
+     * Get the script type for a chain code.
+     *
+     * @example
+     * ```typescript
+     * ChainCode.scriptType(0);  // "p2sh"
+     * ChainCode.scriptType(20); // "p2wsh"
+     * ChainCode.scriptType(40); // "p2trMusig2"
+     * ```
+     */
+    scriptType(chainCode: ChainCode): OutputScriptType;
+};

package/dist/esm/js/fixedScriptWallet/chains.js

@@ -0,0 +1,122 @@
+/**
+ * Chain code utilities for BitGo fixed-script wallets.
+ *
+ * Chain codes define the derivation path component for different script types
+ * and scopes (external/internal) in the format `m/0/0/{chain}/{index}`.
+ */
+import { FixedScriptWalletNamespace } from "../wasm/wasm_utxo.js";
+/** All valid chain codes as a const tuple */
+export const chainCodes = [0, 1, 10, 11, 20, 21, 30, 31, 40, 41];
+// Build static lookup tables once at module load time
+const chainCodeSet = new Set(chainCodes);
+const chainToMeta = new Map();
+const scriptTypeToChain = new Map();
+// Initialize from WASM (called once at load time)
+function assertChainCode(n) {
+    if (!chainCodeSet.has(n)) {
+        throw new Error(`Invalid chain code from WASM: ${n}`);
+    }
+    return n;
+}
+function assertScope(s) {
+    if (s !== "internal" && s !== "external") {
+        throw new Error(`Invalid scope from WASM: ${s}`);
+    }
+    return s;
+}
+for (const tuple of FixedScriptWalletNamespace.chain_code_table()) {
+    if (!Array.isArray(tuple) || tuple.length !== 3) {
+        throw new Error(`Invalid chain_code_table entry: expected [number, string, string]`);
+    }
+    const [rawCode, rawScriptType, rawScope] = tuple;
+    if (typeof rawCode !== "number") {
+        throw new Error(`Invalid chain code type: ${typeof rawCode}`);
+    }
+    if (typeof rawScriptType !== "string") {
+        throw new Error(`Invalid scriptType type: ${typeof rawScriptType}`);
+    }
+    if (typeof rawScope !== "string") {
+        throw new Error(`Invalid scope type: ${typeof rawScope}`);
+    }
+    const code = assertChainCode(rawCode);
+    const scriptType = rawScriptType;
+    const scope = assertScope(rawScope);
+    chainToMeta.set(code, { scope, scriptType });
+    let entry = scriptTypeToChain.get(scriptType);
+    if (!entry) {
+        entry = {};
+        scriptTypeToChain.set(scriptType, entry);
+    }
+    entry[scope] = code;
+}
+/**
+ * ChainCode namespace with utility functions for working with chain codes.
+ */
+export const ChainCode = {
+    /**
+     * Check if a value is a valid chain code.
+     *
+     * @example
+     * ```typescript
+     * if (ChainCode.is(maybeChain)) {
+     *   // maybeChain is now typed as ChainCode
+     *   const scope = ChainCode.scope(maybeChain);
+     * }
+     * ```
+     */
+    is(n) {
+        return typeof n === "number" && chainCodeSet.has(n);
+    },
+    /**
+     * Get the chain code for a script type and scope.
+     *
+     * @example
+     * ```typescript
+     * const externalP2wsh = ChainCode.value("p2wsh", "external"); // 20
+     * const internalP2tr = ChainCode.value("p2trLegacy", "internal"); // 31
+     * ```
+     */
+    value(scriptType, scope) {
+        // legacy alias for p2trLegacy
+        if (scriptType === "p2tr") {
+            scriptType = "p2trLegacy";
+        }
+        const entry = scriptTypeToChain.get(scriptType);
+        if (!entry) {
+            throw new Error(`Invalid scriptType: ${scriptType}`);
+        }
+        return entry[scope];
+    },
+    /**
+     * Get the scope (external/internal) for a chain code.
+     *
+     * @example
+     * ```typescript
+     * ChainCode.scope(0);  // "external"
+     * ChainCode.scope(1);  // "internal"
+     * ChainCode.scope(20); // "external"
+     * ```
+     */
+    scope(chainCode) {
+        const meta = chainToMeta.get(chainCode);
+        if (!meta)
+            throw new Error(`Invalid chainCode: ${chainCode}`);
+        return meta.scope;
+    },
+    /**
+     * Get the script type for a chain code.
+     *
+     * @example
+     * ```typescript
+     * ChainCode.scriptType(0);  // "p2sh"
+     * ChainCode.scriptType(20); // "p2wsh"
+     * ChainCode.scriptType(40); // "p2trMusig2"
+     * ```
+     */
+    scriptType(chainCode) {
+        const meta = chainToMeta.get(chainCode);
+        if (!meta)
+            throw new Error(`Invalid chainCode: ${chainCode}`);
+        return meta.scriptType;
+    },
+};

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

@@ -4,6 +4,7 @@ export { ReplayProtection, type ReplayProtectionArg } from "./ReplayProtection.j
 export { outputScript, address } from "./address.js";
 export { Dimensions } from "./Dimensions.js";
 export { type OutputScriptType, type InputScriptType, type ScriptType } from "./scriptType.js";
+export { ChainCode, chainCodes, type Scope } from "./chains.js";
 export { BitGoPsbt, type NetworkName, type ScriptId, 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";
 import type { ScriptType } from "./scriptType.js";

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

@@ -3,6 +3,7 @@ export { RootWalletKeys } from "./RootWalletKeys.js";
 export { ReplayProtection } from "./ReplayProtection.js";
 export { outputScript, address } from "./address.js";
 export { Dimensions } from "./Dimensions.js";
+export { ChainCode, chainCodes } from "./chains.js";
 // Bitcoin-like PSBT (for all non-Zcash networks)
 export { BitGoPsbt, } from "./BitGoPsbt.js";
 // Zcash-specific PSBT subclass

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

@@ -1,5 +1,6 @@
 export * as address from "./address.js";
 export * as ast from "./ast/index.js";
+export * as bip322 from "./bip322/index.js";
 export * as utxolibCompat from "./utxolibCompat.js";
 export * as fixedScriptWallet from "./fixedScriptWallet/index.js";
 export * as bip32 from "./bip32.js";

package/dist/esm/js/index.js

@@ -6,6 +6,7 @@ void wasm;
 // and to make imports more explicit (e.g., `import { address } from '@bitgo/wasm-utxo'`)
 export * as address from "./address.js";
 export * as ast from "./ast/index.js";
+export * as bip322 from "./bip322/index.js";
 export * as utxolibCompat from "./utxolibCompat.js";
 export * as fixedScriptWallet from "./fixedScriptWallet/index.js";
 export * as bip32 from "./bip32.js";

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

@@ -9,6 +9,106 @@ export class AddressNamespace {
   static from_output_script_with_coin(script: Uint8Array, coin: string, format?: string | null): string;
 }
 
+export class Bip322Namespace {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Add a BIP-0322 message input to an existing BitGoPsbt
+   *
+   * If this is the first input, also adds the OP_RETURN output.
+   * The PSBT must have version 0 per BIP-0322 specification.
+   *
+   * # Arguments
+   * * `psbt` - The BitGoPsbt to add the input to
+   * * `message` - The message to sign
+   * * `chain` - The wallet chain (e.g., 10 for external, 20 for internal)
+   * * `index` - The address index
+   * * `wallet_keys` - The wallet's root keys
+   * * `signer` - Optional signer key name for taproot (e.g., "user", "backup", "bitgo")
+   * * `cosigner` - Optional cosigner key name for taproot
+   * * `tag` - Optional custom tag for message hashing
+   *
+   * # Returns
+   * The index of the added input
+   */
+  static add_bip322_input(psbt: BitGoPsbt, message: string, chain: number, index: number, wallet_keys: WasmRootWalletKeys, signer?: string | null, cosigner?: string | null, tag?: string | null): number;
+  /**
+   * Verify a single input of a BIP-0322 transaction proof
+   *
+   * # Arguments
+   * * `tx` - The signed transaction
+   * * `input_index` - The index of the input to verify
+   * * `message` - The message that was signed
+   * * `chain` - The wallet chain
+   * * `index` - The address index
+   * * `wallet_keys` - The wallet's root keys
+   * * `network` - Network name
+   * * `tag` - Optional custom tag for message hashing
+   *
+   * # Throws
+   * Throws an error if verification fails
+   */
+  static verify_bip322_tx_input(tx: WasmTransaction, input_index: number, message: string, chain: number, index: number, wallet_keys: WasmRootWalletKeys, network: string, tag?: string | null): void;
+  /**
+   * Verify a single input of a BIP-0322 PSBT proof
+   *
+   * # Arguments
+   * * `psbt` - The signed BitGoPsbt
+   * * `input_index` - The index of the input to verify
+   * * `message` - The message that was signed
+   * * `chain` - The wallet chain
+   * * `index` - The address index
+   * * `wallet_keys` - The wallet's root keys
+   * * `tag` - Optional custom tag for message hashing
+   *
+   * # Returns
+   * An array of signer names ("user", "backup", "bitgo") that have valid signatures
+   *
+   * # Throws
+   * Throws an error if verification fails or no valid signatures found
+   */
+  static verify_bip322_psbt_input(psbt: BitGoPsbt, input_index: number, message: string, chain: number, index: number, wallet_keys: WasmRootWalletKeys, tag?: string | null): string[];
+  /**
+   * Verify a single input of a BIP-0322 transaction proof using pubkeys directly
+   *
+   * # Arguments
+   * * `tx` - The signed transaction
+   * * `input_index` - The index of the input to verify
+   * * `message` - The message that was signed
+   * * `pubkeys` - Array of 3 hex-encoded pubkeys [user, backup, bitgo]
+   * * `script_type` - One of: "p2sh", "p2shP2wsh", "p2wsh", "p2tr", "p2trMusig2"
+   * * `is_script_path` - For taproot types, whether script path was used
+   * * `tag` - Optional custom tag for message hashing
+   *
+   * # Returns
+   * An array of pubkey indices (0, 1, 2) that have valid signatures
+   *
+   * # Throws
+   * Throws an error if verification fails
+   */
+  static verify_bip322_tx_input_with_pubkeys(tx: WasmTransaction, input_index: number, message: string, pubkeys: string[], script_type: string, is_script_path?: boolean | null, tag?: string | null): Uint32Array;
+  /**
+   * Verify a single input of a BIP-0322 PSBT proof using pubkeys directly
+   *
+   * # Arguments
+   * * `psbt` - The signed BitGoPsbt
+   * * `input_index` - The index of the input to verify
+   * * `message` - The message that was signed
+   * * `pubkeys` - Array of 3 hex-encoded pubkeys [user, backup, bitgo]
+   * * `script_type` - One of: "p2sh", "p2shP2wsh", "p2wsh", "p2tr", "p2trMusig2"
+   * * `is_script_path` - For taproot types, whether script path was used
+   * * `tag` - Optional custom tag for message hashing
+   *
+   * # Returns
+   * An array of pubkey indices (0, 1, 2) that have valid signatures
+   *
+   * # Throws
+   * Throws an error if verification fails or no valid signatures found
+   */
+  static verify_bip322_psbt_input_with_pubkeys(psbt: BitGoPsbt, input_index: number, message: string, pubkeys: string[], script_type: string, is_script_path?: boolean | null, tag?: string | null): Uint32Array;
+}
+
 export class BitGoPsbt {
   private constructor();
   free(): void;
@@ -379,6 +479,15 @@ export class FixedScriptWalletNamespace {
   free(): void;
   [Symbol.dispose](): void;
   static output_script(keys: WasmRootWalletKeys, chain: number, index: number, network: any): Uint8Array;
+  /**
+   * Get all chain code metadata for building TypeScript lookup tables
+   *
+   * Returns an array of [chainCode, scriptType, scope] tuples where:
+   * - chainCode: u32 (0, 1, 10, 11, 20, 21, 30, 31, 40, 41)
+   * - scriptType: string ("p2sh", "p2shP2wsh", "p2wsh", "p2trLegacy", "p2trMusig2")
+   * - scope: string ("external" or "internal")
+   */
+  static chain_code_table(): any;
   /**
    * Check if a network supports a given fixed-script wallet script type
    *
@@ -553,6 +662,28 @@ export class WasmDimensions {
    * Whether any inputs are segwit (affects overhead calculation)
    */
   has_segwit(): boolean;
+  /**
+   * Get input virtual size (min or max)
+   *
+   * # Arguments
+   * * `size` - "min" or "max", defaults to "max"
+   */
+  get_input_vsize(size?: string | null): number;
+  /**
+   * Get input weight only (min or max)
+   *
+   * # Arguments
+   * * `size` - "min" or "max", defaults to "max"
+   */
+  get_input_weight(size?: string | null): number;
+  /**
+   * Get output virtual size
+   */
+  get_output_vsize(): number;
+  /**
+   * Get output weight
+   */
+  get_output_weight(): number;
   /**
    * Create dimensions for a single output from script bytes
    */
@@ -573,6 +704,10 @@ export class WasmDimensions {
    * Create empty dimensions (zero weight)
    */
   static empty(): WasmDimensions;
+  /**
+   * Multiply dimensions by a scalar
+   */
+  times(n: number): WasmDimensions;
   /**
    * Create dimensions from a BitGoPsbt
    *