Merge pull request #5265 from BitGo/BTC-1450.integrate-descriptor-parseTx.outputDifference

feat(abstract-utxo): add outputDifference utility

Author: OttoAllmendinger

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

@@ -0,0 +1,56 @@
+export type ComparableOutput = {
+  script: Buffer;
+  value: bigint;
+};
+
+export type ParseOutputsResult<T extends ComparableOutput> = {
+  /** These are the external outputs that were explicitly specified in the transaction */
+  explicitExternalOutputs: T[];
+  /**
+   * These are the surprise external outputs that were not explicitly specified in the transaction.
+   * They can be PayGo fees.
+   */
+  implicitExternalOutputs: T[];
+  /**
+   * These are the outputs that were expected to be in the transaction but were not found.
+   */
+  missingOutputs: T[];
+};
+
+export function equalOutput<T extends ComparableOutput>(a: T, b: T): boolean {
+  return a.value === b.value && a.script.equals(b.script);
+}
+
+/**
+ * @returns all outputs in the first array that are not in the second array
+ * Outputs can occur more than once in each array.
+ */
+export function outputDifference<T extends ComparableOutput>(first: T[], second: T[]): T[] {
+  first = first.slice();
+  for (const output of second) {
+    const index = first.findIndex((o) => equalOutput(o, output));
+    if (index !== -1) {
+      first.splice(index, 1);
+    }
+  }
+  return first;
+}
+
+/**
+ * @param actualExternalOutputs - external outputs in the transaction
+ * @param expectedExternalOutputs - external outputs that were expected to be in the transaction
+ * @returns the difference between the actual and expected external outputs
+ */
+export function outputDifferencesWithExpected<T extends ComparableOutput>(
+  actualExternalOutputs: T[],
+  expectedExternalOutputs: T[]
+): ParseOutputsResult<T> {
+  const implicitExternalOutputs = outputDifference(actualExternalOutputs, expectedExternalOutputs);
+  const explicitExternalOutputs = outputDifference(actualExternalOutputs, implicitExternalOutputs);
+  const missingOutputs = outputDifference(expectedExternalOutputs, actualExternalOutputs);
+  return {
+    explicitExternalOutputs,
+    implicitExternalOutputs,
+    missingOutputs,
+  };
+}

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

@@ -0,0 +1,75 @@
+import assert from 'assert';
+
+import {
+  ComparableOutput,
+  equalOutput,
+  outputDifference,
+  outputDifferencesWithExpected,
+} from '../../../src/transaction/descriptor/outputDifference';
+
+describe('outputDifference', function () {
+  function output(script: string, value: bigint | number) {
+    const scriptBuffer = Buffer.from(script, 'hex');
+    if (scriptBuffer.toString('hex') !== script) {
+      throw new Error('invalid script');
+    }
+    return {
+      script: Buffer.from(script, 'hex'),
+      value: BigInt(value),
+    };
+  }
+
+  const a = output('aa', 1);
+  const a2 = output('aa', 2);
+  const b = output('bb', 2);
+  const c = output('cc', 3);
+
+  describe('equalOutput', function () {
+    it('has expected result', function () {
+      assert.deepStrictEqual(equalOutput(a, a), true);
+      assert.deepStrictEqual(equalOutput(a, a2), false);
+      assert.deepStrictEqual(equalOutput(a, b), false);
+    });
+  });
+
+  describe('outputDifference', function () {
+    assert.deepStrictEqual(outputDifference([], []), []);
+    assert.deepStrictEqual(outputDifference([a], []), [a]);
+    assert.deepStrictEqual(outputDifference([], [a]), []);
+    assert.deepStrictEqual(outputDifference([a], [a]), []);
+    assert.deepStrictEqual(outputDifference([a, a], [a]), [a]);
+    assert.deepStrictEqual(outputDifference([a, a, a], [a]), [a, a]);
+    assert.deepStrictEqual(outputDifference([a, b, c], [a, b]), [c]);
+    assert.deepStrictEqual(outputDifference([a, b, c, a], [a, b]), [c, a]);
+
+    assert.deepStrictEqual(outputDifference([a], [a2]), [a]);
+    assert.deepStrictEqual(outputDifference([a2], [a]), [a2]);
+  });
+
+  describe('outputDifferencesWithExpected', function () {
+    function test(
+      outputs: ComparableOutput[],
+      recipients: ComparableOutput[],
+      expected: {
+        missing: ComparableOutput[];
+        explicit: ComparableOutput[];
+        implicit: ComparableOutput[];
+      }
+    ) {
+      const result = outputDifferencesWithExpected(outputs, recipients);
+      assert.deepStrictEqual(result, {
+        explicitExternalOutputs: expected.explicit,
+        implicitExternalOutputs: expected.implicit,
+        missingOutputs: expected.missing,
+      });
+    }
+
+    test([a], [], { missing: [], explicit: [], implicit: [a] });
+    test([], [a], { missing: [a], explicit: [], implicit: [] });
+    test([a], [a], { missing: [], explicit: [a], implicit: [] });
+    test([a], [a2], { missing: [a2], explicit: [], implicit: [a] });
+    test([b], [a], { missing: [a], explicit: [], implicit: [b] });
+    test([a, a], [a], { missing: [], explicit: [a], implicit: [a] });
+    test([a, b], [a], { missing: [], explicit: [a], implicit: [b] });
+  });
+});