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

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from "./types/index.js";
+export * from "./crypto.js";
+export * from "./external.js";
+export { PrivacyPoolSDK } from "./core/sdk.js";
+
+// Additional Types (not included in types/index.js)
+export * from "./types/account.js";
+export * from "./types/events.js";
+
+// Errors
+export * from "./errors/base.error.js";
+export * from "./errors/account.error.js";
+
+// Interfaces
+export * from "./interfaces/circuits.interface.js";
+
+// Services (exported for advanced usage)
+export { CommitmentService } from "./core/commitment.service.js";
+export { WithdrawalService } from "./core/withdrawal.service.js";
+export { AccountService } from "./core/account.service.js";
+export { DataService } from "./core/data.service.js";
+
+// Logging utilities (exported so consumers can control log level)
+export { Logger, LogLevel } from "./utils/logger.js";
+

package/src/interfaces/blockchainProvider.interface.ts

@@ -0,0 +1,13 @@
+import { Address } from "../internal.js";
+
+/**
+ * Represents an interface for a blockchain provider.
+ */
+export interface IBlockchainProvider {
+  /**
+   * Retrieves the balance of the specified address.
+   * @param {Address} address The address for which to retrieve the balance.
+   * @returns {Promise<bigint>} A Promise that resolves to the balance of the address.
+   */
+  getBalance(address: Address): Promise<bigint>;
+}

package/src/interfaces/circuits.interface.ts

@@ -0,0 +1,34 @@
+/**
+ * Available circuit types in the system.
+ */
+export enum CircuitName {
+  Commitment = "commitment",
+  Withdraw = "withdraw",
+}
+
+/**
+ * Type for circuit input signals.
+ */
+export type CircuitSignals = {
+  [key: string]: bigint | bigint[] | string;
+};
+
+/**
+ * Interface for accessing circuit-related resources.
+ */
+export interface CircuitsInterface {
+  /**
+   * Gets the WASM binary for a circuit.
+   */
+  getWasm(name: CircuitName): Promise<Uint8Array>;
+
+  /**
+   * Gets the proving key for a circuit.
+   */
+  getProvingKey(name: CircuitName): Promise<Uint8Array>;
+
+  /**
+   * Gets the verification key for a circuit.
+   */
+  getVerificationKey(name: CircuitName): Promise<Uint8Array>;
+}

package/src/interfaces/contracts.interface.ts

@@ -0,0 +1,66 @@
+import { Address } from "viem";
+import { Withdrawal, WithdrawalProof } from "../types/withdrawal.js";
+import { CommitmentProof, Hash } from "../types/commitment.js";
+
+export interface SolidityGroth16Proof {
+  pA: [bigint, bigint];
+  pB: [[bigint, bigint], [bigint, bigint]];
+  pC: [bigint, bigint];
+  pubSignals: bigint[];
+}
+
+export interface AssetConfig {
+  pool: Address,
+  minimumDepositAmount: bigint,
+  vettingFeeBPS: bigint,
+  maxRelayFeeBPS: bigint
+}
+
+export interface TransactionResponse {
+  hash: string;
+  wait: () => Promise<void>;
+}
+
+export interface ContractInteractions {
+  depositERC20(
+    asset: Address,
+    amount: bigint,
+    precommitment: bigint,
+  ): Promise<TransactionResponse>;
+
+  depositETH(
+    amount: bigint,
+    precommitment: bigint,
+  ): Promise<TransactionResponse>;
+
+  withdraw(
+    withdrawal: Withdrawal,
+    withdrawalProof: WithdrawalProof,
+    scope: Hash,
+  ): Promise<TransactionResponse>;
+
+  relay(
+    withdrawal: Withdrawal,
+    withdrawalProof: WithdrawalProof,
+    scope: Hash,
+  ): Promise<TransactionResponse>;
+
+  ragequit(
+    commitmentProof: CommitmentProof,
+    privacyPoolAddress: Address,
+  ): Promise<TransactionResponse>;
+
+  getScope(privacyPoolAddress: Address): Promise<bigint>;
+  getStateRoot(privacyPoolAddress: Address): Promise<bigint>;
+  getStateSize(privacyPoolAddress: Address): Promise<bigint>;
+  getAssetConfig(assetAddress: Address): Promise<AssetConfig>;
+  getScopeData(
+    scope: bigint,
+  ): Promise<{ poolAddress: Address | null; assetAddress: Address | null }>;
+
+  approveERC20(
+    spenderAddress: Address,
+    tokenAddress: Address,
+    amount: bigint,
+  ): Promise<TransactionResponse>;
+}

package/src/interfaces/index.ts

@@ -0,0 +1 @@
+export * from "./blockchainProvider.interface.js";

package/src/internal.ts

@@ -0,0 +1,6 @@
+export type { Address } from "viem";
+export * from "./exceptions/index.js";
+export * from "./interfaces/index.js";
+export * from "./providers/index.js";
+export * from "./circuits/index.js";
+export * from "./constants.js";

package/src/keys.ts

@@ -0,0 +1,42 @@
+import { poseidon } from "maci-crypto/build/ts/hashing.js";
+import { Hash, Secret } from "./types/index.js";
+import { Hex } from "viem";
+import { generatePrivateKey } from "viem/accounts";
+
+export function genMasterKeys(seed?: Hex): [Secret, Secret] {
+  const preimage = seed ? poseidon([BigInt(seed)]) : BigInt(generatePrivateKey());
+
+  const masterKey1 = poseidon([preimage, BigInt(1)]) as Secret;
+  const masterKey2 = poseidon([preimage, BigInt(2)]) as Secret;
+
+  return [masterKey1, masterKey2];
+}
+
+/**
+ * Computes a Poseidon hash for the given nullifier and secret.
+ *
+ * @param {Secret} nullifier - The nullifier to hash.
+ * @param {Secret} secret - The secret to hash.
+ * @returns {Hash} The Poseidon hash.
+ */
+export function getDepositSecrets(
+  masterKey: [Secret, Secret],
+  scope: Hash,
+  index: bigint,
+): { nullifier: Secret; secret: Secret } {
+  const depositNullifier = poseidon([masterKey[0], scope, index]) as Secret;
+  const depositSecret = poseidon([masterKey[1], scope, index]) as Secret;
+
+  return { nullifier: depositNullifier, secret: depositSecret };
+}
+
+export function getWithdrawalSecrets(
+  masterKey: [Secret, Secret],
+  label: Hash,
+  index: bigint,
+): { nullifier: Secret; secret: Secret } {
+  const withdrawalNullifier = poseidon([masterKey[0], label, index]) as Secret;
+  const withdrawalSecret = poseidon([masterKey[1], label, index]) as Secret;
+
+  return { nullifier: withdrawalNullifier, secret: withdrawalSecret };
+}

package/src/providers/blockchainProvider.ts

@@ -0,0 +1,26 @@
+import type { Address, Chain, HttpTransport } from "viem";
+import { createPublicClient, http } from "viem";
+import { mainnet } from "viem/chains";
+
+import { IBlockchainProvider, InvalidRpcUrl } from "../internal.js";
+
+export class BlockchainProvider implements IBlockchainProvider {
+  private client: ReturnType<typeof createPublicClient<HttpTransport, Chain>>;
+
+  constructor(rpcUrl: string) {
+    // dummy check for the rpcUrl
+    if (!rpcUrl || !rpcUrl.startsWith("http")) {
+      throw new InvalidRpcUrl(rpcUrl);
+    }
+
+    this.client = createPublicClient({
+      chain: mainnet,
+      transport: http(rpcUrl),
+    });
+  }
+
+  /** @inheritdoc */
+  async getBalance(address: Address): Promise<bigint> {
+    return this.client.getBalance({ address });
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1 @@
+export * from "./blockchainProvider.js";

package/src/types/account.ts

@@ -0,0 +1,35 @@
+import { Hash, Secret } from "./commitment.js";
+import { Hex } from "viem";
+import { RagequitEvent } from "./events.js";
+
+export interface PoolAccount {
+  label: Hash;
+  deposit: AccountCommitment;
+  children: AccountCommitment[];
+  ragequit?: RagequitEvent
+}
+
+export interface AccountCommitment {
+  hash: Hash;
+  value: bigint;
+  label: Hash;
+  nullifier: Secret;
+  secret: Secret;
+  blockNumber: bigint;
+  timestamp?: bigint;
+  txHash: Hex;
+}
+
+export interface PrivacyPoolAccount {
+  masterKeys: [masterNullifier: Secret, masterSecret: Secret];
+  poolAccounts: Map<Hash, PoolAccount[]>;
+  creationTimestamp?: bigint;
+  lastUpdateTimestamp?: bigint;
+}
+
+export interface PoolInfo {
+  chainId: number;
+  address: Hex;
+  scope: Hash;
+  deploymentBlock: bigint;
+}

package/src/types/commitment.ts

@@ -0,0 +1,50 @@
+import { Groth16Proof, PublicSignals } from "snarkjs";
+
+/**
+ * Represents a hash value in the system.
+ * This is a branded type to ensure type safety.
+ */
+export type Hash = bigint & { readonly __brand: unique symbol };
+
+/**
+ * Represents a secret value in the system.
+ * This is a branded type to ensure type safety.
+ */
+export type Secret = bigint & { readonly __brand: unique symbol };
+
+/**
+ * Represents a precommitment structure containing the hash, nullifier, and secret.
+ * All hashes are computed using Poseidon.
+ */
+export interface Precommitment {
+  readonly hash: Hash;
+  readonly nullifier: Secret;
+  readonly secret: Secret;
+}
+
+/**
+ * Represents the preimage of a commitment containing the value, label, and precommitment.
+ */
+export interface CommitmentPreimage {
+  readonly value: bigint;
+  readonly label: bigint;
+  readonly precommitment: Precommitment;
+}
+
+/**
+ * Represents a complete commitment structure.
+ * All hashes are computed using Poseidon.
+ */
+export interface Commitment {
+  readonly hash: Hash;
+  readonly nullifierHash: Hash;
+  readonly preimage: CommitmentPreimage;
+}
+
+/**
+ * Represents the result of a commitment proof operation.
+ */
+export interface CommitmentProof {
+  readonly proof: Groth16Proof;
+  readonly publicSignals: PublicSignals;
+}

package/src/types/events.ts

@@ -0,0 +1,82 @@
+import { Address, Hex } from "viem";
+import { Hash } from "./commitment.js";
+
+/**
+ * Represents a deposit event from a privacy pool
+ */
+export interface DepositEvent {
+  depositor: string;
+  commitment: Hash;
+  label: Hash;
+  value: bigint;
+  precommitment: Hash;
+  blockNumber: bigint;
+  transactionHash: Hex;
+}
+
+/**
+ * Represents a withdrawal event from a privacy pool
+ */
+export interface WithdrawalEvent {
+  withdrawn: bigint;
+  spentNullifier: Hash;
+  newCommitment: Hash;
+  blockNumber: bigint;
+  transactionHash: Hex;
+}
+
+/**
+ * Represents a ragequit event from a privacy pool
+ */
+export interface RagequitEvent {
+  ragequitter: string;
+  commitment: Hash;
+  label: Hash;
+  value: bigint;
+  blockNumber: bigint;
+  transactionHash: Hex;
+}
+
+/**
+ * Configuration for a chain's data provider
+ */
+export interface ChainConfig {
+  chainId: number;
+  privacyPoolAddress: Address;
+  startBlock: bigint;
+  rpcUrl: string;
+}
+
+/**
+ * Event filter options
+ */
+export interface EventFilterOptions {
+  fromBlock?: bigint;
+  toBlock?: bigint;
+  depositor?: string;
+  limit?: number;
+  skip?: number;
+}
+
+/**
+ * Collection of pool events
+ */
+export interface PoolEvents {
+  deposits: DepositEvent[];
+  withdrawals: WithdrawalEvent[];
+}
+
+export interface PoolEventsSuccess {
+  depositEvents: Map<Hash, DepositEvent>;
+  withdrawalEvents: Map<Hash, WithdrawalEvent>;
+  ragequitEvents: Map<Hash, RagequitEvent>;
+}
+
+export interface PoolEventsError {
+  reason: string;
+  scope: Hash;
+}
+
+export type PoolEventsResult = Map<Hash, PoolEventsSuccess | PoolEventsError>;
+
+export type ProcessedDepositEventsResult = Map<Hash, DepositEvent>;

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from "./commitment.js";
+export * from "./withdrawal.js";
+export * from "./keys.js";
+export * from "./rateLimit.js";

package/src/types/keys.ts

@@ -0,0 +1,6 @@
+import { Secret } from "./commitment.js";
+
+export interface MasterKeys {
+  masterNullifier: Secret;
+  masterSecret: Secret;
+}

package/src/types/rateLimit.ts

@@ -0,0 +1,66 @@
+/**
+ * Configuration options for rate-limited log fetching
+ */
+export interface LogFetchConfig {
+  /**
+   * Maximum number of blocks to fetch in a single RPC call.
+   * Default: 10000 (typical limit for most RPC providers)
+   */
+  blockChunkSize: number;
+
+  /**
+   * Maximum number of concurrent log fetch operations.
+   * Default: 3
+   */
+  concurrency: number;
+
+  /**
+   * Delay in milliseconds between chunk requests (for additional throttling).
+   * Default: 0 (no delay)
+   */
+  chunkDelayMs: number;
+
+  /**
+   * Whether to retry failed chunk fetches.
+   * Default: true
+   */
+  retryOnFailure: boolean;
+
+  /**
+   * Maximum number of retries for a failed chunk.
+   * Default: 3
+   */
+  maxRetries: number;
+
+  /**
+   * Base delay for exponential backoff on retries (ms).
+   * Default: 1000
+   */
+  retryBaseDelayMs: number;
+}
+
+/**
+ * Default log fetch configuration
+ */
+export const DEFAULT_LOG_FETCH_CONFIG: LogFetchConfig = {
+  blockChunkSize: 10000,
+  concurrency: 3,
+  chunkDelayMs: 0,
+  retryOnFailure: true,
+  maxRetries: 3,
+  retryBaseDelayMs: 1000,
+};
+
+/**
+ * Per-chain log fetch configuration map
+ * Maps chainId to its specific LogFetchConfig
+ */
+export type ChainLogFetchConfig = Map<number, Partial<LogFetchConfig>>;
+
+/**
+ * Block range for chunked fetching
+ */
+export interface BlockRange {
+  fromBlock: bigint;
+  toBlock: bigint;
+}

package/src/types/withdrawal.ts

@@ -0,0 +1,33 @@
+import { Address, Hex } from "viem";
+import { Groth16Proof, PublicSignals } from "snarkjs";
+import { LeanIMTMerkleProof } from "@zk-kit/lean-imt";
+import { Hash, Secret } from "./commitment.js";
+
+/**
+ * Represents a withdrawal request in the system.
+ */
+export interface Withdrawal {
+  readonly processooor: Address;
+  readonly data: Hex;
+}
+
+export interface WithdrawalProof {
+  readonly proof: Groth16Proof;
+  readonly publicSignals: PublicSignals;
+}
+
+/**
+ * Input parameters required for withdrawal proof generation.
+ */
+export interface WithdrawalProofInput {
+  readonly context: bigint;
+  readonly withdrawalAmount: bigint;
+  readonly stateMerkleProof: LeanIMTMerkleProof<bigint>;
+  readonly aspMerkleProof: LeanIMTMerkleProof<bigint>;
+  readonly stateRoot: Hash;
+  readonly stateTreeDepth: bigint;
+  readonly aspRoot: Hash;
+  readonly aspTreeDepth: bigint;
+  readonly newSecret: Secret;
+  readonly newNullifier: Secret;
+}

package/src/utils/logger.ts

@@ -0,0 +1,56 @@
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+}
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  prefix?: string;
+  enabled?: boolean;
+}
+
+export class Logger {
+  private level: LogLevel;
+  private prefix: string;
+  private enabled: boolean;
+
+  constructor(options: LoggerOptions = {}) {
+    this.level = options.level ?? LogLevel.INFO;
+    this.prefix = options.prefix ?? "";
+    this.enabled = options.enabled ?? true;
+  }
+
+  private formatMessage(level: string, message: string): string {
+    return `${new Date().toISOString()} [${this.prefix}::${level}] ${message}`;
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    if (this.enabled && this.level <= LogLevel.DEBUG) {
+      console.debug(this.formatMessage("DEBUG", message), ...args);
+    }
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    if (this.enabled && this.level <= LogLevel.INFO) {
+      console.log(this.formatMessage("INFO", message), ...args);
+    }
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    if (this.enabled && this.level <= LogLevel.WARN) {
+      console.warn(this.formatMessage("WARN", message), ...args);
+    }
+  }
+
+  error(message: string, error?: Error, ...args: unknown[]): void {
+    if (this.enabled && this.level <= LogLevel.ERROR) {
+      console.error(
+        this.formatMessage("ERROR", message),
+        error?.stack ?? "",
+        ...args,
+      );
+    }
+  }
+}