Merge pull request #5252 from BitGo/BTC-1450.impl-explainTx-descriptors-wallets

feat(abstract-utxo): add explainPsbt function for descriptor wallets

Author: OttoAllmendinger

modules/abstract-utxo/.prettierignore

@@ -1,2 +1,3 @@
 .nyc_output/
 dist/
+*.json

modules/abstract-utxo/src/abstractUtxoCoin.ts

@@ -143,6 +143,7 @@ export function isWalletOutput(output: Output): output is FixedScriptWalletOutpu
 
 export interface TransactionExplanation extends BaseTransactionExplanation<string, string> {
   locktime: number;
+  /** NOTE: this actually only captures external outputs */
   outputs: Output[];
   changeOutputs: Output[];
 

modules/abstract-utxo/src/transaction/descriptor/explainPsbt.ts

@@ -0,0 +1,56 @@
+import * as utxolib from '@bitgo/utxo-lib';
+import { ITransactionRecipient } from '@bitgo/sdk-core';
+
+import * as coreDescriptors from '../../core/descriptor';
+import { ParsedOutput } from '../../core/descriptor/psbt/parse';
+import { toExtendedAddressFormat } from '../recipient';
+import { TransactionExplanation } from '../../abstractUtxoCoin';
+
+function toRecipient(output: ParsedOutput, network: utxolib.Network): ITransactionRecipient {
+  return {
+    address: toExtendedAddressFormat(output.script, network),
+    amount: output.value.toString(),
+  };
+}
+
+function sumValues(arr: { value: bigint }[]): bigint {
+  return arr.reduce((sum, e) => sum + e.value, BigInt(0));
+}
+
+function getInputSignaturesForInputIndex(psbt: utxolib.bitgo.UtxoPsbt, inputIndex: number): number {
+  const { partialSig } = psbt.data.inputs[inputIndex];
+  if (!partialSig) {
+    return 0;
+  }
+  return partialSig.reduce((agg, p) => {
+    const valid = psbt.validateSignaturesOfInputCommon(inputIndex, p.pubkey);
+    return agg + (valid ? 1 : 0);
+  }, 0);
+}
+
+function getInputSignatures(psbt: utxolib.bitgo.UtxoPsbt): number[] {
+  return psbt.data.inputs.map((_, i) => getInputSignaturesForInputIndex(psbt, i));
+}
+
+export function explainPsbt(
+  psbt: utxolib.bitgo.UtxoPsbt,
+  descriptors: coreDescriptors.DescriptorMap
+): TransactionExplanation {
+  const parsedTransaction = coreDescriptors.parse(psbt, descriptors, psbt.network);
+  const { inputs, outputs } = parsedTransaction;
+  const externalOutputs = outputs.filter((o) => o.scriptId === undefined);
+  const changeOutputs = outputs.filter((o) => o.scriptId !== undefined);
+  const fee = sumValues(inputs) - sumValues(outputs);
+  const inputSignatures = getInputSignatures(psbt);
+  return {
+    inputSignatures,
+    signatures: inputSignatures.reduce((a, b) => Math.min(a, b), Infinity),
+    locktime: psbt.locktime,
+    id: psbt.getUnsignedTx().getId(),
+    outputs: externalOutputs.map((o) => toRecipient(o, psbt.network)),
+    outputAmount: sumValues(externalOutputs).toString(),
+    changeOutputs: changeOutputs.map((o) => toRecipient(o, psbt.network)),
+    changeAmount: sumValues(changeOutputs).toString(),
+    fee: fee.toString(),
+  };
+}

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

@@ -0,0 +1,2 @@
+export { DescriptorMap } from '../../core/descriptor';
+export { explainPsbt } from './explainPsbt';

modules/abstract-utxo/test/core/descriptor/descriptor.utils.ts

@@ -1,7 +1,8 @@
 import { Descriptor } from '@bitgo/wasm-miniscript';
 
 import { DescriptorMap, PsbtParams } from '../../../src/core/descriptor';
-import { getKeyTriple } from '../key.utils';
+import { getKeyTriple, KeyTriple } from '../key.utils';
+import { BIP32Interface } from '@bitgo/utxo-lib';
 
 export function getDefaultXPubs(seed?: string): string[] {
   return getKeyTriple(seed).map((k) => k.neutered().toBase58());
@@ -21,15 +22,22 @@ export type DescriptorTemplate =
    */
   | 'ShWsh2Of3CltvDrop';
 
-function multi(m: number, n: number, keys: string[], path: string): string {
+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) => `${k}/${path}`).join(',')})`;
+  return `multi(${m},${keys.map((k) => `${toXPub(k)}/${path}`).join(',')})`;
 }
 
 export function getPsbtParams(t: DescriptorTemplate): Partial<PsbtParams> {
@@ -44,7 +52,7 @@ export function getPsbtParams(t: DescriptorTemplate): Partial<PsbtParams> {
 
 export function getDescriptorString(
   template: DescriptorTemplate,
-  keys: string[] = getDefaultXPubs(),
+  keys: KeyTriple | string[] = getDefaultXPubs(),
   path = '0/*'
 ): string {
   switch (template) {
@@ -62,13 +70,16 @@ export function getDescriptorString(
 
 export function getDescriptor(
   template: DescriptorTemplate,
-  keys: string[] = getDefaultXPubs(),
+  keys: KeyTriple | string[] = getDefaultXPubs(),
   path = '0/*'
 ): Descriptor {
   return Descriptor.fromString(getDescriptorString(template, keys, path), 'derivable');
 }
 
-export function getDescriptorMap(template: DescriptorTemplate, keys: string[] = getDefaultXPubs()): DescriptorMap {
+export function getDescriptorMap(
+  template: DescriptorTemplate,
+  keys: KeyTriple | string[] = getDefaultXPubs()
+): DescriptorMap {
   return toDescriptorMap({
     external: getDescriptor(template, keys, '0/*').toString(),
     internal: getDescriptor(template, keys, '1/*').toString(),

modules/abstract-utxo/test/transaction/descriptor/explainPsbt.ts

@@ -0,0 +1,30 @@
+import assert from 'assert';
+
+import { explainPsbt } from '../../../src/transaction/descriptor';
+import { mockPsbtDefaultWithDescriptorTemplate } from '../../core/descriptor/psbt/mock.utils';
+import { getDescriptorMap } from '../../core/descriptor/descriptor.utils';
+import { getFixture } from '../../core/fixtures.utils';
+import { getKeyTriple } from '../../core/key.utils';
+import { TransactionExplanation } from '../../../src';
+
+async function assertEqualFixture(name: string, v: unknown) {
+  assert.deepStrictEqual(v, await getFixture(__dirname + '/fixtures/' + name, v));
+}
+
+function assertSignatureCount(expl: TransactionExplanation, signatures: number, inputSignatures: number[]) {
+  assert.deepStrictEqual(expl.signatures, signatures);
+  assert.deepStrictEqual(expl.inputSignatures, inputSignatures);
+}
+
+describe('explainPsbt', function () {
+  it('has expected values', async function () {
+    const psbt = mockPsbtDefaultWithDescriptorTemplate('Wsh2Of3');
+    const keys = getKeyTriple('a');
+    const descriptorMap = getDescriptorMap('Wsh2Of3', keys);
+    await assertEqualFixture('explainPsbt.a.json', explainPsbt(psbt, descriptorMap));
+    psbt.signAllInputsHD(keys[0]);
+    assertSignatureCount(explainPsbt(psbt, descriptorMap), 1, [1, 1]);
+    psbt.signAllInputsHD(keys[1]);
+    assertSignatureCount(explainPsbt(psbt, descriptorMap), 2, [2, 2]);
+  });
+});

modules/abstract-utxo/test/transaction/descriptor/fixtures/explainPsbt.a.json

@@ -0,0 +1,24 @@
+{
+  "inputSignatures": [
+    0,
+    0
+  ],
+  "signatures": 0,
+  "locktime": 0,
+  "id": "b9b272a1f0407ea461aca2da115b3399311f424949653c37d5c0023102add158",
+  "outputs": [
+    {
+      "address": "bc1qvn279lx29cg843u77p3c37npay7w4uc4xw5d92xxa92z8gd3lkuq4w8477",
+      "amount": "400000"
+    }
+  ],
+  "outputAmount": "400000",
+  "changeOutputs": [
+    {
+      "address": "bc1q2yau645jl7k577lmanqn9a0ulcgcqm0wrrmx09dppd3kcwguvyzqk86umj",
+      "amount": "400000"
+    }
+  ],
+  "changeAmount": "400000",
+  "fee": "1200000"
+}