@sabaaa1/common 0.0.1

package/src/functions/kyc/authentoHelper.ts

@@ -0,0 +1,44 @@
+import { v4 } from 'uuid';
+import { IHinkal } from '../../data-structures/Hinkal/IHinkal';
+import { openDefaultPassportWindow } from './openDefaultPassportWindow';
+
+export const AUTHENTO = {
+  verifyMessageText:
+    'Sign this message to prove your ownership of this address and proceed with the identity verification process.',
+  domainName: 'Hinkal',
+  type: {
+    Message: [
+      { name: 'content', type: 'string' },
+      { name: 'for', type: 'string' },
+      { name: 'timestamp', type: 'string' },
+      { name: 'nonce', type: 'string' },
+    ],
+  },
+};
+
+export const authentoKycHandler = async (hinkal: IHinkal, shortName: string, onboardURL: string) => {
+  try {
+    const { domainName, type } = AUTHENTO;
+    const nonce = v4();
+    const currentTimeStamp = Date.now().toString();
+    const domain = { name: domainName };
+    const message = {
+      content: AUTHENTO.verifyMessageText,
+      for: domainName,
+      timestamp: currentTimeStamp,
+      nonce,
+    };
+    const signature = await hinkal.signTypedData(domain, type, message);
+    const address = await hinkal.getEthereumAddress();
+    const url =
+      `${onboardURL}verify/${domainName}?` +
+      `address=${address}&` +
+      `ts=${currentTimeStamp}&` +
+      `nonce=${nonce}&` +
+      `signature=${signature}&` +
+      `levelType=BASIC`;
+    openDefaultPassportWindow(url, shortName, 700, 510);
+  } catch (err) {
+    console.error('authentoHelper error: ', err);
+  }
+};

package/src/functions/kyc/index.ts

@@ -0,0 +1,3 @@
+export * from '../web3/functionCalls/accessTokenCalls';
+export * from './passportHelper';
+export * from './openDefaultPassportWindow';

package/src/functions/kyc/openDefaultPassportWindow.ts

@@ -0,0 +1,9 @@
+export const openDefaultPassportWindow = (onboardURL: string, shortName: string, height = 650, width = 400) => {
+  const top = window!.top!.outerHeight / 2 + window!.top!.screenY - height / 2;
+  const left = window!.top!.outerWidth / 2 + window!.top!.screenX - width / 2;
+  window.open(
+    onboardURL,
+    shortName,
+    `toolbar=no, menubar=no, width=${width}, height=${height}, top=${top}, left=${left}`,
+  );
+};

package/src/functions/kyc/passportHelper.ts

@@ -0,0 +1,13 @@
+import { SupportedPassports } from '../../constants/kyc.constants';
+import { Passports } from '../../types/kyc.types';
+
+import { IHinkal } from '../../data-structures/Hinkal/IHinkal';
+
+import { openDefaultPassportWindow } from './openDefaultPassportWindow';
+
+export const openPassportWindow = (passport: Passports, hinkal: IHinkal, height = 650, width = 400) => {
+  const { onboardURL, shortName, customHandleKYC } = SupportedPassports[passport];
+
+  if (!customHandleKYC) openDefaultPassportWindow(onboardURL, shortName, height, width);
+  else customHandleKYC(hinkal, shortName, onboardURL);
+};

package/src/functions/kyc/zkMeHelper.ts

@@ -0,0 +1,69 @@
+import { type Provider, type TransactionRequest, type ZkMeWidgetMessageBody } from '@zkmelabs/widget';
+import { ethers } from 'ethers';
+import { IHinkal } from '../../data-structures/Hinkal/IHinkal';
+import { getHinkalZkMeProvider } from '../../data-structures/Hinkal/hinkalGetZkMeProvider';
+import { openDefaultPassportWindow } from './openDefaultPassportWindow';
+
+async function messageListener(ev: MessageEvent<ZkMeWidgetMessageBody>, provider: Provider): Promise<any> {
+  const zkMeWidgetOrign = 'https://widget.zk.me';
+  if (ev.origin !== zkMeWidgetOrign) {
+    return;
+  }
+  if (ev.data.method === 'getUserAccounts') {
+    const userAccounts = await provider.getUserAccounts();
+    ev.source?.postMessage(
+      {
+        id: ev.data.id,
+        message: 'ok',
+        data: userAccounts,
+      },
+      { targetOrigin: ev.origin },
+    );
+  }
+
+  if (ev.data.method === 'getAccessToken') {
+    const accessToken = await provider.getAccessToken();
+
+    ev.source?.postMessage(
+      {
+        id: ev.data.id,
+        message: 'ok',
+        data: accessToken,
+      },
+      { targetOrigin: ev.origin },
+    );
+  }
+  if (ev.data.method === 'delegateTransaction') {
+    const params = ev.data.params as TransactionRequest;
+    if (provider.delegateTransaction) {
+      const delegateTx = await provider.delegateTransaction(params);
+      ev.source?.postMessage(
+        {
+          id: ev.data.id,
+          message: 'ok',
+          data: delegateTx,
+        },
+        { targetOrigin: ev.origin },
+      );
+    }
+  }
+}
+
+export const zkMeKycHandler = async (
+  hinkal: IHinkal,
+  shortName: string,
+  onboardURL: string,
+  params: {
+    merchId: string;
+  },
+) => {
+  const provider = getHinkalZkMeProvider(hinkal);
+
+  const accessToken = await provider.getAccessToken();
+  const chainId = hinkal.getCurrentChainId();
+
+  const zkChainString = ethers.utils.hexlify(chainId);
+  window.addEventListener('message', (event) => messageListener(event, provider));
+  const url = `${onboardURL}?mchNo=${params.merchId}&name=HinkalProtocol&chainId=${zkChainString}&accessToken=${accessToken}`;
+  openDefaultPassportWindow(url, shortName, 700, 510);
+};

package/src/functions/pre-transaction/constructAdminData.ts

@@ -0,0 +1,21 @@
+import { hashEthereumAddress } from '../utils/addresses';
+import { AdminDataType, AdminTransactionType } from '../../types/admin.types';
+
+export const constructAdminData = (
+  action: AdminTransactionType | undefined,
+  chainId: number,
+  erc20TokenAddresses: string[],
+  amountChanges: bigint[],
+  ethereumAddress: string,
+): AdminDataType | undefined => {
+  if (!action) return undefined;
+
+  return {
+    hashedOwner: hashEthereumAddress(ethereumAddress),
+    chainId,
+    timestamp: Date.now(),
+    action,
+    erc20TokenAddresses,
+    erc20TokenAmount: amountChanges.map(String),
+  };
+};

package/src/functions/pre-transaction/getExternalSwapAddress.ts

@@ -0,0 +1,30 @@
+import { networkRegistry } from '../../constants/chains.constants';
+import { IHinkal } from '../../data-structures/Hinkal/IHinkal';
+import { ExternalActionId } from '../../types/external-action.types';
+
+export const getExternalSwapAddress = (hinkal: IHinkal, externalActionId: ExternalActionId): string => {
+  const { contractData } = networkRegistry[hinkal.getCurrentChainId()];
+
+  let externalAddress: string | undefined;
+
+  switch (externalActionId) {
+    case ExternalActionId.Uniswap:
+      externalAddress = contractData?.uniswapExternalActionAddress;
+      break;
+    case ExternalActionId.Odos:
+      externalAddress = contractData?.odosExternalActionInstanceAddress;
+      break;
+    case ExternalActionId.OneInch:
+      externalAddress = contractData?.oneInchExternalActionInstanceAddress;
+      break;
+    case ExternalActionId.Lifi:
+      externalAddress = contractData?.hinkalAddress;
+      break;
+    default:
+      externalAddress = contractData?.uniswapExternalActionAddress;
+      break;
+  }
+  if (!externalAddress) throw new Error('No external Address set during swap');
+
+  return externalAddress;
+};

package/src/functions/pre-transaction/getFeeStructure.ts

@@ -0,0 +1,44 @@
+import { FeeStructure } from '../../types/hinkal.types';
+import { ExternalActionId } from '../../types/external-action.types';
+import { processGasEstimates } from './process-gas-estimates';
+import { CallInfo } from '../../types/API.types';
+import { getERC20Token } from '../utils/erc20tokenFunctions';
+import { caseInsensitiveEqual } from '../utils/caseInsensitive.utils';
+import { Logger } from '../../error-handling/logger';
+import { defaultFeeToken } from '../../constants/fees.constants';
+
+export const getFeeStructure = async (
+  chainId: number,
+  feeTokenAddress: string | undefined,
+  erc20Addresses: string[],
+  externalActionId: ExternalActionId,
+  calls: CallInfo[] = [],
+  variableRate = 0n,
+): Promise<FeeStructure> => {
+  const feeToken = getERC20Token(feeTokenAddress ?? defaultFeeToken, chainId);
+  if (!feeToken) throw new Error('failed to find feeToken');
+
+  const numberOfInputs = erc20Addresses.some((tokenAddress) => caseInsensitiveEqual(tokenAddress, feeTokenAddress))
+    ? erc20Addresses.length + 1
+    : erc20Addresses.length;
+
+  const { priceOfTransactionInToken } = await processGasEstimates(
+    chainId,
+    feeToken,
+    externalActionId,
+    numberOfInputs,
+    undefined,
+    calls,
+  );
+  if (priceOfTransactionInToken === undefined) throw new Error('failed to process gas estimates');
+
+  const feeStructure: FeeStructure = {
+    feeToken: feeToken.erc20TokenAddress,
+    flatFee: priceOfTransactionInToken,
+    variableRate,
+  };
+
+  Logger.log(feeStructure);
+
+  return feeStructure;
+};

package/src/functions/pre-transaction/getFlatFees.ts

@@ -0,0 +1,88 @@
+import { CallInfo, ERC20Token, ExternalActionId, INTERACTION } from '../../types';
+import { getERC20Token } from '../utils/erc20tokenFunctions';
+import { processGasEstimates } from './process-gas-estimates';
+import { getInteractionFromAction } from './interaction-to-action';
+import { FeeInfo } from '../../types/fee.types';
+
+/**
+ * Infer INTERACTION type from given @param externalActionId and @param action
+ * and return `flatFee` along with `feeUnit` - the token corespond with the fee,
+ * `priceOfTransactionInToken`, and `priceOfTransactionInUSD`
+ */
+export const getFlatFees = async (
+  chainId: number,
+  erc20Addresses: string[],
+  externalActionId: ExternalActionId,
+  amountChanges: bigint[],
+  /** if provided, gas will be estimated using this token */
+  gasTokenAddress?: string, // TODO: Update all functions that call getFlatFees() to pass in this value explicitly (where it is needed)
+  calls: CallInfo[] = [],
+): Promise<FeeInfo> => {
+  let token: ERC20Token | undefined;
+  const interaction = getInteractionFromAction(externalActionId);
+  if (interaction === INTERACTION.NONE) throw Error('No interaction was choosen');
+
+  let flatFeeTokenIndexEmporium;
+  switch (interaction) {
+    case INTERACTION.WITHDRAW:
+      token = getERC20Token(erc20Addresses[0], chainId);
+      break;
+    case INTERACTION.SWAP:
+      token = getERC20Token(erc20Addresses[1], chainId);
+      break;
+    case INTERACTION.STAKING: // INTENTIONAL: fall through pattern
+    case INTERACTION.UNSTAKING:
+      token = getERC20Token(erc20Addresses[1], chainId);
+      break;
+    case INTERACTION.CLAIMING:
+      token = getERC20Token(erc20Addresses[1], chainId);
+      break;
+    case INTERACTION.EMPORIUM:
+      flatFeeTokenIndexEmporium = amountChanges.findIndex((item) => item > 0n);
+      token = getERC20Token(erc20Addresses[flatFeeTokenIndexEmporium], chainId);
+      break;
+    default:
+      break;
+  }
+
+  let priceOfTransactionInToken: bigint | undefined;
+  let priceOfTransactionInUSD: number | undefined;
+
+  const numberOfInputs = amountChanges.length;
+
+  if (token) {
+    ({ priceOfTransactionInToken, priceOfTransactionInUSD } = await processGasEstimates(
+      chainId,
+      token,
+      externalActionId,
+      numberOfInputs,
+      undefined,
+      calls,
+    ));
+  }
+  const flatFees = new Array<bigint>(numberOfInputs).fill(0n);
+
+  switch (interaction) {
+    case INTERACTION.WITHDRAW:
+      flatFees[0] = priceOfTransactionInToken || 0n;
+      break;
+    case INTERACTION.SWAP:
+      flatFees[1] = priceOfTransactionInToken || 0n;
+      break;
+    case INTERACTION.STAKING: // INTENTIONAL: fall through pattern
+    case INTERACTION.UNSTAKING:
+      flatFees[1] = priceOfTransactionInToken || 0n; // for staking
+      flatFees[0] = priceOfTransactionInToken || 0n; // for unstaking
+      break;
+    case INTERACTION.CLAIMING:
+      flatFees[1] = priceOfTransactionInToken || 0n;
+      break;
+    case INTERACTION.EMPORIUM:
+      if (flatFeeTokenIndexEmporium !== undefined && flatFeeTokenIndexEmporium !== -1)
+        flatFees[flatFeeTokenIndexEmporium] = priceOfTransactionInToken || 0n;
+      break;
+    default:
+      break;
+  }
+  return { flatFees, priceOfTransactionInToken, feeUnit: token, priceOfTransactionInUSD };
+};

package/src/functions/pre-transaction/getSignatureDataForTransact.ts

@@ -0,0 +1,16 @@
+import { UserKeys } from '../../data-structures/crypto-keys';
+import { defaultSignatureData } from '../../constants/protocol.constants';
+import { API } from '../../API/API';
+import { SignatureData } from '../../types/crypto.types';
+
+export const getSignatureDataForTransact = async (
+  currentChainId: number,
+  ethereumAddress: string,
+  userKeys: UserKeys,
+  kycRequired: boolean,
+  hasAccessToken: boolean,
+): Promise<SignatureData> => {
+  if (!kycRequired || hasAccessToken) return defaultSignatureData;
+
+  return (await API.getAccessTokenSignature(currentChainId, ethereumAddress, userKeys.getAccessKey())).signatureData;
+};

package/src/functions/pre-transaction/getVolatileTransferAmount.ts

@@ -0,0 +1,56 @@
+import { Logger } from '../../error-handling';
+import { simulateVolatileTokenTransfer } from '../../API/is-tx-stateless';
+import { TokenChecker } from '../../data-structures/token-price-fetcher/TokenChecker';
+import { type ERC20Token, type VolatileTokenChange } from '../../types/token.types';
+
+/**
+ * Adjusts the token amount changes for volatile tokens based on actual transfer simulation results.
+ *
+ * This function identifies potentially volatile tokens with negative amount changes,
+ * simulates their transfers to estimate the real balance impact, and then updates
+ * the original `amountChanges` array accordingly with the simulated balance differences.
+ */
+export const modifyVolatileTokenAmountChanges = async (
+  chainId: number,
+  tokens: ERC20Token[],
+  amountChanges: bigint[],
+  targetAddress?: string,
+): Promise<bigint[]> => {
+  try {
+    const volatileTokenSpends: VolatileTokenChange[] = tokens
+      .map((token, index) => {
+        const plainAmount = amountChanges[index];
+        if (token && TokenChecker.isPotentiallyVolatile(token)) {
+          return {
+            tokenAddress: token.erc20TokenAddress,
+            amount: plainAmount.toString(),
+            ...(targetAddress !== undefined ? { targetAddress } : {}),
+            originalIndex: index,
+          };
+        }
+        return null;
+      })
+      .filter((t): t is VolatileTokenChange => t !== null);
+
+    if (volatileTokenSpends.length === 0) {
+      return amountChanges;
+    }
+
+    const results = await simulateVolatileTokenTransfer(chainId, volatileTokenSpends);
+
+    const newAmountChanges = amountChanges.map((amount, index) => {
+      const indexOfResult = volatileTokenSpends.findIndex((t) => t.originalIndex === index);
+      if (indexOfResult !== -1 && results[indexOfResult].success) {
+        const newAmount = results[indexOfResult].balanceDifference;
+
+        return newAmount ? BigInt(newAmount) : amount;
+      }
+      return amount;
+    });
+
+    return newAmountChanges;
+  } catch (error: any) {
+    Logger.error('Volatile transfer simulation failed:', error);
+    return amountChanges;
+  }
+};

package/src/functions/pre-transaction/index.ts

@@ -0,0 +1,7 @@
+export * from './interaction-to-action';
+export * from './outputUtxoProcessing';
+export * from './process-gas-estimates';
+export * from './getFlatFees';
+export * from './outputApprovalDataProcessing';
+export * from './getVolatileTransferAmount';
+export * from './constructAdminData';

package/src/functions/pre-transaction/interaction-to-action.ts

@@ -0,0 +1,17 @@
+import { ExternalActionId, INTERACTION } from '../../types';
+
+export const getInteractionFromAction = (externalActionId: ExternalActionId): INTERACTION => {
+  if (externalActionId === ExternalActionId.Transact) return INTERACTION.WITHDRAW;
+  // eslint-disable-next-line no-else-return
+  else if (
+    [ExternalActionId.Uniswap, ExternalActionId.Odos, ExternalActionId.OneInch].includes(
+      externalActionId as ExternalActionId,
+    )
+  )
+    return INTERACTION.SWAP;
+  else if (externalActionId === ExternalActionId.Emporium) {
+    return INTERACTION.EMPORIUM;
+  }
+
+  return INTERACTION.NONE;
+};

package/src/functions/pre-transaction/merge-with-fee-structure-emporium.ts

@@ -0,0 +1,50 @@
+import { FeeStructure } from '../../types/hinkal.types';
+import { type IHinkal } from '../../data-structures/Hinkal/IHinkal';
+import { getPublicAddressBalance } from '../web3/getPublicAddressBalance';
+import { mergeWithFeeStructure } from './merge-with-fee-structure';
+import { createTransferToEmporiumOp } from '../private-wallet/emporium.helpers';
+import { zeroAddress } from '../../constants/protocol.constants';
+import { ContractType } from '../../types/ethereum-network.types';
+import { maxBigInt } from '../utils/amounts.utils';
+
+export const mergeWithFeeStructureEmporium = async (
+  hinkal: IHinkal,
+  walletAddress: string,
+  emporiumOps: string[],
+  erc20Addresses: string[],
+  amountChanges: bigint[],
+  feeStructure: FeeStructure,
+  feeTokenChange: bigint,
+) => {
+  let feeAmountToTransfer = 0n;
+  const nonPositiveFeeTokenChange = feeTokenChange < 0n ? feeTokenChange : 0n;
+
+  const netAmount =
+    (await getPublicAddressBalance(hinkal, feeStructure.feeToken, walletAddress)) + nonPositiveFeeTokenChange;
+
+  // Case 1: If we need to fund proxy, then we also need to send whole flat fee
+  if (netAmount < 0) {
+    feeAmountToTransfer = feeStructure.flatFee;
+  } else {
+    // Case 2: If we do not need to fund proxy, we use existing amount to fund flat fee
+    feeAmountToTransfer = maxBigInt(feeStructure.flatFee - netAmount, 0n);
+  }
+
+  if (feeAmountToTransfer === 0n) return;
+
+  mergeWithFeeStructure(hinkal.getCurrentChainId(), erc20Addresses, amountChanges, {
+    ...feeStructure,
+    flatFee: feeAmountToTransfer,
+  });
+
+  emporiumOps.push(
+    createTransferToEmporiumOp(
+      feeStructure.feeToken === zeroAddress
+        ? undefined
+        : hinkal.getContractWithFetcher(ContractType.ERC20Contract, feeStructure.feeToken),
+      walletAddress,
+      feeAmountToTransfer,
+      false,
+    ),
+  );
+};

package/src/functions/pre-transaction/merge-with-fee-structure.ts

@@ -0,0 +1,35 @@
+import { Logger } from '../../error-handling/logger';
+import { FeeStructure } from '../../types/hinkal.types';
+import { caseInsensitiveEqual } from '../utils/caseInsensitive.utils';
+import { FeeOverTransactionValueError } from '../../error-handling/customErrors/FeeOverTransactionValueError';
+import { getERC20Token } from '../utils/erc20tokenFunctions';
+
+export const mergeWithFeeStructure = (
+  chainId: number,
+  erc20Addresses: string[],
+  amountChanges: bigint[],
+  feeStructure: FeeStructure,
+) => {
+  Logger.log('amount changes before merge', { amountChanges });
+
+  const feeTokenIndex = erc20Addresses.findIndex((tokenAddress) =>
+    caseInsensitiveEqual(tokenAddress, feeStructure.feeToken),
+  );
+
+  if (feeTokenIndex === -1) {
+    erc20Addresses.push(feeStructure.feeToken);
+    amountChanges.push(-1n * feeStructure.flatFee);
+    Logger.log('amount changes after merge', { amountChanges });
+    return;
+  }
+
+  if (amountChanges[feeTokenIndex] > 0 && amountChanges[feeTokenIndex] < feeStructure.flatFee) {
+    throw new FeeOverTransactionValueError({
+      totalFeeWEI: feeStructure.flatFee,
+      feeUnit: getERC20Token(feeStructure.feeToken, chainId),
+    });
+  }
+
+  amountChanges[feeTokenIndex] -= feeStructure.flatFee;
+  Logger.log('amount changes after merge', { amountChanges });
+};

package/src/functions/pre-transaction/outputApprovalDataProcessing.ts

@@ -0,0 +1,95 @@
+import { Utxo } from '../../data-structures/utxo/Utxo';
+import { IHinkal } from '../../data-structures/Hinkal/IHinkal';
+import { transactionErrorCodes } from '../../error-handling/error-codes.constants';
+import { APPROVED_UTXO_CONVERSION_COUNT } from '../../constants/conversion.constants';
+import { defaultUseApprovalUTXOData } from '../../types/hinkal.types';
+import { isUseApprovalDataEmpty } from '../utils/processUseApprovalUtxoData';
+import { countTotalAmountInUtxos } from '../utils/amounts.utils';
+import { caseInsensitiveEqual } from '../utils/caseInsensitive.utils';
+
+export const outputApprovalDataProcessing = (
+  hinkal: IHinkal,
+  inputUtxos: Utxo[],
+  amountChange: bigint,
+  interactionToIgnore?: string, // in case of inside transact, we do not want take approvals we already approved for this interaction
+  tokenId?: number,
+) => {
+  if (tokenId && tokenId > 0) throw new Error(transactionErrorCodes.INSUFFICIENT_FUNDS);
+  const totalAmount = countTotalAmountInUtxos(inputUtxos);
+  const { erc20TokenAddress } = inputUtxos[0];
+  const relevantApprovedUtxos = hinkal
+    .getApprovedUtxosForToken(erc20TokenAddress)
+    .filter((utxo) => !caseInsensitiveEqual(utxo.interactionAddress, interactionToIgnore));
+
+  const useApprovalUtxoData = defaultUseApprovalUTXOData(APPROVED_UTXO_CONVERSION_COUNT, 0n);
+
+  if (amountChange < 0n && totalAmount + amountChange < 0n) {
+    let neededAmount = -(totalAmount + amountChange);
+
+    for (let i = 0; i < Math.min(relevantApprovedUtxos.length, APPROVED_UTXO_CONVERSION_COUNT); i += 1) {
+      if (neededAmount === 0n) break;
+      const currentUtxo = relevantApprovedUtxos[i];
+
+      const newApprovalChange = currentUtxo.amount >= neededAmount ? -neededAmount : -currentUtxo.amount;
+
+      neededAmount += newApprovalChange;
+
+      useApprovalUtxoData.approvalChanges[i] = newApprovalChange;
+      useApprovalUtxoData.externalApprovalAddresses[i] = currentUtxo.interactionAddress;
+      useApprovalUtxoData.conversionInHinkalAddress[i] = currentUtxo.inHinkalAddress;
+    }
+    if (neededAmount !== 0n) throw new Error(transactionErrorCodes.INSUFFICIENT_FUNDS);
+  }
+  return { useApprovalUtxoData: isUseApprovalDataEmpty(useApprovalUtxoData) ? undefined : useApprovalUtxoData };
+};
+
+export const outputApprovalDataProcessingForHinkalApprove = (
+  hinkal: IHinkal,
+  inputUtxos: Utxo[],
+  approvedTo: string,
+  approvalAmount: bigint,
+  deltaAmount: bigint, // amount change has additional fee information
+  tokenId?: number,
+) => {
+  if (tokenId && tokenId > 0) throw new Error(transactionErrorCodes.INSUFFICIENT_FUNDS);
+  const totalAmount = countTotalAmountInUtxos(inputUtxos);
+  const { erc20TokenAddress } = inputUtxos[0];
+
+  const useApprovalUtxoData = defaultUseApprovalUTXOData(APPROVED_UTXO_CONVERSION_COUNT, 0n);
+  const inHinkalAddress = hinkal.userKeys.getInHinkalAddress(approvedTo);
+  const relevantApprovedUtxos = hinkal.getApprovedUtxosForToken(erc20TokenAddress).sort((a, b) => {
+    if (a.inHinkalAddress === inHinkalAddress) return -1;
+    if (b.inHinkalAddress === inHinkalAddress) return 1;
+    if (a.amount === b.amount) return 0;
+    return a.amount < b.amount ? -1 : 1;
+  });
+
+  const hasApprovedToHinkalAddress = relevantApprovedUtxos[0]?.inHinkalAddress === inHinkalAddress;
+  const alreadyApprovedAmount = hasApprovedToHinkalAddress ? relevantApprovedUtxos[0].amount : 0n;
+  const approvalDif = approvalAmount - alreadyApprovedAmount; // we now this is positive
+
+  useApprovalUtxoData.approvalChanges[0] = approvalDif;
+  useApprovalUtxoData.externalApprovalAddresses[0] = approvedTo;
+  useApprovalUtxoData.conversionInHinkalAddress[0] = hinkal.userKeys.getInHinkalAddress(approvedTo);
+
+  // If user has approval on current HinkalAddress, we skip the 0 index because it's already processed.
+  const startingIndex = hasApprovedToHinkalAddress ? 1 : 0;
+
+  /* We always append to useApprovalUtxoData starting from index 1, when startingIndex is 0, offset
+     is 1, when startingIndex is 1, offset is 0 */
+  const indexOffset = startingIndex === 0 ? 1 : 0;
+
+  let deltaAmountOverride = deltaAmount;
+  for (let i = startingIndex; i < Math.min(APPROVED_UTXO_CONVERSION_COUNT, relevantApprovedUtxos.length); i += 1) {
+    if (i + indexOffset >= APPROVED_UTXO_CONVERSION_COUNT) break;
+    const currentUtxo = relevantApprovedUtxos[i];
+    deltaAmountOverride += currentUtxo.amount;
+    useApprovalUtxoData.approvalChanges[i + indexOffset] = -currentUtxo.amount;
+    useApprovalUtxoData.externalApprovalAddresses[i + indexOffset] = currentUtxo.interactionAddress;
+    useApprovalUtxoData.conversionInHinkalAddress[i + indexOffset] = currentUtxo.inHinkalAddress;
+  }
+
+  if (totalAmount + deltaAmountOverride < 0n) throw new Error(transactionErrorCodes.INSUFFICIENT_FUNDS);
+
+  return { useApprovalUtxoData, deltaAmountOverride };
+};

package/src/functions/pre-transaction/outputUtxoProcessing.ts

@@ -0,0 +1,52 @@
+import { UserKeys } from '../../data-structures/crypto-keys/keys';
+import { Utxo } from '../../data-structures/utxo/Utxo';
+import { bigintMax, countTotalAmountInUtxos } from '../utils/amounts.utils';
+import { transactionErrorCodes } from '../../error-handling/error-codes.constants';
+
+export const outputUtxoProcessing = (
+  userKeys: UserKeys,
+  inputUtxos: Utxo[],
+  amountChange: bigint,
+  timeStamp?: string,
+  tokenId?: number,
+  revertIfNegative = true,
+  recipientAddress?: string,
+  recipientAmountChange?: bigint,
+) => {
+  // 1) let outputAmount =  depositAmount + allInputUtxos.amount
+  const totalAmount = countTotalAmountInUtxos(inputUtxos);
+  const { erc20TokenAddress } = inputUtxos[0];
+
+  if (revertIfNegative && amountChange < 0n && totalAmount + amountChange < 0n) {
+    throw Error(transactionErrorCodes.INSUFFICIENT_FUNDS_TO_TRANSACT);
+  }
+
+  // 2) outputUtxos array for withdrawal: filling up to 1 outputUtxos -> if less
+  const outputUtxos = [
+    new Utxo({
+      amount: bigintMax(totalAmount + amountChange, 0n),
+      erc20TokenAddress,
+      shieldedPrivateKey: userKeys.getShieldedPrivateKey(),
+      timeStamp,
+      tokenId,
+    }),
+  ];
+
+  // 3) in case of transfer, we need to add the recipient utxo
+  if (recipientAddress !== undefined && recipientAmountChange !== undefined) {
+    const [randomization, stealthAddress, encryptionKey] = recipientAddress.split(',');
+
+    outputUtxos.push(
+      new Utxo({
+        amount: recipientAmountChange,
+        erc20TokenAddress,
+        randomization: BigInt(randomization),
+        stealthAddress,
+        encryptionKey,
+        timeStamp,
+      }),
+    );
+  }
+
+  return { outputUtxos };
+};