feat(utxo-core): add descriptor support for fixed script wallets

Add functionality to generate output descriptors compatible with BitGo's
proprietary HD wallet setup. Support p2sh, p2shP2wsh, and p2wsh script
types for both internal and external chains.

Issue: BTC-2170

Co-authored-by: llm-git <[email protected]>

Author: OttoAllmendinger

modules/utxo-core/src/descriptor/fromFixedScriptWallet.ts

@@ -0,0 +1,53 @@
+import * as utxolib from '@bitgo/utxo-lib';
+import { Descriptor, ast } from '@bitgo/wasm-miniscript';
+
+import { DescriptorMap } from './DescriptorMap';
+
+/** Expand a template with the given root wallet keys and chain code */
+function expand(rootWalletKeys: utxolib.bitgo.RootWalletKeys, keyIndex: number, chainCode: number): string {
+  if (keyIndex !== 0 && keyIndex !== 1 && keyIndex !== 2) {
+    throw new Error('Invalid key index');
+  }
+  const xpub = rootWalletKeys.triple[keyIndex].neutered().toBase58();
+  const prefix = rootWalletKeys.derivationPrefixes[keyIndex];
+  return xpub + '/' + prefix + '/' + chainCode + '/*';
+}
+
+/**
+ * Get a standard output descriptor that corresponds to the proprietary HD wallet setup
+ * used in BitGo wallets.
+ * Only supports a subset of script types.
+ */
+export function getDescriptorForScriptType(
+  rootWalletKeys: utxolib.bitgo.RootWalletKeys,
+  scriptType: 'p2sh' | 'p2shP2wsh' | 'p2wsh',
+  scope: 'internal' | 'external'
+): Descriptor {
+  const chain =
+    scope === 'external'
+      ? utxolib.bitgo.getExternalChainCode(scriptType)
+      : utxolib.bitgo.getInternalChainCode(scriptType);
+  const multi: ast.MiniscriptNode = {
+    multi: [2, ...rootWalletKeys.triple.map((_, i) => expand(rootWalletKeys, i, chain))],
+  };
+  switch (scriptType) {
+    case 'p2sh':
+      return Descriptor.fromString(ast.formatNode({ sh: multi }), 'derivable');
+    case 'p2shP2wsh':
+      return Descriptor.fromString(ast.formatNode({ sh: { wsh: multi } }), 'derivable');
+    case 'p2wsh':
+      return Descriptor.fromString(ast.formatNode({ wsh: multi }), 'derivable');
+    default:
+      throw new Error(`Unsupported script type ${scriptType}`);
+  }
+}
+
+export function getNamedDescriptorsForRootWalletKeys(rootWalletKeys: utxolib.bitgo.RootWalletKeys): DescriptorMap {
+  const scriptTypes = ['p2sh', 'p2shP2wsh', 'p2wsh'] as const;
+  const scopes = ['external', 'internal'] as const;
+  return new Map(
+    scriptTypes.flatMap((scriptType) =>
+      scopes.map((scope) => [`${scriptType}/${scope}`, getDescriptorForScriptType(rootWalletKeys, scriptType, scope)])
+    )
+  );
+}

modules/utxo-core/test/descriptor/fromFixedScriptWallet.ts

@@ -0,0 +1,133 @@
+import * as assert from 'node:assert/strict';
+
+import * as utxolib from '@bitgo/utxo-lib';
+import { Descriptor } from '@bitgo/wasm-miniscript';
+
+import {
+  getDescriptorForScriptType,
+  getNamedDescriptorsForRootWalletKeys,
+} from '../../src/descriptor/fromFixedScriptWallet';
+
+function getRootWalletKeys(derivationPrefixes?: utxolib.bitgo.Triple<string>): utxolib.bitgo.RootWalletKeys {
+  // This is a fixed script wallet, so we use a fixed key triple.
+  // In practice, this would be derived from the wallet's root keys.
+  return new utxolib.bitgo.RootWalletKeys(utxolib.testutil.getKeyTriple('fixedScript'), derivationPrefixes);
+}
+
+const customPrefixes: (utxolib.bitgo.Triple<string> | undefined)[] = [
+  undefined,
+  ['1/2', '1/2', '1/2'], // Custom prefixes for testing
+  ['1/2', '3/4', '5/6'], // Different custom prefixes
+];
+const scriptTypes = ['p2sh', 'p2shP2wsh', 'p2wsh'] as const;
+const scope = ['external', 'internal'] as const;
+const index = [0, 1, 2];
+
+/** Get the expected max weight to satisfy the descriptor */
+function getExpectedMaxWeightToSatisfy(scriptType: utxolib.bitgo.outputScripts.ScriptType2Of3) {
+  switch (scriptType) {
+    case 'p2sh':
+      return 256;
+    case 'p2shP2wsh':
+      return 99;
+    case 'p2wsh':
+      return 64;
+    default:
+      throw new Error('unexpected script type');
+  }
+}
+
+/** Compute the total size of the input, including overhead */
+function getTotalInputSize(vSize: number) {
+  const sizeOpPushData1 = 1;
+  const sizeOpPushData2 = 2;
+  return 32 /* txid */ + 4 /* vout */ + 4 /* nSequence */ + (vSize < 255 ? sizeOpPushData1 : sizeOpPushData2) + vSize;
+}
+
+/** Get the full expected vSize of the input including overhead */
+function getExpectedVSize(scriptType: utxolib.bitgo.outputScripts.ScriptType2Of3) {
+  // https://github.com/BitGo/BitGoJS/blob/master/modules/unspents/docs/input-costs.md
+  switch (scriptType) {
+    case 'p2sh':
+      return 298;
+    case 'p2shP2wsh':
+      return 140;
+    case 'p2wsh':
+      return 105;
+    default:
+      throw new Error('unexpected script type');
+  }
+}
+
+function runTestGetDescriptorWithScriptType(
+  customPrefix: utxolib.bitgo.Triple<string> | undefined,
+  scriptType: 'p2sh' | 'p2shP2wsh' | 'p2wsh',
+  index: number,
+  scope: 'internal' | 'external'
+) {
+  describe(`customPrefix=${customPrefix}, scriptType=${scriptType}, index=${index}, scope=${scope}`, function () {
+    const rootWalletKeys = getRootWalletKeys(customPrefix);
+    const chainCode =
+      scope === 'external'
+        ? utxolib.bitgo.getExternalChainCode(scriptType)
+        : utxolib.bitgo.getInternalChainCode(scriptType);
+    const derivedKeys = rootWalletKeys.deriveForChainAndIndex(chainCode, index);
+    const scriptUtxolib = utxolib.bitgo.outputScripts.createOutputScript2of3(
+      derivedKeys.publicKeys,
+      scriptType
+    ).scriptPubKey;
+
+    let descriptor: Descriptor;
+
+    before(function () {
+      descriptor = getDescriptorForScriptType(rootWalletKeys, scriptType, scope);
+    });
+
+    it('address should match descriptor', function () {
+      const scriptFromDescriptor = Buffer.from(descriptor.atDerivationIndex(index).scriptPubkey());
+      assert.deepStrictEqual(scriptUtxolib.toString('hex'), scriptFromDescriptor.toString('hex'));
+    });
+
+    it('should have expected weights', function () {
+      assert.ok(Number.isInteger(descriptor.maxWeightToSatisfy()));
+      const vSize = Math.ceil(descriptor.maxWeightToSatisfy() / 4);
+      assert.equal(vSize, getExpectedMaxWeightToSatisfy(scriptType));
+      assert.equal(getTotalInputSize(vSize), getExpectedVSize(scriptType));
+    });
+  });
+}
+
+function runTestGetDescriptorMap(customPrefix: utxolib.bitgo.Triple<string> | undefined) {
+  describe(`getNamedDescriptorsForRootWalletKeys with customPrefix=${customPrefix}`, function () {
+    const rootWalletKeys = getRootWalletKeys(customPrefix);
+    const descriptorMap = getNamedDescriptorsForRootWalletKeys(rootWalletKeys);
+
+    it('should return a map with the correct number of entries', function () {
+      assert.equal(descriptorMap.size, scriptTypes.length * scope.length);
+    });
+
+    scriptTypes.forEach((scriptType) => {
+      scope.forEach((s) => {
+        const key = `${scriptType}/${s}`;
+        it(`should have a correct descriptor for ${key}`, function () {
+          const descriptorFromMap = descriptorMap.get(key);
+          assert.ok(descriptorFromMap, `Descriptor for ${key} should exist`);
+          const expectedDescriptor = getDescriptorForScriptType(rootWalletKeys, scriptType, s);
+          assert.equal(descriptorFromMap.toString(), expectedDescriptor.toString());
+        });
+      });
+    });
+  });
+}
+
+customPrefixes.forEach((customPrefix) => {
+  scriptTypes.forEach((scriptType) => {
+    index.forEach((index) => {
+      scope.forEach((scope) => {
+        runTestGetDescriptorWithScriptType(customPrefix, scriptType, index, scope);
+      });
+    });
+  });
+
+  runTestGetDescriptorMap(customPrefix);
+});