@bitgo/wasm-utxo 1.42.0 → 1.44.0

package/README.md

@@ -31,6 +31,36 @@ Zcash support includes:
 - **Height-Based API**: Preferred `createEmpty()` method automatically selects correct consensus rules
 - **Parity Testing**: Validated against `zebra-chain` for accuracy across all network upgrades
 
+## Inspect Feature
+
+The `inspect` feature adds PSBT and transaction parsing into hierarchical node trees,
+useful for building tree-view UIs and CLI formatters.
+
+It is behind a Cargo feature flag because it pulls in extra dependencies (`serde`, `serde_json`,
+`num-bigint`, `hex`) that are not needed for core wallet operations.
+
+### Rust
+
+```rust
+// Cargo.toml
+wasm-utxo = { path = ".", features = ["inspect"] }
+
+// Usage
+use wasm_utxo::inspect::{parse_psbt_bytes_with_network, parse_tx_bytes_with_network, Node};
+```
+
+### TypeScript
+
+Available as a separate import path, not included in the main `@bitgo/wasm-utxo` entry:
+
+```typescript
+import { parsePsbtToNode, parseTxToNode, isInspectEnabled } from "@bitgo/wasm-utxo/inspect";
+```
+
+The published npm package includes stub implementations that return `isInspectEnabled() === false`
+and throw runtime errors from the parse functions. To get a working build, compile the WASM with
+`--features inspect` (see [`packages/webui/scripts/build-wasm.sh`](../webui/scripts/build-wasm.sh)).
+
 ## Building
 
 ### Mac

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

@@ -195,7 +195,7 @@ class BitGoPsbt {
      */
     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);
+        return this._wasm.add_replay_protection_input(ecpair.wasm, inputOptions.txid, inputOptions.vout, inputOptions.value, inputOptions.sequence, inputOptions.prevTx);
     }
     /**
      * Get the unsigned transaction ID

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

@@ -52,3 +52,10 @@ export declare function supportsScriptType(coin: CoinName, scriptType: ScriptTyp
  * ```
  */
 export declare function createOpReturnScript(data?: Uint8Array): Uint8Array;
+/**
+ * Get the P2SH-P2PK output script for a compressed public key
+ *
+ * @param pubkey - The compressed public key bytes (33 bytes)
+ * @returns The P2SH-P2PK output script as a Uint8Array
+ */
+export declare function p2shP2pkOutputScript(pubkey: Uint8Array): Uint8Array;

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZcashBitGoPsbt = exports.BitGoPsbt = exports.assertChainCode = exports.chainCodes = exports.ChainCode = exports.inputScriptTypes = exports.outputScriptTypes = exports.Dimensions = exports.address = exports.outputScript = exports.ReplayProtection = exports.RootWalletKeys = void 0;
 exports.supportsScriptType = supportsScriptType;
 exports.createOpReturnScript = createOpReturnScript;
+exports.p2shP2pkOutputScript = p2shP2pkOutputScript;
 const wasm_utxo_js_1 = require("../wasm/wasm_utxo.js");
 var RootWalletKeys_js_1 = require("./RootWalletKeys.js");
 Object.defineProperty(exports, "RootWalletKeys", { enumerable: true, get: function () { return RootWalletKeys_js_1.RootWalletKeys; } });
@@ -73,3 +74,12 @@ function supportsScriptType(coin, scriptType) {
 function createOpReturnScript(data) {
     return wasm_utxo_js_1.FixedScriptWalletNamespace.create_op_return_script(data);
 }
+/**
+ * Get the P2SH-P2PK output script for a compressed public key
+ *
+ * @param pubkey - The compressed public key bytes (33 bytes)
+ * @returns The P2SH-P2PK output script as a Uint8Array
+ */
+function p2shP2pkOutputScript(pubkey) {
+    return wasm_utxo_js_1.FixedScriptWalletNamespace.p2sh_p2pk_output_script(pubkey);
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Inspect - TypeScript bindings for PSBT and Transaction parsing
+ *
+ * Provides typed wrappers around the WASM inspect functions that return
+ * hierarchical node structures suitable for display as collapsible trees.
+ *
+ * Import via: `import { ... } from "@bitgo/wasm-utxo/inspect"`
+ */
+import type { CoinName } from "../coinName.js";
+/** Re-export CoinName for convenience */
+export type { CoinName };
+/** All supported networks in order of parsing priority */
+export declare const allNetworks: CoinName[];
+/**
+ * Primitive value types that can appear in a Node.
+ * Buffer values are hex-encoded strings, Integer is a decimal string for BigInt support.
+ */
+export type PrimitiveType = "String" | "Buffer" | "Integer" | "U8" | "U16" | "U32" | "U64" | "I8" | "I16" | "I32" | "I64" | "Boolean" | "None";
+/**
+ * A tagged union representing primitive values in the parse tree.
+ */
+export interface Primitive {
+    type: PrimitiveType;
+    value?: string | number | boolean;
+}
+/**
+ * A node in the parse tree representing a PSBT or transaction element.
+ */
+export interface Node {
+    label: string;
+    value: Primitive;
+    children: Node[];
+}
+/**
+ * Parse a PSBT and return a typed node tree.
+ *
+ * @param psbtBytes - The raw PSBT bytes
+ * @param network - The network coin name (e.g., "btc", "ltc", "bch")
+ * @returns A Node tree representing the parsed PSBT structure
+ * @throws If the PSBT bytes are invalid or network is unknown
+ */
+export declare function parsePsbtToNode(psbtBytes: Uint8Array, network: CoinName): Node;
+/**
+ * Parse a transaction and return a typed node tree.
+ *
+ * @param txBytes - The raw transaction bytes
+ * @param network - The network coin name (e.g., "btc", "ltc", "bch")
+ * @returns A Node tree representing the parsed transaction structure
+ * @throws If the transaction bytes are invalid or network is unknown
+ */
+export declare function parseTxToNode(txBytes: Uint8Array, network: CoinName): Node;
+/**
+ * Try to parse a PSBT with all networks and return the first one that succeeds.
+ *
+ * @param psbtBytes - The raw PSBT bytes
+ * @param networks - Optional list of networks to try (defaults to all networks)
+ * @returns An object with the parsed Node and detected network, or null if all fail
+ */
+export declare function tryParsePsbt(psbtBytes: Uint8Array, networks?: CoinName[]): {
+    node: Node;
+    network: CoinName;
+} | null;
+/**
+ * Try to parse a transaction with all networks and return the first one that succeeds.
+ *
+ * @param txBytes - The raw transaction bytes
+ * @param networks - Optional list of networks to try (defaults to all networks)
+ * @returns An object with the parsed Node and detected network, or null if all fail
+ */
+export declare function tryParseTx(txBytes: Uint8Array, networks?: CoinName[]): {
+    node: Node;
+    network: CoinName;
+} | null;
+/**
+ * Parse a PSBT at the raw byte level and return a typed node tree.
+ *
+ * Unlike `parsePsbtToNode`, this function exposes the raw key-value pair
+ * structure as defined in BIP-174, showing:
+ * - Raw key type IDs and their human-readable names
+ * - Proprietary keys with their structured format
+ * - Unknown/unrecognized keys that standard parsers might skip
+ *
+ * @param psbtBytes - The raw PSBT bytes
+ * @param network - The network coin name (e.g., "btc", "ltc", "zec")
+ * @returns A Node tree representing the raw PSBT key-value structure
+ * @throws If the PSBT bytes are invalid or network is unknown
+ */
+export declare function parsePsbtRawToNode(psbtBytes: Uint8Array, network: CoinName): Node;
+/**
+ * Try to parse a raw PSBT with all networks and return the first one that succeeds.
+ *
+ * @param psbtBytes - The raw PSBT bytes
+ * @param networks - Optional list of networks to try (defaults to all networks)
+ * @returns An object with the parsed Node and detected network, or null if all fail
+ */
+export declare function tryParsePsbtRaw(psbtBytes: Uint8Array, networks?: CoinName[]): {
+    node: Node;
+    network: CoinName;
+} | null;
+/**
+ * Check if the inspect feature is enabled in the WASM build.
+ *
+ * @returns true if the feature is enabled, false otherwise
+ */
+export declare function isInspectEnabled(): boolean;

package/dist/cjs/js/inspect/index.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Inspect - TypeScript bindings for PSBT and Transaction parsing
+ *
+ * Provides typed wrappers around the WASM inspect functions that return
+ * hierarchical node structures suitable for display as collapsible trees.
+ *
+ * Import via: `import { ... } from "@bitgo/wasm-utxo/inspect"`
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allNetworks = void 0;
+exports.parsePsbtToNode = parsePsbtToNode;
+exports.parseTxToNode = parseTxToNode;
+exports.tryParsePsbt = tryParsePsbt;
+exports.tryParseTx = tryParseTx;
+exports.parsePsbtRawToNode = parsePsbtRawToNode;
+exports.tryParsePsbtRaw = tryParsePsbtRaw;
+exports.isInspectEnabled = isInspectEnabled;
+const wasm_utxo_js_1 = require("../wasm/wasm_utxo.js");
+/** All supported networks in order of parsing priority */
+exports.allNetworks = [
+    "btc",
+    "tbtc",
+    "tbtc4",
+    "tbtcsig",
+    "tbtcbgsig",
+    "ltc",
+    "tltc",
+    "bch",
+    "tbch",
+    "bcha",
+    "tbcha",
+    "btg",
+    "tbtg",
+    "bsv",
+    "tbsv",
+    "dash",
+    "tdash",
+    "doge",
+    "tdoge",
+    "zec",
+    "tzec",
+];
+/**
+ * Parse a PSBT and return a typed node tree.
+ *
+ * @param psbtBytes - The raw PSBT bytes
+ * @param network - The network coin name (e.g., "btc", "ltc", "bch")
+ * @returns A Node tree representing the parsed PSBT structure
+ * @throws If the PSBT bytes are invalid or network is unknown
+ */
+function parsePsbtToNode(psbtBytes, network) {
+    const json = (0, wasm_utxo_js_1.parsePsbtToJson)(psbtBytes, network);
+    return JSON.parse(json);
+}
+/**
+ * Parse a transaction and return a typed node tree.
+ *
+ * @param txBytes - The raw transaction bytes
+ * @param network - The network coin name (e.g., "btc", "ltc", "bch")
+ * @returns A Node tree representing the parsed transaction structure
+ * @throws If the transaction bytes are invalid or network is unknown
+ */
+function parseTxToNode(txBytes, network) {
+    const json = (0, wasm_utxo_js_1.parseTxToJson)(txBytes, network);
+    return JSON.parse(json);
+}
+/**
+ * Try to parse a PSBT with all networks and return the first one that succeeds.
+ *
+ * @param psbtBytes - The raw PSBT bytes
+ * @param networks - Optional list of networks to try (defaults to all networks)
+ * @returns An object with the parsed Node and detected network, or null if all fail
+ */
+function tryParsePsbt(psbtBytes, networks = exports.allNetworks) {
+    for (const network of networks) {
+        try {
+            const node = parsePsbtToNode(psbtBytes, network);
+            return { node, network };
+        }
+        catch {
+            // Try next network
+        }
+    }
+    return null;
+}
+/**
+ * Try to parse a transaction with all networks and return the first one that succeeds.
+ *
+ * @param txBytes - The raw transaction bytes
+ * @param networks - Optional list of networks to try (defaults to all networks)
+ * @returns An object with the parsed Node and detected network, or null if all fail
+ */
+function tryParseTx(txBytes, networks = exports.allNetworks) {
+    for (const network of networks) {
+        try {
+            const node = parseTxToNode(txBytes, network);
+            return { node, network };
+        }
+        catch {
+            // Try next network
+        }
+    }
+    return null;
+}
+/**
+ * Parse a PSBT at the raw byte level and return a typed node tree.
+ *
+ * Unlike `parsePsbtToNode`, this function exposes the raw key-value pair
+ * structure as defined in BIP-174, showing:
+ * - Raw key type IDs and their human-readable names
+ * - Proprietary keys with their structured format
+ * - Unknown/unrecognized keys that standard parsers might skip
+ *
+ * @param psbtBytes - The raw PSBT bytes
+ * @param network - The network coin name (e.g., "btc", "ltc", "zec")
+ * @returns A Node tree representing the raw PSBT key-value structure
+ * @throws If the PSBT bytes are invalid or network is unknown
+ */
+function parsePsbtRawToNode(psbtBytes, network) {
+    const json = (0, wasm_utxo_js_1.parsePsbtRawToJson)(psbtBytes, network);
+    return JSON.parse(json);
+}
+/**
+ * Try to parse a raw PSBT with all networks and return the first one that succeeds.
+ *
+ * @param psbtBytes - The raw PSBT bytes
+ * @param networks - Optional list of networks to try (defaults to all networks)
+ * @returns An object with the parsed Node and detected network, or null if all fail
+ */
+function tryParsePsbtRaw(psbtBytes, networks = exports.allNetworks) {
+    for (const network of networks) {
+        try {
+            const node = parsePsbtRawToNode(psbtBytes, network);
+            return { node, network };
+        }
+        catch {
+            // Try next network
+        }
+    }
+    return null;
+}
+/**
+ * Check if the inspect feature is enabled in the WASM build.
+ *
+ * @returns true if the feature is enabled, false otherwise
+ */
+function isInspectEnabled() {
+    return (0, wasm_utxo_js_1.isInspectEnabled)();
+}

package/dist/cjs/js/transaction.d.ts

@@ -14,11 +14,30 @@ export interface ITransaction {
 export declare class Transaction implements ITransaction {
     private _wasm;
     private constructor();
+    /**
+     * Create an empty transaction (version 1, locktime 0)
+     */
+    static create(): Transaction;
     static fromBytes(bytes: Uint8Array): Transaction;
     /**
      * @internal Create from WASM instance directly (avoids re-parsing bytes)
      */
     static fromWasm(wasm: WasmTransaction): Transaction;
+    /**
+     * Add an input to the transaction
+     * @param txid - Previous transaction ID (hex string)
+     * @param vout - Output index being spent
+     * @param sequence - Optional sequence number (default: 0xFFFFFFFF)
+     * @returns The index of the newly added input
+     */
+    addInput(txid: string, vout: number, sequence?: number): number;
+    /**
+     * Add an output to the transaction
+     * @param script - Output script (scriptPubKey)
+     * @param value - Value in satoshis
+     * @returns The index of the newly added output
+     */
+    addOutput(script: Uint8Array, value: bigint): number;
     toBytes(): Uint8Array;
     /**
      * Get the transaction ID (txid)

package/dist/cjs/js/transaction.js

@@ -12,6 +12,12 @@ class Transaction {
     constructor(_wasm) {
         this._wasm = _wasm;
     }
+    /**
+     * Create an empty transaction (version 1, locktime 0)
+     */
+    static create() {
+        return new Transaction(wasm_utxo_js_1.WasmTransaction.create());
+    }
     static fromBytes(bytes) {
         return new Transaction(wasm_utxo_js_1.WasmTransaction.from_bytes(bytes));
     }
@@ -21,6 +27,25 @@ class Transaction {
     static fromWasm(wasm) {
         return new Transaction(wasm);
     }
+    /**
+     * Add an input to the transaction
+     * @param txid - Previous transaction ID (hex string)
+     * @param vout - Output index being spent
+     * @param sequence - Optional sequence number (default: 0xFFFFFFFF)
+     * @returns The index of the newly added input
+     */
+    addInput(txid, vout, sequence) {
+        return this._wasm.add_input(txid, vout, sequence);
+    }
+    /**
+     * Add an output to the transaction
+     * @param script - Output script (scriptPubKey)
+     * @param value - Value in satoshis
+     * @returns The index of the newly added output
+     */
+    addOutput(script, value) {
+        return this._wasm.add_output(script, value);
+    }
     toBytes() {
         return this._wasm.to_bytes();
     }

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

@@ -181,7 +181,7 @@ export class BitGoPsbt {
      * # Returns
      * The index of the newly added input
      */
-    add_replay_protection_input(ecpair: WasmECPair, txid: string, vout: number, value: bigint, sequence?: number | null): number;
+    add_replay_protection_input(ecpair: WasmECPair, txid: string, vout: number, value: bigint, sequence?: number | null, prev_tx?: Uint8Array | null): number;
     /**
      * Add a wallet input with full PSBT metadata
      *
@@ -756,6 +756,16 @@ export class FixedScriptWalletNamespace {
     static create_op_return_script(data?: Uint8Array | null): Uint8Array;
     static output_script(keys: WasmRootWalletKeys, chain: number, index: number, network: any): Uint8Array;
     static output_script_with_network_str(keys: WasmRootWalletKeys, chain: number, index: number, network: string): Uint8Array;
+    /**
+     * Get the P2SH-P2PK output script for a compressed public key
+     *
+     * # Arguments
+     * * `pubkey` - The compressed public key bytes (33 bytes)
+     *
+     * # Returns
+     * The P2SH-P2PK output script as bytes
+     */
+    static p2sh_p2pk_output_script(pubkey: Uint8Array): Uint8Array;
     /**
      * Check if a network supports a given fixed-script wallet script type
      *
@@ -1220,6 +1230,33 @@ export class WasmTransaction {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Add an input to the transaction
+     *
+     * # Arguments
+     * * `txid` - The transaction ID (hex string) of the output being spent
+     * * `vout` - The output index being spent
+     * * `sequence` - Optional sequence number (default: 0xFFFFFFFF)
+     *
+     * # Returns
+     * The index of the newly added input
+     */
+    add_input(txid: string, vout: number, sequence?: number | null): number;
+    /**
+     * Add an output to the transaction
+     *
+     * # 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;
+    /**
+     * Create an empty transaction (version 1, locktime 0)
+     */
+    static create(): WasmTransaction;
     /**
      * Deserialize a transaction from bytes
      *
@@ -1497,3 +1534,74 @@ export class WrapPsbt {
      */
     version(): number;
 }
+
+/**
+ * Check if the inspect feature is enabled.
+ *
+ * # Returns
+ * `true` if the feature is enabled, `false` otherwise
+ */
+export function isInspectEnabled(): boolean;
+
+/**
+ * Parse a PSBT at the raw byte level and return a JSON representation.
+ *
+ * Unlike `parsePsbtToJson`, this function exposes the raw key-value pair
+ * structure as defined in BIP-174, showing:
+ * - Raw key type IDs and their human-readable names
+ * - Proprietary keys with their structured format
+ * - Unknown/unrecognized keys that standard parsers might skip
+ *
+ * # Arguments
+ * * `psbt_bytes` - The raw PSBT bytes
+ * * `coin_name` - The network coin name (e.g., "btc", "ltc", "zec")
+ *
+ * # Returns
+ * A JSON string representing the raw PSBT key-value structure
+ *
+ * # Errors
+ * Returns an error if:
+ * - The `inspect` feature is not enabled
+ * - The PSBT bytes are invalid
+ * - The network name is unknown
+ */
+export function parsePsbtRawToJson(psbt_bytes: Uint8Array, coin_name: string): string;
+
+/**
+ * Parse a PSBT and return a JSON representation of its structure.
+ *
+ * This function parses the PSBT using the standard bitcoin crate parser
+ * and returns a hierarchical node structure suitable for display.
+ *
+ * # Arguments
+ * * `psbt_bytes` - The raw PSBT bytes
+ * * `coin_name` - The network coin name (e.g., "btc", "ltc", "bch")
+ *
+ * # Returns
+ * A JSON string representing the parsed PSBT structure
+ *
+ * # Errors
+ * Returns an error if:
+ * - The `inspect` feature is not enabled
+ * - The PSBT bytes are invalid
+ * - The network name is unknown
+ */
+export function parsePsbtToJson(psbt_bytes: Uint8Array, coin_name: string): string;
+
+/**
+ * Parse a transaction and return a JSON representation of its structure.
+ *
+ * # Arguments
+ * * `tx_bytes` - The raw transaction bytes
+ * * `coin_name` - The network coin name (e.g., "btc", "ltc", "bch")
+ *
+ * # Returns
+ * A JSON string representing the parsed transaction structure
+ *
+ * # Errors
+ * Returns an error if:
+ * - The `inspect` feature is not enabled
+ * - The transaction bytes are invalid
+ * - The network name is unknown
+ */
+export function parseTxToJson(tx_bytes: Uint8Array, coin_name: string): string;