Merge pull request #5258 from BitGo/BTC-1450.descriptorBuilder

feat(abstract-utxo): add DescriptorBuilder and parser

Author: OttoAllmendinger

modules/abstract-utxo/src/descriptor/builder/builder.ts

@@ -0,0 +1,52 @@
+import { BIP32Interface } from '@bitgo/utxo-lib';
+import { Descriptor } from '@bitgo/wasm-miniscript';
+
+type DescriptorWithKeys<TName extends string> = {
+  name: TName;
+  keys: BIP32Interface[];
+  path: string;
+};
+
+export type DescriptorBuilder =
+  | DescriptorWithKeys<'Wsh2Of2'>
+  | DescriptorWithKeys<'Wsh2Of3'>
+  /*
+   * This is a wrapped segwit 2of3 multisig that also uses a relative locktime with
+   * an OP_DROP (requiring a miniscript extension).
+   * It is basically what is used in CoreDao staking transactions.
+   */
+  | (DescriptorWithKeys<'ShWsh2Of3CltvDrop'> & { locktime: number });
+
+function toXPub(k: BIP32Interface | string): string {
+  if (typeof k === 'string') {
+    return k;
+  }
+  return k.neutered().toBase58();
+}
+
+function multi(m: number, n: number, keys: BIP32Interface[] | string[], path: string): string {
+  if (n < m) {
+    throw new Error(`Cannot create ${m} of ${n} multisig`);
+  }
+  if (keys.length < n) {
+    throw new Error(`Not enough keys for ${m} of ${n} multisig: keys.length=${keys.length}`);
+  }
+  keys = keys.slice(0, n);
+  return `multi(${m},${keys.map((k) => `${toXPub(k)}/${path}`).join(',')})`;
+}
+
+function getDescriptorString(builder: DescriptorBuilder): string {
+  switch (builder.name) {
+    case 'Wsh2Of3':
+      return `wsh(${multi(2, 3, builder.keys, builder.path)})`;
+    case 'Wsh2Of2':
+      return `wsh(${multi(2, 2, builder.keys, builder.path)})`;
+    case 'ShWsh2Of3CltvDrop':
+      return `sh(wsh(and_v(r:after(${builder.locktime}),${multi(2, 3, builder.keys, builder.path)})))`;
+  }
+  throw new Error(`Unknown descriptor template: ${builder}`);
+}
+
+export function getDescriptorFromBuilder(builder: DescriptorBuilder): Descriptor {
+  return Descriptor.fromString(getDescriptorString(builder), 'derivable');
+}

modules/abstract-utxo/src/descriptor/builder/index.ts

@@ -0,0 +1,2 @@
+export { getDescriptorFromBuilder, DescriptorBuilder } from './builder';
+export { parseDescriptor } from './parse';

modules/abstract-utxo/src/descriptor/builder/parse.ts

@@ -0,0 +1,113 @@
+import { BIP32Interface } from '@bitgo/utxo-lib';
+import * as utxolib from '@bitgo/utxo-lib';
+import { Descriptor } from '@bitgo/wasm-miniscript';
+import { DescriptorBuilder, getDescriptorFromBuilder } from './builder';
+
+type NodeUnary<Key extends string> = { [k in Key]: unknown };
+
+function isUnaryNode<TKey extends string>(node: unknown, key: TKey): node is NodeUnary<TKey> {
+  if (typeof node !== 'object' || node === null) {
+    return false;
+  }
+  const keys = Object.keys(node);
+  return keys.length === 1 && keys[0] === key;
+}
+
+function unwrapNode(node: unknown, path: string[]): unknown {
+  let current = node;
+  for (const key of path) {
+    if (!isUnaryNode(current, key)) {
+      return undefined;
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+function parseMulti(node: unknown): {
+  threshold: number;
+  keys: BIP32Interface[];
+  path: string;
+} {
+  if (!Array.isArray(node)) {
+    throw new Error('Unexpected node');
+  }
+  const [threshold, ...keyNodes] = node;
+  if (typeof threshold !== 'number') {
+    throw new Error('Expected threshold number');
+  }
+  const keyWithPath = keyNodes.map((keyNode) => {
+    if (!isUnaryNode(keyNode, 'XPub')) {
+      throw new Error('Expected XPub node');
+    }
+    if (typeof keyNode.XPub !== 'string') {
+      throw new Error('Expected XPub string');
+    }
+    const parts = keyNode.XPub.split('/');
+    return { xpub: parts[0], path: parts.slice(1).join('/') };
+  });
+  const paths = keyWithPath.map((k) => k.path);
+  paths.forEach((path, i) => {
+    if (path !== paths[0]) {
+      throw new Error(`Expected all paths to be the same: ${path} !== ${paths[0]}`);
+    }
+  });
+  return {
+    threshold,
+    keys: keyWithPath.map((k) => utxolib.bip32.fromBase58(k.xpub)),
+    path: paths[0],
+  };
+}
+
+export function parseDescriptorNode(node: unknown): DescriptorBuilder {
+  const wshMsMulti = unwrapNode(node, ['Wsh', 'Ms', 'Multi']);
+  if (wshMsMulti) {
+    const { threshold, keys, path } = parseMulti(wshMsMulti);
+    let name;
+    if (threshold === 2 && keys.length === 2) {
+      name = 'Wsh2Of2';
+    } else if (threshold === 2 && keys.length === 3) {
+      name = 'Wsh2Of3';
+    } else {
+      throw new Error('Unexpected multisig');
+    }
+    return {
+      name,
+      keys,
+      path,
+    };
+  }
+
+  const shWshMsAndV = unwrapNode(node, ['Sh', 'Wsh', 'Ms', 'AndV']);
+  if (shWshMsAndV) {
+    if (Array.isArray(shWshMsAndV) && shWshMsAndV.length === 2) {
+      const [a, b] = shWshMsAndV;
+      const dropAfterAbsLocktime = unwrapNode(a, ['Drop', 'After', 'absLockTime']);
+      if (typeof dropAfterAbsLocktime !== 'number') {
+        throw new Error('Expected absLockTime number');
+      }
+      if (!isUnaryNode(b, 'Multi')) {
+        throw new Error('Expected Multi node');
+      }
+      const multi = parseMulti(b.Multi);
+      if (multi.threshold === 2 && multi.keys.length === 3) {
+        return {
+          name: 'ShWsh2Of3CltvDrop',
+          locktime: dropAfterAbsLocktime,
+          keys: multi.keys,
+          path: multi.path,
+        };
+      }
+    }
+  }
+
+  throw new Error('Not implemented');
+}
+
+export function parseDescriptor(descriptor: Descriptor): DescriptorBuilder {
+  const builder = parseDescriptorNode(descriptor.node());
+  if (getDescriptorFromBuilder(builder).toString() !== descriptor.toString()) {
+    throw new Error('Failed to parse descriptor');
+  }
+  return builder;
+}

modules/abstract-utxo/test/descriptor/builder.ts

@@ -0,0 +1,38 @@
+import * as assert from 'assert';
+
+import { parseDescriptor, DescriptorBuilder, getDescriptorFromBuilder } from '../../src/descriptor/builder';
+import { getKeyTriple } from '../core/key.utils';
+
+function getDescriptorBuilderForType(name: DescriptorBuilder['name']): DescriptorBuilder {
+  const keys = getKeyTriple().map((k) => k.neutered());
+  switch (name) {
+    case 'Wsh2Of2':
+    case 'Wsh2Of3':
+      return {
+        name,
+        keys: keys.slice(0, name === 'Wsh2Of3' ? 3 : 2),
+        path: '0/*',
+      };
+    case 'ShWsh2Of3CltvDrop':
+      return {
+        name,
+        keys,
+        path: '0/*',
+        locktime: 1,
+      };
+  }
+}
+
+function describeForName(n: DescriptorBuilder['name']) {
+  describe(`DescriptorBuilder ${n}`, () => {
+    it('parses descriptor template', () => {
+      const builder = getDescriptorBuilderForType(n);
+      const descriptor = getDescriptorFromBuilder(builder);
+      assert.deepStrictEqual(builder, parseDescriptor(descriptor));
+    });
+  });
+}
+
+describeForName('Wsh2Of2');
+describeForName('Wsh2Of3');
+describeForName('ShWsh2Of3CltvDrop');