feat(wasm-utxo): port descriptor wallet functionality from utxo-core

This commit adds descriptor wallet functionality to wasm-utxo that was
previously in @bitgo/utxo-core. It introduces a new `descriptorWallet`
module with comprehensive support for descriptor-based wallet operations
including:

- Descriptor map handling and derivation
- Output and address management
- Virtual size calculation
- PSBT creation and parsing
- Pattern matching for descriptor ASTs
- Script satisfaction testing

The port removes the dependency on utxolib by using wasm-utxo's native
classes directly, simplifying the code path for descriptor wallet
operations.

Issue: BTC-2866

Co-authored-by: llm-git <llm-git@ttll.de>

Author: OttoAllmendinger

packages/wasm-utxo/js/descriptorWallet/DescriptorMap.ts

@@ -0,0 +1,20 @@
+/**
+ * DescriptorMap type and utilities.
+ * Moved from @bitgo/utxo-core.
+ */
+import { Descriptor } from "../index.js";
+
+/** Map from descriptor name to descriptor (TypeScript Map) */
+export type DescriptorMap = Map<string, Descriptor>;
+
+/** Convert an array of descriptor name-value pairs to a descriptor map */
+export function toDescriptorMap(
+  descriptors: { name: string; value: Descriptor | string }[],
+): DescriptorMap {
+  return new Map(
+    descriptors.map((d) => [
+      d.name,
+      d.value instanceof Descriptor ? d.value : Descriptor.fromStringDetectType(d.value),
+    ]),
+  );
+}

packages/wasm-utxo/js/descriptorWallet/DescriptorOutput.ts

@@ -0,0 +1,67 @@
+/**
+ * Descriptor output types and utilities.
+ * Moved from @bitgo/utxo-core.
+ */
+import { Descriptor } from "../index.js";
+
+import { getFixedOutputSum, MaxOutput, Output, PrevOutput } from "./Output.js";
+import { DescriptorMap } from "./DescriptorMap.js";
+import { getDescriptorAtIndexCheckScript } from "./derive.js";
+
+export type WithDescriptor<T> = T & {
+  descriptor: Descriptor;
+};
+
+export type WithOptDescriptor<T> = T & {
+  descriptor?: Descriptor;
+};
+
+export function isInternalOutput<T extends object>(
+  output: T | WithDescriptor<T>,
+): output is WithDescriptor<T> {
+  return "descriptor" in output && output.descriptor !== undefined;
+}
+
+export function isExternalOutput<T extends object>(output: T | WithDescriptor<T>): output is T {
+  return !isInternalOutput(output);
+}
+
+/**
+ * @return the sum of the external outputs that are not 'max'
+ * @param outputs
+ */
+export function getExternalFixedAmount(outputs: WithOptDescriptor<Output | MaxOutput>[]): bigint {
+  return getFixedOutputSum(outputs.filter(isExternalOutput));
+}
+
+export type DescriptorWalletOutput = PrevOutput & {
+  descriptorName: string;
+  descriptorIndex: number | undefined;
+};
+
+export type DerivedDescriptorWalletOutput = WithDescriptor<PrevOutput>;
+
+export function toDerivedDescriptorWalletOutput(
+  output: DescriptorWalletOutput,
+  descriptorMap: DescriptorMap,
+): DerivedDescriptorWalletOutput {
+  const descriptor = descriptorMap.get(output.descriptorName);
+  if (!descriptor) {
+    throw new Error(`Descriptor not found: ${output.descriptorName}`);
+  }
+  if (!(descriptor instanceof Descriptor)) {
+    throw new Error(`Expected Descriptor instance for ${output.descriptorName}`);
+  }
+  const descriptorAtIndex = getDescriptorAtIndexCheckScript(
+    descriptor,
+    output.descriptorIndex,
+    output.witnessUtxo.script,
+    output.descriptorName,
+  );
+  return {
+    hash: output.hash,
+    index: output.index,
+    witnessUtxo: output.witnessUtxo,
+    descriptor: descriptorAtIndex,
+  };
+}

packages/wasm-utxo/js/descriptorWallet/MIGRATION.md

@@ -0,0 +1,85 @@
+# Migration Guide: utxo-core/descriptor to wasm-utxo/descriptorWallet
+
+This module provides descriptor wallet functionality that was previously in `@bitgo/utxo-core`.
+
+## Import Changes
+
+### Before (utxo-core)
+
+```typescript
+import {
+  DescriptorMap,
+  toDescriptorMap,
+  findDescriptorForInput,
+  createPsbt,
+  parse,
+  getDescriptorAtIndex,
+  createScriptPubKeyFromDescriptor,
+  getVirtualSize,
+} from "@bitgo/utxo-core/descriptor";
+```
+
+### After (wasm-utxo)
+
+```typescript
+import { descriptorWallet } from "@bitgo/wasm-utxo";
+
+const {
+  toDescriptorMap,
+  findDescriptorForInput,
+  createPsbt,
+  parse,
+  getDescriptorAtIndex,
+  createScriptPubKeyFromDescriptor,
+  getVirtualSize,
+} = descriptorWallet;
+```
+
+## API Changes
+
+### PSBT Creation
+
+The `createPsbt` function returns a `wasm-utxo.Psbt` instead of `utxolib.bitgo.UtxoPsbt`.
+
+```typescript
+// Before: Returns utxolib.bitgo.UtxoPsbt
+const psbt = createPsbt(params, inputs, outputs);
+
+// After: Returns wasm-utxo Psbt
+const psbt = descriptorWallet.createPsbt(params, inputs, outputs);
+```
+
+### Address Creation
+
+The `createAddressFromDescriptor` function takes a `CoinName` instead of `utxolib.Network`:
+
+```typescript
+// Before
+createAddressFromDescriptor(descriptor, index, utxolib.networks.bitcoin);
+
+// After
+descriptorWallet.createAddressFromDescriptor(descriptor, index, "Bitcoin");
+```
+
+### Signing
+
+Use `signWithKey` from the descriptorWallet module:
+
+```typescript
+// Before
+tx.signInputHD(vin, signerKeychain);
+
+// After
+descriptorWallet.signWithKey(psbt, signerKeychain);
+```
+
+## Not Ported
+
+The following are intentionally **not** included in this migration:
+
+- `fromFixedScriptWallet` - Converting fixed-script wallets to descriptors should remain in utxo-core or abstract-utxo
+
+## Network Support
+
+Descriptor wallets are currently only supported for Bitcoin mainnet and testnet.
+Altcoin descriptor wallets should continue using the fixed-script wallet approach.

packages/wasm-utxo/js/descriptorWallet/Output.ts

@@ -0,0 +1,79 @@
+/**
+ * Output types and utilities for descriptor wallets.
+ * Moved from @bitgo/utxo-core.
+ */
+
+export type Output<TValue = bigint> = {
+  script: Uint8Array;
+  value: TValue;
+};
+export type MaxOutput = Output<"max">;
+type ValueBigInt = { value: bigint };
+type ValueMax = { value: "max" };
+
+/**
+ * @return true if the output is a max output
+ */
+export function isMaxOutput<A extends ValueBigInt, B extends ValueMax>(output: A | B): output is B {
+  return output.value === "max";
+}
+
+/**
+ * @return the max output if there is one
+ * @throws if there are multiple max outputs
+ */
+export function getMaxOutput<A extends ValueBigInt, B extends ValueMax>(
+  outputs: (A | B)[],
+): B | undefined {
+  const max = outputs.filter(isMaxOutput<A, B>);
+  if (max.length === 0) {
+    return undefined;
+  }
+  if (max.length > 1) {
+    throw new Error("Multiple max outputs");
+  }
+  return max[0];
+}
+
+/**
+ * @return the sum of the outputs
+ */
+export function getOutputSum(outputs: ValueBigInt[]): bigint {
+  return outputs.reduce((sum, output) => sum + output.value, 0n);
+}
+
+/**
+ * @return the sum of the outputs that are not 'max'
+ */
+export function getFixedOutputSum(outputs: (ValueBigInt | ValueMax)[]): bigint {
+  return getOutputSum(outputs.filter((o): o is Output => !isMaxOutput(o)));
+}
+
+/**
+ * @param outputs
+ * @param params
+ * @return the outputs with the 'max' output replaced with the max amount
+ */
+export function toFixedOutputs<A extends ValueBigInt, B extends ValueMax>(
+  outputs: (A | B)[],
+  params: { maxAmount: bigint },
+): A[] {
+  // assert that there is at most one max output
+  const maxOutput = getMaxOutput<A, B>(outputs);
+  return outputs.map((output): A => {
+    if (isMaxOutput(output)) {
+      if (output !== maxOutput) {
+        throw new Error("illegal state");
+      }
+      return { ...output, value: params.maxAmount };
+    } else {
+      return output;
+    }
+  });
+}
+
+export type PrevOutput = {
+  hash: string;
+  index: number;
+  witnessUtxo: Output;
+};

packages/wasm-utxo/js/descriptorWallet/VirtualSize.ts

@@ -0,0 +1,141 @@
+/**
+ * Virtual size estimation for descriptor wallets.
+ * Moved from @bitgo/utxo-core.
+ */
+import { Descriptor, Psbt } from "../index.js";
+import { Dimensions } from "../fixedScriptWallet/Dimensions.js";
+
+import { DescriptorMap } from "./DescriptorMap.js";
+
+// Transaction overhead for segwit transactions
+// 4 (version) + 1 (marker) + 1 (flag) + 1 (input count) + 1 (output count) + 4 (locktime) = 12
+// Weight units: 4*10 + 2 = 42, vsize = ceil(42/4) = 10.5
+const TX_SEGWIT_OVERHEAD_VSIZE = 10.5;
+
+function getScriptPubKeyLength(descType: string): number {
+  // See https://bitcoinops.org/en/tools/calc-size/
+  switch (descType) {
+    case "Wpkh":
+      // https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#p2wpkh
+      return 22;
+    case "Sh":
+    case "ShWsh":
+    case "ShWpkh":
+      // https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki#specification
+      return 23;
+    case "Pkh":
+      return 25;
+    case "Wsh":
+    case "Tr":
+      // P2WSH: https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#p2wsh
+      // P2TR: https://github.com/bitcoin/bips/blob/58ffd93812ff25e87d53d1f202fbb389fdfb85bb/bip-0341.mediawiki#script-validation-rules
+      // > A Taproot output is a native SegWit output (see BIP141) with version number 1, and a 32-byte witness program.
+      // 32 bytes for the hash, 1 byte for the version, 1 byte for the push opcode
+      return 34;
+    case "Bare":
+      throw new Error("cannot determine scriptPubKey length for Bare descriptor");
+    default:
+      throw new Error("unexpected descriptor type " + descType);
+  }
+}
+
+function getInputVSizeForDescriptor(descriptor: Descriptor): number {
+  // FIXME(BTC-1489): this can overestimate the size of the input significantly
+  const maxWeight = descriptor.maxWeightToSatisfy();
+  const maxVSize = Math.ceil(maxWeight / 4);
+  const sizeOpPushdata1 = 1;
+  const sizeOpPushdata2 = 2;
+  return (
+    // inputId
+    32 +
+    // vOut
+    4 +
+    // nSequence
+    4 +
+    // script overhead
+    (maxVSize < 255 ? sizeOpPushdata1 : sizeOpPushdata2) +
+    // script
+    maxVSize
+  );
+}
+
+export function getInputVSizesForDescriptors(descriptors: DescriptorMap): Record<string, number> {
+  return Object.fromEntries(
+    Array.from(descriptors.entries()).map(([name, d]) => {
+      return [name, getInputVSizeForDescriptor(d)];
+    }),
+  );
+}
+
+export function getChangeOutputVSizesForDescriptor(d: Descriptor): {
+  inputVSize: number;
+  outputVSize: number;
+} {
+  return {
+    inputVSize: getInputVSizeForDescriptor(d),
+    outputVSize: getScriptPubKeyLength(d.descType() as string),
+  };
+}
+
+type InputWithDescriptorName = { descriptorName: string };
+type OutputWithScript = { script: Uint8Array };
+
+type Tx<TInput> = {
+  inputs: TInput[];
+  outputs: OutputWithScript[];
+};
+
+export function getVirtualSize(tx: Tx<Descriptor>): number;
+export function getVirtualSize(tx: Tx<InputWithDescriptorName>, descriptors: DescriptorMap): number;
+export function getVirtualSize(
+  tx: Tx<Descriptor> | Tx<InputWithDescriptorName>,
+  descriptorMap?: DescriptorMap,
+): number {
+  const lookup = descriptorMap ? getInputVSizesForDescriptors(descriptorMap) : undefined;
+  const inputVSize = tx.inputs.reduce((sum, input) => {
+    if (input instanceof Descriptor) {
+      return sum + getInputVSizeForDescriptor(input);
+    }
+    if ("descriptorName" in input) {
+      if (!lookup) {
+        throw new Error("missing descriptorMap");
+      }
+      const vsize = lookup[input.descriptorName];
+      if (!vsize) {
+        throw new Error(`Could not find descriptor ${input.descriptorName}`);
+      }
+      return sum + vsize;
+    }
+    throw new Error("unexpected input");
+  }, 0);
+
+  const outputVSize = tx.outputs.reduce((sum, o) => {
+    // Use the Dimensions class to calculate output vsize
+    return sum + Dimensions.fromOutput({ length: o.script.length }).getOutputVSize();
+  }, 0);
+
+  // we will just assume that we have at least one segwit input
+  return inputVSize + outputVSize + TX_SEGWIT_OVERHEAD_VSIZE;
+}
+
+export function getVirtualSizeEstimateForPsbt(psbt: Psbt, descriptorMap: DescriptorMap): number {
+  const inputCount = psbt.inputCount();
+  const outputCount = psbt.outputCount();
+
+  // Calculate a rough estimate based on descriptor map
+  // For a more accurate estimation, we would need to deserialize the PSBT data
+  let totalInputVSize = 0;
+  for (const descriptor of descriptorMap.values()) {
+    totalInputVSize += getInputVSizeForDescriptor(descriptor);
+  }
+
+  // Average input size * input count
+  const avgInputVSize = descriptorMap.size > 0 ? totalInputVSize / descriptorMap.size : 100; // fallback
+
+  const inputVSize = avgInputVSize * inputCount;
+
+  // Assume P2WPKH outputs (34 bytes each) as a reasonable default
+  const outputVSize = outputCount * Dimensions.fromOutput({ length: 34 }).getOutputVSize();
+
+  return inputVSize + outputVSize + TX_SEGWIT_OVERHEAD_VSIZE;
+}