Rewrite transaction balance / fee calculation logic

.changeset/smart-avocados-type.md

@@ -0,0 +1,5 @@
+---
+"@blaze-cardano/tx": patch
+---
+
+Adds a new Coin Selection algorithm as an export (while keeping the default selection algo intact for now).

packages/blaze-tx/package.json

@@ -21,7 +21,9 @@
     "dev": "tsup src/index.ts --format esm,cjs --watch --dts --external rxjs",
     "lint": "eslint \"src/**/*.ts*\"",
     "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
-    "test": "jest"
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
   "devDependencies": {
     "@blaze-cardano/eslint-config": "workspace:*",

packages/blaze-tx/src/coinSelectors/hvfSelector.ts

@@ -0,0 +1,203 @@
+import {
+  type Address,
+  AssetId,
+  hardCodedProtocolParams,
+  type TokenMap,
+  TransactionOutput,
+  type TransactionUnspentOutput,
+  Value,
+} from "@blaze-cardano/core";
+import * as value from "../value";
+import type { CoinSelectionFunc, SelectionResult } from "../types";
+import { calculateMinAda, isEqualUTxO, stringifyBigint } from "../utils";
+
+/**
+ * Returns a list of UTxOs whose total assets are equal to or greater than the asset value provided
+ * @link https://github.com/Anastasia-Labs/lucid-evolution/blob/main/packages/utils/src/utxo.ts#L112
+ * @param utxos list of available utxos
+ * @param assetsRequired minimum total assets required
+ * @param includeUTxOsWithScriptRef Whether to include UTxOs with scriptRef or not. default = false
+ */
+export const selectUTxOs = (
+  utxos: TransactionUnspentOutput[],
+  totalRequired: Value,
+  includeUTxOsWithScriptRef: boolean = false,
+): TransactionUnspentOutput[] => {
+  const selectedUtxos: TransactionUnspentOutput[] = [];
+  let isSelected = false;
+  isSelected = false;
+  const assetsRequired = new Map<string, bigint>([
+    ...Object.entries({
+      lovelace: totalRequired.coin(),
+    }),
+    ...(totalRequired.multiasset()?.entries() || []),
+  ]);
+
+  for (const utxo of utxos) {
+    if (!includeUTxOsWithScriptRef && utxo.output().scriptRef()) continue;
+    isSelected = false;
+    for (const [unit, amount] of assetsRequired) {
+      const assetAmount =
+        unit === "lovelace"
+          ? utxo.output().amount().coin()
+          : utxo.output().amount().multiasset()?.get(AssetId(unit));
+      if (assetAmount) {
+        if (assetAmount >= amount) {
+          assetsRequired.delete(unit);
+        } else {
+          assetsRequired.set(unit, amount - assetAmount);
+        }
+        isSelected = true;
+      }
+    }
+    if (isSelected) {
+      selectedUtxos.push(utxo);
+    }
+    if (assetsRequired.size == 0) {
+      break;
+    }
+  }
+  if (assetsRequired.size > 0) return [];
+  return selectedUtxos;
+};
+
+const calculateExtraLovelace = (
+  leftoverAssets: Value,
+  address: Address,
+  coinsPerUtxoByte: number,
+): Value => {
+  const output = new TransactionOutput(address, leftoverAssets);
+  const minLovelace = calculateMinAda(output, coinsPerUtxoByte);
+  const currentLovelace = leftoverAssets.coin();
+  return currentLovelace >= minLovelace
+    ? new Value(0n)
+    : new Value(minLovelace - currentLovelace);
+};
+
+/**
+ * Performs coin selection to obtain the "requiredAssets" and then carries out
+ * recursive coin selection to ensure that leftover assets (selectedAssets + externalAssets - requiredAssets)
+ * have enough ADA to satisfy minimum ADA requirement for them to be sent as change output.
+ * If "requiredAssets" is empty, it still checks for minimum ADA requirement of "externalAssets"
+ * and does coin selection if required.
+ * @param inputs
+ * @param requiredAssets
+ * @param coinsPerUtxoByte
+ * @param externalAssets
+ * @param error
+ * @returns
+ */
+export const recursive = (
+  inputs: TransactionUnspentOutput[],
+  requiredAssets: Value,
+  externalAssets: Value = new Value(0n),
+  coinsPerUtxoByte: number = hardCodedProtocolParams.coinsPerUtxoByte,
+): SelectionResult => {
+  const firstInput = inputs[0];
+  let selected: TransactionUnspentOutput[] = selectUTxOs(
+    inputs,
+    requiredAssets,
+  );
+  if (!firstInput || selected.length === 0) {
+    throw new Error(
+      `Your wallet does not have enough funds to cover the required assets: ${stringifyBigint(requiredAssets.toCore())}. Or it contains UTxOs with reference scripts; which are excluded from coin selection.`,
+    );
+  }
+
+  const selectedAssets: Value = value.sum(
+    selected.map((s) => s.output().amount()),
+  );
+
+  let availableAssets = value.sub(selectedAssets, requiredAssets);
+  availableAssets = value.sum([availableAssets, externalAssets]);
+
+  let extraLovelace: Value | undefined = calculateExtraLovelace(
+    availableAssets,
+    firstInput.output().address(),
+    coinsPerUtxoByte,
+  );
+
+  let remainingInputs = inputs;
+
+  while (extraLovelace.coin() > 0n) {
+    remainingInputs = remainingInputs.filter(
+      (i, index) => !selected[index] || !isEqualUTxO(i, selected[index]),
+    );
+
+    const extraSelected = selectUTxOs(remainingInputs, extraLovelace);
+    if (extraSelected.length === 0) {
+      throw new Error(
+        `Your wallet does not have enough funds to cover required minimum ADA for change output: ${stringifyBigint(extraLovelace.toCore())}. Or it contains UTxOs with reference scripts; which are excluded from coin selection.`,
+      );
+    }
+
+    const extraSelectedAssets: Value = value.sum(
+      extraSelected.map((v) => v.output().amount()),
+    );
+    selected = [...selected, ...extraSelected];
+    availableAssets = value.sum([availableAssets, extraSelectedAssets]);
+
+    extraLovelace = calculateExtraLovelace(
+      availableAssets,
+      firstInput.output().address(),
+      coinsPerUtxoByte,
+    );
+  }
+
+  const leftoverInputs = inputs.filter((i) => !selected.includes(i));
+
+  return {
+    selectedInputs: selected,
+    leftoverInputs,
+    selectedValue: selectedAssets,
+  };
+};
+
+/**
+ * This coin selection algorithm follows a Highest Value First (HVF) function, taking into consideration things like fee estimation.
+ * Inspiration taken from Lucid Evolution: https://github.com/Anastasia-Labs/lucid-evolution/blob/main/packages/lucid/src/tx-builder/internal/CompleteTxBuilder.ts#L789
+ * @param inputs
+ * @param collectedAssets
+ * @param preliminaryFee
+ * @param externalAssets
+ * @param coinsPerUtxoByte
+ * @returns
+ */
+export const hvfSelector: CoinSelectionFunc = (
+  inputs,
+  collectedAssets,
+  preliminaryFee = 0,
+  externalAssets = new Value(0n),
+  coinsPerUtxoByte = hardCodedProtocolParams.coinsPerUtxoByte,
+) => {
+  const requiredAssets = new Value(
+    collectedAssets.coin() + externalAssets.coin() + BigInt(preliminaryFee),
+  );
+  const nonRequiredAssets = new Value(0n);
+
+  externalAssets.multiasset()?.forEach((amount, id) => {
+    const requiredMultiAsset = requiredAssets.multiasset()?.get(id);
+    const nonRequiredMultiAsset = nonRequiredAssets.multiasset()?.get(id);
+    if (amount < 0n) {
+      if (nonRequiredMultiAsset) {
+        (nonRequiredAssets.multiasset() as TokenMap).set(
+          id,
+          nonRequiredMultiAsset + amount,
+        );
+      } else {
+        nonRequiredAssets.setMultiasset(new Map([[AssetId(id), amount]]));
+      }
+    } else {
+      if (requiredMultiAsset) {
+        (requiredAssets.multiasset() as TokenMap).set(
+          id,
+          requiredMultiAsset + amount,
+        );
+      } else {
+        requiredAssets.setMultiasset(new Map([[AssetId(id), amount]]));
+      }
+    }
+  });
+
+  return recursive(inputs, requiredAssets, nonRequiredAssets, coinsPerUtxoByte);
+};

packages/blaze-tx/src/coinSelection.ts → packages/blaze-tx/src/coinSelectors/micahsSelector.ts

@@ -1,16 +1,7 @@
 import type { TransactionUnspentOutput } from "@blaze-cardano/core";
 import { Value, UTxOSelectionError } from "@blaze-cardano/core";
-import * as value from "./value";
-
-/**
- * The result of a coin selection operation.
- * It includes the selected inputs, the total value of the selected inputs, and the remaining inputs.
- */
-export type SelectionResult = {
-  selectedInputs: TransactionUnspentOutput[];
-  selectedValue: Value;
-  inputs: TransactionUnspentOutput[];
-};
+import * as value from "../value";
+import type { CoinSelectionFunc, SelectionResult } from "../types";
 
 /**
  * The wide selection algorithm is a multiasset coin selector that doesn't care about magnitude.
@@ -59,7 +50,11 @@ function wideSelection(
       acc = value.merge(acc, bestStep[1]);
     }
   }
-  return { selectedInputs, selectedValue: acc, inputs: availableInputs };
+  return {
+    selectedInputs,
+    selectedValue: acc,
+    leftoverInputs: availableInputs,
+  };
 }
 
 /**
@@ -110,7 +105,11 @@ function deepSelection(
       acc = value.merge(acc, bestStep[1]);
     }
   }
-  return { selectedInputs, selectedValue: acc, inputs: availableInputs };
+  return {
+    selectedInputs,
+    selectedValue: acc,
+    leftoverInputs: availableInputs,
+  };
 }
 
 /**
@@ -120,15 +119,15 @@ function deepSelection(
  * @param {Value} dearth - The value to be covered by the selected inputs.
  * @returns {SelectionResult} The result of the coin selection operation.
  */
-export function micahsSelector(
-  inputs: TransactionUnspentOutput[],
-  dearth: Value,
-): SelectionResult {
+export const micahsSelector: CoinSelectionFunc = (
+  inputs,
+  dearth,
+): SelectionResult => {
   const wideResult = wideSelection(inputs, dearth);
   const remainingDearth = value.positives(
     value.sub(dearth, wideResult.selectedValue),
   );
-  const deepResult = deepSelection(wideResult.inputs, remainingDearth);
+  const deepResult = deepSelection(wideResult.leftoverInputs, remainingDearth);
   const finalDearth = value.positives(
     value.sub(remainingDearth, deepResult.selectedValue),
   );
@@ -145,6 +144,6 @@ export function micahsSelector(
       wideResult.selectedValue,
       deepResult.selectedValue,
     ),
-    inputs: deepResult.inputs,
+    leftoverInputs: deepResult.leftoverInputs,
   };
-}
+};

packages/blaze-tx/src/index.ts

@@ -3,3 +3,4 @@ export * as Value from "./value";
 export { makeValue } from "./value";
 export * from "./data";
 export * from "./utils";
+export * as CoinSelector from "./coinSelectors/hvfSelector";