@bitgo/wasm-utxo 1.14.0 → 1.15.0

package/README.md

@@ -24,10 +24,20 @@ This project is under active development.
 
 ## Building
 
-If your system has problems with `wasm-pack` (Mac M1), you can use the `Container.mk` Makefile to build the wasm files:
+### Mac
+
+Requires Homebrew LLVM (Apple's Clang doesn't support WASM targets):
+
+```bash
+brew install llvm
+npm run build
+```
+
+### Docker (optional)
+
+If you prefer a containerized build environment:
 
 ```bash
-cd packages/wasm-utxo
 make -f Container.mk build-image
 make -f Container.mk build-wasm
 ```

package/dist/cjs/js/fixedScriptWallet/BitGoPsbt.d.ts

@@ -21,6 +21,7 @@ export type ParsedInput = {
     value: bigint;
     scriptId: ScriptId | null;
     scriptType: InputScriptType;
+    sequence: number;
 };
 export type ParsedOutput = {
     address: string | null;
@@ -36,9 +37,77 @@ export type ParsedTransaction = {
     minerFee: bigint;
     virtualSize: number;
 };
+export type CreateEmptyOptions = {
+    /** Transaction version (default: 2) */
+    version?: number;
+    /** Lock time (default: 0) */
+    lockTime?: number;
+};
+export type AddInputOptions = {
+    /** Previous transaction ID (hex string) */
+    txid: string;
+    /** Output index being spent */
+    vout: number;
+    /** Value in satoshis (for witness_utxo) */
+    value: bigint;
+    /** Sequence number (default: 0xFFFFFFFE for RBF) */
+    sequence?: number;
+    /** Full previous transaction (for non-segwit strict compliance) */
+    prevTx?: Uint8Array;
+};
+export type AddOutputOptions = {
+    /** Output script (scriptPubKey) */
+    script: Uint8Array;
+    /** Value in satoshis */
+    value: bigint;
+};
+/** Key identifier for signing ("user", "backup", or "bitgo") */
+export type SignerKey = "user" | "backup" | "bitgo";
+/** Specifies signer and cosigner for Taproot inputs */
+export type SignPath = {
+    /** Key that will sign */
+    signer: SignerKey;
+    /** Key that will co-sign */
+    cosigner: SignerKey;
+};
+export type AddWalletInputOptions = {
+    /** Script location in wallet (chain + index) */
+    scriptId: ScriptId;
+    /** Sign path - required for p2tr/p2trMusig2 (chains 30-41) */
+    signPath?: SignPath;
+};
+export type AddWalletOutputOptions = {
+    /** Chain code (0/1=p2sh, 10/11=p2shP2wsh, 20/21=p2wsh, 30/31=p2tr, 40/41=p2trMusig2) */
+    chain: number;
+    /** Derivation index */
+    index: number;
+    /** Value in satoshis */
+    value: bigint;
+};
 export declare class BitGoPsbt {
     private wasm;
     private constructor();
+    /**
+     * Create an empty PSBT for the given network with wallet keys
+     *
+     * The wallet keys are used to set global xpubs in the PSBT, which identifies
+     * the keys that will be used for signing.
+     *
+     * @param network - Network name (utxolib name like "bitcoin" or coin name like "btc")
+     * @param walletKeys - The wallet's root keys (sets global xpubs in the PSBT)
+     * @param options - Optional transaction parameters (version, lockTime)
+     * @returns A new empty BitGoPsbt instance
+     *
+     * @example
+     * ```typescript
+     * // Create empty PSBT with wallet keys
+     * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys);
+     *
+     * // Create with custom version and lockTime
+     * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 1, lockTime: 500000 });
+     * ```
+     */
+    static createEmpty(network: NetworkName, walletKeys: WalletKeysArg, options?: CreateEmptyOptions): BitGoPsbt;
     /**
      * Deserialize a PSBT from bytes
      * @param bytes - The PSBT bytes
@@ -46,11 +115,147 @@ export declare class BitGoPsbt {
      * @returns A BitGoPsbt instance
      */
     static fromBytes(bytes: Uint8Array, network: NetworkName): BitGoPsbt;
+    /**
+     * Add an input to the PSBT
+     *
+     * This adds a transaction input and corresponding PSBT input metadata.
+     * The witness_utxo is automatically populated for modern signing compatibility.
+     *
+     * @param options - Input options (txid, vout, value, sequence)
+     * @param script - Output script of the UTXO being spent
+     * @returns The index of the newly added input
+     *
+     * @example
+     * ```typescript
+     * const inputIndex = psbt.addInput({
+     *   txid: "abc123...",
+     *   vout: 0,
+     *   value: 100000n,
+     * }, outputScript);
+     * ```
+     */
+    addInput(options: AddInputOptions, script: Uint8Array): number;
+    /**
+     * Add an output to the PSBT
+     *
+     * @param options - Output options (script, value)
+     * @returns The index of the newly added output
+     *
+     * @example
+     * ```typescript
+     * const outputIndex = psbt.addOutput({
+     *   script: outputScript,
+     *   value: 50000n,
+     * });
+     * ```
+     */
+    addOutput(options: AddOutputOptions): number;
+    /**
+     * 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.
+     *
+     * For p2sh/p2shP2wsh/p2wsh: Sets bip32Derivation, witnessScript, redeemScript (signPath not needed)
+     * For p2tr/p2trMusig2 script path: Sets tapLeafScript, tapBip32Derivation (signPath required)
+     * For p2trMusig2 key path: Sets tapInternalKey, tapMerkleRoot, tapBip32Derivation, musig2 participants (signPath required)
+     *
+     * @param inputOptions - Common input options (txid, vout, value, sequence)
+     * @param walletKeys - The wallet's root keys
+     * @param walletOptions - Wallet-specific options (scriptId, signPath, prevTx)
+     * @returns The index of the newly added input
+     *
+     * @example
+     * ```typescript
+     * // Add a p2shP2wsh input (signPath not needed)
+     * const inputIndex = psbt.addWalletInput(
+     *   { txid: "abc123...", vout: 0, value: 100000n },
+     *   walletKeys,
+     *   { scriptId: { chain: 10, index: 0 } },  // p2shP2wsh external
+     * );
+     *
+     * // Add a p2trMusig2 key path input (signPath required)
+     * const inputIndex = psbt.addWalletInput(
+     *   { txid: "def456...", vout: 1, value: 50000n },
+     *   walletKeys,
+     *   { scriptId: { chain: 40, index: 5 }, signPath: { signer: "user", cosigner: "bitgo" } },
+     * );
+     *
+     * // Add p2trMusig2 with backup key (script path spend)
+     * const inputIndex = psbt.addWalletInput(
+     *   { txid: "ghi789...", vout: 0, value: 75000n },
+     *   walletKeys,
+     *   { scriptId: { chain: 40, index: 3 }, signPath: { signer: "user", cosigner: "backup" } },
+     * );
+     * ```
+     */
+    addWalletInput(inputOptions: AddInputOptions, walletKeys: WalletKeysArg, walletOptions: AddWalletInputOptions): number;
+    /**
+     * 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.
+     *
+     * For p2sh/p2shP2wsh/p2wsh: Sets bip32Derivation, witnessScript, redeemScript
+     * For p2tr/p2trMusig2: Sets tapInternalKey, tapBip32Derivation
+     *
+     * @param walletKeys - The wallet's root keys
+     * @param options - Output options including chain, index, and value
+     * @returns The index of the newly added output
+     *
+     * @example
+     * ```typescript
+     * // Add a p2shP2wsh change output
+     * const outputIndex = psbt.addWalletOutput(walletKeys, {
+     *   chain: 11,  // p2shP2wsh internal (change)
+     *   index: 0,
+     *   value: 50000n,
+     * });
+     *
+     * // Add a p2trMusig2 change output
+     * const outputIndex = psbt.addWalletOutput(walletKeys, {
+     *   chain: 41,  // p2trMusig2 internal (change)
+     *   index: 5,
+     *   value: 25000n,
+     * });
+     * ```
+     */
+    addWalletOutput(walletKeys: WalletKeysArg, options: AddWalletOutputOptions): number;
+    /**
+     * 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.
+     *
+     * @param inputOptions - Common input options (txid, vout, value, sequence)
+     * @param key - ECPair containing the public key for the replay protection input
+     * @returns The index of the newly added input
+     *
+     * @example
+     * ```typescript
+     * // Add a replay protection input using ECPair
+     * const inputIndex = psbt.addReplayProtectionInput(
+     *   { txid: "abc123...", vout: 0, value: 1000n },
+     *   replayProtectionKey,
+     * );
+     * ```
+     */
+    addReplayProtectionInput(inputOptions: AddInputOptions, key: ECPairArg): number;
     /**
      * Get the unsigned transaction ID
      * @returns The unsigned transaction ID
      */
     unsignedTxid(): string;
+    /**
+     * Get the transaction version
+     * @returns The transaction version number
+     */
+    get version(): number;
+    /**
+     * Get the transaction lock time
+     * @returns The transaction lock time
+     */
+    get lockTime(): number;
     /**
      * Parse transaction with wallet keys to identify wallet inputs/outputs
      * @param walletKeys - The wallet keys to use for identification

package/dist/cjs/js/fixedScriptWallet/BitGoPsbt.js

@@ -11,6 +11,31 @@ class BitGoPsbt {
     constructor(wasm) {
         this.wasm = wasm;
     }
+    /**
+     * Create an empty PSBT for the given network with wallet keys
+     *
+     * The wallet keys are used to set global xpubs in the PSBT, which identifies
+     * the keys that will be used for signing.
+     *
+     * @param network - Network name (utxolib name like "bitcoin" or coin name like "btc")
+     * @param walletKeys - The wallet's root keys (sets global xpubs in the PSBT)
+     * @param options - Optional transaction parameters (version, lockTime)
+     * @returns A new empty BitGoPsbt instance
+     *
+     * @example
+     * ```typescript
+     * // Create empty PSBT with wallet keys
+     * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys);
+     *
+     * // Create with custom version and lockTime
+     * const psbt = BitGoPsbt.createEmpty("bitcoin", walletKeys, { version: 1, lockTime: 500000 });
+     * ```
+     */
+    static createEmpty(network, walletKeys, options) {
+        const keys = RootWalletKeys_js_1.RootWalletKeys.from(walletKeys);
+        const wasm = wasm_utxo_js_1.BitGoPsbt.create_empty(network, keys.wasm, options?.version, options?.lockTime);
+        return new BitGoPsbt(wasm);
+    }
     /**
      * Deserialize a PSBT from bytes
      * @param bytes - The PSBT bytes
@@ -21,6 +46,145 @@ class BitGoPsbt {
         const wasm = wasm_utxo_js_1.BitGoPsbt.from_bytes(bytes, network);
         return new BitGoPsbt(wasm);
     }
+    /**
+     * Add an input to the PSBT
+     *
+     * This adds a transaction input and corresponding PSBT input metadata.
+     * The witness_utxo is automatically populated for modern signing compatibility.
+     *
+     * @param options - Input options (txid, vout, value, sequence)
+     * @param script - Output script of the UTXO being spent
+     * @returns The index of the newly added input
+     *
+     * @example
+     * ```typescript
+     * const inputIndex = psbt.addInput({
+     *   txid: "abc123...",
+     *   vout: 0,
+     *   value: 100000n,
+     * }, outputScript);
+     * ```
+     */
+    addInput(options, script) {
+        return this.wasm.add_input(options.txid, options.vout, options.value, script, options.sequence, options.prevTx);
+    }
+    /**
+     * Add an output to the PSBT
+     *
+     * @param options - Output options (script, value)
+     * @returns The index of the newly added output
+     *
+     * @example
+     * ```typescript
+     * const outputIndex = psbt.addOutput({
+     *   script: outputScript,
+     *   value: 50000n,
+     * });
+     * ```
+     */
+    addOutput(options) {
+        return this.wasm.add_output(options.script, options.value);
+    }
+    /**
+     * 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.
+     *
+     * For p2sh/p2shP2wsh/p2wsh: Sets bip32Derivation, witnessScript, redeemScript (signPath not needed)
+     * For p2tr/p2trMusig2 script path: Sets tapLeafScript, tapBip32Derivation (signPath required)
+     * For p2trMusig2 key path: Sets tapInternalKey, tapMerkleRoot, tapBip32Derivation, musig2 participants (signPath required)
+     *
+     * @param inputOptions - Common input options (txid, vout, value, sequence)
+     * @param walletKeys - The wallet's root keys
+     * @param walletOptions - Wallet-specific options (scriptId, signPath, prevTx)
+     * @returns The index of the newly added input
+     *
+     * @example
+     * ```typescript
+     * // Add a p2shP2wsh input (signPath not needed)
+     * const inputIndex = psbt.addWalletInput(
+     *   { txid: "abc123...", vout: 0, value: 100000n },
+     *   walletKeys,
+     *   { scriptId: { chain: 10, index: 0 } },  // p2shP2wsh external
+     * );
+     *
+     * // Add a p2trMusig2 key path input (signPath required)
+     * const inputIndex = psbt.addWalletInput(
+     *   { txid: "def456...", vout: 1, value: 50000n },
+     *   walletKeys,
+     *   { scriptId: { chain: 40, index: 5 }, signPath: { signer: "user", cosigner: "bitgo" } },
+     * );
+     *
+     * // Add p2trMusig2 with backup key (script path spend)
+     * const inputIndex = psbt.addWalletInput(
+     *   { txid: "ghi789...", vout: 0, value: 75000n },
+     *   walletKeys,
+     *   { scriptId: { chain: 40, index: 3 }, signPath: { signer: "user", cosigner: "backup" } },
+     * );
+     * ```
+     */
+    addWalletInput(inputOptions, walletKeys, walletOptions) {
+        const keys = RootWalletKeys_js_1.RootWalletKeys.from(walletKeys);
+        return this.wasm.add_wallet_input(inputOptions.txid, inputOptions.vout, inputOptions.value, keys.wasm, walletOptions.scriptId.chain, walletOptions.scriptId.index, walletOptions.signPath?.signer, walletOptions.signPath?.cosigner, inputOptions.sequence, inputOptions.prevTx);
+    }
+    /**
+     * 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.
+     *
+     * For p2sh/p2shP2wsh/p2wsh: Sets bip32Derivation, witnessScript, redeemScript
+     * For p2tr/p2trMusig2: Sets tapInternalKey, tapBip32Derivation
+     *
+     * @param walletKeys - The wallet's root keys
+     * @param options - Output options including chain, index, and value
+     * @returns The index of the newly added output
+     *
+     * @example
+     * ```typescript
+     * // Add a p2shP2wsh change output
+     * const outputIndex = psbt.addWalletOutput(walletKeys, {
+     *   chain: 11,  // p2shP2wsh internal (change)
+     *   index: 0,
+     *   value: 50000n,
+     * });
+     *
+     * // Add a p2trMusig2 change output
+     * const outputIndex = psbt.addWalletOutput(walletKeys, {
+     *   chain: 41,  // p2trMusig2 internal (change)
+     *   index: 5,
+     *   value: 25000n,
+     * });
+     * ```
+     */
+    addWalletOutput(walletKeys, options) {
+        const keys = RootWalletKeys_js_1.RootWalletKeys.from(walletKeys);
+        return this.wasm.add_wallet_output(options.chain, options.index, options.value, keys.wasm);
+    }
+    /**
+     * 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.
+     *
+     * @param inputOptions - Common input options (txid, vout, value, sequence)
+     * @param key - ECPair containing the public key for the replay protection input
+     * @returns The index of the newly added input
+     *
+     * @example
+     * ```typescript
+     * // Add a replay protection input using ECPair
+     * const inputIndex = psbt.addReplayProtectionInput(
+     *   { txid: "abc123...", vout: 0, value: 1000n },
+     *   replayProtectionKey,
+     * );
+     * ```
+     */
+    addReplayProtectionInput(inputOptions, key) {
+        const ecpair = ecpair_js_1.ECPair.from(key);
+        return this.wasm.add_replay_protection_input(ecpair.wasm, inputOptions.txid, inputOptions.vout, inputOptions.value, inputOptions.sequence);
+    }
     /**
      * Get the unsigned transaction ID
      * @returns The unsigned transaction ID
@@ -28,6 +192,20 @@ class BitGoPsbt {
     unsignedTxid() {
         return this.wasm.unsigned_txid();
     }
+    /**
+     * Get the transaction version
+     * @returns The transaction version number
+     */
+    get version() {
+        return this.wasm.version();
+    }
+    /**
+     * Get the transaction lock time
+     * @returns The transaction lock time
+     */
+    get lockTime() {
+        return this.wasm.lock_time();
+    }
     /**
      * Parse transaction with wallet keys to identify wallet inputs/outputs
      * @param walletKeys - The wallet keys to use for identification

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

@@ -1,4 +1,4 @@
 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, } from "./BitGoPsbt.js";

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

@@ -13,10 +13,31 @@ 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 unsigned transaction ID
    */
@@ -41,6 +62,44 @@ 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;
+  /**
+   * 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
    *
@@ -181,6 +240,23 @@ 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;
   /**
    * Parse outputs with wallet keys to identify which outputs belong to a wallet
    *
@@ -213,6 +289,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
    *