@sabaaa1/common 0.0.1

package/src/functions/snarkjs/generateZkProofEnclave.ts

@@ -0,0 +1,45 @@
+import { GenerateProofResponseType } from '../../types/remote-proof.types';
+import { NewZkCallDataType } from '../../types/snark.types';
+import { getWASMFile, getZKeyFile } from './getZKFiles';
+import { ENCLAVE_EC2_URL } from './constant';
+import { ProverVersion } from '../../types/hinkal.types';
+import { makeEnclaveHandshakeAndEncryptInput } from '../utils/encryptInputForEnclave';
+import { httpClient } from '../../data-structures/tor';
+
+const retrieveVerifierFilename = (verifierName: string): string => {
+  if (verifierName.startsWith('http')) {
+    const splitVerifierName = verifierName.split('/');
+    const result = splitVerifierName.at(-1);
+    if (!result) throw new Error('invalid verifierName');
+    return result;
+  }
+  return verifierName;
+};
+
+export const generateZkProofEnclave = async (
+  proverVersion: ProverVersion,
+  chainId: number,
+  verifierName: string,
+  input: any,
+): Promise<{ zkCallData: NewZkCallDataType; publicSignals: string[] }> => {
+  const wasmFilename = retrieveVerifierFilename(getWASMFile(proverVersion, verifierName, chainId));
+  const zKeyFilename = retrieveVerifierFilename(getZKeyFile(proverVersion, verifierName, chainId));
+
+  // encrypt data for enclave, results are in base64
+  const { keyCiphertext, inputCiphertext } = await makeEnclaveHandshakeAndEncryptInput(input);
+
+  const data = {
+    chainId,
+    circuit_wasm: wasmFilename,
+    circuit_zkey: zKeyFilename,
+    input: inputCiphertext,
+    key: keyCiphertext,
+    version: proverVersion,
+  };
+
+  // generate proof and get necessary result from enclave
+  const proofResponse = await httpClient.post<GenerateProofResponseType>(`${ENCLAVE_EC2_URL}/generate`, data);
+  const { public_signals: publicSignals, zk_calldata: zkCallData } = proofResponse;
+
+  return { zkCallData, publicSignals };
+};

package/src/functions/snarkjs/generateZkProofSelf.ts

@@ -0,0 +1,29 @@
+import { NewZkCallDataType, ProverVersion, ZkResultType } from '../../types';
+import { getWASMFile, getZKeyFile } from './getZKFiles';
+import { performTaskWithWorker } from '../../webworker/performTaskWithWorker';
+import { SnarkJSPayload, SnarkJSWorkerActionType } from '../../webworker/snarkjsWorker/snarkjsWorker.types';
+import { WorkerVariant } from '../../webworker/worker.registry';
+
+export const generateZkProofSelf = async (
+  proverVersion: ProverVersion,
+  chainId: number,
+  verifierName: string,
+  input: any,
+): Promise<{ zkCallData: NewZkCallDataType; publicSignals: string[] }> => {
+  const wasmFilePath = getWASMFile(proverVersion, verifierName, chainId);
+  const zKeyFilePath = getZKeyFile(proverVersion, verifierName, chainId);
+
+  // snarkjs `input` param is structuredClone() safe so we can safely pass to worker
+  const { publicSignals, zkCallData } = await performTaskWithWorker<
+    SnarkJSPayload,
+    ZkResultType & { zkCallData: NewZkCallDataType }
+  >({
+    type: WorkerVariant.SnarkJS,
+    payload: {
+      type: SnarkJSWorkerActionType.FULL_PROVE,
+      data: { input, chainId, wasmFilePath, zKeyFilePath },
+    },
+  });
+
+  return { zkCallData, publicSignals };
+};

package/src/functions/snarkjs/getOriginalSender.ts

@@ -0,0 +1,4 @@
+import { zeroAddress } from '../../constants/protocol.constants';
+
+export const getOriginalSender = (externalAddress: string, relay: string) =>
+  relay === zeroAddress ? externalAddress ?? zeroAddress : zeroAddress;

package/src/functions/snarkjs/getZKFiles.ts

@@ -0,0 +1,29 @@
+import { ProverVersion } from '../../types/hinkal.types';
+import { chainIds } from '../../constants/chains.constants';
+import { localVerifiers, prodVerifiers } from './constant';
+
+export const getWASMFile = (proverVersion: ProverVersion, filename: string, chainId: number) => {
+  const exactVersion = proverVersion === 'v1x0' ? '' : proverVersion;
+  if (chainId === chainIds.localhost) {
+    const verifier = localVerifiers[`${filename}${exactVersion}Wasm` as keyof typeof localVerifiers];
+    return verifier;
+  }
+  const verifier = prodVerifiers(chainId, proverVersion)[
+    `${filename}${exactVersion}Wasm` as keyof typeof prodVerifiers
+  ];
+  console.log({ verifier });
+  return verifier;
+};
+
+export const getZKeyFile = (proverVersion: ProverVersion, filename: string, chainId: number) => {
+  const exactVersion = proverVersion === 'v1x0' ? '' : proverVersion;
+  if (chainId === chainIds.localhost) {
+    const verifier = localVerifiers[`${filename}${exactVersion}Zkey` as keyof typeof localVerifiers];
+    return verifier;
+  }
+  const verifier = prodVerifiers(chainId, proverVersion)[
+    `${filename}${exactVersion}Zkey` as keyof typeof prodVerifiers
+  ];
+
+  return verifier;
+};

package/src/functions/snarkjs/index.ts

@@ -0,0 +1,4 @@
+export * from './constructGeneralZkProof';
+export * from './constructEmporiumProof';
+export * from './common.snarkjs';
+export * from './generateZkProof';

package/src/functions/staking/index.ts

@@ -0,0 +1,78 @@
+/* eslint-disable no-await-in-loop */
+/* eslint-disable @typescript-eslint/dot-notation */
+/* eslint-disable no-continue */
+/* eslint-disable no-restricted-syntax */
+import { ethers } from 'ethers';
+import { UserKeys } from '../../data-structures/crypto-keys/keys';
+import sodium from 'libsodium-wrappers';
+import { poseidonHash } from '../../crypto';
+
+interface StakeDecryptOutput {
+  stakeBlinding: bigint;
+  stakedTokenRecipient: string;
+}
+
+export const encryptStake = (stakeBlinding: bigint, stakedTokenRecipient: string, encryptionKey: string) => {
+  const dataToEncrypt = ethers.utils.defaultAbiCoder.encode(
+    ['uint256', 'address'],
+    [stakeBlinding, stakedTokenRecipient],
+  );
+  const encryptedData = sodium.crypto_box_seal(dataToEncrypt, ethers.utils.arrayify(encryptionKey)); // (data,key)
+  const encryptedString = `0x${Buffer.from(encryptedData).toString('hex')}`;
+  return encryptedString;
+};
+
+export const decryptStake = (
+  encryptedStakeCommitmentContent: string,
+  minterKeys: UserKeys,
+): StakeDecryptOutput | undefined => {
+  const bufferData = Buffer.from(encryptedStakeCommitmentContent.slice(2), 'hex');
+  const { publicKey, privateKey } = UserKeys.getEncryptionKeyPair(minterKeys.getShieldedPrivateKey());
+
+  try {
+    const rawData = sodium.crypto_box_seal_open(
+      bufferData,
+      ethers.utils.arrayify(publicKey),
+      ethers.utils.arrayify(privateKey),
+    );
+
+    const decryptedAbiEncodedData = Buffer.from(rawData).toString('utf-8');
+    const [stakeBlinding, stakedTokenRecipient] = ethers.utils.defaultAbiCoder.decode(
+      ['uint256', 'address'],
+      decryptedAbiEncodedData,
+    );
+    return { stakeBlinding: stakeBlinding.toBigInt(), stakedTokenRecipient };
+  } catch {
+    console.log('failed to decrypt');
+    return undefined;
+  }
+};
+
+export const createStakeCommitment = (
+  isStake: boolean,
+  stakedTokenRecipient: string,
+  stakeBlinding: bigint,
+  tokenAddress: string,
+  amountChange: bigint,
+  timeStamp: bigint,
+) => {
+  return BigInt(
+    poseidonHash(...[isStake, stakedTokenRecipient, stakeBlinding, tokenAddress, amountChange, timeStamp].map(BigInt)),
+  );
+};
+
+export const calculateStakeNullifier = (stakeCommitment: bigint, blinding: bigint) => {
+  return poseidonHash(stakeCommitment, blinding);
+};
+
+export const encodeHStakeMetadata = (
+  action: 1 | 0,
+  stakeCommitment: bigint,
+  depositorAddress: string,
+  encryptedContent: string,
+  encryptedContentAlt: string,
+) =>
+  ethers.utils.defaultAbiCoder.encode(
+    ['uint8', 'uint256', 'address', 'bytes', 'bytes'],
+    [action, stakeCommitment, depositorAddress, encryptedContent, encryptedContentAlt],
+  );

package/src/functions/utils/addresses.ts

@@ -0,0 +1,37 @@
+import { ethers } from 'ethers';
+import { StealthAddressStructure } from '../../types/circom-data.types';
+
+export const isValidPrivateAddress = (address: string): boolean => {
+  const [randomization, stealthAddress, encryptionKey] = address.split(',');
+
+  const missingVariable = !randomization || !stealthAddress || !encryptionKey;
+  const incorrectAddressFormat = stealthAddress?.substring(0, 2) !== '0x' || encryptionKey?.substring(0, 2) !== '0x';
+  const incorrectLength = encryptionKey?.length !== 66 || stealthAddress?.length > 66 || stealthAddress?.length < 64;
+  const incorrectSymbols = address?.includes('"');
+
+  return !(missingVariable || incorrectAddressFormat || incorrectLength || incorrectSymbols);
+};
+
+export const isValidExtendedPrivateAddress = (address: string): boolean => {
+  const [randomization, stealthAddress, H0, H1] = address.split(',');
+  const missingVariable = !stealthAddress || !randomization || !H0 || !H1;
+  const incorrectAddressFormat = stealthAddress?.substring(0, 2) !== '0x';
+  const incorrectLength = stealthAddress?.length > 66 || stealthAddress?.length < 64;
+  const incorrectSymbols = address?.includes('"');
+
+  return !(missingVariable || incorrectAddressFormat || incorrectLength || incorrectSymbols);
+};
+
+export const constructStealthAddressStructure = (recipientInfo: string): StealthAddressStructure => {
+  const [randomization, stealthAddress, H0, H1] = recipientInfo.split(',');
+  return {
+    extraRandomization: BigInt(randomization),
+    stealthAddress: BigInt(stealthAddress),
+    H0: BigInt(H0),
+    H1: BigInt(H1),
+  };
+};
+
+export const hashEthereumAddress = (ethereumAddress: string): string => {
+  return ethers.utils.keccak256(ethers.utils.toUtf8Bytes(ethereumAddress.toLowerCase()));
+};

package/src/functions/utils/amounts.utils.test.ts

@@ -0,0 +1,91 @@
+import { toCommaSeparatedNumberString, trimLeadingZeros } from './amounts.utils';
+
+describe('toCommaSeparatedNumberString', () => {
+  it('should format number string with commas', () => {
+    const numberString = '1234567890.1234567890';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('1,234,567,890.1234567890');
+  });
+
+  it('should format integer part with commas', () => {
+    const numberString = '9876543210';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('9,876,543,210');
+  });
+
+  it('should handle number string without decimal part', () => {
+    const numberString = '1234567890';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('1,234,567,890');
+  });
+
+  it('should handle number string with empty decimal part', () => {
+    const numberString = '1234567890.';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('1,234,567,890.');
+  });
+
+  it('should handle number string with leading zeros', () => {
+    const numberString = '0000123456.789000';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('123,456.789000');
+  });
+});
+
+describe('toCommaSeparatedNumberString', () => {
+  it('should format number string with commas', () => {
+    const numberString = '1234567890.1234567890';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('1,234,567,890.1234567890');
+  });
+
+  it('should format integer part with commas', () => {
+    const numberString = '9876543210';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('9,876,543,210');
+  });
+
+  it('should handle number string without decimal part', () => {
+    const numberString = '1234567890';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('1,234,567,890');
+  });
+
+  it('should handle number string with empty decimal part', () => {
+    const numberString = '1234567890.';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('1,234,567,890.');
+  });
+
+  it('should handle number string with leading zeros', () => {
+    const numberString = '0000123456.789000';
+    const result = toCommaSeparatedNumberString(numberString);
+    expect(result).toEqual('123,456.789000');
+  });
+});
+
+describe('trimLeadingZeros', () => {
+  it('should trim repeating zeros to single zero', () => {
+    const numberString = '0000000';
+    const result = trimLeadingZeros(numberString);
+    expect(result).toEqual('0');
+  });
+
+  it('should keep one leading zero before decimal point', () => {
+    const numberString = '0.123';
+    const result = trimLeadingZeros(numberString);
+    expect(result).toEqual('0.123');
+  });
+
+  it('should trim leading zeros before integer part', () => {
+    const numberString = '0000123456.789000';
+    const result = trimLeadingZeros(numberString);
+    expect(result).toEqual('123456.789000');
+  });
+
+  it('should not trim leading zeros if there is no integer part', () => {
+    const numberString = '0.789000';
+    const result = trimLeadingZeros(numberString);
+    expect(result).toEqual('0.789000');
+  });
+});

package/src/functions/utils/amounts.utils.ts

@@ -0,0 +1,119 @@
+import { type Utxo } from '../../data-structures/utxo/Utxo';
+import { BigIntable } from '../../types/big-intable.types';
+
+export const calculateSum = (arr: number[]) => arr.reduce((prev, item) => prev + item, 0);
+export const calculateBigIntSum = (arr: bigint[]) => arr.reduce((prev, item) => prev + item, 0n);
+
+export const beepsToPercentage = (beeps: number) => beeps / 100;
+export const calculateAmountUsingBeeps = (beep: bigint, amount: bigint) => (amount * beep) / 10000n;
+
+export function toBigInt(value: BigIntable): bigint {
+  if (typeof value === 'object' && 'toBigInt' in value) {
+    return value.toBigInt();
+  }
+  return BigInt(value);
+}
+
+/** Converts the value to a BigInt or returns undefined if can't */
+export const toBigIntOrUndefined = (value: any) => {
+  try {
+    return BigInt(value);
+  } catch {
+    return undefined;
+  }
+};
+
+/** Converts the value to a number or returns undefined if can't */
+export const toNumberOrUndefined = (value: any): number | undefined => {
+  const num = Number(value);
+  return Number.isNaN(num) ? undefined : num;
+};
+
+export const toInt = (param: string | undefined, defaultValue: number): number =>
+  param ? parseInt(param, 10) : defaultValue;
+
+export function bigintApplySugar() {
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  // To support serialization through JSON.stringify. Do not call in libraries!
+  BigInt.prototype.toJSON = function toJSON() {
+    return this.toString();
+  };
+}
+
+export function bigintMax(...values: bigint[]): bigint {
+  return values.reduce((max, value) => (value > max ? value : max));
+}
+
+// here + before Number convers string to number and cuts unused 0s at the end
+export function fixDecimalsAmount(n: number) {
+  if (n === 0) {
+    return 0;
+  }
+  return n < 0.00000099999 ? '< 0.000001' : +Number(n).toFixed(6);
+}
+
+export const getValueFirstNDigit = (num: number, numberOfDigits: number): string => {
+  const numStr = num.toFixed(20); // if num = 0.03232e-17 -> it will transform to 0.00...03232
+
+  const indexOfDecimal = numStr.indexOf('.');
+  // If there's no decimal point, return the original number (or handle this case as you need)
+  if (indexOfDecimal === -1) return numStr;
+
+  // Determine the end position for substring, which is start position + n digits after decimal
+  const endPosition = indexOfDecimal + numberOfDigits + 1;
+
+  // Get the string from the start to the specified end position
+  const resultStr = numStr.substring(0, endPosition);
+
+  return resultStr;
+};
+
+export const trimLeadingZeros = (numberString: string): string => {
+  // String of repeating 0's (e.g. '0000000') should be replaced with '0', not empty string
+  if (/^0+$/.test(numberString)) {
+    return '0';
+  }
+  // One leading zero before decimal point is valid
+  if (/^0\.\d+$/.test(numberString)) {
+    return numberString;
+  }
+  const trimmed = numberString.replace(/^0+/, '');
+  return trimmed.startsWith('.') ? `0${trimmed}` : trimmed;
+};
+
+export const toCommaSeparatedNumberString = (numberString: string): string => {
+  const parts = numberString.split('.');
+  const integerPart = parts[0];
+  // Only add the . and decimal part if exist
+  const decimalPart = parts.length > 1 ? `.${parts[1]}` : '';
+
+  // Use a regular expression to format the integer part with commas
+  const formattedIntegerPart = trimLeadingZeros(integerPart).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+
+  return `${formattedIntegerPart}${decimalPart}`;
+};
+
+export const truncateToDecimalPlaces = (numStr: string, decimalPlaces = 18): string => {
+  const match = numStr.match(/^(\d+)(\.(\d+))?$/);
+  if (match) {
+    const integerPart = match[1];
+    const decimalPart = match[3]?.slice(0, decimalPlaces) || '';
+    return decimalPart ? `${integerPart}.${decimalPart}` : integerPart;
+  }
+  return numStr;
+};
+
+/** Return absolute value of BigInt */
+export const absBigInt = (n: bigint) => (n < 0n ? -n : n);
+
+/** Return the smallest values of the 2 or 3 values provided */
+export const minBigInt = (a: bigint, b: bigint, c?: bigint) => {
+  const minOne = a < b ? a : b;
+  if (!c) return minOne;
+  return minOne < c ? minOne : c;
+};
+
+export const maxBigInt = (a: bigint, b: bigint) => (a > b ? a : b);
+
+export const countTotalAmountInUtxos = (utxos: Utxo[]) => utxos.reduce((prev, { amount }) => prev + amount, 0n);

package/src/functions/utils/arraysMatch.ts

@@ -0,0 +1,4 @@
+export const arraysMatch = (array1: unknown[], array2: unknown[]) => {
+  if (array1.length !== array2.length) return false;
+  return array1.every((element, index) => element === array2[index]);
+};

package/src/functions/utils/cacheDevice.utils.ts

@@ -0,0 +1,21 @@
+import { type HinkalConfig } from '../../types/hinkal.types';
+import { isNode } from '../../constants';
+import { FileCacheDevice, LocalStorageCacheDevice } from '../../data-structures/cacheDevices';
+
+export const createCacheDevice = (hinkalConfig?: HinkalConfig) => {
+  if (isNode) {
+    let useFileCache: boolean | undefined;
+    let cacheFilePath: string | undefined;
+
+    if (hinkalConfig) {
+      ({ useFileCache, cacheFilePath } = hinkalConfig);
+    }
+
+    // eslint-disable-next-line global-require, @typescript-eslint/no-var-requires
+    const path = require('path');
+    const cachePath: string = path.resolve(process.cwd(), 'hinkalCache.json');
+    return new FileCacheDevice(useFileCache, cacheFilePath ?? cachePath);
+  } else {
+    return new LocalStorageCacheDevice(hinkalConfig?.disableCaching, hinkalConfig?.serializedCache);
+  }
+};

package/src/functions/utils/cacheFunctions.ts

@@ -0,0 +1,154 @@
+import { type IHinkal } from '../../data-structures/Hinkal/IHinkal';
+import { ContractType } from '../../types/ethereum-network.types';
+import { type DecodedTx } from '../../types/transactions.types';
+import { type EncryptedOutputWithSign } from '../../types/commitments.types';
+import { deserializeDecodedTxs, serializeDecodedTxs } from './getDataFromTransaction';
+import { get, set } from 'idb-keyval';
+
+// CACHE FOR ENCRYPTED OUTPUTS
+
+export interface HinkalCacheInterface {
+  encryptedOutputs: EncryptedOutputWithSign[];
+  lastOutput: string;
+}
+
+const emptyHinkalCache: HinkalCacheInterface = {
+  encryptedOutputs: [],
+  lastOutput: '',
+};
+
+const getShortPublicKeyAndHinkalAddress = (shieldedPublicKey: string, hinkalAddress: string) => {
+  const shortPublicKey = shieldedPublicKey.substring(0, 25);
+  const shortHinkalAddress = hinkalAddress.substring(0, 25);
+  return { shortPublicKey, shortHinkalAddress };
+};
+
+export const getFilePath = (chainId: number, shortPublicKey: string, shortHinkalAddress: string) => {
+  return `hinkalCache-${chainId}-${shortPublicKey}-${shortHinkalAddress}`;
+};
+
+export const getHinkalCache = (hinkal: IHinkal, chainId: number, shieldedPublicKey: string): HinkalCacheInterface => {
+  const hinkalAddress = hinkal.getContract(ContractType.HinkalContract).address;
+  if (!chainId || !shieldedPublicKey || !hinkalAddress) throw Error('GetHinkalCache: incorrect arguments');
+
+  const { shortPublicKey, shortHinkalAddress } = getShortPublicKeyAndHinkalAddress(shieldedPublicKey, hinkalAddress);
+
+  return JSON.parse(
+    hinkal.cacheDevice.get(getFilePath(chainId, shortPublicKey, shortHinkalAddress)) ??
+      JSON.stringify(emptyHinkalCache),
+  );
+};
+
+export const setHinkalCache = (
+  hinkalCache: HinkalCacheInterface,
+  hinkal: IHinkal,
+  chainId: number,
+  shieldedPublicKey: string,
+) => {
+  const hinkalAddress = hinkal.getContract(ContractType.HinkalContract).address;
+  if (!chainId || !shieldedPublicKey || !hinkalAddress) throw Error('SetHinkalCache: incorrect arguments');
+
+  const { shortPublicKey, shortHinkalAddress } = getShortPublicKeyAndHinkalAddress(shieldedPublicKey, hinkalAddress);
+
+  hinkal.cacheDevice.set(getFilePath(chainId, shortPublicKey, shortHinkalAddress), JSON.stringify(hinkalCache));
+};
+
+export const resetCache = (hinkal: IHinkal, chainId: number, shieldedPublicKey: string) => {
+  setHinkalCache(emptyHinkalCache, hinkal, chainId, shieldedPublicKey);
+};
+
+// CACHE FOR TRANSACTIONS
+
+const constructTxsCacheKey = (chainId: number, shortPublicKey: string, shortHinkalAddress: string) => {
+  return `txsCache-${chainId}-${shortPublicKey}-${shortHinkalAddress}`;
+};
+
+export const saveTxsCache = async (
+  txs: DecodedTx[],
+  chainId: number,
+  shieldedPublicKey: string,
+  hinkalAddress: string,
+  lastHash: string,
+  hinkal: IHinkal,
+) => {
+  if (!chainId || !shieldedPublicKey || !hinkalAddress) throw Error('saveTxsCache: incorrect arguments');
+  const { shortPublicKey, shortHinkalAddress } = getShortPublicKeyAndHinkalAddress(shieldedPublicKey, hinkalAddress);
+  const serializedTxs = serializeDecodedTxs(txs);
+  const key = constructTxsCacheKey(chainId, shortPublicKey, shortHinkalAddress);
+  const stringContent = JSON.stringify({ serializedTxs, lastHash });
+  try {
+    await set(key, stringContent);
+  } catch {
+    // if indexeddb not available fall back to localstorage
+    hinkal.cacheDevice.set(key, stringContent);
+  }
+};
+
+const emptyCacheString = { serializedTxs: [], lastHash: '' }; // if we use undefined instead of '', then we will not be able to get it after stringify and parse
+
+export const loadTxsCache = async (
+  chainId: number,
+  shieldedPublicKey: string,
+  hinkalAddress: string,
+  hinkal: IHinkal,
+) => {
+  if (!chainId || !shieldedPublicKey || !hinkalAddress) throw Error('loadTxsCache: incorrect arguments');
+  const { shortPublicKey, shortHinkalAddress } = getShortPublicKeyAndHinkalAddress(shieldedPublicKey, hinkalAddress);
+  const key = constructTxsCacheKey(chainId, shortPublicKey, shortHinkalAddress);
+  let stringData: string | null | undefined;
+  try {
+    const stringDataIndexedDB = await get<string>(key);
+    if (!stringDataIndexedDB) throw new Error('Empty indexedDB cache');
+    stringData = stringDataIndexedDB;
+  } catch {
+    stringData = hinkal.cacheDevice.get(key);
+  }
+  const { serializedTxs, lastHash } = JSON.parse(stringData ?? JSON.stringify(emptyCacheString)) as {
+    serializedTxs: DecodedTx<string, string>[];
+    lastHash: string;
+  };
+  const decodedTxs = serializedTxs.map((tx) => deserializeDecodedTxs(tx));
+  return { decodedTxs, lastHash: lastHash === '' ? undefined : lastHash }; // we want to have undefined value instead of empty string '', since server does not like "/" at the end of the request
+};
+
+// CACHE FOR InHinkalAddresses
+export const getInHinkalAddressesFilePath = (chainId: number, shortPublicKey: string, shortHinkalAddress: string) => {
+  return `hinkalApprovalsCache-${chainId}-${shortPublicKey}-${shortHinkalAddress}`;
+};
+
+export const setInHinkalAddressesCache = (
+  hinkalCache: Record<string, string>,
+  hinkal: IHinkal,
+  chainId: number,
+  shieldedPublicKey: string,
+) => {
+  const hinkalAddress = hinkal.getContract(ContractType.HinkalContract, undefined, chainId).address;
+  if (!chainId || !shieldedPublicKey || !hinkalAddress) throw Error('SetHinkalCache: incorrect arguments');
+
+  const { shortPublicKey, shortHinkalAddress } = getShortPublicKeyAndHinkalAddress(shieldedPublicKey, hinkalAddress);
+
+  hinkal.cacheDevice.set(
+    getInHinkalAddressesFilePath(chainId, shortPublicKey, shortHinkalAddress),
+    JSON.stringify(hinkalCache),
+  );
+};
+
+export const getInHinkalAddressesCache = (
+  hinkal: IHinkal,
+  chainId: number,
+  shieldedPublicKey: string,
+): Record<string, string> => {
+  const hinkalAddress = hinkal.getContract(ContractType.HinkalContract, undefined, chainId).address;
+  if (!chainId || !shieldedPublicKey || !hinkalAddress) throw Error('GetHinkalCache: incorrect arguments');
+
+  const { shortPublicKey, shortHinkalAddress } = getShortPublicKeyAndHinkalAddress(shieldedPublicKey, hinkalAddress);
+
+  return JSON.parse(
+    hinkal.cacheDevice.get(getInHinkalAddressesFilePath(chainId, shortPublicKey, shortHinkalAddress)) ??
+      JSON.stringify(emptyHinkalCache),
+  ) as Record<string, string>;
+};
+
+export const resetInHinkalAddressesCache = (hinkal: IHinkal, chainId: number, shieldedPublicKey: string) => {
+  setInHinkalAddressesCache({}, hinkal, chainId, shieldedPublicKey);
+};

package/src/functions/utils/caseInsensitive.utils.ts

@@ -0,0 +1,10 @@
+export const caseInsensitiveEqual = (a?: string | null, b?: string | null) => {
+  if (a === undefined || b === undefined || a === null || b === null) return false;
+  return a.toLowerCase() === b.toLowerCase();
+};
+
+export const lowerCaseIncludes = (array: string[], address?: string) =>
+  array.some((item) => caseInsensitiveEqual(item, address));
+
+export const lowerCaseStartsWith = (array: string[], s: string) =>
+  array.some((item) => item.toLowerCase().startsWith(s.toLowerCase()));

package/src/functions/utils/convertEmporiumOpToCallInfo.ts

@@ -0,0 +1,19 @@
+import { CallInfo } from '../../types/API.types';
+import { ethers } from 'ethers';
+import { networkRegistry } from '../../constants/chains.constants';
+
+export const convertEmporiumOpToCallInfo = (op: string, walletAddress: string, chainId: number): CallInfo => {
+  const { hinkalAddress } = networkRegistry[chainId].contractData;
+
+  const opBytes = ethers.utils.arrayify(op);
+  const toBytes = opBytes.slice(0, 20);
+  const invokeWalletBytes = opBytes.slice(20, 21);
+  const valueBytes = opBytes.slice(21, 37);
+  const calldataBytes = opBytes.slice(37);
+
+  const [to, value, invokeWallet, calldata] = [toBytes, valueBytes, invokeWalletBytes, calldataBytes].map((bytes) =>
+    ethers.utils.hexlify(bytes),
+  );
+
+  return { from: BigInt(invokeWallet) > 0 ? walletAddress : hinkalAddress, to, value: BigInt(value), calldata };
+};

package/src/functions/utils/convertIntegrationProviderToExternalActionId.ts

@@ -0,0 +1,14 @@
+import { IntegrationProvider } from '../../types/hinkal.types';
+import { ExternalActionId } from '../../types/external-action.types';
+
+const conversionTable: Record<IntegrationProvider, ExternalActionId | undefined> = {
+  [IntegrationProvider.UNISWAP]: ExternalActionId.Uniswap,
+  [IntegrationProvider.ODOS]: ExternalActionId.Odos,
+  [IntegrationProvider.ONEINCH]: ExternalActionId.OneInch,
+  [IntegrationProvider.LIFI]: ExternalActionId.Lifi,
+  [IntegrationProvider.ALL]: undefined,
+  [IntegrationProvider.NONE]: undefined,
+};
+
+export const convertIntegrationProviderToExternalActionId = (integrationProvider: IntegrationProvider) =>
+  conversionTable[integrationProvider];