Merge pull request #5326 from BitGo/BTC-1708.add-helper-createDescriptorWallet

feat(abstract-utxo): add helper for descriptor wallet creation

Author: OttoAllmendinger

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

@@ -1,8 +1,41 @@
 import * as t from 'io-ts';
+import { Descriptor } from '@bitgo/wasm-miniscript';
+import { BIP32Interface, networks } from '@bitgo/utxo-lib';
+import { signMessage, verifyMessage } from '@bitgo/sdk-core';
 
-export const NamedDescriptor = t.type({
-  name: t.string,
-  value: t.string,
-});
+export const NamedDescriptor = t.intersection(
+  [
+    t.type({
+      name: t.string,
+      value: t.string,
+    }),
+    t.partial({
+      signatures: t.union([t.array(t.string), t.undefined]),
+    }),
+  ],
+  'NamedDescriptor'
+);
 
 export type NamedDescriptor = t.TypeOf<typeof NamedDescriptor>;
+
+export function createNamedDescriptorWithSignature(
+  name: string,
+  descriptor: Descriptor,
+  signingKey: BIP32Interface
+): NamedDescriptor {
+  const value = descriptor.toString();
+  const signature = signMessage(value, signingKey, networks.bitcoin).toString('hex');
+  return { name, value, signatures: [signature] };
+}
+
+export function assertHasValidSignature(namedDescriptor: NamedDescriptor, key: BIP32Interface): void {
+  if (namedDescriptor.signatures === undefined) {
+    throw new Error(`Descriptor ${namedDescriptor.name} does not have a signature`);
+  }
+  const isValid = namedDescriptor.signatures.some((signature) => {
+    return verifyMessage(namedDescriptor.value, key, Buffer.from(signature, 'hex'), networks.bitcoin);
+  });
+  if (!isValid) {
+    throw new Error(`Descriptor ${namedDescriptor.name} does not have a valid signature (key=${key.toBase58()})`);
+  }
+}

modules/abstract-utxo/src/descriptor/createWallet/createDescriptorWallet.ts

@@ -0,0 +1,73 @@
+import { BitGoAPI } from '@bitgo/sdk-api';
+import * as utxolib from '@bitgo/utxo-lib';
+import { Wallet } from '@bitgo/sdk-core';
+
+import { AbstractUtxoCoin } from '../../abstractUtxoCoin';
+import { IDescriptorWallet } from '../descriptorWallet';
+import { NamedDescriptor } from '../NamedDescriptor';
+
+import { DescriptorFromKeys } from './createDescriptors';
+
+export async function createDescriptorWallet(
+  bitgo: BitGoAPI,
+  coin: AbstractUtxoCoin,
+  {
+    descriptors,
+    ...params
+  }: {
+    type: 'hot';
+    label: string;
+    enterprise: string;
+    keys: string[];
+    descriptors: NamedDescriptor[];
+  }
+): Promise<IDescriptorWallet> {
+  // We don't use `coin.wallets().add` here because it does a bunch of validation that does not make sense
+  // for descriptor wallets.
+  const newWallet = await bitgo
+    .post(coin.url('/wallet/add'))
+    .send({
+      ...params,
+      coinSpecific: { descriptors },
+    })
+    .result();
+  return new Wallet(bitgo, coin, newWallet) as IDescriptorWallet;
+}
+
+export async function createDescriptorWalletWithWalletPassphrase(
+  bitgo: BitGoAPI,
+  coin: AbstractUtxoCoin,
+  {
+    enterprise,
+    walletPassphrase,
+    descriptorsFromKeys,
+    ...params
+  }: {
+    label: string;
+    enterprise: string;
+    walletPassphrase: string;
+    descriptorsFromKeys: DescriptorFromKeys;
+    [key: string]: unknown;
+  }
+): Promise<IDescriptorWallet> {
+  const userKeychain = await coin.keychains().createUserKeychain(walletPassphrase);
+  const backupKeychain = await coin.keychains().createBackup();
+  const bitgoKeychain = await coin.keychains().createBitGo({ enterprise });
+  if (!userKeychain.prv) {
+    throw new Error('Missing private key');
+  }
+  const userKey = utxolib.bip32.fromBase58(userKeychain.prv);
+  const cosigners = [backupKeychain, bitgoKeychain].map((keychain) => {
+    if (!keychain.pub) {
+      throw new Error('Missing public key');
+    }
+    return utxolib.bip32.fromBase58(keychain.pub);
+  });
+  return createDescriptorWallet(bitgo, coin, {
+    ...params,
+    type: 'hot',
+    enterprise,
+    keys: [userKeychain.id, backupKeychain.id, bitgoKeychain.id],
+    descriptors: descriptorsFromKeys(userKey, cosigners),
+  });
+}

modules/abstract-utxo/src/descriptor/createWallet/createDescriptors.ts

@@ -0,0 +1,44 @@
+import { BIP32Interface } from '@bitgo/utxo-lib';
+
+import { createNamedDescriptorWithSignature, NamedDescriptor } from '../NamedDescriptor';
+import { getDescriptorFromBuilder, DescriptorBuilder } from '../builder';
+
+export type DescriptorFromKeys = (userKey: BIP32Interface, cosigners: BIP32Interface[]) => NamedDescriptor[];
+
+/**
+ * Create a pair of external and internal descriptors for a 2-of-3 multisig wallet.
+ * Overrides the path of the builder to use the external and internal derivation paths (0/* and 1/*).
+ *
+ * @param builder
+ * @param userKey
+ */
+function createExternalInternalPair(
+  builder: DescriptorBuilder,
+  userKey: BIP32Interface
+): [NamedDescriptor, NamedDescriptor] {
+  if (userKey.isNeutered()) {
+    throw new Error('User key must be private');
+  }
+  return [
+    createNamedDescriptorWithSignature(
+      builder.name + '/external',
+      getDescriptorFromBuilder({ ...builder, path: '0/*' }),
+      userKey
+    ),
+    createNamedDescriptorWithSignature(
+      builder.name + '/internal',
+      getDescriptorFromBuilder({ ...builder, path: '1/*' }),
+      userKey
+    ),
+  ];
+}
+
+/**
+ * Create a pair of external and internal descriptors for a 2-of-3 multisig wallet.
+ *
+ * @param userKey
+ * @param cosigners
+ * @constructor
+ */
+export const DefaultWsh2Of3: DescriptorFromKeys = (userKey, cosigners) =>
+  createExternalInternalPair({ name: 'Wsh2Of3', keys: [userKey.neutered(), ...cosigners], path: '' }, userKey);

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

@@ -0,0 +1,2 @@
+export * from './createDescriptors';
+export * from './createDescriptorWallet';

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

@@ -3,3 +3,4 @@ export { assertDescriptorWalletAddress } from './assertDescriptorWalletAddress';
 export { NamedDescriptor } from './NamedDescriptor';
 export { isDescriptorWallet, getDescriptorMapFromWallet } from './descriptorWallet';
 export { getPolicyForEnv } from './validatePolicy';
+export * as createWallet from './createWallet';

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

@@ -0,0 +1,22 @@
+import assert from 'assert';
+
+import { assertHasValidSignature, createNamedDescriptorWithSignature } from '../../src/descriptor/NamedDescriptor';
+import { getKeyTriple } from '../core/key.utils';
+import { getDescriptorFromBuilder } from '../../src/descriptor/builder';
+import { getFixture } from '../core/fixtures.utils';
+
+describe('NamedDescriptor', function () {
+  it('creates named descriptor with signature', async function () {
+    const keys = getKeyTriple();
+    const namedDescriptor = createNamedDescriptorWithSignature(
+      'foo',
+      getDescriptorFromBuilder({ name: 'Wsh2Of2', keys, path: '0/*' }),
+      keys[0]
+    );
+    assert.deepStrictEqual(
+      await getFixture(__dirname + '/fixtures/NamedDescriptorWithSignature.json', namedDescriptor),
+      namedDescriptor
+    );
+    assertHasValidSignature(namedDescriptor, keys[0]);
+  });
+});

modules/abstract-utxo/test/descriptor/createWallet/createDescriptors.ts

@@ -0,0 +1,20 @@
+import assert from 'assert';
+
+import { getKeyTriple } from '../../core/key.utils';
+import { assertHasValidSignature } from '../../../src/descriptor/NamedDescriptor';
+import { DefaultWsh2Of3 } from '../../../src/descriptor/createWallet';
+import { getFixture } from '../../core/fixtures.utils';
+
+describe('createDescriptors', function () {
+  it('should create standard named descriptors', async function () {
+    const keys = getKeyTriple();
+    const namedDescriptors = DefaultWsh2Of3(keys[0], keys.slice(1));
+    assert.deepStrictEqual(
+      namedDescriptors,
+      await getFixture(__dirname + '/fixtures/DefaultWsh2Of3.json', namedDescriptors)
+    );
+    for (const namedDescriptor of namedDescriptors) {
+      assertHasValidSignature(namedDescriptor, keys[0]);
+    }
+  });
+});

modules/abstract-utxo/test/descriptor/createWallet/fixtures/DefaultWsh2Of3.json

@@ -0,0 +1,16 @@
+[
+  {
+    "name": "Wsh2Of3/external",
+    "value": "wsh(multi(2,xpub661MyMwAqRbcFXS2qwsTkaFc7PEpwDXWgY1Hx2MS7XywhW24sTjQzxiUgnGNW5v6DsW9Z8JcAqf8a22v21jDSA3DwLbbpt2ra3WbP83QNvP/0/*,xpub661MyMwAqRbcGfiaWcoeKLerFu3qRfy6zSYAwnmxSKW8JSauRajFsAsRHs2pV4q5rxkb4ynx4Bm8t54McTCp8V27s7XsdpD8T4s56etpjro/0/*,xpub661MyMwAqRbcH4HzWiCwmYajy1SXZngxHvpYDNEX4xjrDAneAm6rnpPuPPXcBRsSgxupDBmH2tzPHkikNrnLbsvTHemPFHSFbZxonZcCwFi/0/*))#x382fygz",
+    "signatures": [
+      "20f303b798a75260ce7934e8fff7d8da12fd1b99dbd74879596c201d6acc344cbd151291c25d3d5fba428e844a6eb63a45f645deb2a5ae44e51d968614d4de9a39"
+    ]
+  },
+  {
+    "name": "Wsh2Of3/internal",
+    "value": "wsh(multi(2,xpub661MyMwAqRbcFXS2qwsTkaFc7PEpwDXWgY1Hx2MS7XywhW24sTjQzxiUgnGNW5v6DsW9Z8JcAqf8a22v21jDSA3DwLbbpt2ra3WbP83QNvP/1/*,xpub661MyMwAqRbcGfiaWcoeKLerFu3qRfy6zSYAwnmxSKW8JSauRajFsAsRHs2pV4q5rxkb4ynx4Bm8t54McTCp8V27s7XsdpD8T4s56etpjro/1/*,xpub661MyMwAqRbcH4HzWiCwmYajy1SXZngxHvpYDNEX4xjrDAneAm6rnpPuPPXcBRsSgxupDBmH2tzPHkikNrnLbsvTHemPFHSFbZxonZcCwFi/1/*))#73gjjc7a",
+    "signatures": [
+      "1fd2b2d9e294e9fe56ccba37d9992220c9bc16bb4c05fbd4f700de2eff1ae1dc051d1b3573304c470a61d5f5c4fa652a785cf9a69865b44da7059701bc9ee8173f"
+    ]
+  }
+]

modules/abstract-utxo/test/descriptor/fixtures/NamedDescriptorWithSignature.json

@@ -0,0 +1,7 @@
+{
+  "name": "foo",
+  "value": "wsh(multi(2,xpub661MyMwAqRbcFXS2qwsTkaFc7PEpwDXWgY1Hx2MS7XywhW24sTjQzxiUgnGNW5v6DsW9Z8JcAqf8a22v21jDSA3DwLbbpt2ra3WbP83QNvP/0/*,xpub661MyMwAqRbcGfiaWcoeKLerFu3qRfy6zSYAwnmxSKW8JSauRajFsAsRHs2pV4q5rxkb4ynx4Bm8t54McTCp8V27s7XsdpD8T4s56etpjro/0/*))#qd26atvj",
+  "signatures": [
+    "20c5eac59397664cc8cdf07b92b85bc55f6d91051aac522a78f7d1ab72043543cd17c3436e11d96d3326274754812c3dd0e693c6330a6cdab1e3e53d618a066091"
+  ]
+}

modules/bitgo/test/v2/unit/coins/utxo/descriptorAddress.ts

@@ -27,6 +27,7 @@ describe('descriptor wallets', function () {
     return {
       name,
       value: withChecksum(`sh(multi(2,${a}/*,${b}/*))`),
+      signatures: [],
     };
   }