feat(abstract-utxo): allow 'max' value in ExpectedOutput

Issue: BTC-1697

Author: OttoAllmendinger

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

@@ -1,50 +1,68 @@
-export type ComparableOutput = {
+export type ComparableOutput<TValue> = {
   script: Buffer;
-  value: bigint;
+  value: TValue;
 };
 
-export function equalOutput<T extends ComparableOutput>(a: T, b: T): boolean {
-  return a.value === b.value && a.script.equals(b.script);
+/** Actual outputs have fixed values. */
+export type ActualOutput = ComparableOutput<bigint>;
+
+/** Expected outputs can have a fixed value or 'max'. */
+export type ExpectedOutput = ComparableOutput<bigint | 'max'>;
+
+/**
+ * @param a
+ * @param b
+ * @returns whether the two outputs are equal. Outputs with value `max` are considered equal to any other output with the same script.
+ */
+export function matchingOutput<TValue>(a: ComparableOutput<TValue>, b: ComparableOutput<TValue>): boolean {
+  if (a.value === 'max' || b.value === 'max') {
+    return a.script.equals(b.script);
+  }
+  return a.script.equals(b.script) && a.value === b.value;
 }
 
 /**
- * @returns all outputs in the first array that are not in the second array
+ * @returns all outputs in the first array that are not in the second array.
  * Outputs can occur more than once in each array.
+ * An output with value `max` is considered equal to any other output with the same script.
  */
-export function outputDifference<T extends ComparableOutput>(first: T[], second: T[]): T[] {
+export function outputDifference<A extends ActualOutput | ExpectedOutput, B extends ActualOutput | ExpectedOutput>(
+  first: A[],
+  second: B[]
+): A[] {
   first = first.slice();
   for (const output of second) {
-    const index = first.findIndex((o) => equalOutput(o, output));
+    const index = first.findIndex((o) => matchingOutput(o, output));
     if (index !== -1) {
       first.splice(index, 1);
     }
   }
   return first;
 }
 
-export type OutputDifferenceWithExpected<T extends ComparableOutput> = {
+export type OutputDifferenceWithExpected<TActual extends ActualOutput, TExpected extends ExpectedOutput> = {
   /** These are the external outputs that were expected and found in the transaction. */
-  explicitExternalOutputs: T[];
+  explicitExternalOutputs: TActual[];
   /**
    * These are the surprise external outputs that were not explicitly specified in the transaction.
    * They can be PayGo fees.
    */
-  implicitExternalOutputs: T[];
+  implicitExternalOutputs: TActual[];
   /**
    * These are the outputs that were expected to be in the transaction but were not found.
    */
-  missingOutputs: T[];
+  missingOutputs: TExpected[];
 };
 
 /**
  * @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[]
-): OutputDifferenceWithExpected<T> {
+export function outputDifferencesWithExpected<TActual extends ActualOutput, TExpected extends ExpectedOutput>(
+  actualExternalOutputs: TActual[],
+  expectedExternalOutputs: TExpected[]
+): OutputDifferenceWithExpected<TActual, TExpected> {
   const implicitExternalOutputs = outputDifference(actualExternalOutputs, expectedExternalOutputs);
   const explicitExternalOutputs = outputDifference(actualExternalOutputs, implicitExternalOutputs);
   const missingOutputs = outputDifference(expectedExternalOutputs, actualExternalOutputs);

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

@@ -25,7 +25,8 @@ function toParsedOutput(recipient: ITransactionRecipient, network: utxolib.Netwo
   };
 }
 
-type ParsedOutputs = OutputDifferenceWithExpected<ParsedOutput> & {
+// TODO(BTC-1697): allow outputs with `value: 'max'` here
+type ParsedOutputs = OutputDifferenceWithExpected<ParsedOutput, ParsedOutput> & {
   outputs: ParsedOutput[];
   changeOutputs: ParsedOutput[];
 };

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

@@ -1,59 +1,77 @@
 import assert from 'assert';
 
 import {
-  ComparableOutput,
-  equalOutput,
+  ActualOutput,
+  ExpectedOutput,
+  matchingOutput,
   outputDifference,
   outputDifferencesWithExpected,
 } from '../../../src/transaction/descriptor/outputDifference';
 
 describe('outputDifference', function () {
-  function output(script: string, value: bigint | number) {
+  function output(script: string, value: bigint | number): ActualOutput;
+  function output(script: string, value: 'max'): ExpectedOutput;
+  function output(script: string, value: bigint | number | 'max'): ActualOutput | ExpectedOutput {
     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),
+      value: value === 'max' ? 'max' : BigInt(value),
     };
   }
 
   const a = output('aa', 1);
   const a2 = output('aa', 2);
-  const b = output('bb', 2);
-  const c = output('cc', 3);
+  const aMax = output('aa', 'max');
+  const b = output('bb', 1);
+  const c = output('cc', 1);
 
   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);
+      assert.deepStrictEqual(matchingOutput(a, a), true);
+      assert.deepStrictEqual(matchingOutput(a, a2), false);
+      assert.deepStrictEqual(matchingOutput(a, b), false);
+      assert.deepStrictEqual(matchingOutput(aMax, b), false);
+
+      assert.deepStrictEqual(matchingOutput(aMax, a), true);
+      assert.deepStrictEqual(matchingOutput(a, aMax), true);
+      // this one does not appear in practice but is a valid comparison
+      assert.deepStrictEqual(matchingOutput(aMax, aMax), true);
     });
   });
 
   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]);
+    it('has expected result', function () {
+      assert.deepStrictEqual(outputDifference([], []), []);
+      assert.deepStrictEqual(outputDifference([a], []), [a]);
+      assert.deepStrictEqual(outputDifference([aMax], []), [aMax]);
+      assert.deepStrictEqual(outputDifference([], [a]), []);
+      assert.deepStrictEqual(outputDifference([], [aMax]), []);
+      assert.deepStrictEqual(outputDifference([a], [a]), []);
+      assert.deepStrictEqual(outputDifference([a], [aMax]), []);
+      assert.deepStrictEqual(outputDifference([aMax], [a]), []);
+      assert.deepStrictEqual(outputDifference([a, a], [a]), [a]);
+      assert.deepStrictEqual(outputDifference([a, a], [aMax]), [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], [aMax, 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]);
+      assert.deepStrictEqual(outputDifference([a], [a2]), [a]);
+      assert.deepStrictEqual(outputDifference([a2], [a]), [a2]);
+    });
   });
 
   describe('outputDifferencesWithExpected', function () {
     function test(
-      outputs: ComparableOutput[],
-      recipients: ComparableOutput[],
+      outputs: ActualOutput[],
+      recipients: ExpectedOutput[],
       expected: {
-        missing: ComparableOutput[];
-        explicit: ComparableOutput[];
-        implicit: ComparableOutput[];
+        missing: ExpectedOutput[];
+        explicit: ActualOutput[];
+        implicit: ActualOutput[];
       }
     ) {
       const result = outputDifferencesWithExpected(outputs, recipients);
@@ -64,12 +82,14 @@ describe('outputDifference', function () {
       });
     }
 
-    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] });
+    it('has expected result', function () {
+      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] });
+    });
   });
 });