@0xbow/privacy-pools-core-sdk 0.0.0-83f8c2

package/src/core/data.service.ts

@@ -0,0 +1,492 @@
+import {
+  type PublicClient,
+  type Hex,
+  createPublicClient,
+  http,
+  parseAbiItem,
+} from "viem";
+import { mapLimit } from "async";
+import {
+  ChainConfig,
+  DepositEvent,
+  WithdrawalEvent,
+  RagequitEvent,
+} from "../types/events.js";
+import { PoolInfo } from "../types/account.js";
+import { Hash } from "../types/commitment.js";
+import {
+  LogFetchConfig,
+  DEFAULT_LOG_FETCH_CONFIG,
+  BlockRange,
+} from "../types/rateLimit.js";
+import { Logger } from "../utils/logger.js";
+import { DataError } from "../errors/data.error.js";
+import { ErrorCode } from "../errors/base.error.js";
+
+// Event signatures from the contract
+const DEPOSIT_EVENT = parseAbiItem('event Deposited(address indexed _depositor, uint256 _commitment, uint256 _label, uint256 _value, uint256 _merkleRoot)');
+const WITHDRAWAL_EVENT = parseAbiItem('event Withdrawn(address indexed _processooor, uint256 _value, uint256 _spentNullifier, uint256 _newCommitment)');
+const RAGEQUIT_EVENT = parseAbiItem('event Ragequit(address indexed _ragequitter, uint256 _commitment, uint256 _label, uint256 _value)');
+
+/**
+ * Service responsible for fetching and managing privacy pool events across multiple chains.
+ * Handles event retrieval, parsing, and validation for deposits, withdrawals, and ragequits.
+ * 
+ * @remarks
+ * This service uses viem's PublicClient to efficiently fetch and process blockchain events.
+ * It supports multiple chains and provides robust error handling and validation.
+ * All uint256 values from events are handled as bigints, with Hash type assertions for commitment-related fields.
+ */
+export class DataService {
+  private readonly clients: Map<number, PublicClient> = new Map();
+  private readonly logger: Logger;
+  private readonly logFetchConfig: LogFetchConfig;
+
+  /**
+   * Initialize the data service with chain configurations
+   *
+   * @param chainConfigs - Array of chain configurations containing chainId, RPC URL, and API key
+   * @param logFetchConfig - Optional configuration for rate-limited log fetching
+   * @throws {DataError} If client initialization fails for any chain
+   */
+  constructor(
+    private readonly chainConfigs: ChainConfig[],
+    logFetchConfig: Partial<LogFetchConfig> = {}
+  ) {
+    this.logger = new Logger({ prefix: "Data" });
+    this.logFetchConfig = { ...DEFAULT_LOG_FETCH_CONFIG, ...logFetchConfig };
+
+    try {
+      for (const config of chainConfigs) {
+        if (!config.rpcUrl) {
+          throw new Error(`Missing RPC URL for chain ${config.chainId}`);
+        }
+
+        const client = createPublicClient({
+          transport: http(config.rpcUrl),
+        });
+        this.clients.set(config.chainId, client);
+      }
+    } catch (error) {
+      throw new DataError(
+        "Failed to initialize PublicClient",
+        ErrorCode.NETWORK_ERROR,
+        { error: error instanceof Error ? error.message : "Unknown error" },
+      );
+    }
+  }
+
+  /**
+   * Get deposit events for a specific chain
+   *
+   * @param pool - Pool info containing chainId, address, and deployment block
+   * @returns Array of deposit events with properly typed fields (bigint for numbers, Hash for commitments)
+   * @throws {DataError} If client is not configured, network error occurs, or event data is invalid
+   */
+  async getDeposits(pool: PoolInfo): Promise<DepositEvent[]> {
+    try {
+      const client = this.getClientForChain(pool.chainId);
+      const config = this.getConfigForChain(pool.chainId);
+
+      const fromBlock = pool.deploymentBlock ?? config.startBlock;
+      const toBlock = await this.getCurrentBlock(pool.chainId);
+      const ranges = this.generateBlockRanges(
+        fromBlock,
+        toBlock,
+        this.logFetchConfig.blockChunkSize
+      );
+
+      this.logger.debug(
+        `Fetching deposits in ${ranges.length} chunks for pool ${pool.address}`
+      );
+
+      // Use async.mapLimit for controlled concurrency
+      const allLogs = await mapLimit<BlockRange, unknown[]>(
+        ranges,
+        this.logFetchConfig.concurrency,
+        async (range: BlockRange) => {
+          if (this.logFetchConfig.chunkDelayMs > 0) {
+            await this.sleep(this.logFetchConfig.chunkDelayMs);
+          }
+          return this.fetchLogsWithRetry(
+            client,
+            pool.address,
+            DEPOSIT_EVENT,
+            range
+          );
+        }
+      );
+
+      // Flatten and parse results
+      const flatLogs = allLogs.flat();
+
+      return flatLogs.map((log: unknown) => {
+        try {
+          const typedLog = log as {
+            args?: {
+              _depositor?: string;
+              _commitment?: bigint;
+              _label?: bigint;
+              _value?: bigint;
+              _merkleRoot?: bigint;
+            };
+            blockNumber?: bigint;
+            transactionHash?: Hex;
+          };
+
+          if (!typedLog.args) {
+            throw DataError.invalidLog("deposit", "missing args");
+          }
+
+          const {
+            _depositor: depositor,
+            _commitment: commitment,
+            _label: label,
+            _value: value,
+            _merkleRoot: precommitment,
+          } = typedLog.args;
+
+          if (
+            !depositor ||
+            !commitment ||
+            !label ||
+            !precommitment ||
+            !typedLog.blockNumber ||
+            !typedLog.transactionHash
+          ) {
+            throw DataError.invalidLog("deposit", "missing required fields");
+          }
+
+          return {
+            depositor: depositor.toLowerCase(),
+            commitment: commitment as Hash,
+            label: label as Hash,
+            value: value || BigInt(0),
+            precommitment: precommitment as Hash,
+            blockNumber: BigInt(typedLog.blockNumber),
+            transactionHash: typedLog.transactionHash,
+          };
+        } catch (error) {
+          if (error instanceof DataError) throw error;
+          throw DataError.invalidLog(
+            "deposit",
+            error instanceof Error ? error.message : "Unknown error"
+          );
+        }
+      });
+    } catch (error) {
+      if (error instanceof DataError) throw error;
+      throw DataError.networkError(
+        pool.chainId,
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+
+  /**
+   * Get withdrawal events for a specific chain
+   *
+   * @param pool - Pool info containing chainId, address, and deployment block
+   * @param fromBlock - Optional starting block (defaults to pool deployment block)
+   * @returns Array of withdrawal events with properly typed fields (bigint for numbers, Hash for commitments)
+   * @throws {DataError} If client is not configured, network error occurs, or event data is invalid
+   */
+  async getWithdrawals(
+    pool: PoolInfo,
+    fromBlock: bigint = pool.deploymentBlock
+  ): Promise<WithdrawalEvent[]> {
+    try {
+      const client = this.getClientForChain(pool.chainId);
+      const config = this.getConfigForChain(pool.chainId);
+
+      const startBlock = fromBlock ?? config.startBlock;
+      const toBlock = await this.getCurrentBlock(pool.chainId);
+      const ranges = this.generateBlockRanges(
+        startBlock,
+        toBlock,
+        this.logFetchConfig.blockChunkSize
+      );
+
+      this.logger.debug(
+        `Fetching withdrawals in ${ranges.length} chunks for pool ${pool.address}`
+      );
+
+      // Use async.mapLimit for controlled concurrency
+      const allLogs = await mapLimit<BlockRange, unknown[]>(
+        ranges,
+        this.logFetchConfig.concurrency,
+        async (range: BlockRange) => {
+          if (this.logFetchConfig.chunkDelayMs > 0) {
+            await this.sleep(this.logFetchConfig.chunkDelayMs);
+          }
+          return this.fetchLogsWithRetry(
+            client,
+            pool.address,
+            WITHDRAWAL_EVENT,
+            range
+          );
+        }
+      );
+
+      // Flatten and parse results
+      const flatLogs = allLogs.flat();
+
+      return flatLogs.map((log: unknown) => {
+        try {
+          const typedLog = log as {
+            args?: {
+              _value?: bigint;
+              _spentNullifier?: bigint;
+              _newCommitment?: bigint;
+            };
+            blockNumber?: bigint;
+            transactionHash?: Hex;
+          };
+
+          if (!typedLog.args) {
+            throw DataError.invalidLog("withdrawal", "missing args");
+          }
+
+          const {
+            _value: value,
+            _spentNullifier: spentNullifier,
+            _newCommitment: newCommitment,
+          } = typedLog.args;
+
+          if (
+            !value ||
+            !spentNullifier ||
+            !newCommitment ||
+            !typedLog.blockNumber ||
+            !typedLog.transactionHash
+          ) {
+            throw DataError.invalidLog("withdrawal", "missing required fields");
+          }
+
+          return {
+            withdrawn: value,
+            spentNullifier: spentNullifier as Hash,
+            newCommitment: newCommitment as Hash,
+            blockNumber: BigInt(typedLog.blockNumber),
+            transactionHash: typedLog.transactionHash,
+          };
+        } catch (error) {
+          if (error instanceof DataError) throw error;
+          throw DataError.invalidLog(
+            "withdrawal",
+            error instanceof Error ? error.message : "Unknown error"
+          );
+        }
+      });
+    } catch (error) {
+      if (error instanceof DataError) throw error;
+      throw DataError.networkError(
+        pool.chainId,
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+
+  /**
+   * Get ragequit events for a specific chain
+   *
+   * @param pool - Pool info containing chainId, address, and deployment block
+   * @param fromBlock - Optional starting block (defaults to pool deployment block)
+   * @returns Array of ragequit events with properly typed fields (bigint for numbers, Hash for commitments)
+   * @throws {DataError} If client is not configured, network error occurs, or event data is invalid
+   */
+  async getRagequits(
+    pool: PoolInfo,
+    fromBlock: bigint = pool.deploymentBlock
+  ): Promise<RagequitEvent[]> {
+    try {
+      const client = this.getClientForChain(pool.chainId);
+      const config = this.getConfigForChain(pool.chainId);
+
+      const startBlock = fromBlock ?? config.startBlock;
+      const toBlock = await this.getCurrentBlock(pool.chainId);
+      const ranges = this.generateBlockRanges(
+        startBlock,
+        toBlock,
+        this.logFetchConfig.blockChunkSize
+      );
+
+      this.logger.debug(
+        `Fetching ragequits in ${ranges.length} chunks for pool ${pool.address}`
+      );
+
+      // Use async.mapLimit for controlled concurrency
+      const allLogs = await mapLimit<BlockRange, unknown[]>(
+        ranges,
+        this.logFetchConfig.concurrency,
+        async (range: BlockRange) => {
+          if (this.logFetchConfig.chunkDelayMs > 0) {
+            await this.sleep(this.logFetchConfig.chunkDelayMs);
+          }
+          return this.fetchLogsWithRetry(
+            client,
+            pool.address,
+            RAGEQUIT_EVENT,
+            range
+          );
+        }
+      );
+
+      // Flatten and parse results
+      const flatLogs = allLogs.flat();
+
+      return flatLogs.map((log: unknown) => {
+        try {
+          const typedLog = log as {
+            args?: {
+              _ragequitter?: string;
+              _commitment?: bigint;
+              _label?: bigint;
+              _value?: bigint;
+            };
+            blockNumber?: bigint;
+            transactionHash?: Hex;
+          };
+
+          if (!typedLog.args) {
+            throw DataError.invalidLog("ragequit", "missing args");
+          }
+
+          const {
+            _ragequitter: ragequitter,
+            _commitment: commitment,
+            _label: label,
+            _value: value,
+          } = typedLog.args;
+
+          if (
+            !ragequitter ||
+            !commitment ||
+            !label ||
+            !typedLog.blockNumber ||
+            !typedLog.transactionHash
+          ) {
+            throw DataError.invalidLog("ragequit", "missing required fields");
+          }
+
+          return {
+            ragequitter: ragequitter.toLowerCase(),
+            commitment: commitment as Hash,
+            label: label as Hash,
+            value: value || BigInt(0),
+            blockNumber: BigInt(typedLog.blockNumber),
+            transactionHash: typedLog.transactionHash,
+          };
+        } catch (error) {
+          if (error instanceof DataError) throw error;
+          throw DataError.invalidLog(
+            "ragequit",
+            error instanceof Error ? error.message : "Unknown error"
+          );
+        }
+      });
+    } catch (error) {
+      if (error instanceof DataError) throw error;
+      throw DataError.networkError(
+        pool.chainId,
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+
+  /**
+   * Gets the current block number for a chain
+   */
+  private async getCurrentBlock(chainId: number): Promise<bigint> {
+    const client = this.getClientForChain(chainId);
+    return client.getBlockNumber();
+  }
+
+  /**
+   * Generates block ranges for chunked fetching
+   */
+  private generateBlockRanges(
+    fromBlock: bigint,
+    toBlock: bigint,
+    chunkSize: number
+  ): BlockRange[] {
+    const ranges: BlockRange[] = [];
+    let current = fromBlock;
+
+    while (current <= toBlock) {
+      const end = current + BigInt(chunkSize) - 1n;
+      ranges.push({
+        fromBlock: current,
+        toBlock: end > toBlock ? toBlock : end,
+      });
+      current = end + 1n;
+    }
+
+    return ranges;
+  }
+
+  /**
+   * Fetches logs for a single block range with retry logic
+   */
+  private async fetchLogsWithRetry<T>(
+    client: PublicClient,
+    address: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    event: any,
+    range: BlockRange
+  ): Promise<T[]> {
+    const maxRetries = this.logFetchConfig.retryOnFailure
+      ? this.logFetchConfig.maxRetries
+      : 0;
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const logs = await client.getLogs({
+          address: address as `0x${string}`,
+          event,
+          fromBlock: range.fromBlock,
+          toBlock: range.toBlock,
+        });
+        return logs as T[];
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (attempt < maxRetries) {
+          const delay =
+            this.logFetchConfig.retryBaseDelayMs * Math.pow(2, attempt);
+          this.logger.warn(
+            `Log fetch failed, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`,
+            { error: lastError.message, range }
+          );
+          await this.sleep(delay);
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Helper to add delay between requests
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  private getClientForChain(chainId: number): PublicClient {
+    const client = this.clients.get(chainId);
+    if (!client) {
+      throw DataError.chainNotConfigured(chainId);
+    }
+    return client;
+  }
+
+  private getConfigForChain(chainId: number): ChainConfig {
+    const config = this.chainConfigs.find((c) => c.chainId === chainId);
+    if (!config) {
+      throw DataError.chainNotConfigured(chainId);
+    }
+    return config;
+  }
+}

package/src/core/sdk.ts

@@ -0,0 +1,92 @@
+import { CommitmentService } from "./commitment.service.js";
+import { WithdrawalService } from "./withdrawal.service.js";
+import { CircuitsInterface } from "../interfaces/circuits.interface.js";
+import { Commitment, CommitmentProof } from "../types/commitment.js";
+import { WithdrawalProof, WithdrawalProofInput } from "../types/withdrawal.js";
+import { ContractInteractionsService } from "./contracts.service.js";
+import { Hex, Address, Chain } from "viem";
+import { AccountCommitment } from "../types/account.js";
+
+/**
+ * Main SDK class providing access to all privacy pool functionality.
+ * Uses Poseidon hash for all commitment operations.
+ */
+export class PrivacyPoolSDK {
+  private readonly commitmentService: CommitmentService;
+  private readonly withdrawalService: WithdrawalService;
+
+  constructor(circuits: CircuitsInterface) {
+    this.commitmentService = new CommitmentService(circuits);
+    this.withdrawalService = new WithdrawalService(circuits);
+  }
+
+  public createContractInstance(
+    rpcUrl: string,
+    chain: Chain,
+    entrypointAddress: Address,
+    privateKey: Hex,
+  ): ContractInteractionsService {
+    return new ContractInteractionsService(
+      rpcUrl,
+      chain,
+      entrypointAddress,
+      privateKey,
+    );
+  }
+
+  /**
+   * Generates a commitment proof.
+   *
+   * @param value - Value to commit
+   * @param label - Label for the commitment
+   * @param nullifier - Nullifier for the commitment
+   * @param secret - Secret for the commitment
+   */
+  public async proveCommitment(
+    value: bigint,
+    label: bigint,
+    nullifier: bigint,
+    secret: bigint,
+  ): Promise<CommitmentProof> {
+    return this.commitmentService.proveCommitment(
+      value,
+      label,
+      nullifier,
+      secret,
+    );
+  }
+
+  /**
+   * Verifies a commitment proof.
+   *
+   * @param proof - The proof to verify
+   */
+  public async verifyCommitment(proof: CommitmentProof): Promise<boolean> {
+    return this.commitmentService.verifyCommitment(proof);
+  }
+
+  /**
+   * Generates a withdrawal proof.
+   *
+   * @param commitment - Commitment to withdraw
+   * @param input - Input parameters for the withdrawal
+   * @param withdrawal - Withdrawal details
+   */
+  public async proveWithdrawal(
+    commitment: Commitment | AccountCommitment ,
+    input: WithdrawalProofInput,
+  ): Promise<WithdrawalProof> {
+    return await this.withdrawalService.proveWithdrawal(commitment, input);
+  }
+
+  /**
+   * Verifies a withdrawal proof.
+   *
+   * @param withdrawalProof - The withdrawal payload to verify
+   */
+  public async verifyWithdrawal(
+    withdrawalProof: WithdrawalProof,
+  ): Promise<boolean> {
+    return this.withdrawalService.verifyWithdrawal(withdrawalProof);
+  }
+}

package/src/core/withdrawal.service.ts

@@ -0,0 +1,126 @@
+import * as snarkjs from "snarkjs";
+import { ProofError } from "../errors/base.error.js";
+import {
+  CircuitName,
+  CircuitsInterface,
+} from "../interfaces/circuits.interface.js";
+import { WithdrawalProof, WithdrawalProofInput } from "../types/withdrawal.js";
+import { AccountCommitment, Commitment } from "../index.js";
+
+/**
+ * Service responsible for handling withdrawal-related operations.
+ */
+export class WithdrawalService {
+  constructor(private readonly circuits: CircuitsInterface) {}
+
+  /**
+   * Generates a withdrawal proof.
+   *
+   * @param commitment - Commitment to withdraw
+   * @param input - Input parameters for the withdrawal
+   * @param withdrawal - Withdrawal details
+   * @returns Promise resolving to withdrawal payload
+   * @throws {ProofError} If proof generation fails
+   */
+  public async proveWithdrawal(
+    commitment: Commitment | AccountCommitment,
+    input: WithdrawalProofInput
+  ): Promise<WithdrawalProof> {
+    try {
+      const inputSignals = this.prepareInputSignals(commitment, input);
+
+      const wasm = await this.circuits.getWasm(CircuitName.Withdraw);
+      const zkey = await this.circuits.getProvingKey(CircuitName.Withdraw);
+
+      const { proof, publicSignals } = await snarkjs.groth16.fullProve(
+        inputSignals,
+        wasm,
+        zkey,
+      );
+
+      return {
+        proof,
+        publicSignals,
+      };
+    } catch (error) {
+      throw ProofError.generationFailed({
+        error: error instanceof Error ? error.message : "Unknown error",
+      });
+    }
+  }
+
+  /**
+   * Verifies a withdrawal proof.
+   *
+   * @param withdrawalPayload - The withdrawal payload to verify
+   * @returns Promise resolving to boolean indicating proof validity
+   * @throws {ProofError} If verification fails
+   */
+  public async verifyWithdrawal(
+    withdrawalPayload: WithdrawalProof,
+  ): Promise<boolean> {
+    try {
+      const vkeyBin = await this.circuits.getVerificationKey(
+        CircuitName.Withdraw,
+      );
+      const vkey = JSON.parse(new TextDecoder("utf-8").decode(vkeyBin));
+      return await snarkjs.groth16.verify(
+        vkey,
+        withdrawalPayload.publicSignals,
+        withdrawalPayload.proof,
+      );
+    } catch (error) {
+      throw ProofError.verificationFailed({
+        error: error instanceof Error ? error.message : "Unknown error",
+      });
+    }
+  }
+
+  /**
+   * Prepares input signals for the withdrawal circuit.
+   */
+  private prepareInputSignals(
+    commitment: Commitment | AccountCommitment,
+    input: WithdrawalProofInput
+  ): Record<string, bigint | bigint[] | string> {
+    let existingValue: bigint;
+    let existingNullifier: bigint;
+    let existingSecret: bigint;
+    let label: bigint;
+    if ("preimage" in commitment) {
+      existingValue = commitment.preimage.value;
+      existingNullifier = commitment.preimage.precommitment.nullifier;
+      existingSecret = commitment.preimage.precommitment.secret;
+      label = commitment.preimage.label;
+    } else {
+      existingValue = commitment.value;
+      existingNullifier = commitment.nullifier;
+      existingSecret = commitment.secret;
+      label = commitment.label;
+    }
+
+    return {
+      // Public signals
+      withdrawnValue: input.withdrawalAmount,
+      stateRoot: input.stateRoot,
+      stateTreeDepth: input.stateTreeDepth,
+      ASPRoot: input.aspRoot,
+      ASPTreeDepth: input.aspTreeDepth,
+      context: input.context,
+
+      // Private signals
+      label,
+      existingValue,
+      existingNullifier,
+      existingSecret,
+      newNullifier: input.newNullifier,
+      newSecret: input.newSecret,
+
+      // Merkle Proofs
+      stateSiblings: input.stateMerkleProof.siblings,
+      stateIndex: BigInt(input.stateMerkleProof.index),
+      ASPSiblings: input.aspMerkleProof.siblings,
+      ASPIndex: BigInt(input.aspMerkleProof.index),
+    };
+  }
+}