@bitgo/wasm-utxo 1.21.0 → 1.22.0

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

@@ -0,0 +1,236 @@
+/**
+ * BIP-0322 Generic Signed Message Format
+ *
+ * This module implements BIP-0322 for BitGo fixed-script wallets.
+ * It allows proving control of wallet addresses by signing arbitrary messages.
+ *
+ * @example
+ * ```typescript
+ * import { bip322, fixedScriptWallet } from '@bitgo/wasm-utxo';
+ *
+ * // Create wallet keys
+ * const walletKeys = fixedScriptWallet.RootWalletKeys.from([userXpub, backupXpub, bitgoXpub]);
+ *
+ * // Create an empty PSBT for BIP-0322 (version 0 required)
+ * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 0 });
+ *
+ * // Add BIP-0322 inputs
+ * const idx0 = bip322.addBip322Input(psbt, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ *
+ * // Sign the input
+ * psbt.sign(idx0, userXpriv);
+ * psbt.sign(idx0, bitgoXpriv);
+ *
+ * // Verify the input
+ * bip322.verifyBip322PsbtInput(psbt, idx0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ * ```
+ */
+import { BitGoPsbt, type NetworkName, type ScriptId, type SignPath } from "../fixedScriptWallet/BitGoPsbt.js";
+import { type WalletKeysArg } from "../fixedScriptWallet/RootWalletKeys.js";
+import { type OutputScriptType } from "../fixedScriptWallet/scriptType.js";
+import { Transaction } from "../transaction.js";
+export type { OutputScriptType };
+/**
+ * Parameters for adding a BIP-0322 input to a PSBT
+ */
+export type AddBip322InputParams = {
+    /** The message to sign (UTF-8 string) */
+    message: string;
+    /** The wallet script location (chain and index) */
+    scriptId: ScriptId;
+    /** The wallet's root keys */
+    rootWalletKeys: WalletKeysArg;
+    /**
+     * Sign path for taproot inputs (required for p2tr/p2trMusig2).
+     * Specifies which two keys will sign the message.
+     */
+    signPath?: SignPath;
+    /** Custom tag for message hashing (default: "BIP0322-signed-message") */
+    tag?: string;
+};
+/**
+ * Parameters for verifying a BIP-0322 input
+ */
+export type VerifyBip322InputParams = {
+    /** The message that was signed */
+    message: string;
+    /** The wallet script location (chain and index) */
+    scriptId: ScriptId;
+    /** The wallet's root keys */
+    rootWalletKeys: WalletKeysArg;
+    /** Custom tag if one was used during signing */
+    tag?: string;
+};
+/**
+ * Parameters for verifying a BIP-0322 transaction input
+ */
+export type VerifyBip322TxInputParams = VerifyBip322InputParams & {
+    /** Network name (default: "bitcoin") */
+    network?: NetworkName;
+};
+/**
+ * Add a BIP-0322 message input to an existing BitGoPsbt
+ *
+ * The PSBT must have version 0 per BIP-0322 specification. Use
+ * `BitGoPsbt.createEmpty(network, walletKeys, { version: 0 })` to create one.
+ *
+ * On the first input added, this also adds the required OP_RETURN output.
+ *
+ * @param psbt - The BitGoPsbt to add the input to (must have version 0)
+ * @param params - Input parameters including message, scriptId, and wallet keys
+ * @returns The index of the added input
+ *
+ * @example
+ * ```typescript
+ * // Create a BIP-0322 PSBT
+ * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 0 });
+ *
+ * // Add inputs
+ * const idx0 = bip322.addBip322Input(psbt, {
+ *   message: "I control this address",
+ *   scriptId: { chain: 10, index: 5 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ *
+ * // Sign with user and bitgo keys
+ * psbt.sign(idx0, userXpriv);
+ * psbt.sign(idx0, bitgoXpriv);
+ * ```
+ */
+export declare function addBip322Input(psbt: BitGoPsbt, params: AddBip322InputParams): number;
+/**
+ * Verify a single input of a BIP-0322 transaction proof
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address corresponding to the given message.
+ *
+ * @param tx - The signed transaction
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, scriptId, and wallet keys
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Extract and verify the transaction
+ * psbt.finalizeAllInputs();
+ * const txBytes = psbt.extractTransaction();
+ * const tx = Transaction.fromBytes(txBytes, "bitcoin");
+ *
+ * bip322.verifyBip322TxInput(tx, 0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ *   network: "bitcoin",
+ * });
+ * ```
+ */
+export declare function verifyBip322TxInput(tx: Transaction, inputIndex: number, params: VerifyBip322TxInputParams): void;
+/** Signer key name */
+export type SignerName = "user" | "backup" | "bitgo";
+/** Triple of hex-encoded pubkeys [user, backup, bitgo] */
+export type PubkeyTriple = [string, string, string];
+/**
+ * Parameters for verifying a BIP-0322 input with pubkeys
+ */
+export type VerifyBip322WithPubkeysParams = {
+    /** The message that was signed */
+    message: string;
+    /** Hex-encoded pubkeys [user, backup, bitgo] */
+    pubkeys: PubkeyTriple;
+    /** Script type */
+    scriptType: OutputScriptType;
+    /** For taproot types, whether script path was used */
+    isScriptPath?: boolean;
+    /** Custom tag if one was used during signing */
+    tag?: string;
+};
+/**
+ * Parameters for verifying a BIP-0322 transaction input with pubkeys
+ */
+export type VerifyBip322TxWithPubkeysParams = VerifyBip322WithPubkeysParams;
+/**
+ * Verify a single input of a BIP-0322 PSBT proof
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address by checking:
+ * - The PSBT structure follows BIP-0322 (version 0, OP_RETURN output)
+ * - The input references the correct virtual to_spend transaction
+ * - At least one valid signature exists from the wallet keys
+ *
+ * @param psbt - The signed PSBT
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, scriptId, and wallet keys
+ * @returns An array of signer names ("user", "backup", "bitgo") that have valid signatures
+ * @throws Error if verification fails or no valid signatures found
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed PSBT input
+ * const signers = bip322.verifyBip322PsbtInput(psbt, 0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ * console.log(signers); // ["user", "bitgo"]
+ * ```
+ */
+export declare function verifyBip322PsbtInput(psbt: BitGoPsbt, inputIndex: number, params: VerifyBip322InputParams): SignerName[];
+/**
+ * Verify a single input of a BIP-0322 PSBT proof using pubkeys directly
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address by checking:
+ * - The PSBT structure follows BIP-0322 (version 0, OP_RETURN output)
+ * - The input references the correct virtual to_spend transaction
+ * - At least one valid signature exists from the provided pubkeys
+ *
+ * @param psbt - The signed PSBT
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, pubkeys, and script type
+ * @returns An array of pubkey indices (0, 1, 2) that have valid signatures
+ * @throws Error if verification fails or no valid signatures found
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed PSBT input with pubkeys
+ * const signerIndices = bip322.verifyBip322PsbtInputWithPubkeys(psbt, 0, {
+ *   message: "Hello, World!",
+ *   pubkeys: [userPubkey, backupPubkey, bitgoPubkey],
+ *   scriptType: "p2shP2wsh",
+ * });
+ * console.log(signerIndices); // [0, 2] for user+bitgo
+ * ```
+ */
+export declare function verifyBip322PsbtInputWithPubkeys(psbt: BitGoPsbt, inputIndex: number, params: VerifyBip322WithPubkeysParams): number[];
+/**
+ * Verify a single input of a BIP-0322 transaction proof using pubkeys directly
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address corresponding to the given message.
+ *
+ * @param tx - The signed transaction
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, pubkeys, and script type
+ * @returns An array of pubkey indices (0, 1, 2) that have valid signatures
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed transaction input with pubkeys
+ * const signerIndices = bip322.verifyBip322TxInputWithPubkeys(tx, 0, {
+ *   message: "Hello, World!",
+ *   pubkeys: [userPubkey, backupPubkey, bitgoPubkey],
+ *   scriptType: "p2wsh",
+ * });
+ * console.log(signerIndices); // [0, 2] for user+bitgo
+ * ```
+ */
+export declare function verifyBip322TxInputWithPubkeys(tx: Transaction, inputIndex: number, params: VerifyBip322TxWithPubkeysParams): number[];

package/dist/esm/js/bip322/index.js

@@ -0,0 +1,186 @@
+/**
+ * BIP-0322 Generic Signed Message Format
+ *
+ * This module implements BIP-0322 for BitGo fixed-script wallets.
+ * It allows proving control of wallet addresses by signing arbitrary messages.
+ *
+ * @example
+ * ```typescript
+ * import { bip322, fixedScriptWallet } from '@bitgo/wasm-utxo';
+ *
+ * // Create wallet keys
+ * const walletKeys = fixedScriptWallet.RootWalletKeys.from([userXpub, backupXpub, bitgoXpub]);
+ *
+ * // Create an empty PSBT for BIP-0322 (version 0 required)
+ * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 0 });
+ *
+ * // Add BIP-0322 inputs
+ * const idx0 = bip322.addBip322Input(psbt, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ *
+ * // Sign the input
+ * psbt.sign(idx0, userXpriv);
+ * psbt.sign(idx0, bitgoXpriv);
+ *
+ * // Verify the input
+ * bip322.verifyBip322PsbtInput(psbt, idx0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ * ```
+ */
+import { Bip322Namespace } from "../wasm/wasm_utxo.js";
+import { RootWalletKeys } from "../fixedScriptWallet/RootWalletKeys.js";
+/**
+ * Add a BIP-0322 message input to an existing BitGoPsbt
+ *
+ * The PSBT must have version 0 per BIP-0322 specification. Use
+ * `BitGoPsbt.createEmpty(network, walletKeys, { version: 0 })` to create one.
+ *
+ * On the first input added, this also adds the required OP_RETURN output.
+ *
+ * @param psbt - The BitGoPsbt to add the input to (must have version 0)
+ * @param params - Input parameters including message, scriptId, and wallet keys
+ * @returns The index of the added input
+ *
+ * @example
+ * ```typescript
+ * // Create a BIP-0322 PSBT
+ * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 0 });
+ *
+ * // Add inputs
+ * const idx0 = bip322.addBip322Input(psbt, {
+ *   message: "I control this address",
+ *   scriptId: { chain: 10, index: 5 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ *
+ * // Sign with user and bitgo keys
+ * psbt.sign(idx0, userXpriv);
+ * psbt.sign(idx0, bitgoXpriv);
+ * ```
+ */
+export function addBip322Input(psbt, params) {
+    const keys = RootWalletKeys.from(params.rootWalletKeys);
+    return Bip322Namespace.add_bip322_input(psbt.wasm, params.message, params.scriptId.chain, params.scriptId.index, keys.wasm, params.signPath?.signer, params.signPath?.cosigner, params.tag);
+}
+/**
+ * Verify a single input of a BIP-0322 transaction proof
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address corresponding to the given message.
+ *
+ * @param tx - The signed transaction
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, scriptId, and wallet keys
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Extract and verify the transaction
+ * psbt.finalizeAllInputs();
+ * const txBytes = psbt.extractTransaction();
+ * const tx = Transaction.fromBytes(txBytes, "bitcoin");
+ *
+ * bip322.verifyBip322TxInput(tx, 0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ *   network: "bitcoin",
+ * });
+ * ```
+ */
+export function verifyBip322TxInput(tx, inputIndex, params) {
+    const keys = RootWalletKeys.from(params.rootWalletKeys);
+    const network = params.network ?? "bitcoin";
+    Bip322Namespace.verify_bip322_tx_input(tx.wasm, inputIndex, params.message, params.scriptId.chain, params.scriptId.index, keys.wasm, network, params.tag);
+}
+/**
+ * Verify a single input of a BIP-0322 PSBT proof
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address by checking:
+ * - The PSBT structure follows BIP-0322 (version 0, OP_RETURN output)
+ * - The input references the correct virtual to_spend transaction
+ * - At least one valid signature exists from the wallet keys
+ *
+ * @param psbt - The signed PSBT
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, scriptId, and wallet keys
+ * @returns An array of signer names ("user", "backup", "bitgo") that have valid signatures
+ * @throws Error if verification fails or no valid signatures found
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed PSBT input
+ * const signers = bip322.verifyBip322PsbtInput(psbt, 0, {
+ *   message: "Hello, World!",
+ *   scriptId: { chain: 10, index: 0 },
+ *   rootWalletKeys: walletKeys,
+ * });
+ * console.log(signers); // ["user", "bitgo"]
+ * ```
+ */
+export function verifyBip322PsbtInput(psbt, inputIndex, params) {
+    const keys = RootWalletKeys.from(params.rootWalletKeys);
+    return Bip322Namespace.verify_bip322_psbt_input(psbt.wasm, inputIndex, params.message, params.scriptId.chain, params.scriptId.index, keys.wasm, params.tag);
+}
+/**
+ * Verify a single input of a BIP-0322 PSBT proof using pubkeys directly
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address by checking:
+ * - The PSBT structure follows BIP-0322 (version 0, OP_RETURN output)
+ * - The input references the correct virtual to_spend transaction
+ * - At least one valid signature exists from the provided pubkeys
+ *
+ * @param psbt - The signed PSBT
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, pubkeys, and script type
+ * @returns An array of pubkey indices (0, 1, 2) that have valid signatures
+ * @throws Error if verification fails or no valid signatures found
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed PSBT input with pubkeys
+ * const signerIndices = bip322.verifyBip322PsbtInputWithPubkeys(psbt, 0, {
+ *   message: "Hello, World!",
+ *   pubkeys: [userPubkey, backupPubkey, bitgoPubkey],
+ *   scriptType: "p2shP2wsh",
+ * });
+ * console.log(signerIndices); // [0, 2] for user+bitgo
+ * ```
+ */
+export function verifyBip322PsbtInputWithPubkeys(psbt, inputIndex, params) {
+    return Array.from(Bip322Namespace.verify_bip322_psbt_input_with_pubkeys(psbt.wasm, inputIndex, params.message, params.pubkeys, params.scriptType, params.isScriptPath, params.tag));
+}
+/**
+ * Verify a single input of a BIP-0322 transaction proof using pubkeys directly
+ *
+ * This verifies that the specified input correctly proves control of the
+ * wallet address corresponding to the given message.
+ *
+ * @param tx - The signed transaction
+ * @param inputIndex - The index of the input to verify
+ * @param params - Verification parameters including message, pubkeys, and script type
+ * @returns An array of pubkey indices (0, 1, 2) that have valid signatures
+ * @throws Error if verification fails
+ *
+ * @example
+ * ```typescript
+ * // Verify the signed transaction input with pubkeys
+ * const signerIndices = bip322.verifyBip322TxInputWithPubkeys(tx, 0, {
+ *   message: "Hello, World!",
+ *   pubkeys: [userPubkey, backupPubkey, bitgoPubkey],
+ *   scriptType: "p2wsh",
+ * });
+ * console.log(signerIndices); // [0, 2] for user+bitgo
+ * ```
+ */
+export function verifyBip322TxInputWithPubkeys(tx, inputIndex, params) {
+    return Array.from(Bip322Namespace.verify_bip322_tx_input_with_pubkeys(tx.wasm, inputIndex, params.message, params.pubkeys, params.scriptType, params.isScriptPath, params.tag));
+}

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;