@bitgo-forks/avalanchejs 4.1.0-alpha.1

package/src/vms/pvm/utxoCalculationFns/useUnlockedUTXOs.ts

@@ -0,0 +1,138 @@
+import { verifySignaturesMatch } from '../../../vms/utils/calculateSpend/utils';
+import {
+  TransferableOutput,
+  TransferOutput,
+  TransferableInput,
+  TransferInput,
+  OutputOwners,
+} from '../../../serializable';
+import { BigIntPr, Int } from '../../../serializable/primitives';
+import type { StakeableLockOut } from '../../../serializable/pvm';
+import {
+  isTransferOut,
+  isStakeableLockOut,
+  addressesFromBytes,
+} from '../../../utils';
+import { bigIntMin } from '../../../utils/bigintMath';
+import type { UTXOCalculationState } from '../../utils/calculateSpend';
+
+export function useUnlockedUTXOs({
+  amountsToBurn,
+  utxos,
+  fromAddresses,
+  amountsToStake,
+  options,
+  changeOutputs,
+  inputUTXOs,
+  inputs,
+  stakeOutputs,
+  ...state
+}: UTXOCalculationState): UTXOCalculationState {
+  const changeOwner = new OutputOwners(
+    new BigIntPr(0n),
+    new Int(1),
+    addressesFromBytes(options.changeAddresses),
+  );
+  const usableUTXOs = utxos.filter((utxo) => {
+    if (isTransferOut(utxo.output)) {
+      return true;
+    }
+    const out = utxo.output;
+    if (!isStakeableLockOut(out) || !isTransferOut(out.transferOut)) {
+      return false;
+    }
+    return out.getLocktime() < options.minIssuanceTime;
+  });
+
+  verifySignaturesMatch(
+    usableUTXOs,
+    (utxo) => {
+      return (
+        isTransferOut(utxo.output)
+          ? utxo.output
+          : (utxo.output as StakeableLockOut).transferOut
+      ) as TransferOutput;
+    },
+    fromAddresses,
+    options,
+  ).forEach(({ sigData, data: utxo }) => {
+    const remainingAmountToBurn = amountsToBurn.get(utxo.assetId.value()) ?? 0n;
+
+    const remainingAmountToStake =
+      amountsToStake.get(utxo.assetId.value()) ?? 0n;
+
+    if (!remainingAmountToBurn && !remainingAmountToStake) {
+      return;
+    }
+
+    const utxoTransferout = (
+      isTransferOut(utxo.output)
+        ? utxo.output
+        : (utxo.output as StakeableLockOut).transferOut
+    ) as TransferOutput;
+
+    inputs.push(
+      new TransferableInput(
+        utxo.utxoId,
+        utxo.assetId,
+        TransferInput.fromNative(utxoTransferout.amount(), sigData.sigIndicies),
+      ),
+    );
+
+    inputUTXOs.push(utxo);
+
+    const amountToBurn = bigIntMin(
+      remainingAmountToBurn,
+      utxoTransferout.amt.value(),
+    );
+
+    amountsToBurn.set(
+      utxo.assetId.value(),
+      remainingAmountToBurn - amountToBurn,
+    );
+
+    const amountAvailableToStake = utxoTransferout.amount() - amountToBurn;
+
+    const amountToStake = bigIntMin(
+      remainingAmountToStake,
+      amountAvailableToStake,
+    );
+
+    amountsToStake.set(
+      utxo.assetId.value(),
+      (amountsToStake.get(utxo.assetId.value()) ?? 0n) - amountToStake,
+    );
+
+    if (amountToStake > 0n) {
+      stakeOutputs.push(
+        new TransferableOutput(
+          utxo.assetId,
+          new TransferOutput(new BigIntPr(amountToStake), changeOwner),
+        ),
+      );
+    }
+
+    const remainingAmount = amountAvailableToStake - amountToStake;
+    if (remainingAmount > 0) {
+      changeOutputs.push(
+        new TransferableOutput(
+          utxo.assetId,
+          new TransferOutput(new BigIntPr(remainingAmount), changeOwner),
+        ),
+      );
+    }
+  });
+
+  return {
+    ...state,
+    amountsToBurn,
+    utxos,
+    fromAddresses,
+    amountsToStake,
+    options,
+    changeOutputs,
+    inputUTXOs,
+    inputs,
+    stakeOutputs,
+  };
+}

package/src/vms/utils/calculateSpend/calculateSpend.spec.ts

@@ -0,0 +1,205 @@
+import { BigIntPr, Int } from '../../../serializable/primitives';
+import { testContext } from '../../../fixtures/context';
+import {
+  fromAddressBytes,
+  getLockedUTXO,
+  getStakeableLockoutOutput,
+  getValidUtxo,
+  testAvaxAssetID,
+  testUTXOID1,
+  testUTXOID2,
+  testUTXOID3,
+  testUtxos,
+} from '../../../fixtures/transactions';
+import { addressesFromBytes } from '../../../utils';
+import { calculateUTXOSpend } from './calculateSpend';
+import {
+  useSpendableLockedUTXOs,
+  useUnlockedUTXOs,
+} from '../../pvm/utxoCalculationFns';
+import { compareTransferableOutputs } from '../../../utils/sort';
+import {
+  OutputOwners,
+  TransferableOutput,
+  TransferInput,
+  TransferOutput,
+} from '../../../serializable';
+import { TransferableInput } from '../../../serializable';
+import { Address, Id } from '../../../serializable/fxs/common';
+import { NoSigMatchError } from './utils';
+import { useAvmAndCorethUTXOs } from '../../../vms/avm/utxoCalculationFns';
+import type { StakeableLockOut } from '../../../serializable/pvm';
+import { StakeableLockIn } from '../../../serializable/pvm';
+import { UTXOID } from '../../../serializable/avax';
+
+describe('src/vms/pvm/spend/calculateSpend.spec.ts', () => {
+  it('should pay down burn and stake from utxos', () => {
+    const burnAmount = 100n;
+    const unlockedUTXOAmount = 200n;
+    const stakeAmount = 1000000n;
+
+    const stakeAmount1 = 500000n;
+    const stakeAmount2 = 600000n;
+    const lockTime1 = BigInt(Math.floor(new Date().getTime() / 1000)) + 100000n;
+    const lockTime2 = BigInt(Math.floor(new Date().getTime() / 1000)) + 200000n;
+
+    const { stakeOutputs, changeOutputs, inputs } = calculateUTXOSpend(
+      new Map([[testContext.avaxAssetID, burnAmount]]),
+      new Map([[testContext.avaxAssetID, stakeAmount]]),
+      [
+        getValidUtxo(new BigIntPr(unlockedUTXOAmount)),
+        getStakeableLockoutOutput(testUTXOID1, stakeAmount1, lockTime1),
+        getStakeableLockoutOutput(testUTXOID2, stakeAmount2, lockTime2),
+      ],
+      addressesFromBytes(fromAddressBytes),
+      { changeAddresses: fromAddressBytes, minIssuanceTime: 0n } as any,
+      [useSpendableLockedUTXOs, useUnlockedUTXOs],
+    );
+
+    const getExpectedStakeOut = (lockTime: bigint, amount: bigint) =>
+      new TransferableOutput(
+        testAvaxAssetID,
+        getStakeableLockoutOutput(
+          Id.fromHex(''), // does not matter, we only need the output of the UTXO
+          amount,
+          lockTime,
+        ).output as StakeableLockOut,
+      );
+
+    const getExpectedStakeInput = (
+      utxoID: UTXOID,
+      amount: bigint,
+      lockTime: bigint,
+    ) =>
+      new TransferableInput(
+        utxoID,
+        testAvaxAssetID,
+        new StakeableLockIn(
+          new BigIntPr(lockTime),
+          TransferInput.fromNative(amount, [0]),
+        ),
+      );
+
+    // sorted stake outputs
+    expect(stakeOutputs.length).toEqual(2);
+
+    expect(stakeOutputs[0]).toStrictEqual(
+      getExpectedStakeOut(lockTime1, 500000n),
+    );
+    expect(stakeOutputs[1]).toStrictEqual(
+      getExpectedStakeOut(lockTime2, 500000n),
+    );
+
+    // sorted inputs
+    expect(inputs.length).toEqual(3);
+
+    expect(inputs[0]).toStrictEqual(
+      getExpectedStakeInput(
+        new UTXOID(testUTXOID1, new Int(0)),
+        stakeAmount1,
+        lockTime1,
+      ),
+    );
+    expect(inputs[1]).toStrictEqual(
+      new TransferableInput(
+        new UTXOID(testUTXOID3, new Int(0)),
+        testAvaxAssetID,
+        TransferInput.fromNative(unlockedUTXOAmount, [0]),
+      ),
+    );
+    expect(inputs[2]).toStrictEqual(
+      getExpectedStakeInput(
+        new UTXOID(testUTXOID2, new Int(0)),
+        stakeAmount2,
+        lockTime2,
+      ),
+    );
+
+    // sorted change outputs
+    expect(changeOutputs.length).toEqual(2);
+
+    expect(changeOutputs[0]).toStrictEqual(
+      new TransferableOutput(
+        testAvaxAssetID,
+        new TransferOutput(
+          new BigIntPr(unlockedUTXOAmount - burnAmount),
+          new OutputOwners(
+            new BigIntPr(0n),
+            new Int(1),
+            addressesFromBytes(fromAddressBytes),
+          ),
+        ),
+      ),
+    );
+    expect(changeOutputs[1]).toStrictEqual(
+      getExpectedStakeOut(lockTime2, stakeAmount1 + stakeAmount2 - stakeAmount),
+    );
+  });
+  it('Should verify if the changeOutputs, inputs and stakeOutputs have been sorted', () => {
+    const burnAmount = 100n;
+    const unlockedUTXOAmount = 200n;
+    const lockedUTXOAmount = 1000000n;
+    const stakeUTXOAmount = 1000000n;
+
+    const { stakeOutputs, changeOutputs, inputs } = calculateUTXOSpend(
+      new Map([[testContext.avaxAssetID, burnAmount]]),
+      new Map([[testContext.avaxAssetID, stakeUTXOAmount]]),
+      [
+        getValidUtxo(new BigIntPr(unlockedUTXOAmount)),
+        getLockedUTXO(new BigIntPr(lockedUTXOAmount)),
+      ],
+      addressesFromBytes(fromAddressBytes),
+      { changeAddresses: fromAddressBytes } as any,
+      [useSpendableLockedUTXOs, useUnlockedUTXOs],
+    );
+
+    expect(stakeOutputs).toEqual(
+      [...stakeOutputs].sort(compareTransferableOutputs),
+    );
+    expect(changeOutputs).toEqual(
+      [...changeOutputs].sort(compareTransferableOutputs),
+    );
+    expect(inputs).toEqual([...inputs].sort(TransferableInput.compare));
+  });
+
+  it('Should throw an error when the UTXO owner "fromAddress" doesnt match any UTXOs', () => {
+    const tryUseFunctionAndThrowMismatchError = (useFn: (() => any)[]) => {
+      return calculateUTXOSpend(
+        new Map([[testContext.avaxAssetID, 100n]]),
+        new Map([[testContext.avaxAssetID, 10000n]]),
+        [
+          getValidUtxo(new BigIntPr(10000n)),
+          getLockedUTXO(new BigIntPr(10000n)),
+          getStakeableLockoutOutput(testUTXOID1, 300n),
+          getStakeableLockoutOutput(testUTXOID2, 10000n),
+          ...testUtxos(),
+        ],
+        // use random address that doesnt belong to any utxos we have in the test
+        addressesFromBytes([
+          Address.fromString(
+            'X-fuji1xwdz5ca4pl443ghm6ez63m7yr64wu6u7qhksa2',
+          ).toBytes(),
+        ]),
+        {
+          changeAddresses: fromAddressBytes,
+          minIssuanceTime: 1000000000000n,
+        } as any,
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        [...useFn],
+      );
+    };
+
+    function catchAndEqualNoSigMatch(useFns) {
+      try {
+        tryUseFunctionAndThrowMismatchError(useFns);
+      } catch (err) {
+        expect(err).toEqual(NoSigMatchError);
+      }
+    }
+
+    catchAndEqualNoSigMatch([useUnlockedUTXOs]);
+    catchAndEqualNoSigMatch([useSpendableLockedUTXOs, useUnlockedUTXOs]);
+    catchAndEqualNoSigMatch([useAvmAndCorethUTXOs]);
+  });
+});

package/src/vms/utils/calculateSpend/calculateSpend.ts

@@ -0,0 +1,131 @@
+import { TransferableInput } from '../../../serializable';
+import type { Utxo } from '../../../serializable/avax/utxo';
+import type { Address } from '../../../serializable/fxs/common';
+import { AddressMaps } from '../../../utils/addressMap';
+import { compareTransferableOutputs } from '../../../utils/sort';
+import type { SpendOptionsRequired } from '../../common';
+import type { UTXOCalculationFn, UTXOCalculationResult } from './models';
+
+export const defaultSpendResult = (): UTXOCalculationResult => ({
+  inputs: [],
+  inputUTXOs: [],
+  stakeOutputs: [],
+  changeOutputs: [],
+  addressMaps: new AddressMaps(),
+});
+
+/**
+ * Make sure that the next state recieves a deep copy so that it cant mutate state. This is great if we need to
+ * diagnose where something was changed. We can view state by state by putting logs between state cycles.
+ *
+ * @param state the state from previous action function
+ * @returns UTXOCalculationResult
+ */
+function deepCopyState(state) {
+  return {
+    ...state,
+    amountsToBurn: new Map([...state.amountsToBurn]),
+    amountsToStake: new Map([...state.amountsToStake]),
+    inputs: [...state.inputs],
+    inputUTXOs: [...state.inputUTXOs],
+    stakeOutputs: [...state.stakeOutputs],
+    changeOutputs: [...state.changeOutputs],
+  };
+}
+/**
+ * The idea here is a iterator style UTXO operator function system. Pass in the UTXOs and all of its operating functions. Each
+ * function takes into account the state and performs its state changes. The next function is given a copy of the previous
+ * and makes it updates. This way there is no mutations between functions but we can see from function to function what changes
+ * were made if needed.
+ *
+ * In the very near future we can break the operator functions into much smaller chunks and have very precise operators instead of one
+ * operator that deals with unlocked tokens for burn and stake and inputs all in one
+ *
+ * @param amountsToBurn
+ * @param utxos
+ * @param amountsToStake
+ * @param fromAddresses
+ * @param options
+ * @param utxoParsers
+ * @returns
+ */
+export function calculateUTXOSpend(
+  amountsToBurn = new Map<string, bigint>(),
+  amountsToStake = new Map<string, bigint>(),
+  utxos: Utxo[],
+  fromAddresses: Address[],
+  options: SpendOptionsRequired,
+  utxoCalculationFns: [UTXOCalculationFn, ...UTXOCalculationFn[]],
+): UTXOCalculationResult {
+  const startState = {
+    amountsToBurn,
+    utxos,
+    amountsToStake,
+    fromAddresses,
+    options,
+    ...defaultSpendResult(),
+  };
+  const result = (
+    [
+      ...utxoCalculationFns,
+      function verifyAmountToBurnIsFulfilled({ amountsToBurn, ...state }) {
+        amountsToBurn.forEach((amount, assetId) => {
+          if (amount !== 0n) {
+            throw new Error(
+              `insufficient funds (Burn Amount): need ${amount} more units of ${assetId} to burn`,
+            );
+          }
+        });
+
+        return { amountsToBurn, ...state };
+      },
+      function verifyAmountToStateIsFulfilled({ amountsToStake, ...state }) {
+        amountsToStake.forEach((amount, assetId) => {
+          if (amount !== 0n) {
+            throw new Error(
+              `insufficient funds (Stake Amount): need ${amount} more units of ${assetId} to stake`,
+            );
+          }
+        });
+
+        return { amountsToStake, ...state };
+      },
+      function sortTransferableInputs({ inputs, ...state }) {
+        inputs.sort(TransferableInput.compare);
+        return { inputs, ...state };
+      },
+      function sortChangeOutputs({ changeOutputs, ...state }) {
+        changeOutputs.sort(compareTransferableOutputs);
+        return { changeOutputs, ...state };
+      },
+      function sortStakeOutputs({ stakeOutputs, ...state }) {
+        stakeOutputs.sort(compareTransferableOutputs);
+        return { stakeOutputs, ...state };
+      },
+      function getAdressMaps({ inputs, inputUTXOs, ...state }) {
+        const addressMaps = AddressMaps.fromTransferableInputs(
+          inputs,
+          inputUTXOs,
+          options.minIssuanceTime,
+          fromAddresses.map((add) => add.toBytes()),
+        );
+        return { inputs, inputUTXOs, ...state, addressMaps };
+      },
+    ] as UTXOCalculationFn[]
+  ).reduce((state, next) => {
+    // to prevent mutation we deep copy the arrays and maps before passing off to
+    // the next operator
+    return next(deepCopyState(state));
+  }, startState);
+  const {
+    /* eslint-disable @typescript-eslint/no-unused-vars */
+    amountsToBurn: _amountsToBurn,
+    amountsToStake: _amountsToStake,
+    fromAddresses: _fromAddresses,
+    options: _options,
+    utxos: _utxos,
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    ...calculationResults
+  } = result;
+  return calculationResults;
+}

package/src/vms/utils/calculateSpend/index.ts

@@ -0,0 +1,2 @@
+export * from './calculateSpend';
+export * from './models';

package/src/vms/utils/calculateSpend/models.ts

@@ -0,0 +1,28 @@
+import type { Utxo } from '../../../serializable/avax/utxo';
+import type {
+  TransferableOutput,
+  TransferableInput,
+} from '../../../serializable';
+import type { Address } from '../../../serializable/fxs/common';
+import type { SpendOptionsRequired } from '../../common';
+import type { AddressMaps } from '../../../utils/addressMap';
+
+export interface UTXOCalculationResult {
+  inputs: TransferableInput[];
+  inputUTXOs: Utxo[];
+  stakeOutputs: TransferableOutput[];
+  changeOutputs: TransferableOutput[];
+  addressMaps: AddressMaps;
+}
+
+export interface UTXOCalculationState extends UTXOCalculationResult {
+  amountsToBurn: Map<string, bigint>;
+  utxos: Utxo[];
+  fromAddresses: Address[];
+  amountsToStake: Map<string, bigint>;
+  options: SpendOptionsRequired;
+}
+
+export type UTXOCalculationFn = (
+  values: UTXOCalculationState,
+) => UTXOCalculationState;

package/src/vms/utils/calculateSpend/utils/index.ts

@@ -0,0 +1 @@
+export * from './verifySignaturesMatch';

package/src/vms/utils/calculateSpend/utils/verifySignaturesMatch.ts

@@ -0,0 +1,44 @@
+import type { MatchOwnerResult } from '../../../../utils/matchOwners';
+import { matchOwners } from '../../../../utils/matchOwners';
+import type { TransferOutput } from '../../../../serializable';
+
+export type verifySigMatchItem<T> = Required<{
+  sigData: MatchOwnerResult;
+  data: T;
+}>;
+
+export const NoSigMatchError = new Error('No addresses match UTXO owners');
+
+/**
+ * The idea here is to verify that a given set of utxos contains any utxos that share addresses
+ * with the fromAddresses array. If not we should be throwing an error as the tx is being formulated
+ * incoreectly
+ *
+ * @param set the utxo or data set, this can change depening on the calcFn
+ * @param getTransferOutput a callback that takes a utxo and gets the output
+ * @param fromAddresses the addresses the utxos should belong to
+ * @param options
+ * @returns T[]
+ */
+export function verifySignaturesMatch<T>(
+  set: T[],
+  getTransferOutput: (utxo: T) => TransferOutput,
+  fromAddresses,
+  options,
+): verifySigMatchItem<T>[] {
+  const outs = set.reduce((acc, data) => {
+    const out = getTransferOutput(data);
+
+    const sigData = matchOwners(
+      out.outputOwners,
+      fromAddresses,
+      options.minIssuanceTime,
+    );
+
+    return sigData ? [...acc, { sigData, data }] : acc;
+  }, [] as verifySigMatchItem<T>[]);
+
+  if (set.length && !outs.length) throw NoSigMatchError;
+
+  return outs;
+}