@sabaaa1/common 0.0.4 → 0.0.7

package/src/functions/utils/create-provider.ts

@@ -0,0 +1,11 @@
+import { TorExternalProvider } from '../../providers/TorExternalProvider';
+import { ethers } from 'ethers';
+
+export const createProvider = (rpcUrl: string) => {
+  return new ethers.providers.JsonRpcProvider(rpcUrl);
+};
+
+export const createTorRpcProvider = (rpcUrl: string) => {
+  const torProvider = new TorExternalProvider(rpcUrl);
+  return new ethers.providers.Web3Provider(torProvider);
+};

package/src/functions/utils/encodeTokenWithId.ts

@@ -0,0 +1,4 @@
+import { TokenWithId } from '../../types/token-with-id.types';
+
+export const encodeTokenWithId = (tokenWithId: TokenWithId) =>
+  `${tokenWithId.erc20TokenAddress.toLowerCase()}-${tokenWithId.tokenId}`;

package/src/functions/utils/encryptInputForEnclave.ts

@@ -0,0 +1,119 @@
+import * as forge from 'node-forge';
+import { type HandshakeResponseType } from '../../types/remote-proof.types';
+import { ENCLAVE_EC2_URL } from '../snarkjs/constant';
+import { ethers } from 'ethers';
+import sodium from 'libsodium-wrappers';
+import { httpClient } from '../../data-structures/tor';
+
+const RSA_2048_THRESHOLD = 214;
+
+const makeHandshakeForPublicKey = async () => {
+  // obtain public key used for assymetric encryption from enclave
+  const handshakeResponse = await httpClient.get<HandshakeResponseType>(`${ENCLAVE_EC2_URL}/handshake`);
+  const kmsPk = handshakeResponse.public_key;
+
+  // parse and create publickey object with forge
+  const pkBytes = forge.util.decode64(kmsPk);
+  const asn1 = forge.asn1.fromDer(pkBytes);
+  return forge.pki.publicKeyFromAsn1(asn1);
+};
+
+const numberishToString = (value: unknown) => {
+  if (typeof value === 'bigint' || typeof value === 'number') {
+    return value.toString();
+  }
+  return value;
+};
+
+const convertHexStringToBytes = (aHexString: string) => {
+  // Forge doesn't know how to handle '0x' and returns invalid value unless we remove it
+  return forge.util.hexToBytes(aHexString.replace('0x', ''));
+};
+
+const serializeInput = (input: Record<string, unknown>) => {
+  const inputCopy = structuredClone(input);
+
+  Object.entries(inputCopy).forEach(([key, value]) => {
+    inputCopy[key] = numberishToString(value);
+
+    if (Array.isArray(value)) {
+      if (Array.isArray(value[0])) {
+        inputCopy[key] = value.map((outer: unknown[]) => outer.map(numberishToString));
+      } else {
+        inputCopy[key] = value.map(numberishToString);
+      }
+    }
+  });
+
+  return inputCopy;
+};
+
+const assymetricEncrypt = (publicKey: forge.pki.rsa.PublicKey, content: Uint8Array) => {
+  const contentHex = ethers.utils.hexlify(content).slice(2); // forge tries to convert '0x' and silently adds random byte
+  const bytes = convertHexStringToBytes(contentHex);
+  if (bytes.length > RSA_2048_THRESHOLD) throw new Error('too many bytes passed to assymetric_encrypt');
+
+  const encrypted = publicKey.encrypt(bytes, 'RSA-OAEP', {
+    md: forge.md.sha1.create(),
+    mgf1: { md: forge.md.sha1.create() },
+    label: null,
+  });
+
+  return forge.util.encode64(encrypted);
+};
+
+const symmetricEncrypt = (key: Uint8Array, message: Uint8Array) => {
+  const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+  const ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);
+
+  // bundle nonce with ciphertext, PyNaCL recongizes this formart when calling decrypt automatically
+  const nonceAndCiphertextCombinedHex = ethers.utils.hexlify(nonce) + ethers.utils.hexlify(ciphertext).slice(2);
+  const nonceAndCiphertextCombinedBytes = convertHexStringToBytes(nonceAndCiphertextCombinedHex);
+
+  return forge.util.encode64(nonceAndCiphertextCombinedBytes);
+};
+
+// to send data to enclave securely, we need to encrypt the data
+// we use combination of assymetric and symmetric encryption to achive this.
+//
+// because the enclave uses AWS key management service (KMS) underneath to securly decrypt data
+// we are limited in the assymetric encryption algorithms we can use
+// enclave currently uses RSAES_OAEP_SHA_1 for assymetric encryption algorithm, this algorithm is supported by KMS
+//
+// there is 1 big issue with this algorithm, it can't decrypt more than 214 bytes at a time
+// we can encrypt entire input assymetrically and decrypt it into chunks, but this would be a very slow process
+//
+// to work around this limitation and to make encryption and decryption faster
+// instead of assymetrically encrypting the entire input
+// we generate a random `key` value, which is then used to symetrically encrypt the input with libsodium
+// we then assymetrically encrypt `key` using the enclave's public key
+//
+// after receiving encrypted `input` and `key` values
+// the enclave decrypts `key` using AWS KMS and uses it to decrypt `input` with PyNaCL (sodium for python)
+//
+// encrypted `input` and `key` values are sent to enclave in base64 format
+const encryptUint8ArrayForEnclave = (inputUint8Array: Uint8Array, publicKey: forge.pki.rsa.PublicKey) => {
+  const key = sodium.randombytes_buf(sodium.crypto_secretbox_KEYBYTES);
+
+  const keyCiphertext = assymetricEncrypt(publicKey, key);
+  const inputCiphertext = symmetricEncrypt(key, inputUint8Array);
+
+  return { keyCiphertext, inputCiphertext };
+};
+
+const encryptInputForEnclave = (input: any, publicKey: forge.pki.rsa.PublicKey) => {
+  const serializedInput = serializeInput(input);
+  const inputStr = JSON.stringify(serializedInput);
+  const inputUint8Array = new TextEncoder().encode(inputStr);
+  return encryptUint8ArrayForEnclave(inputUint8Array, publicKey);
+};
+
+export const makeEnclaveHandshakeAndEncryptInput = async (input: any) => {
+  const pk = await makeHandshakeForPublicKey();
+  return encryptInputForEnclave(input, pk);
+};
+
+export const makeEnclaveHandshakeAndEncryptUint8Array = async (inputUint8Array: Uint8Array) => {
+  const pk = await makeHandshakeForPublicKey();
+  return encryptUint8ArrayForEnclave(inputUint8Array, pk);
+};

package/src/functions/utils/enum.utils.ts

@@ -0,0 +1,30 @@
+/** Verifies that the value is in the enumType specified */
+export function isInEnum<T>(enumType: T, value: any): value is T[keyof T] {
+  return Object.values(enumType as unknown[]).includes(value as T[keyof T]);
+}
+
+/** Converts a string value to an Enum member
+ *  If a value can't be matched to a valid option in the enum, returns undefined (or throws if throwIfInvalid = true) */
+export function toEnumValue<T>(e: T, value: any, throwIfInvalid = false): T[keyof T] | undefined {
+  if (isInEnum<T>(e, value)) {
+    return value;
+  }
+  const errMsg = `Value ${JSON.stringify(value)} is not a valid member of enum ${JSON.stringify(e)}.`;
+  if (throwIfInvalid) {
+    throw new Error(errMsg);
+  }
+  // globalLogger.error(errMsg)
+  return undefined;
+}
+
+/** returns first item in an enum that is included somewhere in the target string
+ * e.g. enumInString(ErrorCode, '001-badpassword: error') => ErrorCode.BadPassword
+ */
+export function enumInString<T extends Record<string, string>>(enumType: T, searchString: any): T[keyof T] | undefined {
+  if (!searchString) return undefined;
+  // eslint-disable-next-line no-restricted-syntax
+  for (const [, value] of Object.entries(enumType)) {
+    if (searchString?.includes(value)) return toEnumValue(enumType, value);
+  }
+  return undefined;
+}

package/src/functions/utils/erc20tokenFunctions.ts

@@ -0,0 +1,110 @@
+import { getERC20Registry } from '../../constants/token-data';
+import { customTokenRegistry } from '../../data-structures/custom-token-registry/CustomTokenRegistry';
+import { ERC20Token, TokenChanges } from '../../types/token.types';
+import { getAmountInToken } from '../web3/etherFunctions';
+import { fixDecimalsAmount } from './amounts.utils';
+import { TokenType, zeroAddress } from '../../constants/protocol.constants';
+import { PopularTokenSymbols } from '../../constants/token-data/popularTokens.constants';
+import { chainIds } from '../../constants/chains.constants';
+
+export const getErc20TokensForChain = (chainId: number) => {
+  const permittedRegistry = getERC20Registry(chainId);
+  const customTokens = customTokenRegistry.getCustomTokens(chainId);
+
+  return [...permittedRegistry, ...customTokens];
+};
+
+export const getERC20Token = (address: string, chainId: number, fromList?: ERC20Token[]) => {
+  return (fromList ?? getErc20TokensForChain(chainId))?.find((el) => {
+    if (address === undefined) {
+      return false;
+    }
+    return el.erc20TokenAddress.toLowerCase() === address.toLowerCase();
+  });
+};
+
+export const getERC20TokenBySymbol = (symbol: string, chainId: number) => {
+  return getErc20TokensForChain(chainId)?.find((el) => {
+    if (symbol === undefined) {
+      return false;
+    }
+    return el.symbol.toLowerCase() === symbol.toLowerCase();
+  });
+};
+
+export const getHToken = (token: ERC20Token, chainId: number) => {
+  const tokenRegistry = getERC20Registry(chainId);
+  if (!token.hasHToken) return undefined;
+  return tokenRegistry.find(
+    (candidate) =>
+      candidate.underlyingErc20TokenAddress?.toLowerCase() === token.erc20TokenAddress.toLowerCase() &&
+      candidate.isHToken,
+  );
+};
+
+export const aggregateTokenChanges = (tokenChanges: TokenChanges<bigint>[]): TokenChanges<bigint>[] => {
+  const aggregated = tokenChanges.reduce(
+    (acc, { amount, token, nftIds }) => {
+      const key = token.erc20TokenAddress.toLowerCase();
+
+      if (acc[key]) {
+        acc[key].amount += amount;
+      } else {
+        acc[key] = {
+          amount,
+          token,
+          nftIds,
+        };
+      }
+
+      return acc;
+    },
+    {} as Record<string, TokenChanges<bigint>>,
+  );
+
+  return Object.values(aggregated);
+};
+
+export const formatTokenChangesList = (tokenChanges: TokenChanges<bigint>[]) => {
+  return tokenChanges
+    .map(({ amount, token, nftIds }) => {
+      if (amount === 0n) return undefined; // in some cases, token amount can be zero, for example on equlibrium's USR pool on base. the transaction sends us a token which is immediatelly spent
+      const sign = amount > 0n ? '+' : '-';
+      const amountInToken = Number(getAmountInToken(token, amount));
+      return {
+        token,
+        amount: `${sign}${fixDecimalsAmount(amountInToken > 0 ? amountInToken : -amountInToken)}`,
+        nftIds,
+      };
+    })
+    .filter((item): item is Exclude<typeof item, undefined> => !!item);
+};
+
+export const isNFTToken = (token: ERC20Token) => {
+  return token.nftTokenType === TokenType.ERC721 || token.nftTokenType === TokenType.ERC1155;
+};
+
+export const isArcNativeToken = (token: ERC20Token) => {
+  return token.chainId === chainIds.arcTestnet && token.erc20TokenAddress === zeroAddress;
+};
+
+export const searchCompareFunction = (token: ERC20Token, searchString: string) => {
+  const normalizedSearch = searchString.toLowerCase();
+  return (
+    token.symbol.toLowerCase().includes(normalizedSearch) ||
+    token.name.toLowerCase().includes(normalizedSearch) ||
+    token.erc20TokenAddress.toLowerCase().startsWith(normalizedSearch)
+  );
+};
+
+export const sortTokens = (tokens: ERC20Token[]) => {
+  const popularTokens = tokens.filter((token) =>
+    PopularTokenSymbols.some((tokenSymbol) => tokenSymbol.symbol === token.symbol),
+  );
+  const nonPopularTokens = tokens.filter(
+    (token) => !PopularTokenSymbols.some((tokenSymbol) => tokenSymbol.symbol === token.symbol),
+  );
+  const sortedPopularTokens = popularTokens.sort((a, b) => a.symbol.localeCompare(b.symbol, 'en-US'));
+  const sortedNonPopularTokens = nonPopularTokens.sort((a, b) => a.symbol.localeCompare(b.symbol, 'en-US'));
+  return [...sortedPopularTokens, ...sortedNonPopularTokens];
+};

package/src/functions/utils/ethers-formatter.utils.ts

@@ -0,0 +1,32 @@
+import { ethers as ethersV6 } from 'ethers-v6h';
+import { RelayerTransaction } from '../../types/relayer.types';
+
+export const convertV6ReceiptToRelayer = (v6Receipt: ethersV6.TransactionReceipt): RelayerTransaction => {
+  const relayerTransaction: RelayerTransaction = {
+    to: v6Receipt.to || '',
+    from: v6Receipt.from,
+    contractAddress: v6Receipt.contractAddress,
+    gasUsed: {
+      type: 'BigNumber',
+      hex: v6Receipt.gasUsed.toString(),
+    },
+    logsBloom: v6Receipt.logsBloom,
+    blockHash: v6Receipt.blockHash,
+    transactionHash: v6Receipt.hash,
+    blockNumber: v6Receipt.blockNumber,
+    confirmations: 1, // Set to 1 as default
+    cumulativeGasUsed: {
+      type: 'BigNumber',
+      hex: v6Receipt.cumulativeGasUsed.toString(),
+    },
+    effectiveGasPrice: {
+      type: 'BigNumber',
+      hex: v6Receipt.gasPrice ? v6Receipt.gasPrice.toString() : '0x0',
+    },
+    status: v6Receipt.status !== null ? Number(v6Receipt.status) : 0,
+    type: v6Receipt.type !== null ? Number(v6Receipt.type) : 0,
+    byzantium: true,
+  };
+
+  return relayerTransaction;
+};

package/src/functions/utils/evmNetworkFunctions.ts

@@ -0,0 +1,9 @@
+import { chainIdsByType, EthereumNetworkType, networkRegistry } from '../../constants';
+import { EthereumNetwork } from '../../types';
+
+export const getNetworkObject = (chainId: number): EthereumNetwork => networkRegistry[chainId];
+
+export const getNetworkType = (network: EthereumNetwork): EthereumNetworkType =>
+  Object.keys(chainIdsByType)[
+    Object.values(chainIdsByType).findIndex((chainIdArr) => chainIdArr.includes(network.chainId))
+  ] as EthereumNetworkType;

package/src/functions/utils/external-action.utils.ts

@@ -0,0 +1,15 @@
+import { ethers } from 'ethers';
+import { CIRCOM_P } from '../../constants/protocol.constants';
+import { ExternalActionId } from '../../types/external-action.types';
+
+export const getExternalActionIdHash = (externalActionId: ExternalActionId | 0n) => {
+  if (externalActionId === 0n) return 0n;
+  return BigInt(ethers.utils.id(externalActionId)) % CIRCOM_P;
+};
+
+export const getExternalActionIdFromNumber = (externalActionIdNumber: string | bigint) => {
+  if (BigInt(externalActionIdNumber) === 0n) return ExternalActionId.Transact;
+  return Object.values(ExternalActionId).find(
+    (externalActionId) => BigInt(externalActionIdNumber) === getExternalActionIdHash(externalActionId),
+  );
+};

package/src/functions/utils/fees.utils.ts

@@ -0,0 +1,26 @@
+import { NON_NATIVE_GAS_COST_TOKEN_SYMBOL_OPTIONS } from '../../constants/fees.constants';
+import { zeroAddress } from '../../constants/protocol.constants';
+import { defaultFeeStructure, FeeStructure } from '../../types/hinkal.types';
+import { getERC20Token } from './erc20tokenFunctions';
+
+export const generateFeeStructure = (flatFees: bigint[], erc20TokenAddresses: string[]): FeeStructure<bigint> => {
+  if (flatFees.length !== erc20TokenAddresses.length) throw new Error('length mismatch');
+
+  const flatFeeIndex = flatFees.findIndex((flatFee) => flatFee !== 0n);
+  if (flatFeeIndex === -1) return defaultFeeStructure;
+
+  return {
+    feeToken: erc20TokenAddresses[flatFeeIndex],
+    flatFee: flatFees[flatFeeIndex],
+    variableRate: 0n,
+  };
+};
+
+export const getGasTokenSymbols = (chainId: number | undefined): string[] => {
+  if (!chainId) return NON_NATIVE_GAS_COST_TOKEN_SYMBOL_OPTIONS;
+
+  const nativeTokenSymbol = getERC20Token(zeroAddress, chainId)?.symbol;
+  return nativeTokenSymbol && !NON_NATIVE_GAS_COST_TOKEN_SYMBOL_OPTIONS.includes(nativeTokenSymbol)
+    ? [nativeTokenSymbol, ...NON_NATIVE_GAS_COST_TOKEN_SYMBOL_OPTIONS]
+    : NON_NATIVE_GAS_COST_TOKEN_SYMBOL_OPTIONS;
+};

package/src/functions/utils/get-hinkal-approvals.ts

@@ -0,0 +1,36 @@
+import { API } from '../../API';
+import { IHinkal } from '../../data-structures/Hinkal/IHinkal';
+import { ApprovedUtxoWithInteractionAddress, ERC20Token, TokenApproval } from '../../types';
+
+export const getHinkalApprovals = async (hinkal: IHinkal): Promise<TokenApproval[]> => {
+  const chainId = hinkal.getCurrentChainId();
+
+  const approvedUtxos: ApprovedUtxoWithInteractionAddress[] = hinkal.getApprovedUtxos();
+
+  if (approvedUtxos.length === 0) {
+    return [];
+  }
+
+  const uniqueTokenAddresses = [...new Set(approvedUtxos.map((utxo) => utxo.tokenAddress.toLowerCase()))];
+
+  const tokens = (await API.tokensInfoCall(chainId, uniqueTokenAddresses)).filter(
+    (token): token is ERC20Token => !!token,
+  );
+
+  const tokenMap = new Map(tokens.map((token) => [token.erc20TokenAddress.toLowerCase(), token]));
+
+  const hinkalApprovals: TokenApproval[] = approvedUtxos
+    .map((utxo): TokenApproval | null => {
+      const token = tokenMap.get(utxo.tokenAddress.toLowerCase());
+      if (!token) return null;
+
+      return {
+        token,
+        spenderAddress: utxo.interactionAddress,
+        allowance: utxo.amount,
+      };
+    })
+    .filter((approval): approval is TokenApproval => approval !== null && approval.allowance > 0n);
+
+  return hinkalApprovals;
+};

package/src/functions/utils/get-signature-header.ts

@@ -0,0 +1,5 @@
+export const getSignatureHeader = (signature?: string) => ({
+  headers: {
+    'x-user-signature': signature,
+  },
+});

package/src/functions/utils/getBlockExplorerUrl.ts

@@ -0,0 +1,14 @@
+import { chainIds } from '../../constants/chains.constants';
+import { mediaUrls } from '../../constants/mediaUrls.constants';
+
+export const getBlockExplorerUrl = (nonLocalChainId: number) => {
+  if (nonLocalChainId === chainIds.polygon) return mediaUrls.POLY_SCAN;
+  if (nonLocalChainId === chainIds.arbMainnet) return mediaUrls.ARB_SCAN;
+  if (nonLocalChainId === chainIds.ethMainnet) return mediaUrls.ETH_SCAN;
+  if (nonLocalChainId === chainIds.avalanche) return mediaUrls.AVAX_SCAN;
+  if (nonLocalChainId === chainIds.bnbMainnet) return mediaUrls.BSC_SCAN;
+  if (nonLocalChainId === chainIds.base) return mediaUrls.BASE_SCAN;
+  if (nonLocalChainId === chainIds.optimism) return mediaUrls.OPTIMISM_SCAN;
+  if (nonLocalChainId === chainIds.arcTestnet) return mediaUrls.ARC_TESTNET_EXPLORER;
+  return mediaUrls.ETH_SCAN;
+};

package/src/functions/utils/getDataFromTransaction.ts

@@ -0,0 +1,79 @@
+import { BigNumber, utils } from 'ethers';
+import { DecodedTx, DecodedTxWithUtxos } from '../../types';
+
+export const decodeTxInput = (iface: utils.Interface, input: string) => {
+  const parsedData = iface.parseTransaction({ data: input });
+  const { circomData } = parsedData.args;
+  const {
+    extraRandomization,
+    stealthAddress,
+    H0,
+    H1,
+  }: {
+    extraRandomization: BigNumber;
+    stealthAddress: BigNumber;
+    H0: BigNumber;
+    H1: BigNumber;
+  } = circomData.stealthAddressStructure;
+
+  const txData: DecodedTx['decodedInput'] = {
+    erc20TokenAddresses: circomData.erc20TokenAddresses as string[],
+    amountChanges: circomData.amountChanges as BigNumber[],
+    flatFees: circomData.flatFees as BigNumber[],
+    externalActionId: circomData.externalActionId as BigNumber,
+    externalActionMetadata: circomData.externalActionMetadata as string,
+    encryptedOutputs: circomData.encryptedOutputs.map((e: string[][]) => e[0]),
+    hookData: circomData.hookData,
+    stealthAddressStructure: {
+      extraRandomization: extraRandomization.toBigInt(),
+      stealthAddress: stealthAddress.toBigInt(),
+      H0: H0.toBigInt(),
+      H1: H1.toBigInt(),
+    },
+  };
+  return txData;
+};
+
+export const deserializeDecodedTxs = (decodedTx: DecodedTxWithUtxos<string, string>): DecodedTxWithUtxos => {
+  return {
+    ...decodedTx,
+    utxosArray: decodedTx.utxosArray?.map((item) => ({ ...item, amount: BigInt(item.amount) })),
+    decodedInput: {
+      ...decodedTx.decodedInput,
+      amountChanges: decodedTx.decodedInput.amountChanges.map(BigNumber.from),
+      flatFees: decodedTx.decodedInput.flatFees.map(BigNumber.from),
+      externalActionId: BigNumber.from(decodedTx.decodedInput.externalActionId),
+      stealthAddressStructure: {
+        ...decodedTx.decodedInput.stealthAddressStructure,
+        extraRandomization: BigInt(decodedTx.decodedInput.stealthAddressStructure.extraRandomization),
+        stealthAddress: BigInt(decodedTx.decodedInput.stealthAddressStructure.stealthAddress),
+        H0: BigInt(decodedTx.decodedInput.stealthAddressStructure.H0),
+        H1: BigInt(decodedTx.decodedInput.stealthAddressStructure.H1),
+      },
+    },
+  };
+};
+
+export const serializeDecodedTxs = (decodedTxs: DecodedTx[]) => {
+  const serializedTxs = decodedTxs.map((tx) => {
+    const { decodedInput } = tx;
+    return {
+      ...tx,
+      input: '',
+      decodedInput: {
+        ...decodedInput,
+        amountChanges: decodedInput.amountChanges.map((amount) => amount.toString()),
+        flatFees: decodedInput.flatFees.map((fee) => fee.toString()),
+        externalActionId: decodedInput.externalActionId.toString(),
+        stealthAddressStructure: {
+          ...decodedInput.stealthAddressStructure,
+          extraRandomization: String(decodedInput.stealthAddressStructure.extraRandomization),
+          stealthAddress: String(decodedInput.stealthAddressStructure.stealthAddress),
+          H0: String(decodedInput.stealthAddressStructure.H0),
+          H1: String(decodedInput.stealthAddressStructure.H1),
+        },
+      },
+    };
+  });
+  return serializedTxs;
+};

package/src/functions/utils/getRecipientInfoFromUserKeys.ts

@@ -0,0 +1,28 @@
+import { zeroAddress } from '../../constants/protocol.constants';
+import { UserKeys } from '../../data-structures/crypto-keys';
+import { Utxo } from '../../data-structures/utxo/Utxo';
+
+export const getRecipientInfoFromUserKeys = (userKeys: UserKeys) => {
+  const shieldedPrivateKey = userKeys.getShieldedPrivateKey();
+  const encryptionKey = UserKeys.getEncryptionKeyPair(shieldedPrivateKey).publicKey;
+
+  const utxo = new Utxo({ amount: 0n, erc20TokenAddress: zeroAddress, shieldedPrivateKey });
+  const { randomization } = utxo;
+  const stealthAddress = utxo.getStealthAddress();
+
+  if (!randomization || !stealthAddress || !encryptionKey) throw Error('Cannot get recipient information');
+
+  return `${randomization},${stealthAddress},${encryptionKey}`;
+};
+
+export const getExtendedRecipientInfoFromUserKeys = (userKeys: UserKeys) => {
+  const shieldedPrivateKey = userKeys.getShieldedPrivateKey();
+
+  const utxo = new Utxo({ amount: 0n, erc20TokenAddress: zeroAddress, shieldedPrivateKey });
+
+  const { randomization } = utxo;
+  const stealthAddress = utxo.getStealthAddress();
+  const { h0, h1 } = UserKeys.getStealthAddressCompressedPoints(randomization, shieldedPrivateKey);
+
+  return `${randomization},${stealthAddress},${h0},${h1}`;
+};

package/src/functions/utils/inLogicMetadata.ts

@@ -0,0 +1,9 @@
+import { ethers } from 'ethers';
+import { ParsedInLogicMetadata } from '../../types/hinkal.types';
+
+export const encodeParsedInLogicMetadata = (metadata: ParsedInLogicMetadata): string => {
+  return ethers.utils.defaultAbiCoder.encode(
+    ['bytes', 'uint256', 'address[]', 'bytes'],
+    [metadata.signature, metadata.deadline, metadata.erc20TokenAddresses, metadata.externalCallData],
+  );
+};

package/src/functions/utils/involves-permit2-op.ts

@@ -0,0 +1,17 @@
+import { permit2Addresses, uniswapWorkaroundAddresses } from '../../constants/permit2.constants';
+import { caseInsensitiveEqual } from './caseInsensitive.utils';
+
+export const isPermit2Tx = (to: string) =>
+  permit2Addresses.some((permitAddress) => caseInsensitiveEqual(to, permitAddress));
+
+/**
+ * Uniswap appends extra data at the end of the calldada,
+ * which can cause permit and V3 pool approvals to fail.
+ * This function checks whether a workaround is needed by detecting
+ * if any operation includes a known Uniswap-related address.
+ */
+export const uniswapWorkaround = (ops: string[]) => {
+  return ops.some((op) =>
+    uniswapWorkaroundAddresses.some((permitAddress) => op.toLowerCase().includes(permitAddress.slice(2).toLowerCase())),
+  );
+};

package/src/functions/utils/ipfs.ts

@@ -0,0 +1,74 @@
+import { CID } from 'multiformats';
+
+/**
+ * Removes IPFS protocol prefix from input string.
+ *
+ * @param ipfsUrl - An IPFS url (e.g. ipfs://{content id})
+ * @returns IPFS content identifier and (possibly) path in a string
+ * @throws Will throw if the url passed is not IPFS.
+ */
+const removeIpfsProtocolPrefix = (ipfsUrl: string) => {
+  if (ipfsUrl.startsWith('ipfs://ipfs/')) {
+    return ipfsUrl.replace('ipfs://ipfs/', '');
+  } else if (ipfsUrl.startsWith('ipfs://')) {
+    return ipfsUrl.replace('ipfs://', '');
+  }
+  // this method should not be used with non-ipfs urls (i.e. startsWith('ipfs://') === true)
+  throw new Error('this method should not be used with non ipfs urls');
+};
+
+/**
+ * Extracts content identifier and path from an input string.
+ *
+ * @param ipfsUrl - An IPFS URL minus the IPFS protocol prefix
+ * @returns IFPS content identifier (cid) and sub path as string.
+ * @throws Will throw if the url passed is not ipfs.
+ */
+const getIpfsCIDv1AndPath = (ipfsUrl: string) => {
+  const url = removeIpfsProtocolPrefix(ipfsUrl);
+
+  // check if there is a path
+  // (CID is everything preceding first forward slash, path is everything after)
+  const index = url.indexOf('/');
+  const cid = index !== -1 ? url.substring(0, index) : url;
+  const path = index !== -1 ? url.substring(index) : undefined;
+
+  // We want to ensure that the CID is v1 (https://docs.ipfs.io/concepts/content-addressing/#identifier-formats)
+  // because most cid v0s appear to be incompatible with IPFS subdomains
+  return {
+    cid: CID.parse(cid).toV1().toString(),
+    path,
+  };
+};
+
+/**
+ * Adds URL protocol prefix to input URL string if missing.
+ *
+ * @param urlString - An IPFS URL.
+ * @returns A URL with a https:// prepended.
+ */
+const addUrlProtocolPrefix = (urlString: string): string => {
+  if (!urlString.match(/(^http:\/\/)|(^https:\/\/)/u)) {
+    return `https://${urlString}`;
+  }
+  return urlString;
+};
+
+const IPFS_DEFAULT_GATEWAY_URL = 'https://ipfs.io/ipfs/';
+
+/**
+ * Formats URL correctly for use retrieving assets hosted on IPFS.
+ *
+ * @param ipfsUrl - The IFPS URL pointed at the asset.
+ * @param subdomainSupported - Boolean indicating whether the URL should be formatted with subdomains or not.
+ * @returns A formatted URL, with the user's preferred IPFS gateway and format (subdomain or not), pointing to an asset hosted on IPFS.
+ */
+export const getFormattedIpfsUrl = (ipfsUrl: string, subdomainSupported: boolean) => {
+  const { host, protocol, origin } = new URL(addUrlProtocolPrefix(IPFS_DEFAULT_GATEWAY_URL));
+  if (subdomainSupported) {
+    const { cid, path } = getIpfsCIDv1AndPath(ipfsUrl);
+    return `${protocol}//${cid}.ipfs.${host}${path ?? ''}`;
+  }
+  const cidAndPath = removeIpfsProtocolPrefix(ipfsUrl);
+  return `${origin}/ipfs/${cidAndPath}`;
+};

package/src/functions/utils/is-valid-url.ts

@@ -0,0 +1,5 @@
+export const isValidUrl = (url?: string) => {
+  if (!url) return false;
+  const pattern = /^https?:\/\/[a-z0-9.-]+\.[a-z]{2,}(?::\d{1,5})?(?:\/[^\s]*)?$/i;
+  return pattern.test(url.trim());
+};

package/src/functions/utils/lifi.utils.ts

@@ -0,0 +1,3 @@
+import { LIFISCAN_URL } from '../../constants/lifi.constants';
+
+export const getLifiScanURL = (txHash: string) => `${LIFISCAN_URL}/tx/${txHash}`;