@meshsdk/transaction 1.6.0-alpha.11

package/src/transaction/transaction-v2.ts

@@ -0,0 +1,81 @@
+import { Asset, Data, UTxO } from "@meshsdk/common";
+
+export interface TransactionV2 {
+  sendAssets(
+    receiver: string,
+    assets: Asset[],
+    datum?: Data,
+    inlineScript?: string,
+    isInline?: boolean,
+  ): this;
+  spendUtxo(utxo: UTxO, redeemer?: Data): this;
+}
+
+// export type TxBuilder = {
+//   readFrom: (utxos: UTxO[]) => TxBuilder;
+//   collectFrom: (utxos: UTxO[], redeemer?: string | undefined) => TxBuilder;
+//   pay: {
+//     ToAddress: (address: string, assets: Assets) => TxBuilder;
+//     ToAddressWithData: (
+//       address: string,
+//       outputDatum: OutputDatum,
+//       assets?: Assets | undefined,
+//       scriptRef?: Script | undefined
+//     ) => TxBuilder;
+//     ToContract: (
+//       address: string,
+//       outputDatum: OutputDatum,
+//       assets?: Assets | undefined,
+//       scriptRef?: Script | undefined
+//     ) => TxBuilder;
+//   };
+//   addSigner: (address: Address) => TxBuilder;
+//   registerStake: (rewardAddress: RewardAddress) => TxBuilder;
+//   deRegisterStake: (
+//     rewardAddress: RewardAddress,
+//     redeemer?: string
+//   ) => TxBuilder;
+//   withdraw: (
+//     rewardAddress: RewardAddress,
+//     amount: Lovelace,
+//     redeemer?: string
+//   ) => TxBuilder;
+//   mintAssets: (assets: Assets, redeemer?: string | undefined) => TxBuilder;
+//   validFrom: (unixTime: number) => TxBuilder;
+//   validTo: (unixTime: number) => TxBuilder;
+//   delegateTo: (
+//     rewardAddress: RewardAddress,
+//     poolId: PoolId,
+//     redeemer?: Redeemer
+//   ) => TxBuilder;
+//   attachMetadata: (
+//     label: Label,
+//     metadata: Metadata.TransactionMetadata
+//   ) => TxBuilder;
+//   attach: {
+//     Script: (script: Script) => TxBuilder;
+//     SpendingValidator: (spendingValidator: Script) => TxBuilder;
+//     MintingPolicy: (mintingPolicy: Script) => TxBuilder;
+//     CertificateValidator: (certValidator: Script) => TxBuilder;
+//     WithdrawalValidator: (withdrawalValidator: Script) => TxBuilder;
+//   };
+//   complete: (
+//     options?: CompleteTxBuilder.CompleteOptions
+//   ) => Promise<TxSignBuilder.TxSignBuilder>;
+//   completeProgram: (
+//     options?: CompleteTxBuilder.CompleteOptions
+//   ) => Effect.Effect<TxSignBuilder.TxSignBuilder, TransactionError>;
+//   completeSafe: (
+//     options?: CompleteTxBuilder.CompleteOptions
+//   ) => Promise<Either<TxSignBuilder.TxSignBuilder, TransactionError>>;
+//   chainProgram: () => Effect.Effect<
+//     [UTxO[], UTxO[], TxSignBuilder.TxSignBuilder],
+//     TransactionError,
+//     never
+//   >;
+//   chain: () => Promise<[UTxO[], UTxO[], TxSignBuilder.TxSignBuilder]>;
+//   chainSafe: () => Promise<
+//     Either<[UTxO[], UTxO[], TxSignBuilder.TxSignBuilder], TransactionError>
+//   >;
+//   config: () => TxBuilderConfig;
+// };

package/src/utxo-selection/common.ts

@@ -0,0 +1,113 @@
+import { BigNum } from "@meshsdk/common";
+import { resolveTxFees } from "@meshsdk/common";
+import type { Protocol, Quantity, Unit, UTxO } from "@meshsdk/common";
+
+export const enoughValueHasBeenSelected = (
+  selection: UTxO[],
+  assets: Map<Unit, Quantity>
+): boolean => {
+  return Array.from(assets, (asset) => ({
+    unit: asset[0],
+    quantity: BigNum.new(asset[1]),
+  })).every((asset) => {
+    return (
+      selection
+        .filter((utxo) => {
+          return (
+            utxo.output.amount.find((a) => a.unit === asset.unit) !== undefined
+          );
+        })
+        .reduce((selectedQuantity, utxo) => {
+          const utxoQuantity = utxo.output.amount.reduce(
+            (quantity, a) =>
+              quantity.checkedAdd(
+                BigNum.new(asset.unit === a.unit ? a.quantity : "0")
+              ),
+            BigNum.new("0")
+          );
+
+          return selectedQuantity.checkedAdd(utxoQuantity);
+        }, BigNum.new("0"))
+        .lessThan(asset.quantity) === false
+    );
+  });
+};
+
+export const largestLovelaceQuantity = (utxoA: UTxO, utxoB: UTxO): number => {
+  const aLovelaceQuantity = BigNum.new(
+    utxoA.output.amount.find((asset) => asset.unit === "lovelace")?.quantity ??
+      "0"
+  );
+
+  const bLovelaceQuantity = BigNum.new(
+    utxoB.output.amount.find((asset) => asset.unit === "lovelace")?.quantity ??
+      "0"
+  );
+
+  return bLovelaceQuantity.compare(aLovelaceQuantity);
+};
+
+export const maxTxFees = (parameters: Protocol) => {
+  const { maxTxSize, minFeeA, minFeeB } = parameters;
+
+  return BigNum.new(resolveTxFees(maxTxSize, minFeeA, minFeeB));
+};
+
+export const multiAssetUTxO = (utxo: UTxO): boolean =>
+  utxo.output.amount.length > 1;
+
+export const selectedLovelaceQuantity = (multiAsset: UTxO[]) => {
+  return multiAsset.reduce((sum, utxo) => {
+    const lovelace =
+      utxo.output.amount.find((asset) => asset.unit === "lovelace")?.quantity ??
+      "0";
+
+    return sum.checkedAdd(BigNum.new(lovelace));
+  }, BigNum.new("0"));
+};
+
+export const remainingLovelace = (
+  quantity: Quantity,
+  initialUTxOSet: UTxO[]
+) => {
+  const sortedUTxOs = initialUTxOSet.sort(largestLovelaceQuantity);
+
+  const requestedOutputSet = new Map<Unit, Quantity>([["lovelace", quantity]]);
+
+  const selection = selectValue(sortedUTxOs, requestedOutputSet);
+
+  return selection;
+};
+
+export const selectValue = (
+  inputUTxO: UTxO[],
+  outputSet: Map<Unit, Quantity>,
+  selection: UTxO[] = []
+): UTxO[] => {
+  if (
+    inputUTxO.length === 0 ||
+    enoughValueHasBeenSelected(selection, outputSet)
+  ) {
+    return selection;
+  }
+
+  if (valueCanBeSelected(inputUTxO[0]!, outputSet)) {
+    return selectValue(inputUTxO.slice(1), outputSet, [
+      ...selection,
+      inputUTxO[0]!,
+    ]);
+  }
+
+  return selectValue(inputUTxO.slice(1), outputSet, selection);
+};
+
+export const valueCanBeSelected = (
+  utxo: UTxO,
+  assets: Map<Unit, Quantity>
+): boolean => {
+  return Array.from(assets.keys()).some((unit) => {
+    return (
+      utxo.output.amount.find((asset) => asset.unit === unit) !== undefined
+    );
+  });
+};

package/src/utxo-selection/experimental.ts

@@ -0,0 +1,137 @@
+import type { Quantity, UTxO, Unit } from "@meshsdk/common";
+
+export const experimentalSelectUtxos = (
+  requiredAssets: Map<Unit, Quantity>,
+  inputs: UTxO[],
+  threshold: Quantity
+): UTxO[] => {
+  const totalRequiredAssets = new Map<Unit, Quantity>(requiredAssets);
+  totalRequiredAssets.set(
+    "lovelace",
+    String(Number(totalRequiredAssets.get("lovelace") || 0) + Number(threshold))
+  );
+  const utxoMap = new Map<number, UTxO>();
+  for (let i = 0; i < inputs.length; i++) {
+    utxoMap.set(i, inputs[i]!);
+  }
+  const selectedInputs = new Set<number>();
+  const onlyLovelace = new Set<number>();
+  const singletons = new Set<number>();
+  const pairs = new Set<number>();
+  const rest = new Set<number>();
+  for (let i = 0; i < inputs.length; i++) {
+    switch (inputs[i]!.output.amount.length) {
+      case 1: {
+        onlyLovelace.add(i);
+        break;
+      }
+      case 2: {
+        singletons.add(i);
+        break;
+      }
+      case 3: {
+        pairs.add(i);
+        break;
+      }
+      default: {
+        rest.add(i);
+        break;
+      }
+    }
+  }
+
+  const addUtxoWithAssetAmount = (
+    inputIndex: number,
+    assetUnit: string,
+    set: Set<number>
+  ) => {
+    const utxo = utxoMap.get(inputIndex);
+    if (!utxo) return;
+
+    const amount = getAssetAmount(utxo, assetUnit);
+    if (Number(amount) > 0) {
+      selectedInputs.add(inputIndex);
+      set.delete(inputIndex);
+      for (const asset of utxo.output.amount) {
+        totalRequiredAssets.set(
+          asset.unit,
+          String(
+            Number(totalRequiredAssets.get(asset.unit)) - Number(asset.quantity)
+          )
+        );
+      }
+    }
+  };
+
+  for (const assetUnit of totalRequiredAssets.keys()) {
+    if (assetUnit == "lovelace") continue;
+    for (const inputIndex of singletons) {
+      const assetRequired = totalRequiredAssets.get(assetUnit);
+      if (!assetRequired || Number(assetRequired) <= 0) break;
+      addUtxoWithAssetAmount(inputIndex, assetUnit, singletons);
+    }
+
+    for (const inputIndex of pairs) {
+      const assetRequired = totalRequiredAssets.get(assetUnit);
+      if (!assetRequired || Number(assetRequired) <= 0) break;
+      addUtxoWithAssetAmount(inputIndex, assetUnit, pairs);
+    }
+
+    for (const inputIndex of rest) {
+      const assetRequired = totalRequiredAssets.get(assetUnit);
+      if (!assetRequired || Number(assetRequired) <= 0) break;
+      addUtxoWithAssetAmount(inputIndex, assetUnit, rest);
+    }
+  }
+
+  for (const inputIndex of onlyLovelace) {
+    const assetRequired = totalRequiredAssets.get("lovelace");
+    if (!assetRequired || Number(assetRequired) <= 0) break;
+    addUtxoWithAssetAmount(inputIndex, "lovelace", onlyLovelace);
+  }
+
+  for (const inputIndex of singletons) {
+    const assetRequired = totalRequiredAssets.get("lovelace");
+    if (!assetRequired || Number(assetRequired) <= 0) break;
+    addUtxoWithAssetAmount(inputIndex, "lovelace", singletons);
+  }
+
+  for (const inputIndex of pairs) {
+    const assetRequired = totalRequiredAssets.get("lovelace");
+    if (!assetRequired || Number(assetRequired) <= 0) break;
+    addUtxoWithAssetAmount(inputIndex, "lovelace", pairs);
+  }
+
+  for (const inputIndex of rest) {
+    const assetRequired = totalRequiredAssets.get("lovelace");
+    if (!assetRequired || Number(assetRequired) <= 0) break;
+    addUtxoWithAssetAmount(inputIndex, "lovelace", rest);
+  }
+
+  for (const assetUnit of totalRequiredAssets.keys()) {
+    if (Number(totalRequiredAssets.get(assetUnit)) > 0) {
+      console.log("Insufficient funds for", assetUnit);
+      console.log(
+        "Remaining quantity",
+        Number(totalRequiredAssets.get(assetUnit))
+      );
+      return [];
+    }
+  }
+
+  const selectedUtxos: UTxO[] = [];
+  for (const inputIndex of selectedInputs) {
+    const utxo = utxoMap.get(inputIndex);
+    if (utxo) {
+      selectedUtxos.push(utxo);
+    }
+  }
+  return selectedUtxos;
+};
+
+const getAssetAmount = (utxo: UTxO, assetUnit: string): string => {
+  for (const utxoAsset of utxo.output.amount) {
+    if (utxoAsset.unit == assetUnit) return utxoAsset.quantity;
+  }
+  return "0";
+};

package/src/utxo-selection/index.ts

@@ -0,0 +1,69 @@
+import { Unit, Quantity, UTxO } from "@meshsdk/common";
+import { keepRelevant } from "./keepRelevant";
+import { largestFirst } from "./largestFirst";
+import { largestFirstMultiAsset } from "./largestFirstMultiAsset";
+import { experimentalSelectUtxos } from "./experimental";
+
+export {
+  keepRelevant,
+  largestFirst,
+  largestFirstMultiAsset,
+  experimentalSelectUtxos,
+};
+
+/**
+ * All UTxO selection algorithms follows below's interface
+ *
+ * Supported algorithms:
+ * - largestFirst - CIP2 suggested algorithm
+ * - largestFirstMultiAsset - CIP2 suggested algorithm
+ * - keepRelevant - CIP2 suggested algorithm
+ * - experimental - The always evolving algorithm according to the latest research
+ *
+ * @param requestedOutputSet
+ * @param initialUTxOSet
+ * @returns
+ */
+export class UtxoSelection {
+  constructor() {}
+
+  largestFirst(
+    requiredAssets: Map<Unit, Quantity>,
+    inputs: UTxO[],
+    threshold = "5000000"
+  ) {
+    const lovelaceAmount = requiredAssets.get("lovelace") ?? "0";
+    const requiredAssetWithThreshold =
+      BigInt(lovelaceAmount) + BigInt(threshold);
+    return largestFirst(requiredAssetWithThreshold.toString(), inputs, false);
+  }
+
+  keepRelevant(
+    requiredAssets: Map<Unit, Quantity>,
+    inputs: UTxO[],
+    threshold = "5000000"
+  ) {
+    return keepRelevant(requiredAssets, inputs, threshold);
+  }
+
+  largestFirstMultiAsset(
+    requiredAssets: Map<Unit, Quantity>,
+    inputs: UTxO[],
+    threshold: Quantity
+  ) {
+    const lovelaceAmount = requiredAssets.get("lovelace") ?? "0";
+    requiredAssets.set(
+      "lovelace",
+      (BigInt(lovelaceAmount) + BigInt(threshold)).toString()
+    );
+    return largestFirstMultiAsset(requiredAssets, inputs, false);
+  }
+
+  experimental(
+    requiredAssets: Map<Unit, Quantity>,
+    inputs: UTxO[],
+    threshold: Quantity
+  ) {
+    return experimentalSelectUtxos(requiredAssets, inputs, threshold);
+  }
+}

package/src/utxo-selection/keepRelevant.ts

@@ -0,0 +1,35 @@
+import { BigNum, Quantity, UTxO, Unit } from "@meshsdk/common";
+import { remainingLovelace, selectedLovelaceQuantity } from "./common";
+
+export const keepRelevant = (
+  requiredAssets: Map<Unit, Quantity>,
+  inputs: UTxO[],
+  threshold = "5000000"
+) => {
+  const requestedLovelace = BigNum.new(
+    requiredAssets.get("lovelace") ?? "0"
+  ).checkedAdd(BigNum.new(threshold));
+
+  const multiAsset = inputs.filter((utxo) =>
+    utxo.output.amount
+      .filter((asset) => asset.unit !== "lovelace")
+      .some((asset) => requiredAssets.has(asset.unit))
+  );
+
+  const selectedLovelace = selectedLovelaceQuantity(multiAsset);
+
+  const lovelace = selectedLovelace.lessThan(requestedLovelace)
+    ? remainingLovelace(
+        requestedLovelace.clampedSub(selectedLovelace).toString(),
+        inputs.filter((input) => {
+          return !multiAsset.some(
+            (selectedUtxo) =>
+              selectedUtxo.input.txHash === input.input.txHash &&
+              selectedUtxo.input.outputIndex === input.input.outputIndex
+          );
+        })
+      )
+    : [];
+
+  return [...lovelace, ...multiAsset];
+};

package/src/utxo-selection/largestFirst.ts

@@ -0,0 +1,31 @@
+import {
+  Quantity,
+  UTxO,
+  DEFAULT_PROTOCOL_PARAMETERS,
+  BigNum,
+  resolveTxFees,
+  Unit,
+} from "@meshsdk/common";
+import { multiAssetUTxO, largestLovelaceQuantity, selectValue } from "./common";
+
+export const largestFirst = (
+  lovelace: Quantity,
+  initialUTxOSet: UTxO[],
+  includeTxFees = false,
+  { maxTxSize, minFeeA, minFeeB } = DEFAULT_PROTOCOL_PARAMETERS
+): UTxO[] => {
+  const sortedUTxOs = initialUTxOSet
+    .filter((utxo) => multiAssetUTxO(utxo) === false)
+    .sort(largestLovelaceQuantity);
+
+  const maxTxFees = BigNum.new(resolveTxFees(maxTxSize, minFeeA, minFeeB));
+
+  const quantity = includeTxFees
+    ? BigNum.new(lovelace).checkedAdd(maxTxFees).toString()
+    : lovelace;
+
+  const requestedOutputSet = new Map<Unit, Quantity>([["lovelace", quantity]]);
+
+  const selection = selectValue(sortedUTxOs, requestedOutputSet);
+  return selection;
+};

package/src/utxo-selection/largestFirstMultiAsset.ts

@@ -0,0 +1,37 @@
+import {
+  BigNum,
+  DEFAULT_PROTOCOL_PARAMETERS,
+  Quantity,
+  UTxO,
+  Unit,
+} from "@meshsdk/common";
+import {
+  multiAssetUTxO,
+  largestLovelaceQuantity,
+  maxTxFees,
+  selectValue,
+} from "./common";
+
+export const largestFirstMultiAsset = (
+  requestedOutputSet: Map<Unit, Quantity>,
+  initialUTxOSet: UTxO[],
+  includeTxFees = false,
+  parameters = DEFAULT_PROTOCOL_PARAMETERS
+): UTxO[] => {
+  const sortedMultiAssetUTxOs = initialUTxOSet
+    .filter(multiAssetUTxO)
+    .sort(largestLovelaceQuantity);
+
+  const txFees = maxTxFees(parameters);
+  const lovelace = requestedOutputSet.get("lovelace") ?? "0";
+
+  const quantity = includeTxFees
+    ? BigNum.new(lovelace).checkedAdd(txFees).toString()
+    : lovelace;
+
+  requestedOutputSet.set("lovelace", quantity);
+
+  const selection = selectValue(sortedMultiAssetUTxOs, requestedOutputSet);
+
+  return selection;
+};

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@meshsdk/typescript-config/base.json",
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules"]
+}