@0xbow/privacy-pools-core-sdk 0.0.0-3dpf8pk

package/src/core/data.service.ts

@@ -0,0 +1,608 @@
+import {createPublicClient, type Hex, http, parseAbiItem, type PublicClient,} from "viem";
+import {mapLimit} from "async";
+import {ChainConfig, DepositEvent, RagequitEvent, WithdrawalEvent,} from "../types/events.js";
+import {PoolInfo} from "../types/account.js";
+import {Hash} from "../types/commitment.js";
+import {BlockRange, ChainLogFetchConfig, DEFAULT_LOG_FETCH_CONFIG, LogFetchConfig,} from "../types/rateLimit.js";
+import {Logger, LogLevel} 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 logFetchConfigs: Map<number, LogFetchConfig>;
+
+  /**
+   * Initialize the data service with chain configurations
+   *
+   * @param chainConfigs - Array of chain configurations containing chainId, RPC URL, and API key
+   * @param logFetchConfig - Per-chain configuration for rate-limited log fetching as a Map<chainId, config>.
+   *                         Each chain can have its own specific settings (e.g., different block chunk sizes).
+   * @throws {DataError} If client initialization fails for any chain
+   */
+  constructor(
+    private readonly chainConfigs: ChainConfig[],
+    logFetchConfig: ChainLogFetchConfig = new Map()
+  ) {
+    this.logger = new Logger({ prefix: "Data", level: LogLevel.DEBUG });
+
+    // Initialize per-chain configs with defaults merged with chain-specific overrides
+    this.logFetchConfigs = new Map();
+    for (const config of chainConfigs) {
+      const chainSpecificConfig = logFetchConfig.get(config.chainId);
+      this.logFetchConfigs.set(
+        config.chainId,
+        { ...DEFAULT_LOG_FETCH_CONFIG, ...chainSpecificConfig }
+      );
+    }
+
+    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 chainConfig = this.getConfigForChain(pool.chainId);
+      const logConfig = this.getLogFetchConfigForChain(pool.chainId);
+
+      const fromBlock = pool.deploymentBlock ?? chainConfig.startBlock;
+      const toBlock = await this.getCurrentBlock(pool.chainId);
+      const ranges = this.generateBlockRanges(
+        fromBlock,
+        toBlock,
+        logConfig.blockChunkSize
+      );
+
+      this.logger.info(
+        `Fetching deposits in ${ranges.length} chunks for pool ${pool.address}, chunk size is: ${logConfig.blockChunkSize}`
+      );
+
+      // Use async.mapLimit for controlled concurrency
+      const allLogs = await mapLimit<BlockRange, unknown[]>(
+        ranges,
+        logConfig.concurrency,
+        async (range: BlockRange) => {
+          if (logConfig.chunkDelayMs > 0) {
+            await this.sleep(logConfig.chunkDelayMs);
+          }
+          return this.fetchLogsWithRetry(
+            client,
+            pool.address,
+            DEPOSIT_EVENT,
+            range,
+            logConfig
+          );
+        }
+      );
+
+      // Flatten and parse results
+      const flatLogs = allLogs.flat();
+
+      this.logger.debug(`[DataService:getDeposits] Raw logs fetched`, {
+        poolAddress: pool.address,
+        chainId: pool.chainId,
+        fromBlock: fromBlock.toString(),
+        toBlock: toBlock.toString(),
+        chunkCount: ranges.length,
+        rawLogCount: flatLogs.length,
+      });
+
+      const parsed = 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");
+          }
+
+          const result = {
+            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,
+          };
+
+          this.logger.debug(`[DataService:getDeposits] Parsed deposit event`, {
+            poolAddress: pool.address,
+            chainId: pool.chainId,
+            depositor: result.depositor,
+            commitment: result.commitment,
+            label: result.label,
+            value: result.value.toString(),
+            precommitment: result.precommitment,
+            blockNumber: result.blockNumber.toString(),
+            transactionHash: result.transactionHash,
+          });
+
+          return result;
+        } catch (error) {
+          this.logger.debug(`[DataService:getDeposits] Failed to parse deposit log`, {
+            poolAddress: pool.address,
+            chainId: pool.chainId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          if (error instanceof DataError) throw error;
+          throw DataError.invalidLog(
+            "deposit",
+            error instanceof Error ? error.message : "Unknown error"
+          );
+        }
+      });
+
+      this.logger.debug(`[DataService:getDeposits] Deposit fetch complete`, {
+        poolAddress: pool.address,
+        chainId: pool.chainId,
+        totalParsed: parsed.length,
+      });
+
+      return parsed;
+    } 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 chainConfig = this.getConfigForChain(pool.chainId);
+      const logConfig = this.getLogFetchConfigForChain(pool.chainId);
+
+      const startBlock = fromBlock ?? chainConfig.startBlock;
+      const toBlock = await this.getCurrentBlock(pool.chainId);
+      const ranges = this.generateBlockRanges(
+        startBlock,
+        toBlock,
+        logConfig.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,
+        logConfig.concurrency,
+        async (range: BlockRange) => {
+          if (logConfig.chunkDelayMs > 0) {
+            await this.sleep(logConfig.chunkDelayMs);
+          }
+          return this.fetchLogsWithRetry(
+            client,
+            pool.address,
+            WITHDRAWAL_EVENT,
+            range,
+            logConfig
+          );
+        }
+      );
+
+      // Flatten and parse results
+      const flatWithdrawalLogs = allLogs.flat();
+
+      this.logger.debug(`[DataService:getWithdrawals] Raw logs fetched`, {
+        poolAddress: pool.address,
+        chainId: pool.chainId,
+        fromBlock: startBlock.toString(),
+        toBlock: toBlock.toString(),
+        chunkCount: ranges.length,
+        rawLogCount: flatWithdrawalLogs.length,
+      });
+
+      const parsedWithdrawals = flatWithdrawalLogs.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");
+          }
+
+          const result = {
+            withdrawn: value,
+            spentNullifier: spentNullifier as Hash,
+            newCommitment: newCommitment as Hash,
+            blockNumber: BigInt(typedLog.blockNumber),
+            transactionHash: typedLog.transactionHash,
+          };
+
+          this.logger.debug(`[DataService:getWithdrawals] Parsed withdrawal event`, {
+            poolAddress: pool.address,
+            chainId: pool.chainId,
+            withdrawn: result.withdrawn.toString(),
+            spentNullifier: result.spentNullifier,
+            newCommitment: result.newCommitment,
+            blockNumber: result.blockNumber.toString(),
+            transactionHash: result.transactionHash,
+          });
+
+          return result;
+        } catch (error) {
+          this.logger.debug(`[DataService:getWithdrawals] Failed to parse withdrawal log`, {
+            poolAddress: pool.address,
+            chainId: pool.chainId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          if (error instanceof DataError) throw error;
+          throw DataError.invalidLog(
+            "withdrawal",
+            error instanceof Error ? error.message : "Unknown error"
+          );
+        }
+      });
+
+      this.logger.debug(`[DataService:getWithdrawals] Withdrawal fetch complete`, {
+        poolAddress: pool.address,
+        chainId: pool.chainId,
+        totalParsed: parsedWithdrawals.length,
+      });
+
+      return parsedWithdrawals;
+    } 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 chainConfig = this.getConfigForChain(pool.chainId);
+      const logConfig = this.getLogFetchConfigForChain(pool.chainId);
+
+      const startBlock = fromBlock ?? chainConfig.startBlock;
+      const toBlock = await this.getCurrentBlock(pool.chainId);
+      const ranges = this.generateBlockRanges(
+        startBlock,
+        toBlock,
+        logConfig.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,
+        logConfig.concurrency,
+        async (range: BlockRange) => {
+          if (logConfig.chunkDelayMs > 0) {
+            await this.sleep(logConfig.chunkDelayMs);
+          }
+          return this.fetchLogsWithRetry(
+            client,
+            pool.address,
+            RAGEQUIT_EVENT,
+            range,
+            logConfig
+          );
+        }
+      );
+
+      // Flatten and parse results
+      const flatRagequitLogs = allLogs.flat();
+
+      this.logger.debug(`[DataService:getRagequits] Raw logs fetched`, {
+        poolAddress: pool.address,
+        chainId: pool.chainId,
+        fromBlock: startBlock.toString(),
+        toBlock: toBlock.toString(),
+        chunkCount: ranges.length,
+        rawLogCount: flatRagequitLogs.length,
+      });
+
+      const parsedRagequits = flatRagequitLogs.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");
+          }
+
+          const result = {
+            ragequitter: ragequitter.toLowerCase(),
+            commitment: commitment as Hash,
+            label: label as Hash,
+            value: value || BigInt(0),
+            blockNumber: BigInt(typedLog.blockNumber),
+            transactionHash: typedLog.transactionHash,
+          };
+
+          this.logger.debug(`[DataService:getRagequits] Parsed ragequit event`, {
+            poolAddress: pool.address,
+            chainId: pool.chainId,
+            ragequitter: result.ragequitter,
+            commitment: result.commitment,
+            label: result.label,
+            value: result.value.toString(),
+            blockNumber: result.blockNumber.toString(),
+            transactionHash: result.transactionHash,
+          });
+
+          return result;
+        } catch (error) {
+          this.logger.debug(`[DataService:getRagequits] Failed to parse ragequit log`, {
+            poolAddress: pool.address,
+            chainId: pool.chainId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          if (error instanceof DataError) throw error;
+          throw DataError.invalidLog(
+            "ragequit",
+            error instanceof Error ? error.message : "Unknown error"
+          );
+        }
+      });
+
+      this.logger.debug(`[DataService:getRagequits] Ragequit fetch complete`, {
+        poolAddress: pool.address,
+        chainId: pool.chainId,
+        totalParsed: parsedRagequits.length,
+      });
+
+      return parsedRagequits;
+    } 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,
+    logConfig: LogFetchConfig
+  ): Promise<T[]> {
+    const maxRetries = logConfig.retryOnFailure
+      ? logConfig.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 =
+            logConfig.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;
+  }
+
+  private getLogFetchConfigForChain(chainId: number): LogFetchConfig {
+    const config = this.logFetchConfigs.get(chainId);
+    if (!config) {
+      // Fallback to default if not found (shouldn't happen if constructor is correct)
+      return DEFAULT_LOG_FETCH_CONFIG;
+    }
+    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);
+  }
+}