@bitgo/wasm-utxo 1.43.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/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/wasm/wasm_utxo.d.ts

@@ -1534,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;

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

@@ -4778,6 +4778,175 @@ class WrapPsbt {
 if (Symbol.dispose) WrapPsbt.prototype[Symbol.dispose] = WrapPsbt.prototype.free;
 exports.WrapPsbt = WrapPsbt;
 
+/**
+ * Check if the inspect feature is enabled.
+ *
+ * # Returns
+ * `true` if the feature is enabled, `false` otherwise
+ * @returns {boolean}
+ */
+function isInspectEnabled() {
+    const ret = wasm.isInspectEnabled();
+    return ret !== 0;
+}
+exports.isInspectEnabled = isInspectEnabled;
+
+/**
+ * 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
+ * @param {Uint8Array} psbt_bytes
+ * @param {string} coin_name
+ * @returns {string}
+ */
+function parsePsbtRawToJson(psbt_bytes, coin_name) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passArray8ToWasm0(psbt_bytes, wasm.__wbindgen_export);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(coin_name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.parsePsbtRawToJson(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr3 = r0;
+        var len3 = r1;
+        if (r3) {
+            ptr3 = 0; len3 = 0;
+            throw takeObject(r2);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred4_0, deferred4_1, 1);
+    }
+}
+exports.parsePsbtRawToJson = parsePsbtRawToJson;
+
+/**
+ * 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
+ * @param {Uint8Array} psbt_bytes
+ * @param {string} coin_name
+ * @returns {string}
+ */
+function parsePsbtToJson(psbt_bytes, coin_name) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passArray8ToWasm0(psbt_bytes, wasm.__wbindgen_export);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(coin_name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.parsePsbtRawToJson(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr3 = r0;
+        var len3 = r1;
+        if (r3) {
+            ptr3 = 0; len3 = 0;
+            throw takeObject(r2);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred4_0, deferred4_1, 1);
+    }
+}
+exports.parsePsbtToJson = parsePsbtToJson;
+
+/**
+ * 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
+ * @param {Uint8Array} tx_bytes
+ * @param {string} coin_name
+ * @returns {string}
+ */
+function parseTxToJson(tx_bytes, coin_name) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passArray8ToWasm0(tx_bytes, wasm.__wbindgen_export);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(coin_name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.parsePsbtRawToJson(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr3 = r0;
+        var len3 = r1;
+        if (r3) {
+            ptr3 = 0; len3 = 0;
+            throw takeObject(r2);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred4_0, deferred4_1, 1);
+    }
+}
+exports.parseTxToJson = parseTxToJson;
+
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,