feat(cip2): add support for implicit coin

Author: mkazlauskas

Diff for: packages/cip2/src/RoundRobinRandomImprove/change.ts

@@ -7,6 +7,7 @@ import {
   assetWithValueQuantitySelector,
   getCoinQuantity,
   getWithValuesCoinQuantity,
+  ImplicitCoinBigint,
   UtxoSelection,
   UtxoWithValue
 } from './util';
@@ -18,6 +19,7 @@ interface ChangeComputationArgs {
   utxoSelection: UtxoSelection;
   outputValues: Ogmios.util.OgmiosValue[];
   uniqueOutputAssetIDs: string[];
+  implicitCoin: ImplicitCoinBigint;
   estimateTxFee: EstimateTxFeeWithOriginalOutputs;
   computeMinimumCoinQuantity: ComputeMinimumCoinQuantity;
   tokenBundleSizeExceedsLimit: TokenBundleSizeExceedsLimit;
@@ -124,6 +126,7 @@ const computeRequestedAssetChangeBundles = (
   utxoSelected: UtxoWithValue[],
   outputValues: Ogmios.util.OgmiosValue[],
   uniqueOutputAssetIDs: string[],
+  implicitCoin: ImplicitCoinBigint,
   fee: bigint
 ): Ogmios.util.OgmiosValue[] => {
   const assetTotals: Record<string, { selected: bigint; requested: bigint }> = {};
@@ -133,8 +136,8 @@ const computeRequestedAssetChangeBundles = (
       requested: assetQuantitySelector(assetId)(outputValues)
     };
   }
-  const coinTotalSelected = getWithValuesCoinQuantity(utxoSelected);
-  const coinTotalRequested = getCoinQuantity(outputValues) + fee;
+  const coinTotalSelected = getWithValuesCoinQuantity(utxoSelected) + implicitCoin.input;
+  const coinTotalRequested = getCoinQuantity(outputValues) + fee + implicitCoin.deposit;
   const coinChangeTotal = coinTotalSelected - coinTotalRequested;
 
   const { totalCoinBundled, bundles, totalAssetsBundled } = createBundlePerOutput(
@@ -214,20 +217,23 @@ const computeChangeBundles = ({
   utxoSelection,
   outputValues,
   uniqueOutputAssetIDs,
+  implicitCoin,
   computeMinimumCoinQuantity,
   fee = 0n
 }: {
   csl: CardanoSerializationLib;
   utxoSelection: UtxoSelection;
   outputValues: Ogmios.util.OgmiosValue[];
   uniqueOutputAssetIDs: string[];
+  implicitCoin: ImplicitCoinBigint;
   computeMinimumCoinQuantity: ComputeMinimumCoinQuantity;
   fee?: bigint;
 }): UtxoSelection & { changeBundles: Ogmios.util.OgmiosValue[] } => {
   const requestedAssetChangeBundles = computeRequestedAssetChangeBundles(
     utxoSelection.utxoSelected,
     outputValues,
     uniqueOutputAssetIDs,
+    implicitCoin,
     fee
   );
   const requestedAssetChangeBundlesWithLeftoverAssets = redistributeLeftoverAssets(
@@ -248,6 +254,7 @@ const computeChangeBundles = ({
         utxoSelection: pickExtraRandomUtxo(utxoSelection),
         outputValues,
         uniqueOutputAssetIDs,
+        implicitCoin,
         computeMinimumCoinQuantity,
         fee
       });
@@ -295,13 +302,15 @@ export const computeChangeAndAdjustForFee = async ({
   estimateTxFee,
   outputValues,
   uniqueOutputAssetIDs,
+  implicitCoin,
   utxoSelection
 }: ChangeComputationArgs): Promise<ChangeComputationResult> => {
   const changeInclFee = computeChangeBundles({
     csl,
     utxoSelection,
     outputValues,
     uniqueOutputAssetIDs,
+    implicitCoin,
     computeMinimumCoinQuantity
   });
 
@@ -314,8 +323,9 @@ export const computeChangeAndAdjustForFee = async ({
   );
 
   // Ensure fee quantity is covered by current selection
-  const outputValuesWithFee = [...outputValues, { coins: fee }];
-  if (getCoinQuantity(outputValuesWithFee) > getWithValuesCoinQuantity(changeInclFee.utxoSelected)) {
+  const totalOutputCoin = getCoinQuantity(outputValues) + fee + implicitCoin.deposit;
+  const totalInputCoin = getWithValuesCoinQuantity(changeInclFee.utxoSelected) + implicitCoin.input;
+  if (totalOutputCoin > totalInputCoin) {
     if (changeInclFee.utxoRemaining.length === 0) {
       throw new InputSelectionError(InputSelectionFailure.UtxoBalanceInsufficient);
     }
@@ -327,6 +337,7 @@ export const computeChangeAndAdjustForFee = async ({
       outputValues,
       uniqueOutputAssetIDs,
       estimateTxFee,
+      implicitCoin,
       utxoSelection: pickExtraRandomUtxo(changeInclFee)
     });
   }
@@ -336,6 +347,7 @@ export const computeChangeAndAdjustForFee = async ({
     utxoSelection: { utxoRemaining: changeInclFee.utxoRemaining, utxoSelected: changeInclFee.utxoSelected },
     outputValues,
     uniqueOutputAssetIDs,
+    implicitCoin,
     computeMinimumCoinQuantity,
     fee
   });

Diff for: packages/cip2/src/RoundRobinRandomImprove/index.ts

@@ -9,22 +9,33 @@ export const roundRobinRandomImprove = (csl: CardanoSerializationLib): InputSele
   select: async ({
     utxo,
     outputs,
-    constraints: { computeMinimumCost, computeSelectionLimit, computeMinimumCoinQuantity, tokenBundleSizeExceedsLimit }
+    constraints: { computeMinimumCost, computeSelectionLimit, computeMinimumCoinQuantity, tokenBundleSizeExceedsLimit },
+    implicitCoin: implicitCoinAsNumber
   }: InputSelectionParameters): Promise<SelectionResult> => {
-    const { uniqueOutputAssetIDs, utxosWithValue, outputsWithValue } = preprocessArgs(utxo, outputs);
+    const { utxosWithValue, outputsWithValue, uniqueOutputAssetIDs, implicitCoin } = preprocessArgs(
+      utxo,
+      outputs,
+      implicitCoinAsNumber
+    );
 
     const utxoValues = withValuesToValues(utxosWithValue);
     const outputValues = withValuesToValues(outputsWithValue);
-    assertIsBalanceSufficient(uniqueOutputAssetIDs, utxoValues, outputValues);
+    assertIsBalanceSufficient(uniqueOutputAssetIDs, utxoValues, outputValues, implicitCoin);
 
-    const roundRobinSelectionResult = roundRobinSelection(utxosWithValue, outputsWithValue, uniqueOutputAssetIDs);
+    const roundRobinSelectionResult = roundRobinSelection({
+      implicitCoin,
+      outputsWithValue,
+      utxosWithValue,
+      uniqueOutputAssetIDs
+    });
 
     const result = await computeChangeAndAdjustForFee({
       csl,
       computeMinimumCoinQuantity,
       tokenBundleSizeExceedsLimit,
       outputValues,
       uniqueOutputAssetIDs,
+      implicitCoin,
       utxoSelection: roundRobinSelectionResult,
       estimateTxFee: (utxos, changeValues) =>
         computeMinimumCost({

Diff for: packages/cip2/src/RoundRobinRandomImprove/roundRobin.ts

@@ -3,16 +3,17 @@ import {
   assetWithValueQuantitySelector,
   getWithValuesCoinQuantity,
   OutputWithValue,
-  WithValue,
   UtxoSelection,
-  UtxoWithValue
+  UtxoWithValue,
+  RoundRobinRandomImproveArgs,
+  ImplicitCoinBigint
 } from './util';
 
 const improvesSelection = (
   utxoAlreadySelected: UtxoWithValue[],
   input: UtxoWithValue,
   minimumTarget: bigint,
-  getQuantity: (totals: WithValue[]) => bigint
+  getQuantity: (utxo: UtxoWithValue[]) => bigint
 ): boolean => {
   const oldQuantity = getQuantity(utxoAlreadySelected);
   // We still haven't reached the minimum target of
@@ -34,19 +35,23 @@ const improvesSelection = (
   return false;
 };
 
-const listTokensWithin = (uniqueOutputAssetIDs: string[], outputs: OutputWithValue[]) => [
+const listTokensWithin = (
+  uniqueOutputAssetIDs: string[],
+  outputs: OutputWithValue[],
+  implicitCoin: ImplicitCoinBigint
+) => [
   ...uniqueOutputAssetIDs.map((id) => {
     const getQuantity = assetWithValueQuantitySelector(id);
     return {
-      getQuantity,
+      getTotalSelectedQuantity: (utxo: UtxoWithValue[]) => getQuantity(utxo),
       minimumTarget: getQuantity(outputs),
       filterUtxo: (utxo: UtxoWithValue[]) => utxo.filter(({ value: { assets } }) => assets?.[id])
     };
   }),
   {
     // Lovelace
-    getQuantity: (totals: WithValue[]) => getWithValuesCoinQuantity(totals),
-    minimumTarget: getWithValuesCoinQuantity(outputs),
+    getTotalSelectedQuantity: (utxo: UtxoWithValue[]) => getWithValuesCoinQuantity(utxo) + implicitCoin.input,
+    minimumTarget: getWithValuesCoinQuantity(outputs) + implicitCoin.deposit,
     filterUtxo: (utxo: UtxoWithValue[]) => utxo
   }
 ];
@@ -57,27 +62,28 @@ const listTokensWithin = (uniqueOutputAssetIDs: string[], outputs: OutputWithVal
  * Assumes we have already checked that the available UTxO balance is sufficient to cover all tokens in the outputs.
  * Considers all outputs collectively, as a combined output bundle.
  */
-export const roundRobinSelection = (
-  availableUtxo: UtxoWithValue[],
-  outputs: OutputWithValue[],
-  uniqueOutputAssetIDs: string[]
-): UtxoSelection => {
+export const roundRobinSelection = ({
+  utxosWithValue,
+  outputsWithValue,
+  uniqueOutputAssetIDs,
+  implicitCoin
+}: RoundRobinRandomImproveArgs): UtxoSelection => {
   // The subset of the UTxO that has already been selected:
   const utxoSelected: UtxoWithValue[] = [];
   // The subset of the UTxO that remains available for selection:
-  const utxoRemaining = [...availableUtxo];
+  const utxoRemaining = [...utxosWithValue];
   // The set of tokens that we still need to cover:
-  const tokensRemaining = listTokensWithin(uniqueOutputAssetIDs, outputs);
+  const tokensRemaining = listTokensWithin(uniqueOutputAssetIDs, outputsWithValue, implicitCoin);
   while (tokensRemaining.length > 0) {
     // Consider each token in round-robin fashion:
-    for (const [tokenIdx, { filterUtxo, minimumTarget, getQuantity }] of tokensRemaining.entries()) {
+    for (const [tokenIdx, { filterUtxo, minimumTarget, getTotalSelectedQuantity }] of tokensRemaining.entries()) {
       // Attempt to select at random an input that includes
       // this token from the remaining UTxO set:
       const utxo = filterUtxo(utxoRemaining);
       if (utxo.length > 0) {
         const inputIdx = Math.floor(Math.random() * utxo.length);
         const input = utxo[inputIdx];
-        if (improvesSelection(utxoSelected, input, minimumTarget, getQuantity)) {
+        if (improvesSelection(utxoSelected, input, minimumTarget, getTotalSelectedQuantity)) {
           utxoSelected.push(input);
           utxoRemaining.splice(utxoRemaining.indexOf(input), 1);
         } else {

Diff for: packages/cip2/src/RoundRobinRandomImprove/util.ts

@@ -1,5 +1,6 @@
 import { BigIntMath, CSL, Ogmios } from '@cardano-sdk/core';
 import { uniq } from 'lodash-es';
+import { ImplicitCoin } from '../types';
 import { InputSelectionError, InputSelectionFailure } from '../InputSelectionError';
 
 export interface WithValue {
@@ -14,20 +15,32 @@ export interface OutputWithValue extends WithValue {
   output: CSL.TransactionOutput;
 }
 
+export interface ImplicitCoinBigint {
+  input: bigint;
+  deposit: bigint;
+}
+
 export interface RoundRobinRandomImproveArgs {
   utxosWithValue: UtxoWithValue[];
   outputsWithValue: OutputWithValue[];
   uniqueOutputAssetIDs: string[];
+  implicitCoin: ImplicitCoinBigint;
 }
 
 export interface UtxoSelection {
   utxoSelected: UtxoWithValue[];
   utxoRemaining: UtxoWithValue[];
 }
 
+const noImplicitCoin = {
+  deposit: 0,
+  input: 0
+};
+
 export const preprocessArgs = (
   availableUtxo: Set<CSL.TransactionUnspentOutput>,
-  outputs: Set<CSL.TransactionOutput>
+  outputs: Set<CSL.TransactionOutput>,
+  implicitCoinAsNumber: ImplicitCoin = noImplicitCoin
 ): RoundRobinRandomImproveArgs => {
   const utxosWithValue = [...availableUtxo].map((utxo) => ({
     utxo,
@@ -40,7 +53,11 @@ export const preprocessArgs = (
   const uniqueOutputAssetIDs = uniq(
     outputsWithValue.flatMap(({ value: { assets } }) => (assets && Object.keys(assets)) || [])
   );
-  return { uniqueOutputAssetIDs, utxosWithValue, outputsWithValue };
+  const implicitCoin: ImplicitCoinBigint = {
+    deposit: BigInt(implicitCoinAsNumber.deposit || 0),
+    input: BigInt(implicitCoinAsNumber.input || 0)
+  };
+  return { uniqueOutputAssetIDs, utxosWithValue, outputsWithValue, implicitCoin };
 };
 
 export const withValuesToValues = (totals: WithValue[]) => totals.map((t) => t.value);
@@ -58,11 +75,12 @@ export const getWithValuesCoinQuantity = (totals: WithValue[]): bigint => getCoi
 
 export const assertIsCoinBalanceSufficient = (
   utxoValues: Ogmios.util.OgmiosValue[],
-  outputValues: Ogmios.util.OgmiosValue[]
+  outputValues: Ogmios.util.OgmiosValue[],
+  implicitCoin: ImplicitCoinBigint
 ) => {
   const utxoCoinTotal = getCoinQuantity(utxoValues);
   const outputsCoinTotal = getCoinQuantity(outputValues);
-  if (outputsCoinTotal > utxoCoinTotal) {
+  if (outputsCoinTotal + implicitCoin.deposit > utxoCoinTotal + implicitCoin.input) {
     throw new InputSelectionError(InputSelectionFailure.UtxoBalanceInsufficient);
   }
 };
@@ -76,7 +94,8 @@ export const assertIsCoinBalanceSufficient = (
 export const assertIsBalanceSufficient = (
   uniqueOutputAssetIDs: string[],
   utxoValues: Ogmios.util.OgmiosValue[],
-  outputValues: Ogmios.util.OgmiosValue[]
+  outputValues: Ogmios.util.OgmiosValue[],
+  implicitCoin: ImplicitCoinBigint
 ): void => {
   for (const assetId of uniqueOutputAssetIDs) {
     const getAssetQuantity = assetQuantitySelector(assetId);
@@ -86,5 +105,5 @@ export const assertIsBalanceSufficient = (
       throw new InputSelectionError(InputSelectionFailure.UtxoBalanceInsufficient);
     }
   }
-  assertIsCoinBalanceSufficient(utxoValues, outputValues);
+  assertIsCoinBalanceSufficient(utxoValues, outputValues, implicitCoin);
 };

Diff for: packages/cip2/test/RoundRobinRandomImprove.test.ts

@@ -156,30 +156,34 @@ describe('RoundRobinRandomImprove', () => {
     const algorithm = getRoundRobinRandomImprove(csl);
 
     await fc.assert(
-      fc.asyncProperty(generateSelectionParams(), async ({ utxoAmounts, outputsAmounts, constraints }) => {
-        // Run input selection
-        const utxo = new Set(
-          utxoAmounts.map((valueQuantities) => CslTestUtil.createUnspentTxOutput(csl, valueQuantities))
-        );
-        const outputs = new Set(
-          outputsAmounts.map((valueQuantities) => CslTestUtil.createOutput(csl, valueQuantities))
-        );
+      fc.asyncProperty(
+        generateSelectionParams(),
+        async ({ utxoAmounts, outputsAmounts, constraints, implicitCoin }) => {
+          // Run input selection
+          const utxo = new Set(
+            utxoAmounts.map((valueQuantities) => CslTestUtil.createUnspentTxOutput(csl, valueQuantities))
+          );
+          const outputs = new Set(
+            outputsAmounts.map((valueQuantities) => CslTestUtil.createOutput(csl, valueQuantities))
+          );
 
-        try {
-          const results = await algorithm.select({
-            utxo: new Set(utxo),
-            outputs,
-            constraints: SelectionConstraints.mockConstraintsToConstraints(constraints)
-          });
-          assertInputSelectionProperties({ results, outputs, utxo, constraints });
-        } catch (error) {
-          if (error instanceof InputSelectionError) {
-            assertFailureProperties({ error, utxoAmounts, outputsAmounts, constraints });
-          } else {
-            throw error;
+          try {
+            const results = await algorithm.select({
+              utxo: new Set(utxo),
+              outputs,
+              constraints: SelectionConstraints.mockConstraintsToConstraints(constraints),
+              implicitCoin
+            });
+            assertInputSelectionProperties({ results, outputs, utxo, constraints, implicitCoin });
+          } catch (error) {
+            if (error instanceof InputSelectionError) {
+              assertFailureProperties({ error, utxoAmounts, outputsAmounts, constraints, implicitCoin });
+            } else {
+              throw error;
+            }
           }
         }
-      })
+      )
     );
   });
 });