@bitgo/wasm-utxo 1.43.0 → 2.0.0

package/dist/esm/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/esm/js/inspect/index.js

@@ -0,0 +1,140 @@
+/**
+ * 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 { parsePsbtToJson as wasmParsePsbtToJson, parseTxToJson as wasmParseTxToJson, parsePsbtRawToJson as wasmParsePsbtRawToJson, isInspectEnabled as wasmIsInspectEnabled, } from "../wasm/wasm_utxo.js";
+/** All supported networks in order of parsing priority */
+export const 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
+ */
+export function parsePsbtToNode(psbtBytes, network) {
+    const json = wasmParsePsbtToJson(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
+ */
+export function parseTxToNode(txBytes, network) {
+    const json = wasmParseTxToJson(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
+ */
+export function tryParsePsbt(psbtBytes, networks = 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
+ */
+export function tryParseTx(txBytes, networks = 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
+ */
+export function parsePsbtRawToNode(psbtBytes, network) {
+    const json = wasmParsePsbtRawToJson(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
+ */
+export function tryParsePsbtRaw(psbtBytes, networks = 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
+ */
+export function isInspectEnabled() {
+    return wasmIsInspectEnabled();
+}

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

@@ -1,13 +1,20 @@
 import type { PsbtInputData, PsbtOutputData, PsbtOutputDataWithAddress } from "./wasm/wasm_utxo.js";
-/** Common interface for PSBT introspection methods */
-export interface IPsbtIntrospection {
-    readonly inputCount: number;
-    readonly outputCount: number;
+/** Common interface for PSBT types */
+export interface IPsbt {
+    inputCount(): number;
+    outputCount(): number;
     getInputs(): PsbtInputData[];
     getOutputs(): PsbtOutputData[];
+    version(): number;
+    lockTime(): number;
+    unsignedTxId(): string;
+    addInputAtIndex(index: number, txid: string, vout: number, value: bigint, script: Uint8Array, sequence?: number): number;
+    addOutputAtIndex(index: number, script: Uint8Array, value: bigint): number;
+    removeInput(index: number): void;
+    removeOutput(index: number): void;
 }
-/** Extended introspection with address resolution (no coin parameter needed) */
-export interface IPsbtIntrospectionWithAddress extends IPsbtIntrospection {
+/** Extended PSBT with address resolution (no coin parameter needed) */
+export interface IPsbtWithAddress extends IPsbt {
     getOutputsWithAddress(): PsbtOutputDataWithAddress[];
 }
 /**

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

@@ -30,13 +30,9 @@ export declare class Transaction implements ITransaction {
      * @param sequence - Optional sequence number (default: 0xFFFFFFFF)
      * @returns The index of the newly added input
      */
+    addInputAtIndex(index: number, txid: string, vout: number, sequence?: number): number;
     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
-     */
+    addOutputAtIndex(index: number, script: Uint8Array, value: bigint): number;
     addOutput(script: Uint8Array, value: bigint): number;
     toBytes(): Uint8Array;
     /**

package/dist/esm/js/transaction.js

@@ -31,15 +31,15 @@ export class Transaction {
      * @param sequence - Optional sequence number (default: 0xFFFFFFFF)
      * @returns The index of the newly added input
      */
+    addInputAtIndex(index, txid, vout, sequence) {
+        return this._wasm.add_input_at_index(index, txid, vout, sequence);
+    }
     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
-     */
+    addOutputAtIndex(index, script, value) {
+        return this._wasm.add_output_at_index(index, script, value);
+    }
     addOutput(script, value) {
         return this._wasm.add_output(script, value);
     }

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

@@ -116,6 +116,7 @@ export class BitGoPsbt {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    add_input(txid: string, vout: number, value: bigint, script: Uint8Array, sequence?: number | null, prev_tx?: Uint8Array | null): number;
     /**
      * Add an input to the PSBT
      *
@@ -129,29 +130,11 @@ export class BitGoPsbt {
      * # 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;
-    /**
-     * 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_input_at_index(index: number, txid: string, vout: number, value: bigint, script: Uint8Array, sequence?: number | null, prev_tx?: Uint8Array | null): number;
     add_output(script: Uint8Array, value: bigint): number;
-    /**
-     * Add an output to the PSBT by address
-     *
-     * # Arguments
-     * * `address` - The destination address
-     * * `value` - The value in satoshis
-     *
-     * # Returns
-     * The index of the newly added output
-     */
+    add_output_at_index(index: number, script: Uint8Array, value: bigint): number;
     add_output_with_address(address: string, value: bigint): number;
+    add_output_with_address_at_index(index: number, address: string, value: bigint): number;
     /**
      * Add a PayGo attestation to a PSBT output
      *
@@ -165,61 +148,12 @@ export class BitGoPsbt {
      * - `Err(WasmUtxoError)` if the output index is out of bounds or entropy is invalid
      */
     add_paygo_attestation(output_index: number, entropy: Uint8Array, signature: Uint8Array): void;
-    /**
-     * 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, prev_tx?: Uint8Array | null): 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.
-     *
-     * # 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_replay_protection_input_at_index(index: number, ecpair: WasmECPair, txid: string, vout: number, value: bigint, sequence?: number | null, prev_tx?: Uint8Array | null): number;
     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_input_at_index(index: number, txid: string, vout: number, value: bigint, wallet_keys: WasmRootWalletKeys, chain: number, derivation_index: number, signer?: string | null, cosigner?: string | null, sequence?: number | null, prev_tx?: Uint8Array | null): number;
     add_wallet_output(chain: number, index: number, value: bigint, wallet_keys: WasmRootWalletKeys): number;
+    add_wallet_output_at_index(index: number, chain: number, derivation_index: number, value: bigint, wallet_keys: WasmRootWalletKeys): number;
     /**
      * Combine/merge data from another PSBT into this one
      *
@@ -452,6 +386,8 @@ export class BitGoPsbt {
      * Parse transaction with wallet keys to identify wallet inputs/outputs
      */
     parse_transaction_with_wallet_keys(wallet_keys: WasmRootWalletKeys, replay_protection: WasmReplayProtection, paygo_pubkeys?: WasmECPair[] | null): any;
+    remove_input(index: number): void;
+    remove_output(index: number): void;
     /**
      * Serialize the PSBT to bytes
      *
@@ -1230,6 +1166,7 @@ export class WasmTransaction {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    add_input(txid: string, vout: number, sequence?: number | null): number;
     /**
      * Add an input to the transaction
      *
@@ -1241,18 +1178,9 @@ export class WasmTransaction {
      * # 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_input_at_index(index: number, txid: string, vout: number, sequence?: number | null): number;
     add_output(script: Uint8Array, value: bigint): number;
+    add_output_at_index(index: number, script: Uint8Array, value: bigint): number;
     /**
      * Create an empty transaction (version 1, locktime 0)
      */
@@ -1373,6 +1301,7 @@ export class WrapMiniscript {
 export class WrapPsbt {
     free(): void;
     [Symbol.dispose](): void;
+    addInput(txid: string, vout: number, value: bigint, script: Uint8Array, sequence?: number | null): number;
     /**
      * Add an input to the PSBT
      *
@@ -1386,7 +1315,8 @@ export class WrapPsbt {
      * # Returns
      * The index of the newly added input
      */
-    addInput(txid: string, vout: number, value: bigint, script: Uint8Array, sequence?: number | null): number;
+    addInputAtIndex(index: number, txid: string, vout: number, value: bigint, script: Uint8Array, sequence?: number | null): number;
+    addOutput(script: Uint8Array, value: bigint): number;
     /**
      * Add an output to the PSBT
      *
@@ -1397,7 +1327,7 @@ export class WrapPsbt {
      * # Returns
      * The index of the newly added output
      */
-    addOutput(script: Uint8Array, value: bigint): number;
+    addOutputAtIndex(index: number, script: Uint8Array, value: bigint): number;
     clone(): WrapPsbt;
     static deserialize(psbt: Uint8Array): WrapPsbt;
     /**
@@ -1469,6 +1399,8 @@ export class WrapPsbt {
      * Get the number of outputs in the PSBT
      */
     outputCount(): number;
+    removeInput(index: number): void;
+    removeOutput(index: number): void;
     serialize(): Uint8Array;
     /**
      * Sign all inputs with a WasmBIP32 key
@@ -1534,3 +1466,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/esm/js/wasm/wasm_utxo.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./wasm_utxo_bg.js";
 __wbg_set_wasm(wasm);
 
 export {
-    AddressNamespace, Bip322Namespace, BitGoPsbt, FixedScriptWalletNamespace, InscriptionsNamespace, MessageNamespace, UtxolibCompatNamespace, WasmBIP32, WasmDashTransaction, WasmDimensions, WasmECPair, WasmReplayProtection, WasmRootWalletKeys, WasmTransaction, WasmZcashTransaction, WrapDescriptor, WrapMiniscript, WrapPsbt
+    AddressNamespace, Bip322Namespace, BitGoPsbt, FixedScriptWalletNamespace, InscriptionsNamespace, MessageNamespace, UtxolibCompatNamespace, WasmBIP32, WasmDashTransaction, WasmDimensions, WasmECPair, WasmReplayProtection, WasmRootWalletKeys, WasmTransaction, WasmZcashTransaction, WrapDescriptor, WrapMiniscript, WrapPsbt, isInspectEnabled, parsePsbtRawToJson, parsePsbtToJson, parseTxToJson
 } from "./wasm_utxo_bg.js";