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

package/src/crypto.ts

@@ -0,0 +1,226 @@
+import { mnemonicToAccount } from "viem/accounts";
+import { bytesToNumber } from "viem/utils";
+import { poseidon } from "maci-crypto/build/ts/hashing.js";
+import { LeanIMT, LeanIMTMerkleProof } from "@zk-kit/lean-imt";
+import {
+  ErrorCode,
+  PrivacyPoolError,
+} from "./exceptions/privacyPool.exception.js";
+import {
+  Commitment,
+  Hash,
+  Secret,
+  Withdrawal,
+  MasterKeys,
+} from "./types/index.js";
+import { encodeAbiParameters, Hex, keccak256, numberToHex } from "viem";
+import { SNARK_SCALAR_FIELD } from "./constants.js";
+
+/**
+ * Validates that a bigint value is not zero
+ * @param value The value to check
+ * @param name The name of the value for the error message
+ * @throws {PrivacyPoolError} If the value is zero
+ */
+function validateNonZero(value: bigint, name: string) {
+  if (value === BigInt(0)) {
+    throw new PrivacyPoolError(
+      ErrorCode.INVALID_VALUE,
+      `Invalid input: '${name}' cannot be zero.`,
+    );
+  }
+}
+
+/**
+ * Generates two master keys based on some provided seed or a random value.
+ *
+ * @param {Hex} seed - The optional seed.
+ * @returns {MasterKeys} The master key pair.
+ */
+export function generateMasterKeys(mnemonic: string): MasterKeys {
+    if (!mnemonic) {
+        throw new PrivacyPoolError(
+            ErrorCode.INVALID_VALUE,
+            "Invalid input: mnemonic phrase is required."
+        );
+    }
+     
+    const key1 = bytesToNumber(
+      mnemonicToAccount(mnemonic, { accountIndex: 0 }).getHdKey().privateKey!,
+    );
+
+    const key2 = bytesToNumber(
+      mnemonicToAccount(mnemonic, { accountIndex: 1 }).getHdKey().privateKey!,
+    );
+
+    const masterNullifier = poseidon([BigInt(key1)]) as Secret;
+    const masterSecret = poseidon([BigInt(key2)]) as Secret;
+
+  return { masterNullifier, masterSecret };
+}
+
+/**
+ * Generates a nullifier and secret pair for a deposit commitment.
+ *
+ * @param {MasterKeys} keys - The master keys pair.
+ * @param {Hash} scope - The pool scope.
+ * @param {bigint} index - The pool account index for the scope.
+ * @returns {Secret, Secret} The commitment nullifier and secret pair.
+ */
+export function generateDepositSecrets(
+  keys: MasterKeys,
+  scope: Hash,
+  index: bigint,
+): { nullifier: Secret; secret: Secret } {
+  const nullifier = poseidon([keys.masterNullifier, scope, index]) as Secret;
+  const secret = poseidon([keys.masterSecret, scope, index]) as Secret;
+
+  return { nullifier, secret };
+}
+
+/**
+ * Generates a nullifier and secret pair for a withdrawal commitment.
+ *
+ * @param {MasterKeys} keys - The master keys pair.
+ * @param {Hash} label - The deposit commitment label.
+ * @param {bigint} index - The withdrawal index for the pool account.
+ * @returns {Secret, Secret} The commitment nullifier and secret pair.
+ */
+export function generateWithdrawalSecrets(
+  keys: MasterKeys,
+  label: Hash,
+  index: bigint,
+): { nullifier: Secret; secret: Secret } {
+  const nullifier = poseidon([keys.masterNullifier, label, index]) as Secret;
+  const secret = poseidon([keys.masterSecret, label, index]) as Secret;
+
+  return { nullifier, secret };
+}
+
+/**
+ * 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 hashPrecommitment(nullifier: Secret, secret: Secret): Hash {
+  return poseidon([nullifier, secret]) as Hash;
+}
+
+/**
+ * Generates a commitment using the given parameters.
+ *
+ * @param {bigint} value - The value associated with the commitment.
+ * @param {bigint} label - The label used for the commitment.
+ * @param {Secret} nullifier - The nullifier used in the precommitment.
+ * @param {Secret} secret - The secret used in the precommitment.
+ * @returns {Commitment} The generated commitment object.
+ */
+export function getCommitment(
+  value: bigint,
+  label: bigint,
+  nullifier: Secret,
+  secret: Secret,
+): Commitment {
+  validateNonZero(nullifier as bigint, "nullifier");
+  validateNonZero(label, "label");
+  validateNonZero(secret as bigint, "secret");
+
+  const precommitment = {
+    hash: hashPrecommitment(nullifier, secret),
+    nullifier,
+    secret,
+  };
+
+  const hash = poseidon([value, label, precommitment.hash]) as Hash;
+
+  return {
+    hash,
+    nullifierHash: precommitment.hash,
+    preimage: {
+      value,
+      label,
+      precommitment,
+    },
+  };
+}
+
+/**
+ * Generates a Merkle inclusion proof for a given leaf in a set of leaves.
+ *
+ * @param {bigint[]} leaves - Array of leaves for the Lean Incremental Merkle tree.
+ * @param {bigint} leaf - The specific leaf to generate the inclusion proof for.
+ * @returns {LeanIMTMerkleProof<bigint>} A lean incremental Merkle tree inclusion proof.
+ * @throws {Error} If the leaf is not found in the leaves array.
+ */
+export function generateMerkleProof(
+  leaves: bigint[],
+  leaf: bigint,
+): LeanIMTMerkleProof<bigint> {
+  const tree = new LeanIMT<bigint>((a: bigint, b: bigint) => poseidon([a, b]));
+
+  tree.insertMany(leaves);
+
+  const leafIndex = tree.indexOf(leaf);
+
+  // if leaf does not exist in tree, throw error
+  if (leafIndex === -1) {
+    throw new PrivacyPoolError(
+      ErrorCode.MERKLE_ERROR,
+      "Leaf not found in the leaves array.",
+    );
+  }
+
+  const proof = tree.generateProof(leafIndex);
+
+  if (proof.siblings.length < 32) {
+    proof.siblings = [
+      ...proof.siblings,
+      ...Array(32 - proof.siblings.length).fill(BigInt(0)),
+    ];
+  }
+
+  return proof;
+}
+
+export function bigintToHash(value: bigint): Hash {
+  return `0x${value.toString(16).padStart(64, "0")}` as unknown as Hash;
+}
+
+export function bigintToHex(num: bigint | string | undefined): Hex {
+  if (num === undefined) throw new Error("Undefined bigint value!");
+  return `0x${BigInt(num).toString(16).padStart(64, "0")}`;
+}
+
+/**
+ * Calculates the context hash for a withdrawal.
+ */
+export function calculateContext(withdrawal: Withdrawal, scope: Hash): string {
+  const hash =
+    BigInt(
+      keccak256(
+        encodeAbiParameters(
+          [
+            {
+              name: "withdrawal",
+              type: "tuple",
+              components: [
+                { name: "processooor", type: "address" },
+                { name: "data", type: "bytes" },
+              ],
+            },
+            { name: "scope", type: "uint256" },
+          ],
+          [
+            {
+              processooor: withdrawal.processooor,
+              data: withdrawal.data,
+            },
+            scope,
+          ],
+        ),
+      ),
+    ) % SNARK_SCALAR_FIELD;
+  return numberToHex(hash);
+}

package/src/dirname.helper.ts

@@ -0,0 +1,4 @@
+import { dirname } from "path";
+import __filename from "./filename.helper.js";
+
+export default dirname(__filename);

package/src/errors/account.error.ts

@@ -0,0 +1,49 @@
+import { ErrorCode, SDKError } from "./base.error.js";
+import { Hash } from "../types/commitment.js";
+
+export class AccountError extends SDKError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.OPERATION_FAILED,
+    details?: Record<string, unknown>,
+  ) {
+    super(message, code, details);
+    this.name = "AccountError";
+  }
+
+  public static commitmentNotFound(hash: Hash | string): AccountError {
+    const hashStr = typeof hash === 'string' ? hash : hash.toString();
+    return new AccountError(
+      `No account found for commitment ${hashStr}`,
+      ErrorCode.INVALID_INPUT,
+    );
+  }
+
+  public static invalidPoolAccount(): AccountError {
+    return new AccountError(
+      "Invalid pool account state",
+      ErrorCode.INVALID_INPUT,
+    );
+  }
+
+  public static accountInitializationFailed(reason: string): AccountError {
+    return new AccountError(
+      `Failed to initialize account: ${reason}`,
+      ErrorCode.OPERATION_FAILED,
+    );
+  }
+
+  public static duplicatePools(scope: bigint): AccountError {
+    return new AccountError(
+      `Duplicate pools found for scope: ${scope.toString()}`,
+      ErrorCode.INVALID_INPUT,
+    );
+  }
+
+  public static invalidIndex(index: bigint): AccountError {
+    return new AccountError(
+      `Invalid index: ${index.toString()}`,
+      ErrorCode.INVALID_INPUT,
+    );
+  }
+} 

package/src/errors/base.error.ts

@@ -0,0 +1,125 @@
+/**
+ * Unified error codes for the SDK.
+ */
+export enum ErrorCode {
+  // Base errors
+  UNKNOWN = "UNKNOWN",
+  INVALID_INPUT = "INVALID_INPUT",
+  OPERATION_FAILED = "OPERATION_FAILED",
+  NETWORK_ERROR = "NETWORK_ERROR",
+
+  // Proof errors
+  PROOF_GENERATION_FAILED = "PROOF_GENERATION_FAILED",
+  PROOF_VERIFICATION_FAILED = "PROOF_VERIFICATION_FAILED",
+  INVALID_PROOF = "INVALID_PROOF",
+  INVALID_PUBLIC_SIGNALS = "INVALID_PUBLIC_SIGNALS",
+  CIRCUIT_ERROR = "CIRCUIT_ERROR",
+
+  // Contract errors
+  CONTRACT_ERROR = "CONTRACT_ERROR",
+
+  // Crypto errors
+  CRYPTO_ERROR = "CRYPTO_ERROR",
+  MERKLE_ERROR = "MERKLE_ERROR",
+}
+
+/**
+ * Base error class for the SDK.
+ * All other error classes should extend this.
+ */
+export class SDKError extends Error {
+  constructor(
+    message: string,
+    public readonly code: ErrorCode = ErrorCode.UNKNOWN,
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+
+    // Maintains proper stack trace
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  /**
+   * Creates a JSON representation of the error.
+   */
+  public toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Specialized error class for proof-related operations.
+ */
+export class ProofError extends SDKError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.PROOF_GENERATION_FAILED,
+    details?: Record<string, unknown>,
+  ) {
+    super(message, code, details);
+  }
+
+  /**
+   * Creates an error for proof generation failures.
+   */
+  public static generationFailed(
+    details?: Record<string, unknown>,
+  ): ProofError {
+    return new ProofError(
+      "Failed to generate proof",
+      ErrorCode.PROOF_GENERATION_FAILED,
+      details,
+    );
+  }
+
+  /**
+   * Creates an error for proof verification failures.
+   */
+  public static verificationFailed(
+    details?: Record<string, unknown>,
+  ): ProofError {
+    return new ProofError(
+      "Failed to verify proof",
+      ErrorCode.PROOF_VERIFICATION_FAILED,
+      details,
+    );
+  }
+
+  /**
+   * Creates an error for invalid proof format.
+   */
+  public static invalidProof(details?: Record<string, unknown>): ProofError {
+    return new ProofError(
+      "Invalid proof format",
+      ErrorCode.INVALID_PROOF,
+      details,
+    );
+  }
+}
+
+export class ContractError extends SDKError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.CONTRACT_ERROR,
+    details?: Record<string, unknown>,
+  ) {
+    super(message, code);
+    this.name = "ContractError";
+  }
+
+  public static scopeNotFound(scope: bigint): ContractError {
+    return new ContractError(`No pool found for scope ${scope.toString()}`, ErrorCode.CONTRACT_ERROR);
+  }
+
+  public static assetNotFound(address: string): ContractError {
+    return new ContractError(`Asset ${address} has no pool`, ErrorCode.CONTRACT_ERROR);
+  }
+
+}

package/src/errors/data.error.ts

@@ -0,0 +1,34 @@
+import { ErrorCode, SDKError } from "./base.error.js";
+
+export class DataError extends SDKError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.NETWORK_ERROR,
+    details?: Record<string, unknown>,
+  ) {
+    super(message, code, details);
+    this.name = "DataError";
+  }
+
+  public static invalidLog(type: string, reason: string): DataError {
+    return new DataError(
+      `Invalid ${type} log: ${reason}`,
+      ErrorCode.INVALID_INPUT,
+    );
+  }
+
+  public static chainNotConfigured(chainId: number): DataError {
+    return new DataError(
+      `No configuration found for chain ID ${chainId}`,
+      ErrorCode.INVALID_INPUT,
+    );
+  }
+
+  public static networkError(chainId: number, error: Error): DataError {
+    return new DataError(
+      `Network error on chain ${chainId}: ${error.message}`,
+      ErrorCode.NETWORK_ERROR,
+      { originalError: error },
+    );
+  }
+} 

package/src/errors/events.error.ts

@@ -0,0 +1,38 @@
+import { ErrorCode } from "./base.error.js";
+import { DataError } from "./data.error.js";
+import { Hash } from "../types/commitment.js";
+
+export class EventError extends DataError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.NETWORK_ERROR,
+    details?: Record<string, unknown>,
+  ) {
+    super(message, code, details);
+    this.name = "EventError";
+  }
+
+  public static depositEventError(chainId: number, scope: Hash, error: Error): EventError {
+    return new EventError(
+      `Error fetching deposit events for chain ${chainId}: ${error.message}`,
+      ErrorCode.NETWORK_ERROR,
+      { originalError: error, scope },
+    );
+  }
+
+  public static withdrawalEventError(chainId: number, scope: Hash, error: Error): EventError {
+    return new EventError(
+      `Error fetching withdrawal events for chain ${chainId}: ${error.message}`,
+      ErrorCode.NETWORK_ERROR,
+      { originalError: error, scope },
+    );
+  }
+
+  public static ragequitEventError(chainId: number, scope: Hash, error: Error): EventError {
+    return new EventError(
+      `Error fetching ragequit events for chain ${chainId}: ${error.message}`,
+      ErrorCode.NETWORK_ERROR,
+      { originalError: error, scope },
+    );
+  }
+} 

package/src/exceptions/circuitInitialization.exception.ts

@@ -0,0 +1,6 @@
+export class CircuitInitialization extends Error {
+  constructor(message: string) {
+    super(`There was an error initializing the circuits: ${message}`);
+    this.name = "CircuitInitialization";
+  }
+}

package/src/exceptions/fetchArtifacts.exception.ts

@@ -0,0 +1,7 @@
+export class FetchArtifact extends Error {
+  constructor(artifact: URL) {
+    const message = `Encountered error while loading artifact at ${artifact.toString()}.\nIf web, make sure assets are hosted from /artifacts.\nIf Node, make sure the assets were bundled correctly at dist/node/artifacts/`;
+    super(message);
+    this.name = "FetchArtifact";
+  }
+}

package/src/exceptions/index.ts

@@ -0,0 +1,4 @@
+export * from "./invalidRpcUrl.exception.js";
+export * from "./fetchArtifacts.exception.js";
+export * from "./circuitInitialization.exception.js";
+export * from "./privacyPool.exception.js";

package/src/exceptions/invalidRpcUrl.exception.ts

@@ -0,0 +1,6 @@
+export class InvalidRpcUrl extends Error {
+  constructor(url: string) {
+    super(`${url} is invalid`);
+    this.name = "InvalidRpcUrl";
+  }
+}

package/src/exceptions/privacyPool.exception.ts

@@ -0,0 +1,19 @@
+export enum ErrorCode {
+  INVALID_COMMITMENT = "INVALID_COMMITMENT",
+  INVALID_MERKLE_PROOF = "INVALID_MERKLE_PROOF",
+  INVALID_NULLIFIER = "INVALID_NULLIFIER",
+  INVALID_SECRET = "INVALID_SECRET",
+  INVALID_VALUE = "INVALID_VALUE",
+  INVALID_LABEL = "INVALID_LABEL",
+  MERKLE_ERROR = "MERKLE_ERROR",
+}
+
+export class PrivacyPoolError extends Error {
+  constructor(
+    public code: ErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "PrivacyPoolError";
+  }
+}

package/src/external.ts

@@ -0,0 +1,13 @@
+export type { IBlockchainProvider } from "./internal.js";
+
+export { InvalidRpcUrl } from "./internal.js";
+
+export { BlockchainProvider } from "./internal.js";
+
+export { Circuits } from "./circuits/index.js";
+
+export { ContractInteractionsService } from "./core/contracts.service.js";
+
+// This file is for re-exporting external dependencies that need to be available to consumers
+export type { LeanIMTMerkleProof } from "@zk-kit/lean-imt";
+export type { Address } from "viem";

package/src/filename.helper.ts

@@ -0,0 +1,4 @@
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+export default __filename;

package/src/index.ts

@@ -0,0 +1,21 @@
+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";

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";