@sabaaa1/common 0.0.1

package/src/data-structures/cacheDevices/LocalStorageCacheDevice.ts

@@ -0,0 +1,36 @@
+import { CustomJSONStringify } from '../../functions/utils/serialize.utils';
+import { BaseCacheDevice } from './BaseCacheDevice';
+
+export class LocalStorageCacheDevice extends BaseCacheDevice {
+  private localDataStorage: Storage | undefined;
+
+  constructor(disableCaching?: boolean, serializedCache?: Record<string, string>) {
+    super();
+    if (!disableCaching && typeof localStorage !== 'undefined') {
+      this.localDataStorage = localStorage;
+    }
+    if (serializedCache) this.mergeWithSerialized(serializedCache);
+  }
+
+  get(key: string): string | undefined {
+    if (this.localDataStorage) {
+      return this.localDataStorage.getItem(key) ?? undefined;
+    } else {
+      return this.getInMemory(key);
+    }
+  }
+
+  set(key: string, value: string): void {
+    if (this.localDataStorage) {
+      this.localDataStorage.setItem(key, value);
+    } else {
+      this.setInMemory(key, value);
+    }
+  }
+
+  serialize(): Record<string, string> {
+    const keyValuePairs = this.localDataStorage ? Object.entries(localStorage) : [...this.inMemoryCache];
+
+    return Object.fromEntries(keyValuePairs.map(([key, value]) => [key, CustomJSONStringify(value)]));
+  }
+}

package/src/data-structures/cacheDevices/index.ts

@@ -0,0 +1,2 @@
+export * from './FileCacheDevice';
+export * from './LocalStorageCacheDevice';

package/src/data-structures/crypto-keys/decodeUTXO.ts

@@ -0,0 +1,60 @@
+import { BigNumber, ethers } from 'ethers';
+import { IUtxoConstructor, Utxo } from '../utxo/Utxo';
+import { UserKeys } from './keys';
+
+export const abiDecodeUtxo = (encryptedOutput: string) => {
+  // UTXO {uint256 amount;address erc20Address;StealthAddressStructure stealthAddressStructure;uint256 timeStamp;uint256 tokenId; }
+  const decodedUtxo = ethers.utils.defaultAbiCoder.decode(
+    ['uint256', 'address', 'tuple(uint256, uint256, uint256, uint256)', 'uint256', 'uint256'],
+    encryptedOutput,
+  );
+  const amount = (decodedUtxo[0] as BigNumber).toBigInt();
+  const erc20TokenAddress = decodedUtxo[1] as string;
+
+  const randomization = (decodedUtxo[2][0] as BigNumber).toBigInt();
+  const stealthAddress = (decodedUtxo[2][1] as BigNumber).toHexString();
+  const H0 = (decodedUtxo[2][2] as BigNumber).toBigInt();
+  const H1 = (decodedUtxo[2][3] as BigNumber).toBigInt();
+
+  const timeStamp = (decodedUtxo[3] as BigNumber).toString();
+  const tokenId = (decodedUtxo[4] as BigNumber).toNumber();
+  return {
+    amount,
+    erc20TokenAddress,
+    randomization,
+    stealthAddress,
+    H0,
+    H1,
+    timeStamp,
+    tokenId,
+  };
+};
+
+export const decodeUtxoConstructorArgs = (encryptedOutput: string, privateKey: string): IUtxoConstructor => {
+  const { amount, erc20TokenAddress, timeStamp, tokenId, randomization, stealthAddress } =
+    abiDecodeUtxo(encryptedOutput);
+
+  return {
+    amount,
+    erc20TokenAddress,
+    timeStamp,
+    tokenId,
+    randomization,
+    shieldedPrivateKey: privateKey,
+    stealthAddress,
+  };
+};
+
+export const decodeUtxo = (encryptedOutput: string, privateKey: string): Utxo => {
+  return new Utxo(decodeUtxoConstructorArgs(encryptedOutput, privateKey));
+};
+
+export const checkUtxoSignature = (encryptedOutput: string, privateKey: string): boolean => {
+  const { randomization, H0, H1 } = abiDecodeUtxo(encryptedOutput);
+
+  const utxoBelongsToUser = UserKeys.checkSignature(randomization, H0, H1, privateKey);
+
+  if (!utxoBelongsToUser) throw new Error("UTXO doesn't belong to user");
+
+  return utxoBelongsToUser;
+};

package/src/data-structures/crypto-keys/encryptDecryptUtxo.ts

@@ -0,0 +1,74 @@
+import { ethers } from 'ethers';
+import sodium from 'libsodium-wrappers'; // added * as for jest
+import { IUtxoConstructor, Utxo } from '../utxo/Utxo';
+import { UserKeys } from './keys';
+
+/**
+ * encrypt data for the UTXO
+ * @param amount UTXO amount
+ * @param blinding UTXO blinding
+ * @param publicKey sender's encryption public key
+ * @returns returns encrypted data {Uint8Array}
+ */
+export const encryptUtxo = (utxo: Utxo, forceZeroAmount: boolean): Uint8Array => {
+  // converting data to Uint8Array
+  // all data is in hex format
+  const arrayToEncrypt = [
+    Buffer.from(ethers.utils.hexlify(forceZeroAmount ? 0n : utxo.amount)),
+    Buffer.from(ethers.utils.hexlify(utxo.erc20TokenAddress)),
+    Buffer.from(ethers.utils.hexlify(utxo.randomization)),
+    Buffer.from(utxo.getStealthAddress()),
+    Buffer.from(ethers.utils.hexlify(BigInt(utxo.timeStamp))),
+  ];
+  if (utxo.tokenId > 0) arrayToEncrypt.push(Buffer.from(ethers.utils.hexlify(utxo.tokenId)));
+  const bytes = Buffer.concat(arrayToEncrypt);
+
+  // encrypting with encryptionPublicKey
+  const encryptedData = sodium.crypto_box_seal(bytes, ethers.utils.arrayify(utxo.getEncryptionKey()));
+
+  return encryptedData;
+};
+
+export const decryptUtxoConstructorArgs = (encryptedData: Uint8Array, userKeys: UserKeys): IUtxoConstructor => {
+  // decrypting data into Uint8Array
+
+  const { publicKey, privateKey } = UserKeys.getEncryptionKeyPair(userKeys.getShieldedPrivateKey());
+
+  const bufferData = sodium.crypto_box_seal_open(
+    encryptedData,
+    ethers.utils.arrayify(publicKey),
+    ethers.utils.arrayify(privateKey),
+  );
+
+  // converting from Uint8Array into decimals
+  const decryptedData = Buffer.from(bufferData)
+    .toString('utf-8')
+    .split('0x')
+    .filter((e) => e.length !== 0)
+    .map((e, index) => {
+      let field;
+      if ([0, 2, 4, 5].includes(index))
+        field = BigInt(`0x${e}`); // amount, timestamp, tokenId
+      else if ([1, 3].includes(index)) field = `0x${e}`; // erc20TokenAddress and public key
+      return field;
+    });
+
+  return {
+    amount: decryptedData[0] as bigint,
+    erc20TokenAddress: decryptedData[1] as string,
+    randomization: decryptedData[2] as bigint,
+    stealthAddress: decryptedData[3] as string,
+    shieldedPrivateKey: userKeys.getShieldedPrivateKey(),
+    timeStamp: (decryptedData[4] as bigint).toString(),
+    tokenId: decryptedData[5] ? Number(decryptedData[5] as bigint) : 0, // tokenId
+  };
+};
+
+/**
+ * decrypt UTXO data from events
+ * @param encryptedData encrypted UTXO data {Uint8Array}
+ * @param publicKey/privateKey sender's encryption keys
+ * @returns decrypted UTXO data Object {amount, blinding}
+ */
+export const decryptUtxo = (encryptedData: Uint8Array, userKeys: UserKeys) =>
+  new Utxo(decryptUtxoConstructorArgs(encryptedData, userKeys));

package/src/data-structures/crypto-keys/index.ts

@@ -0,0 +1,4 @@
+export * from './decodeUTXO';
+export * from './encryptDecryptUtxo';
+export * from './keys';
+export * from './keyUtils';

package/src/data-structures/crypto-keys/keyUtils.ts

@@ -0,0 +1,8 @@
+import { CIRCOM_P, CIRCOM_P_HALF } from '../../constants/protocol.constants';
+
+export const isCircomNegative = (n: bigint) => {
+  if (n < 0n || n >= CIRCOM_P) throw new RangeError();
+  return n > CIRCOM_P_HALF;
+};
+
+export const getCircomSign = (n: bigint) => (isCircomNegative(n) ? 1n : 0n);

package/src/data-structures/crypto-keys/keys.ts

@@ -0,0 +1,203 @@
+import { ethers, utils } from 'ethers';
+import sodium from 'libsodium-wrappers'; // added * as for jest
+import { CIRCOM_P } from '../../constants/protocol.constants';
+import { babyJubInstance, JubPoint } from '../../crypto/babyJub';
+import { poseidonHash } from '../../crypto/poseidon';
+import { getCircomSign } from './keyUtils';
+import { AttachableMemoryCacheDevice } from '../cacheDevices/AttachableMemoryCacheDevice';
+import { keccak256, toUtf8Bytes } from 'ethers/lib/utils';
+import { ethers as ethersV6 } from 'ethers-v6h';
+import { networkRegistry } from '../../constants/chains.constants';
+
+export const stealthPairCacheDevice = new AttachableMemoryCacheDevice<{ H0: [bigint, bigint]; H1: [bigint, bigint] }>();
+export const stealthAddressCacheDevice = new AttachableMemoryCacheDevice<string>();
+
+export interface EncryptionKeyPair {
+  privateKey: string;
+  publicKey: string;
+}
+
+export const EncryptionKeyPairDefaultValue: EncryptionKeyPair = {
+  privateKey: '',
+  publicKey: '',
+};
+
+export class UserKeys {
+  private signature: string | undefined;
+
+  constructor(_signature?: string) {
+    this.signature = _signature;
+  }
+
+  public getSignature(): string {
+    this.requireSignature();
+    return this.signature!;
+  }
+
+  public setSignature(_signature: string) {
+    this.signature = _signature;
+  }
+
+  private requireSignature() {
+    if (!this.signature) throw Error('No signature provided');
+  }
+
+  public verifyMessage(signingMessage: string) {
+    this.requireSignature();
+    const signerAddress = utils.verifyMessage(signingMessage, this.signature!);
+    return signerAddress;
+  }
+
+  /**
+   * get shielded private key from message signature used to login to the application,
+   * this private key is used to generate encryption keypairs as well as public key
+   * @retuns 0x-prefixed shielded private key
+   */
+  public getShieldedPrivateKey = () => {
+    this.requireSignature();
+    return ethers.utils.keccak256(this.signature!);
+  };
+
+  /**
+   * generate shielded public key from private key
+   * @param privateKey the key used to generate the shielded public key, this should be the signature
+   * that the user provided
+   * @retuns shielded public key in hexstring with 0x prefixed
+   */
+  public getShieldedPublicKey = () => {
+    this.requireSignature();
+    return poseidonHash(this.getShieldedPrivateKey());
+  };
+
+  /**
+   * generate access token, this accessKey is what should be sent to the server for signing
+   * @returns accessKey in hexstring with 0x prefixed
+   */
+  public getAccessKey = () => {
+    this.requireSignature();
+    return poseidonHash(this.getShieldedPrivateKey(), this.getShieldedPublicKey());
+  };
+
+  public static getSignerAddressFromPrivateKey(privateKey: string): string {
+    const wallet = new ethersV6.Wallet(privateKey);
+    return wallet.address;
+  }
+
+  public static deriveSignerFromNonce(userKeys: UserKeys, walletNonce: bigint): ethersV6.Wallet {
+    const str = poseidonHash(walletNonce, userKeys.getShieldedPrivateKey(), userKeys.getShieldedPublicKey());
+    const hash = keccak256(toUtf8Bytes(str));
+    return new ethersV6.Wallet(hash);
+  }
+
+  public static async signMessageFromPrivateKey(privateKey: string, message: string): Promise<string> {
+    const wallet = new ethersV6.Wallet(privateKey);
+    const messageToSign = utils.isHexString(message) ? utils.arrayify(message) : message;
+    return wallet.signMessage(messageToSign);
+  }
+
+  public static signTypedDataFromPrivateKey(
+    privateKey: string,
+    domain: ethers.TypedDataDomain,
+    types: Record<string, Array<ethers.TypedDataField>>,
+    value: Record<string, any>,
+  ): Promise<string> {
+    const wallet = new ethersV6.Wallet(privateKey);
+    return wallet.signTypedData(domain as any, types, value);
+  }
+
+  public static async authorizeDelegationFromPrivateKey(
+    privateKey: string,
+    chainId: number,
+    implementation: string,
+    nonce?: number,
+  ) {
+    const wallet = new ethersV6.Wallet(privateKey);
+    const provider = new ethersV6.JsonRpcProvider(networkRegistry[chainId].fetchRpcUrl);
+    const connected = wallet.connect(provider);
+    return connected.authorize({
+      address: implementation,
+      ...(nonce !== undefined && { nonce }),
+    });
+  }
+
+  public getWalletSalt = (walletNonce: bigint) => {
+    this.requireSignature();
+    return poseidonHash(this.getShieldedPublicKey(), this.getShieldedPrivateKey(), walletNonce);
+  };
+
+  /**
+   * generate inHinkalAddress - a user unique address linking him with a specific app
+   * @returns inHinkalAddress in bigint
+   */
+  public getInHinkalAddress = (interactionAddress: string) => {
+    this.requireSignature();
+    const addressString = poseidonHash(this.getShieldedPrivateKey(), interactionAddress);
+    return BigInt(addressString);
+  };
+
+  /**
+   * generate backend token, which is used for access control on backend
+   * @returns accessKey in hexstring with 0x prefixed
+   */
+  public getBackendToken = () => {
+    this.requireSignature();
+    return poseidonHash(this.getAccessKey(), this.getShieldedPublicKey());
+  };
+
+  public static getRandomizedStealthPair = stealthPairCacheDevice.attach(
+    (s: bigint, privateKey: string): { H0: JubPoint; H1: JubPoint } => {
+      const babyJub = babyJubInstance();
+      const privateKeyAdjusted = BigInt(privateKey) % CIRCOM_P; // there should not be a difference between circom and client privKey
+
+      const multiplier = (s * privateKeyAdjusted) % CIRCOM_P;
+
+      const h0: [Uint8Array, Uint8Array] = babyJub.mulPointEscalar(babyJub.Base8, s);
+      const h1: [Uint8Array, Uint8Array] = babyJub.mulPointEscalar(babyJub.Base8, multiplier);
+
+      const H0: [bigint, bigint] = [BigInt(babyJub.F.toString(h0[0])), BigInt(babyJub.F.toString(h0[1]))];
+      const H1: [bigint, bigint] = [BigInt(babyJub.F.toString(h1[0])), BigInt(babyJub.F.toString(h1[1]))];
+      return { H0, H1 };
+    },
+  );
+
+  public static getStealthAddressCompressedPoints = (s: bigint, privateKey: string) => {
+    const { H0, H1 } = this.getRandomizedStealthPair(s, privateKey);
+    const [h0, h1] = [H0, H1].map((point) => BigInt(point[1]) + 2n ** 255n * getCircomSign(point[0]));
+    return { h0, h1 };
+  };
+
+  public static getStealthAddress = stealthAddressCacheDevice.attach((s: bigint, privateKey: string) => {
+    const { H0, H1 } = this.getRandomizedStealthPair(s, privateKey);
+    const signs = 2n * getCircomSign(H0[0]) + getCircomSign(H1[0]);
+    const arrayToHash = [signs, H0[1], H1[1]];
+    return poseidonHash(...arrayToHash);
+  });
+
+  public static getStealthAddressWithEKey = (s: bigint, privateKey: string) => {
+    const stealthAddress = this.getStealthAddress(s, privateKey);
+    return { stealthAddress, encryptionKey: this.getEncryptionKeyPair(privateKey).publicKey };
+  };
+
+  public static checkSignature = (
+    s: bigint,
+    stealthAddressH0: bigint,
+    stealthAddressH1: bigint,
+    privateKey: string,
+  ): boolean => {
+    const { h0, h1 } = this.getStealthAddressCompressedPoints(s, privateKey);
+    return stealthAddressH0 === h0 && stealthAddressH1 === h1;
+  };
+
+  /**
+   * generate private and public keypair
+   * @param seed seed to use to deterministically generate key, must be in DataHexString format
+   * and must correspond to 32 bytes
+   */
+  public static getEncryptionKeyPair = (privateKey: string): EncryptionKeyPair => {
+    const keyPair = sodium.crypto_box_seed_keypair(ethers.utils.arrayify(privateKey));
+    return {
+      privateKey: ethers.utils.hexlify(keyPair.privateKey),
+      publicKey: ethers.utils.hexlify(keyPair.publicKey),
+    };
+  };
+}

package/src/data-structures/custom-token-registry/CustomTokenRegistry.ts

@@ -0,0 +1,49 @@
+import { ERC20Token } from '../../types';
+
+// TODO: the contents of this class are used in hooks
+// this should be written as a store.
+class CustomTokenRegistry {
+  tokenRegistry: ERC20Token[];
+
+  constructor() {
+    this.tokenRegistry = [];
+  }
+
+  public setTokensFromCache(newTokenRegistries: ERC20Token[]) {
+    this.tokenRegistry = newTokenRegistries;
+  }
+
+  public getCustomTokens(chainId: number): ERC20Token[] {
+    return this.tokenRegistry.filter((token) => token.chainId === chainId);
+  }
+
+  public tokenExists(registry: ERC20Token[], tokenToCheck: ERC20Token) {
+    return registry.find(
+      (token) =>
+        token.erc20TokenAddress === tokenToCheck.erc20TokenAddress ||
+        token.symbol === tokenToCheck.symbol ||
+        token.name === tokenToCheck.name,
+    );
+  }
+
+  public addCustomToken(token: ERC20Token) {
+    const { chainId } = token;
+
+    const currRegistry = this.getCustomTokens(chainId);
+
+    if (!this.tokenExists(currRegistry, token)) {
+      this.tokenRegistry.push(token);
+    }
+  }
+
+  public removeCustomToken(tokenToRemove: ERC20Token) {
+    const { chainId } = tokenToRemove;
+
+    const currRegistry = this.getCustomTokens(chainId);
+
+    const newRegistry = currRegistry.filter((token) => token.erc20TokenAddress !== tokenToRemove.erc20TokenAddress);
+    this.tokenRegistry = newRegistry;
+  }
+}
+
+export const customTokenRegistry = new CustomTokenRegistry();

package/src/data-structures/event-service/AbstractAccessTokenSnapshotService.ts

@@ -0,0 +1,142 @@
+import { zeroAddress } from '../../constants/protocol.constants';
+import { poseidonFunction } from '../../crypto';
+import { toBigInt } from '../../functions/utils/amounts.utils';
+import { MerkleTree, MerkleTreeJson } from '../merkle-tree';
+import { AccessTokenEvent } from '../../types';
+import { AbstractSnapshotService, Snapshot } from './AbstractSnapshotService';
+import { contructMerkleTreeFromSerialized } from '../../functions/utils/merkleTree.utils';
+import { BlockchainEventEmitter } from './BlockchainEventEmitter';
+
+export type SenderAddressIndexMapJson = {
+  address: string;
+  index: number;
+}[];
+
+export type AccessTokenSnapshotPayload = {
+  readonly merkleTree: MerkleTree<bigint>;
+  readonly senderAddresses: string[];
+  readonly senderAddressIndexMap: Map<string, number>;
+};
+
+export type AccessTokenSerializedSnapshot = {
+  latestBlockNumber?: number;
+  merkleTree?: MerkleTreeJson;
+  senderAddresses?: string[];
+  senderAddressIndexMap?: SenderAddressIndexMapJson;
+};
+
+export abstract class AbstractAccessTokenSnapshotService extends AbstractSnapshotService<
+  AccessTokenEvent<bigint>,
+  AccessTokenEvent,
+  AccessTokenSnapshotPayload,
+  AccessTokenSerializedSnapshot
+> {
+  constructor(accessTokenEventFetcher: BlockchainEventEmitter) {
+    super(accessTokenEventFetcher, 'NewAccessKeyAdded');
+  }
+
+  private _merkleTree!: MerkleTree<bigint>;
+
+  private _senderAddresses!: string[];
+
+  private _senderAddressIndexMap!: Map<string, number>;
+
+  get merkleTree() {
+    return this._merkleTree;
+  }
+
+  get senderAddresses() {
+    return this._senderAddresses;
+  }
+
+  get senderAddressIndexMap() {
+    return this._senderAddressIndexMap;
+  }
+
+  protected override serializeSnapshot(snapshot: Snapshot<AccessTokenSnapshotPayload>): AccessTokenSerializedSnapshot {
+    return {
+      merkleTree: snapshot.payload.merkleTree.toJSON(),
+      senderAddresses: Array.from(snapshot.payload.senderAddresses),
+      latestBlockNumber: snapshot.latestBlockNumber,
+      senderAddressIndexMap: Array.from(snapshot.payload.senderAddressIndexMap).map(([address, index]) => ({
+        address,
+        index,
+      })),
+    };
+  }
+
+  protected override deserializeSnapshot(
+    serializedSnapshot: AccessTokenSerializedSnapshot,
+  ): Snapshot<AccessTokenSnapshotPayload> {
+    let merkleTree: MerkleTree<bigint>;
+    let senderAddressIndexMap: Map<string, number>;
+    if (serializedSnapshot.latestBlockNumber && serializedSnapshot.merkleTree) {
+      merkleTree = contructMerkleTreeFromSerialized(serializedSnapshot.merkleTree);
+    } else {
+      merkleTree = MerkleTree.create(poseidonFunction, 0n);
+    }
+
+    if (serializedSnapshot.latestBlockNumber && serializedSnapshot.senderAddressIndexMap) {
+      senderAddressIndexMap = new Map<string, number>(
+        serializedSnapshot.senderAddressIndexMap.map(({ address, index }): [string, number] => [address, index]),
+      );
+    } else {
+      senderAddressIndexMap = new Map<string, number>();
+    }
+
+    return {
+      latestBlockNumber: serializedSnapshot.latestBlockNumber ?? 0,
+      payload: {
+        merkleTree,
+        senderAddresses: serializedSnapshot.senderAddresses ?? [],
+        senderAddressIndexMap,
+      },
+    };
+  }
+
+  protected acceptEvent(event: AccessTokenEvent<bigint>, _blockNumber: number): boolean {
+    try {
+      // merkleTree.insert won't override if it is already inserted.
+      this._merkleTree.insert(event.accessKey, event.index);
+      this._senderAddressIndexMap.set(
+        event.senderAddress,
+        Math.max(Number(event.index), this._senderAddressIndexMap.get(event.senderAddress) ?? 0),
+      );
+      if (!this._senderAddresses.includes(event.senderAddress)) {
+        this._senderAddresses.push(event.senderAddress);
+      }
+      if (event.accessKey === 0n && event.senderAddress === zeroAddress) {
+        this._merkleTree.remove(event.index);
+      }
+      return true;
+    } catch (err) {
+      console.error(err);
+      return false;
+    }
+  }
+
+  protected override mapEvent(event: AccessTokenEvent): AccessTokenEvent<bigint> {
+    const { accessKey, index, senderAddress } = event;
+    return {
+      accessKey: toBigInt(accessKey),
+      index: toBigInt(index),
+      senderAddress,
+    };
+  }
+
+  protected override getSnapshotPayload(): AccessTokenSnapshotPayload {
+    return {
+      merkleTree: this._merkleTree,
+      senderAddresses: this._senderAddresses,
+      senderAddressIndexMap: this._senderAddressIndexMap,
+    };
+  }
+
+  protected override populateSnapshot({
+    payload: { merkleTree, senderAddresses, senderAddressIndexMap },
+  }: Snapshot<AccessTokenSnapshotPayload>) {
+    this._merkleTree = merkleTree;
+    this._senderAddresses = senderAddresses;
+    this._senderAddressIndexMap = senderAddressIndexMap;
+  }
+}