@0xbow/privacy-pools-core-sdk 0.0.0-c084059

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,3 @@
+export * from "./commitment.js";
+export * from "./withdrawal.js";
+export * from "./keys.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/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,
+      );
+    }
+  }
+}