@0xbow/privacy-pools-core-sdk 0.1.5

package/src/core/contracts.service.ts

@@ -0,0 +1,407 @@
+import {
+  Abi,
+  Account,
+  Address,
+  Chain,
+  Hex,
+  PublicClient,
+  WalletClient,
+  createPublicClient,
+  createWalletClient,
+  getAddress,
+  http,
+} from "viem";
+import { Withdrawal, WithdrawalProof } from "../types/withdrawal.js";
+import {
+  ContractInteractions,
+  TransactionResponse,
+} from "../interfaces/contracts.interface.js";
+import { IEntrypointABI } from "../abi/IEntrypoint.js";
+import { IPrivacyPoolABI } from "../abi/IPrivacyPool.js";
+import { ERC20ABI } from "../abi/ERC20.js";
+import { privateKeyToAccount } from "viem/accounts";
+import { CommitmentProof, Hash } from "../types/commitment.js";
+import { bigintToHex } from "../crypto.js";
+import { ContractError } from "../errors/base.error.js";
+
+export class ContractInteractionsService implements ContractInteractions {
+  private publicClient: PublicClient;
+  private walletClient: WalletClient;
+  private entrypointAddress: Address;
+  private account: Account;
+
+  /**
+   * Initializes the contract interactions service.
+   *
+   * @param rpcUrl - The RPC endpoint URL for the blockchain network.
+   * @param chain - The blockchain network configuration.
+   * @param entrypointAddress - The address of the entrypoint contract.
+   * @param accountPrivateKey - The private key used for signing transactions.
+   */
+  constructor(
+    rpcUrl: string,
+    chain: Chain,
+    entrypointAddress: Address,
+    accountPrivateKey: Hex,
+  ) {
+    if (!entrypointAddress) {
+      throw new Error(
+        "Invalid entrypoint addresses provided to ContractInteractionsService",
+      );
+    }
+
+    this.account = privateKeyToAccount(accountPrivateKey);
+
+    this.walletClient = createWalletClient({
+      chain: chain,
+      transport: http(rpcUrl),
+      account: this.account,
+    });
+
+    this.publicClient = createPublicClient({
+      chain: chain,
+      transport: http(rpcUrl),
+    });
+
+    this.entrypointAddress = entrypointAddress;
+  }
+
+  /**
+   * Deposits ERC20 tokens into the privacy pool.
+   *
+   * @param asset - The address of the ERC20 token.
+   * @param amount - The amount of tokens to deposit.
+   * @param precommitment - The precommitment value.
+   * @returns Transaction response containing the transaction hash.
+   */
+  async depositERC20(
+    asset: Address,
+    amount: bigint,
+    precommitment: bigint,
+  ): Promise<TransactionResponse> {
+    try {
+      const { request } = await this.publicClient.simulateContract({
+        address: this.entrypointAddress,
+        abi: IEntrypointABI as Abi,
+        functionName: "deposit",
+        args: [asset, amount, precommitment],
+        value: 0n,
+        account: this.account,
+      });
+      return await this.executeTransaction(request);
+    } catch (error) {
+      console.error("Deposit ERC20 Error:", { error, asset, amount });
+      throw new Error(
+        `Failed to deposit ERC20: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    }
+  }
+
+  /**
+   * Deposits ETH into the privacy pool.
+   *
+   * @param amount - The amount of ETH to deposit.
+   * @param precommitment - The precommitment value.
+   * @returns Transaction response containing the transaction hash.
+   */
+  async depositETH(
+    amount: bigint,
+    precommitment: bigint,
+  ): Promise<TransactionResponse> {
+    try {
+      const { request } = await this.publicClient.simulateContract({
+        address: this.entrypointAddress,
+        abi: IEntrypointABI as Abi,
+        functionName: "deposit",
+        args: [precommitment],
+        value: amount,
+        account: this.account,
+      });
+
+      return await this.executeTransaction(request);
+    } catch (error) {
+      console.error("Deposit ETH Error:", { error, amount });
+      throw new Error(
+        `Failed to deposit ETH: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    }
+  }
+
+  /**
+   * Withdraws funds from the privacy pool.
+   *
+   * @param withdrawal - The withdrawal object containing recipient details and amount.
+   * @param withdrawalProof - The cryptographic proof verifying the withdrawal.
+   * @returns Transaction response containing the transaction hash.
+   */
+  async withdraw(
+    withdrawal: Withdrawal,
+    withdrawalProof: WithdrawalProof,
+    scope: Hash,
+  ): Promise<TransactionResponse> {
+    try {
+      const formattedProof = this.formatProof(withdrawalProof);
+
+      // get pool address from scope
+      const scopeData = await this.getScopeData(scope);
+
+      const { request } = await this.publicClient.simulateContract({
+        address: scopeData.poolAddress,
+        abi: IPrivacyPoolABI as Abi,
+        functionName: "withdraw",
+        account: this.account.address as Address,
+        args: [withdrawal, formattedProof],
+      });
+
+      return await this.executeTransaction(request);
+    } catch (error) {
+      console.error("Withdraw Error Details:", {
+        error,
+        accountAddress: this.account.address,
+      });
+      throw new Error(
+        `Failed to Withdraw: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    }
+  }
+
+  /**
+   * Relays a withdrawal transaction to the entrypoint contract.
+   * This function is used to facilitate relayer transactions.
+   *
+   * @param withdrawal - The withdrawal data structure.
+   * @param withdrawalProof - The cryptographic proof required for withdrawal.
+   * @returns Transaction response containing hash and wait function.
+   */
+  async relay(
+    withdrawal: Withdrawal,
+    withdrawalProof: WithdrawalProof,
+    scope: Hash,
+  ): Promise<TransactionResponse> {
+    try {
+      const formattedProof = this.formatProof(withdrawalProof);
+
+      const { request } = await this.publicClient.simulateContract({
+        address: this.entrypointAddress,
+        abi: [...(IEntrypointABI as Abi), ...(IPrivacyPoolABI as Abi)],
+        functionName: "relay",
+        account: this.account,
+        args: [withdrawal, formattedProof, scope],
+      });
+
+      return await this.executeTransaction(request);
+    } catch (error) {
+      console.error("Withdraw Error Details:", {
+        error,
+        accountAddress: this.account.address,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Executes a ragequit operation, allowing a user to exit the pool
+   * by nullifying their commitment and proving their withdrawal.
+   *
+   * @param commitmentProof - The cryptographic proof of the commitment.
+   * @param privacyPoolAddress - The address of the privacy pool contract.
+   * @returns Transaction response containing hash and wait function.
+   */
+  async ragequit(
+    commitmentProof: CommitmentProof,
+    privacyPoolAddress: Address,
+  ): Promise<TransactionResponse> {
+    try {
+      const formattedProof = this.formatProof(commitmentProof);
+
+      const { request } = await this.publicClient.simulateContract({
+        address: privacyPoolAddress,
+        abi: IPrivacyPoolABI as Abi,
+        functionName: "ragequit",
+        args: [formattedProof],
+        account: this.account,
+      });
+
+      return await this.executeTransaction(request);
+    } catch (error) {
+      console.error("Ragequit Error:", { error });
+      throw new Error(
+        `Failed to Ragequit: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    }
+  }
+
+  /**
+   * Retrieves the scope identifier of a given privacy pool.
+   *
+   * @param privacyPoolAddress - The address of the privacy pool contract.
+   * @returns The scope identifier as a bigint.
+   */
+  async getScope(privacyPoolAddress: Address): Promise<bigint> {
+    const scope = await this.publicClient.readContract({
+      address: privacyPoolAddress,
+      abi: IPrivacyPoolABI as Abi,
+      functionName: "SCOPE",
+      account: this.account,
+    });
+
+    return BigInt(scope as string);
+  }
+
+  /**
+   * Retrieves the latest state root of the privacy pool from the entrypoint contract.
+   *
+   * @param privacyPoolAddress - The address of the privacy pool contract.
+   * @returns The latest state root as a bigint.
+   */
+  async getStateRoot(privacyPoolAddress: Address): Promise<bigint> {
+    const stateRoot = await this.publicClient.readContract({
+      address: privacyPoolAddress,
+      abi: IEntrypointABI as Abi,
+      account: this.account,
+      functionName: "latestRoot",
+    });
+
+    return BigInt(stateRoot as string);
+  }
+
+  /**
+   * Retrieves the current state size of the privacy pool.
+   *
+   * @param privacyPoolAddress - The address of the privacy pool contract.
+   * @returns The size of the state tree as a bigint.
+   */
+  async getStateSize(privacyPoolAddress: Address): Promise<bigint> {
+    const stateSize = await this.publicClient.readContract({
+      address: privacyPoolAddress,
+      abi: IPrivacyPoolABI as Abi,
+      account: this.account,
+      // this should be added in the next update of PrivacyPoolSimple.sol
+      functionName: "currentTreeSize",
+    });
+
+    return BigInt(stateSize as string);
+  }
+
+  /**
+   * Retrieves data about a specific scope, including the associated privacy pool
+   * and the asset used in that pool.
+   *
+   * @param scope - The scope identifier to look up.
+   * @returns An object containing the privacy pool address and asset address.
+   * @throws ContractError if the scope does not exist.
+   */
+  async getScopeData(
+    scope: bigint,
+  ): Promise<{ poolAddress: Address; assetAddress: Address }> {
+    try {
+      // get pool address fro entrypoint
+      const poolAddress = await this.publicClient.readContract({
+        address: this.entrypointAddress,
+        abi: IEntrypointABI as Abi,
+        account: this.account,
+        args: [scope],
+        functionName: "scopeToPool",
+      });
+
+      // if no pool throw error
+      if (
+        !poolAddress ||
+        poolAddress === "0x0000000000000000000000000000000000000000"
+      ) {
+        throw ContractError.scopeNotFound(scope);
+      }
+
+      // get asset adress from pool
+      const assetAddress = await this.publicClient.readContract({
+        address: getAddress(poolAddress as string),
+        abi: IPrivacyPoolABI as Abi,
+        account: this.account,
+        functionName: "ASSET",
+      });
+
+      return {
+        poolAddress: getAddress(poolAddress as string),
+        assetAddress: getAddress(assetAddress as string),
+      };
+    } catch (error) {
+      if (error instanceof ContractError) throw error;
+      console.error(`Error resolving scope ${scope.toString()}:`, error);
+      throw new Error(
+        `Failed to resolve scope ${scope.toString()}: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    }
+  }
+
+  /**
+   * Approves the entrypoint contract to spend a specified amount of ERC20 tokens.
+   *
+   * @param spenderAddress - The address of the entity that will be approved to spend tokens.
+   * @param tokenAddress - The address of the ERC20 token contract.
+   * @param amount - The amount of tokens to approve.
+   * @returns Transaction response containing hash and wait function.
+   */
+  async approveERC20(
+    spenderAddress: Address,
+    tokenAddress: Address,
+    amount: bigint,
+  ): Promise<TransactionResponse> {
+    try {
+      const { request } = await this.publicClient.simulateContract({
+        address: tokenAddress,
+        abi: ERC20ABI as Abi,
+        functionName: "approve",
+        args: [spenderAddress, amount],
+        account: this.account,
+      });
+
+      return await this.executeTransaction(request);
+    } catch (error) {
+      console.error("ERC20 Approval Error:", { error, tokenAddress, amount });
+      throw new Error(
+        `Failed to approve ERC20: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    }
+  }
+
+  private formatProof(proof: CommitmentProof | WithdrawalProof) {
+    return {
+      pA: [
+        bigintToHex(proof.proof.pi_a?.[0]),
+        bigintToHex(proof.proof.pi_a?.[1]),
+      ],
+      pB: [
+        [
+          bigintToHex(proof.proof.pi_b?.[0]?.[1]),
+          bigintToHex(proof.proof.pi_b?.[0]?.[0]),
+        ],
+        [
+          bigintToHex(proof.proof.pi_b?.[1]?.[1]),
+          bigintToHex(proof.proof.pi_b?.[1]?.[0]),
+        ],
+      ],
+      pC: [
+        bigintToHex(proof.proof.pi_c?.[0]),
+        bigintToHex(proof.proof.pi_c?.[1]),
+      ],
+      pubSignals: proof.publicSignals.map(bigintToHex),
+    };
+  }
+
+  private async executeTransaction(request: any): Promise<TransactionResponse> {
+    try {
+      const hash = await this.walletClient.writeContract(request);
+      return {
+        hash,
+        wait: async () => {
+          await this.publicClient.waitForTransactionReceipt({ hash });
+        },
+      };
+    } catch (error) {
+      console.error("Transaction Execution Error:", { error, request });
+      throw new Error(
+        `Transaction failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+      );
+    }
+  }
+}

package/src/core/sdk.ts

@@ -0,0 +1,91 @@
+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";
+
+/**
+ * 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,
+    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,110 @@
+import * as snarkjs from "snarkjs";
+import { ProofError } from "../errors/base.error.js";
+import {
+  CircuitName,
+  CircuitsInterface,
+} from "../interfaces/circuits.interface.js";
+import { Commitment } from "../types/commitment.js";
+import { WithdrawalProof, WithdrawalProofInput } from "../types/withdrawal.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,
+    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,
+    input: WithdrawalProofInput,
+  ): Record<string, bigint | bigint[] | string> {
+    return {
+      // Public signals
+      withdrawnValue: input.withdrawalAmount,
+      stateRoot: input.stateRoot,
+      stateTreeDepth: input.stateTreeDepth,
+      ASPRoot: input.aspRoot,
+      ASPTreeDepth: input.aspTreeDepth,
+      context: input.context,
+
+      // Private signals
+      label: commitment.preimage.label,
+      existingValue: commitment.preimage.value,
+      existingNullifier: commitment.preimage.precommitment.nullifier,
+      existingSecret: commitment.preimage.precommitment.secret,
+      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),
+    };
+  }
+}