nova-privacy-sdk 1.0.0

package/src/utils/merkle_tree.ts

@@ -0,0 +1,207 @@
+import * as hasher from '@lightprotocol/hasher.rs';
+export const DEFAULT_ZERO = 0;
+
+/**
+ * @callback hashFunction
+ * @param left Left leaf
+ * @param right Right leaf
+ */
+/**
+ * Merkle tree
+ */
+export class MerkleTree {
+  /**
+   * Constructor
+   * @param {number} levels Number of levels in the tree
+   * @param {Array} [elements] Initial elements
+   * @param {Object} options
+   * @param {hashFunction} [options.hashFunction] Function used to hash 2 leaves
+   * @param [options.zeroElement] Value for non-existent leaves
+   */
+  levels: number;
+  capacity: number;
+  zeroElement;
+  _zeros: string[];
+  _layers: string[][];
+  _lightWasm: hasher.LightWasm;
+
+  constructor(
+    levels: number,
+    lightWasm: hasher.LightWasm,
+    elements: string[] = [],
+    { zeroElement = DEFAULT_ZERO } = {},
+  ) {
+    this.levels = levels;
+    this.capacity = 2 ** levels;
+    this.zeroElement = zeroElement.toString();
+    this._lightWasm = lightWasm;
+    if (elements.length > this.capacity) {
+      throw new Error("Tree is full");
+    }
+    this._zeros = [];
+    this._layers = [];
+    this._layers[0] = elements;
+    this._zeros[0] = this.zeroElement;
+
+    for (let i = 1; i <= levels; i++) {
+      this._zeros[i] = this._lightWasm.poseidonHashString([
+        this._zeros[i - 1],
+        this._zeros[i - 1],
+      ]);
+    }
+    this._rebuild();
+  }
+
+  _rebuild() {
+    for (let level = 1; level <= this.levels; level++) {
+      this._layers[level] = [];
+      for (let i = 0; i < Math.ceil(this._layers[level - 1].length / 2); i++) {
+        this._layers[level][i] = this._lightWasm.poseidonHashString([
+          this._layers[level - 1][i * 2],
+          i * 2 + 1 < this._layers[level - 1].length
+            ? this._layers[level - 1][i * 2 + 1]
+            : this._zeros[level - 1],
+        ]);
+      }
+    }
+  }
+
+  /**
+   * Get tree root
+   * @returns {*}
+   */
+  root() {
+    return this._layers[this.levels].length > 0
+      ? this._layers[this.levels][0]
+      : this._zeros[this.levels];
+  }
+
+  /**
+   * Insert new element into the tree
+   * @param element Element to insert
+   */
+
+  insert(element: string) {
+    if (this._layers[0].length >= this.capacity) {
+      throw new Error("Tree is full");
+    }
+    this.update(this._layers[0].length, element);
+  }
+
+  /**
+   * Insert multiple elements into the tree. Tree will be fully rebuilt during this operation.
+   * @param {Array} elements Elements to insert
+   */
+  bulkInsert(elements: string[]) {
+    if (this._layers[0].length + elements.length > this.capacity) {
+      throw new Error("Tree is full");
+    }
+    this._layers[0].push(...elements);
+    this._rebuild();
+  }
+
+  // TODO: update does not work debug
+  /**
+   * Change an element in the tree
+   * @param {number} index Index of element to change
+   * @param element Updated element value
+   */
+  update(index: number, element: string) {
+    // index 0 and 1 and element is the commitment hash
+    if (
+      isNaN(Number(index)) ||
+      index < 0 ||
+      index > this._layers[0].length ||
+      index >= this.capacity
+    ) {
+      throw new Error("Insert index out of bounds: " + index);
+    }
+    this._layers[0][index] = element;
+    for (let level = 1; level <= this.levels; level++) {
+      index >>= 1;
+      this._layers[level][index] = this._lightWasm.poseidonHashString([
+        this._layers[level - 1][index * 2],
+        index * 2 + 1 < this._layers[level - 1].length
+          ? this._layers[level - 1][index * 2 + 1]
+          : this._zeros[level - 1],
+      ]);
+    }
+  }
+
+  /**
+   * Get merkle path to a leaf
+   * @param {number} index Leaf index to generate path for
+   * @returns {{pathElements: number[], pathIndex: number[]}} An object containing adjacent elements and left-right index
+   */
+  path(index: number) {
+    if (isNaN(Number(index)) || index < 0 || index >= this._layers[0].length) {
+      throw new Error("Index out of bounds: " + index);
+    }
+    const pathElements: string[] = [];
+    const pathIndices: number[] = [];
+    for (let level = 0; level < this.levels; level++) {
+      pathIndices[level] = index % 2;
+      pathElements[level] =
+        (index ^ 1) < this._layers[level].length
+          ? this._layers[level][index ^ 1]
+          : this._zeros[level];
+      index >>= 1;
+    }
+    return {
+      pathElements,
+      pathIndices,
+    };
+  }
+
+  /**
+   * Find an element in the tree
+   * @param element An element to find
+   * @param comparator A function that checks leaf value equality
+   * @returns {number} Index if element is found, otherwise -1
+   */
+  indexOf(element: string, comparator: Function | null = null) {
+    if (comparator) {
+      return this._layers[0].findIndex((el: string) => comparator(element, el));
+    } else {
+      return this._layers[0].indexOf(element);
+    }
+  }
+
+  /**
+   * Returns a copy of non-zero tree elements
+   * @returns {Object[]}
+   */
+  elements() {
+    return this._layers[0].slice();
+  }
+
+  /**
+   * Serialize entire tree state including intermediate layers into a plain object
+   * Deserializing it back will not require to recompute any hashes
+   * Elements are not converted to a plain type, this is responsibility of the caller
+   */
+  serialize() {
+    return {
+      levels: this.levels,
+      _zeros: this._zeros,
+      _layers: this._layers,
+    };
+  }
+
+  /**
+   * Deserialize data into a MerkleTree instance
+   * Make sure to provide the same hashFunction as was used in the source tree,
+   * otherwise the tree state will be invalid
+   *
+   * @param data
+   * @param hashFunction
+   * @returns {MerkleTree}
+   */
+  static deserialize(data: any, hashFunction: Function) {
+    const instance = Object.assign(Object.create(this.prototype), data);
+    instance._hash = hashFunction;
+    instance.capacity = 2 ** instance.levels;
+    instance.zeroElement = instance._zeros[0];
+    return instance;
+  }
+}

package/src/utils/node-shim.ts

@@ -0,0 +1,6 @@
+import { LocalStorage } from "node-localstorage";
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+
+export { LocalStorage, path, fs, fileURLToPath };

package/src/utils/prover.ts

@@ -0,0 +1,222 @@
+/**
+ * ZK Proof Generation Utilities
+ * 
+ * This file provides functions for generating zero-knowledge proofs for privacy-preserving 
+ * transactions on Solana. It handles both snarkjs and zkutil proof generation workflows.
+ * 
+ * Inspired by: https://github.com/tornadocash/tornado-nova/blob/f9264eeffe48bf5e04e19d8086ee6ec58cdf0d9e/src/prover.js
+ */
+
+/// <reference types="node" />
+
+import * as anchor from "@coral-xyz/anchor";
+import { wtns, groth16 } from 'snarkjs'
+import { FIELD_SIZE } from './constants.js'
+
+// @ts-ignore - ignore TypeScript errors for ffjavascript
+import { utils } from 'ffjavascript'
+
+// Type definitions for external modules
+type WtnsModule = {
+  debug: (input: any, wasmFile: string, wtnsFile: string, symFile: string, options: any, logger: any) => Promise<void>
+  exportJson: (wtnsFile: string) => Promise<any>
+}
+
+type Groth16Module = {
+  fullProve: (
+    input: any,
+    wasmFile: string,
+    zkeyFile: string,
+    logger?: any,
+    wtnsCalcOptions?: { singleThread?: boolean },
+    proverOptions?: { singleThread?: boolean }
+  ) => Promise<{ proof: Proof; publicSignals: string[] }>
+  verify: (vkeyData: any, publicSignals: any, proof: Proof) => Promise<boolean>
+}
+
+type UtilsModule = {
+  stringifyBigInts: (obj: any) => any
+  unstringifyBigInts: (obj: any) => any
+}
+
+// Cast imported modules to their types
+const wtnsTyped = wtns as unknown as WtnsModule
+const groth16Typed = groth16 as unknown as Groth16Module
+const utilsTyped = utils as unknown as UtilsModule
+
+
+// Define interfaces for the proof structures
+interface Proof {
+  pi_a: string[];
+  pi_b: string[][];
+  pi_c: string[];
+  protocol: string;
+  curve: string;
+}
+
+interface ProofResult {
+  proof: Proof
+}
+
+/**
+ * Generates a ZK proof using snarkjs and formats it for use on-chain
+ *
+ * @param input The circuit inputs to generate a proof for
+ * @param keyBasePath The base path for the circuit keys (.wasm and .zkey files)
+ * @param options Optional proof generation options (e.g., singleThread for Deno/Bun)
+ * @returns A proof object with formatted proof elements and public signals
+ */
+async function prove(input: any, keyBasePath: string, options?: { singleThread?: boolean }): Promise<{
+  proof: Proof
+  publicSignals: string[];
+}> {
+  // Detect if we should use single-threaded mode (for Deno/Bun compatibility)
+  const useSingleThread = options?.singleThread ?? shouldUseSingleThread();
+
+  // Single-thread options need to be passed to BOTH witness calculation AND proving
+  const singleThreadOpts = useSingleThread ? { singleThread: true } : undefined;
+
+  // Call fullProve with all parameters:
+  // 1. input, 2. wasmFile, 3. zkeyFile, 4. logger, 5. wtnsCalcOptions, 6. proverOptions
+  return await groth16Typed.fullProve(
+    utilsTyped.stringifyBigInts(input),
+    `${keyBasePath}.wasm`,
+    `${keyBasePath}.zkey`,
+    undefined, // logger parameter
+    singleThreadOpts, // wtnsCalcOptions (5th param) - for witness calculation
+    singleThreadOpts  // proverOptions (6th param) - for proving
+  )
+}
+
+/**
+ * Detect if single-threaded mode should be used
+ */
+function shouldUseSingleThread(): boolean {
+  // @ts-ignore - Deno global
+  if (typeof Deno !== 'undefined') {
+    return true; // Deno has worker issues
+  }
+  // @ts-ignore - Bun global
+  if (typeof Bun !== 'undefined') {
+    return true; // Bun may have worker issues
+  }
+  return false;
+}
+
+export function parseProofToBytesArray(
+  proof: Proof,
+  compressed: boolean = false,
+): {
+  proofA: number[];
+  proofB: number[][];
+  proofC: number[];
+} {
+  const proofJson = JSON.stringify(proof, null, 1);
+  const mydata = JSON.parse(proofJson.toString());
+  try {
+    for (const i in mydata) {
+      if (i == "pi_a" || i == "pi_c") {
+        for (const j in mydata[i]) {
+          mydata[i][j] = Array.from(
+            utils.leInt2Buff(utils.unstringifyBigInts(mydata[i][j]), 32),
+          ).reverse();
+        }
+      } else if (i == "pi_b") {
+        for (const j in mydata[i]) {
+          for (const z in mydata[i][j]) {
+            mydata[i][j][z] = Array.from(
+              utils.leInt2Buff(utils.unstringifyBigInts(mydata[i][j][z]), 32),
+            );
+          }
+        }
+      }
+    }
+
+    if (compressed) {
+      const proofA = mydata.pi_a[0];
+      // negate proof by reversing the bitmask
+      const proofAIsPositive = yElementIsPositiveG1(
+        new anchor.BN(mydata.pi_a[1]),
+      )
+        ? false
+        : true;
+      proofA[0] = addBitmaskToByte(proofA[0], proofAIsPositive);
+      const proofB = mydata.pi_b[0].flat().reverse();
+      const proofBY = mydata.pi_b[1].flat().reverse();
+      const proofBIsPositive = yElementIsPositiveG2(
+        new anchor.BN(proofBY.slice(0, 32)),
+        new anchor.BN(proofBY.slice(32, 64)),
+      );
+      proofB[0] = addBitmaskToByte(proofB[0], proofBIsPositive);
+      const proofC = mydata.pi_c[0];
+      const proofCIsPositive = yElementIsPositiveG1(
+        new anchor.BN(mydata.pi_c[1]),
+      );
+      proofC[0] = addBitmaskToByte(proofC[0], proofCIsPositive);
+      return {
+        proofA,
+        proofB,
+        proofC,
+      };
+    }
+    return {
+      proofA: [mydata.pi_a[0], mydata.pi_a[1]].flat(),
+      proofB: [
+        mydata.pi_b[0].flat().reverse(),
+        mydata.pi_b[1].flat().reverse(),
+      ].flat(),
+      proofC: [mydata.pi_c[0], mydata.pi_c[1]].flat(),
+    };
+  } catch (error: any) {
+    console.error("Error while parsing the proof.", error.message);
+    throw error;
+  }
+}
+
+// mainly used to parse the public signals of groth16 fullProve
+export function parseToBytesArray(publicSignals: string[]): number[][] {
+  const publicInputsJson = JSON.stringify(publicSignals, null, 1);
+  const publicInputsBytesJson = JSON.parse(publicInputsJson.toString());
+  try {
+    const publicInputsBytes = new Array<Array<number>>();
+    for (const i in publicInputsBytesJson) {
+      const ref: Array<number> = Array.from([
+        ...utils.leInt2Buff(utils.unstringifyBigInts(publicInputsBytesJson[i]), 32),
+      ]).reverse();
+      publicInputsBytes.push(ref);
+    }
+
+    return publicInputsBytes;
+  } catch (error: any) {
+    console.error("Error while parsing public inputs.", error.message);
+    throw error;
+  }
+}
+
+function yElementIsPositiveG1(yElement: anchor.BN): boolean {
+  return yElement.lte(FIELD_SIZE.sub(yElement));
+}
+
+function yElementIsPositiveG2(yElement1: anchor.BN, yElement2: anchor.BN): boolean {
+  const fieldMidpoint = FIELD_SIZE.div(new anchor.BN(2));
+
+  // Compare the first component of the y coordinate
+  if (yElement1.lt(fieldMidpoint)) {
+    return true;
+  } else if (yElement1.gt(fieldMidpoint)) {
+    return false;
+  }
+
+  // If the first component is equal to the midpoint, compare the second component
+  return yElement2.lt(fieldMidpoint);
+}
+
+function addBitmaskToByte(byte: number, yIsPositive: boolean): number {
+  if (!yIsPositive) {
+    return (byte |= 1 << 7);
+  } else {
+    return byte;
+  }
+}
+
+export { prove, type Proof }

package/src/utils/utils.ts

@@ -0,0 +1,242 @@
+/**
+ * Utility functions for ZK Cash
+ * 
+ * Provides common utility functions for the ZK Cash system
+ * Based on: https://github.com/tornadocash/tornado-nova
+ */
+
+import BN from 'bn.js';
+import { Utxo } from '../models/utxo.js';
+import * as borsh from 'borsh';
+import { sha256 } from '@ethersproject/sha2';
+import { PublicKey } from '@solana/web3.js';
+import { RELAYER_API_URL, PROGRAM_ID, SOL_TREE_ADDRESS, NOVA_MINT, NOVA_TREE_ADDRESS, NOVASOL_TREE_ADDRESS } from './constants.js';
+import { logger } from './logger.js';
+import { getConfig } from '../config.js';
+
+/**
+ * Calculate deposit fee based on deposit amount and fee rate
+ * @param depositAmount Amount being deposited in lamports
+ * @returns Fee amount in lamports
+ */
+export async function calculateDepositFee(depositAmount: number) {
+  return Math.floor(depositAmount * (await getConfig('deposit_fee_rate')) / 10000);
+}
+
+/**
+ * Calculate withdrawal fee based on withdrawal amount and fee rate
+ * @param withdrawalAmount Amount being withdrawn in lamports
+ * @returns Fee amount in lamports
+ */
+export async function calculateWithdrawalFee(withdrawalAmount: number) {
+  return Math.floor(withdrawalAmount * (await getConfig('withdraw_fee_rate')) / 10000);
+}
+
+/**
+ * Mock encryption function - in real implementation this would be proper encryption
+ * For testing, we just return a fixed prefix to ensure consistent extDataHash
+ * @param value Value to encrypt
+ * @returns Encrypted string representation
+ */
+export function mockEncrypt(value: Utxo): string {
+  return JSON.stringify(value);
+}
+
+/**
+ * Calculates the hash of ext data using Borsh serialization
+ * @param extData External data object containing recipient, amount, encrypted outputs, fee, fee recipient, and mint address
+ * @returns The hash as a Uint8Array (32 bytes)
+ */
+export function getExtDataHash(extData: {
+  recipient: string | PublicKey;
+  extAmount: string | number | BN;
+  encryptedOutput1?: string | Uint8Array;  // Optional for Account Data Separation
+  encryptedOutput2?: string | Uint8Array;  // Optional for Account Data Separation
+  fee: string | number | BN;
+  feeRecipient: string | PublicKey;
+  mintAddress: string | PublicKey;
+}): Uint8Array {
+  // Convert all inputs to their appropriate types
+  const recipient = extData.recipient instanceof PublicKey
+    ? extData.recipient
+    : new PublicKey(extData.recipient);
+
+  const feeRecipient = extData.feeRecipient instanceof PublicKey
+    ? extData.feeRecipient
+    : new PublicKey(extData.feeRecipient);
+
+  const mintAddress = extData.mintAddress instanceof PublicKey
+    ? extData.mintAddress
+    : new PublicKey(extData.mintAddress);
+
+  // Convert to BN for proper i64/u64 handling
+  const extAmount = new BN(extData.extAmount.toString());
+  const fee = new BN(extData.fee.toString());
+
+  // Handle encrypted outputs - they might not be present in Account Data Separation approach
+  const encryptedOutput1 = extData.encryptedOutput1
+    ? Buffer.from(extData.encryptedOutput1 as any)
+    : Buffer.alloc(0); // Empty buffer if not provided
+  const encryptedOutput2 = extData.encryptedOutput2
+    ? Buffer.from(extData.encryptedOutput2 as any)
+    : Buffer.alloc(0); // Empty buffer if not provided
+
+  // Define the borsh schema matching the Rust struct
+  const schema = {
+    struct: {
+      recipient: { array: { type: 'u8', len: 32 } },
+      extAmount: 'i64',
+      encryptedOutput1: { array: { type: 'u8' } },
+      encryptedOutput2: { array: { type: 'u8' } },
+      fee: 'u64',
+      feeRecipient: { array: { type: 'u8', len: 32 } },
+      mintAddress: { array: { type: 'u8', len: 32 } },
+    }
+  };
+
+  const value = {
+    recipient: recipient.toBytes(),
+    extAmount: extAmount,  // BN instance - Borsh handles it correctly with i64 type
+    encryptedOutput1: encryptedOutput1,
+    encryptedOutput2: encryptedOutput2,
+    fee: fee,  // BN instance - Borsh handles it correctly with u64 type
+    feeRecipient: feeRecipient.toBytes(),
+    mintAddress: mintAddress.toBytes(),
+  };
+
+  // Serialize with Borsh
+  const serializedData = borsh.serialize(schema, value);
+
+  // Calculate the SHA-256 hash
+  const hashHex = sha256(serializedData);
+  // Convert from hex string to Uint8Array
+  return Buffer.from(hashHex.slice(2), 'hex');
+}
+
+
+// Function to fetch Merkle proof from API for a given commitment
+export async function fetchMerkleProof(commitment: string, tokenName?: string): Promise<{ pathElements: string[], pathIndices: number[] }> {
+  try {
+    logger.debug(`Fetching Merkle proof for commitment: ${commitment}`);
+    let url = `${RELAYER_API_URL}/merkle/proof/${commitment}`
+    if (tokenName) {
+      url += '?token=' + tokenName
+    }
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch Merkle proof: ${url}`);
+    }
+    const data = await response.json() as { pathElements: string[], pathIndices: number[] };
+    logger.debug(`✓ Fetched Merkle proof with ${data.pathElements.length} elements`);
+    return data;
+  } catch (error) {
+    console.error(`Failed to fetch Merkle proof for commitment ${commitment}:`, error);
+    throw error;
+  }
+}
+
+// Find nullifier PDAs for the given proof
+export function findNullifierPDAs(proof: any) {
+  const [nullifier0PDA] = PublicKey.findProgramAddressSync(
+    [Buffer.from("nullifier0"), Buffer.from(proof.inputNullifiers[0])],
+    PROGRAM_ID
+  );
+
+  const [nullifier1PDA] = PublicKey.findProgramAddressSync(
+    [Buffer.from("nullifier1"), Buffer.from(proof.inputNullifiers[1])],
+    PROGRAM_ID
+  );
+
+  return { nullifier0PDA, nullifier1PDA };
+}
+
+// Function to query remote tree state from indexer API
+export async function queryRemoteTreeState(tokenName?: string): Promise<{ root: string, nextIndex: number }> {
+  try {
+    logger.debug('Fetching Merkle root and nextIndex from API...');
+    let url = `${RELAYER_API_URL}/merkle/root`
+    if (tokenName) {
+      url += '?token=' + tokenName
+    }
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch Merkle root and nextIndex: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json() as { root: string, nextIndex: number };
+    logger.debug(`Fetched root from API: ${data.root}`);
+    logger.debug(`Fetched nextIndex from API: ${data.nextIndex}`);
+    return data;
+  } catch (error) {
+    console.error('Failed to fetch root and nextIndex from API:', error);
+    throw error;
+  }
+}
+
+export function getProgramAccounts() {
+  // Use NOVASOL tree address for SOL transactions (NOVA's SOL tree)
+  const treeAccount = NOVASOL_TREE_ADDRESS
+
+  const [treeTokenAccount] = PublicKey.findProgramAddressSync(
+    [Buffer.from('tree_token')],
+    PROGRAM_ID
+  );
+
+  const [globalConfigAccount] = PublicKey.findProgramAddressSync(
+    [Buffer.from('global_config')],
+    PROGRAM_ID
+  );
+  return { treeAccount, treeTokenAccount, globalConfigAccount }
+}
+
+/**
+ * Get tree account address for a given token/mint
+ * Uses specific addresses for SOL (NOVASOL), NOVA, and other tokens
+ */
+export function getTreeAccountForToken(mintAddress?: PublicKey): PublicKey {
+  if (!mintAddress) {
+    // SOL tree - use NOVASOL tree address
+    return NOVASOL_TREE_ADDRESS
+  }
+  
+  // Check if it's NOVA token and use specific tree address
+  if (mintAddress.equals(NOVA_MINT)) {
+    return NOVA_TREE_ADDRESS
+  }
+  
+  // For other SPL tokens, derive PDA with mint address
+  const [treeAccount] = PublicKey.findProgramAddressSync(
+    [Buffer.from('merkle_tree'), mintAddress.toBuffer()],
+    PROGRAM_ID
+  )
+  return treeAccount
+}
+
+
+export function findCrossCheckNullifierPDAs(proof: any) {
+  const [nullifier2PDA] = PublicKey.findProgramAddressSync(
+    [Buffer.from("nullifier0"), Buffer.from(proof.inputNullifiers[1])],
+    PROGRAM_ID
+  );
+
+  const [nullifier3PDA] = PublicKey.findProgramAddressSync(
+    [Buffer.from("nullifier1"), Buffer.from(proof.inputNullifiers[0])],
+    PROGRAM_ID
+  );
+
+  return { nullifier2PDA, nullifier3PDA };
+}
+
+export function getMintAddressField(mint: PublicKey): string {
+  const mintStr = mint.toString();
+
+  // Special case for SOL (system program)
+  if (mintStr === '11111111111111111111111111111112') {
+    return mintStr;
+  }
+
+  // For SPL tokens (USDC, USDT, etc): use first 31 bytes (248 bits)
+  // This provides better collision resistance than 8 bytes while still fitting in the field
+  // We will only suppport private SOL, USDC and USDT send, so there won't be any collision.
+  const mintBytes = mint.toBytes();
+  return new BN(mintBytes.slice(0, 31), 'be').toString();
+}