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

package/dist/types/abi/IPrivacyPool.d.ts

@@ -0,0 +1,51 @@
+export declare const IPrivacyPoolABI: ({
+    type: string;
+    name: string;
+    inputs: {
+        name: string;
+        type: string;
+        internalType: string;
+    }[];
+    outputs: {
+        name: string;
+        type: string;
+        internalType: string;
+    }[];
+    stateMutability: string;
+    anonymous?: undefined;
+} | {
+    type: string;
+    name: string;
+    inputs: {
+        name: string;
+        type: string;
+        internalType: string;
+        components: {
+            name: string;
+            type: string;
+            internalType: string;
+        }[];
+    }[];
+    outputs: never[];
+    stateMutability: string;
+    anonymous?: undefined;
+} | {
+    type: string;
+    name: string;
+    inputs: {
+        name: string;
+        type: string;
+        indexed: boolean;
+        internalType: string;
+    }[];
+    anonymous: boolean;
+    outputs?: undefined;
+    stateMutability?: undefined;
+} | {
+    type: string;
+    name: string;
+    inputs: never[];
+    outputs?: undefined;
+    stateMutability?: undefined;
+    anonymous?: undefined;
+})[];

package/dist/types/ccip-BZzz1Y5w.js

@@ -0,0 +1,182 @@
+import { B as BaseError, g as getUrl, s as stringify, d as decodeErrorResult, i as isAddressEqual, c as call, a as concat, e as encodeAbiParameters, H as HttpRequestError, b as isHex } from './index-D-_1h8-n.js';
+import 'buffer';
+import 'http';
+import 'https';
+import 'zlib';
+import 'crypto';
+import 'node:crypto';
+import 'events';
+import 'net';
+import 'tls';
+import 'stream';
+import 'url';
+import 'assert';
+import 'os';
+import 'vm';
+import 'worker_threads';
+import 'fs';
+import 'constants';
+import 'readline';
+import 'path';
+
+class OffchainLookupError extends BaseError {
+    constructor({ callbackSelector, cause, data, extraData, sender, urls, }) {
+        super(cause.shortMessage ||
+            'An error occurred while fetching for an offchain result.', {
+            cause,
+            metaMessages: [
+                ...(cause.metaMessages || []),
+                cause.metaMessages?.length ? '' : [],
+                'Offchain Gateway Call:',
+                urls && [
+                    '  Gateway URL(s):',
+                    ...urls.map((url) => `    ${getUrl(url)}`),
+                ],
+                `  Sender: ${sender}`,
+                `  Data: ${data}`,
+                `  Callback selector: ${callbackSelector}`,
+                `  Extra data: ${extraData}`,
+            ].flat(),
+            name: 'OffchainLookupError',
+        });
+    }
+}
+class OffchainLookupResponseMalformedError extends BaseError {
+    constructor({ result, url }) {
+        super('Offchain gateway response is malformed. Response data must be a hex value.', {
+            metaMessages: [
+                `Gateway URL: ${getUrl(url)}`,
+                `Response: ${stringify(result)}`,
+            ],
+            name: 'OffchainLookupResponseMalformedError',
+        });
+    }
+}
+class OffchainLookupSenderMismatchError extends BaseError {
+    constructor({ sender, to }) {
+        super('Reverted sender address does not match target contract address (`to`).', {
+            metaMessages: [
+                `Contract address: ${to}`,
+                `OffchainLookup sender address: ${sender}`,
+            ],
+            name: 'OffchainLookupSenderMismatchError',
+        });
+    }
+}
+
+const offchainLookupSignature = '0x556f1830';
+const offchainLookupAbiItem = {
+    name: 'OffchainLookup',
+    type: 'error',
+    inputs: [
+        {
+            name: 'sender',
+            type: 'address',
+        },
+        {
+            name: 'urls',
+            type: 'string[]',
+        },
+        {
+            name: 'callData',
+            type: 'bytes',
+        },
+        {
+            name: 'callbackFunction',
+            type: 'bytes4',
+        },
+        {
+            name: 'extraData',
+            type: 'bytes',
+        },
+    ],
+};
+async function offchainLookup(client, { blockNumber, blockTag, data, to, }) {
+    const { args } = decodeErrorResult({
+        data,
+        abi: [offchainLookupAbiItem],
+    });
+    const [sender, urls, callData, callbackSelector, extraData] = args;
+    const { ccipRead } = client;
+    const ccipRequest_ = ccipRead && typeof ccipRead?.request === 'function'
+        ? ccipRead.request
+        : ccipRequest;
+    try {
+        if (!isAddressEqual(to, sender))
+            throw new OffchainLookupSenderMismatchError({ sender, to });
+        const result = await ccipRequest_({ data: callData, sender, urls });
+        const { data: data_ } = await call(client, {
+            blockNumber,
+            blockTag,
+            data: concat([
+                callbackSelector,
+                encodeAbiParameters([{ type: 'bytes' }, { type: 'bytes' }], [result, extraData]),
+            ]),
+            to,
+        });
+        return data_;
+    }
+    catch (err) {
+        throw new OffchainLookupError({
+            callbackSelector,
+            cause: err,
+            data,
+            extraData,
+            sender,
+            urls,
+        });
+    }
+}
+async function ccipRequest({ data, sender, urls, }) {
+    let error = new Error('An unknown error occurred.');
+    for (let i = 0; i < urls.length; i++) {
+        const url = urls[i];
+        const method = url.includes('{data}') ? 'GET' : 'POST';
+        const body = method === 'POST' ? { data, sender } : undefined;
+        const headers = method === 'POST' ? { 'Content-Type': 'application/json' } : {};
+        try {
+            const response = await fetch(url.replace('{sender}', sender).replace('{data}', data), {
+                body: JSON.stringify(body),
+                headers,
+                method,
+            });
+            let result;
+            if (response.headers.get('Content-Type')?.startsWith('application/json')) {
+                result = (await response.json()).data;
+            }
+            else {
+                result = (await response.text());
+            }
+            if (!response.ok) {
+                error = new HttpRequestError({
+                    body,
+                    details: result?.error
+                        ? stringify(result.error)
+                        : response.statusText,
+                    headers: response.headers,
+                    status: response.status,
+                    url,
+                });
+                continue;
+            }
+            if (!isHex(result)) {
+                error = new OffchainLookupResponseMalformedError({
+                    result,
+                    url,
+                });
+                continue;
+            }
+            return result;
+        }
+        catch (err) {
+            error = new HttpRequestError({
+                body,
+                details: err.message,
+                url,
+            });
+        }
+    }
+    throw error;
+}
+
+export { ccipRequest, offchainLookup, offchainLookupAbiItem, offchainLookupSignature };

package/dist/types/circuits/circuits.impl.d.ts

@@ -0,0 +1,108 @@
+import { Binaries, CircuitArtifacts, CircuitNameString, CircuitsInterface, VersionString } from "./circuits.interface.js";
+/**
+ * Class representing circuit management and artifact handling.
+ * Implements the CircuitsInterface.
+ */
+export declare class Circuits implements CircuitsInterface {
+    /**
+     * Indicates whether the circuits have been initialized.
+     * @type {boolean}
+     * @protected
+     */
+    protected initialized: boolean;
+    /**
+     * The version of the circuit artifacts being used.
+     * @type {VersionString}
+     * @protected
+     */
+    protected version: VersionString;
+    /**
+     * The binaries containing circuit artifacts such as wasm, vkey, and zkey files.
+     * @type {Binaries}
+     * @protected
+     */
+    protected binaries: Binaries;
+    /**
+     * The base URL for fetching circuit artifacts.
+     * @type {string}
+     * @protected
+     */
+    protected baseUrl: string;
+    /**
+     * Determines whether the environment is a browser.
+     * @returns {boolean} True if running in a browser environment, false otherwise.
+     * @protected
+     */
+    _browser(): boolean;
+    /**
+     * Initializes the circuit manager with binaries and a version.
+     * @param {Binaries} binaries - The binaries containing circuit artifacts.
+     * @param {VersionString} version - The version of the circuit artifacts.
+     * @protected
+     */
+    protected _initialize(binaries: Binaries, version: VersionString): void;
+    /**
+     * Handles initialization of circuit artifacts, fetching them if necessary.
+     * @param {VersionString} [version=Version.latest] - The version of the circuit artifacts.
+     * @throws {CircuitInitialization} If an error occurs during initialization.
+     * @protected
+     * @async
+     */
+    protected _handleInitialization(version?: VersionString): Promise<void>;
+    /**
+     * Fetches a versioned artifact from a given path.
+     * @param {string} artifactPath - The path to the artifact.
+     * @param {VersionString} version - The version of the artifact.
+     * @returns {Promise<Uint8Array>} A promise that resolves to the artifact as a Uint8Array.
+     * @throws {FetchArtifact} If the artifact cannot be fetched.
+     * @protected
+     * @async
+     */
+    _fetchVersionedArtifact(artifactPath: string): Promise<Uint8Array>;
+    /**
+     * Downloads and returns the circuit artifacts for a specific circuit.
+     * @param {CircuitNameString} circuitName - The name of the circuit.
+     * @returns {Promise<CircuitArtifacts>} A promise that resolves to the circuit artifacts.
+     * @protected
+     * @async
+     */
+    _downloadCircuitArtifacts(circuitName: CircuitNameString): Promise<CircuitArtifacts>;
+    /**
+     * Downloads all circuit artifacts for the specified version.
+     * @param {VersionString} version - The version of the artifacts.
+     * @returns {Promise<Binaries>} A promise that resolves to the binaries containing all circuit artifacts.
+     * @async
+     */
+    downloadArtifacts(version: VersionString): Promise<Binaries>;
+    /**
+     * Initializes the circuit artifacts for the specified version.
+     * @param {VersionString} version - The version of the artifacts.
+     * @returns {Promise<void>} A promise that resolves when initialization is complete.
+     * @async
+     */
+    initArtifacts(version: VersionString): Promise<void>;
+    /**
+     * Retrieves the verification key for a specified circuit.
+     * @param {CircuitNameString} circuitName - The name of the circuit.
+     * @param {VersionString} [version=Version.latest] - The version of the artifacts.
+     * @returns {Promise<Uint8Array>} A promise that resolves to the verification key.
+     * @async
+     */
+    getVerificationKey(circuitName: CircuitNameString, version?: VersionString): Promise<Uint8Array>;
+    /**
+     * Retrieves the proving key for a specified circuit.
+     * @param {CircuitNameString} circuitName - The name of the circuit.
+     * @param {VersionString} [version=Version.latest] - The version of the artifacts.
+     * @returns {Promise<Uint8Array>} A promise that resolves to the proving key.
+     * @async
+     */
+    getProvingKey(circuitName: CircuitNameString, version?: VersionString): Promise<Uint8Array>;
+    /**
+     * Retrieves the wasm file for a specified circuit.
+     * @param {CircuitNameString} circuitName - The name of the circuit.
+     * @param {VersionString} [version=Version.latest] - The version of the artifacts.
+     * @returns {Promise<Uint8Array>} A promise that resolves to the wasm file.
+     * @async
+     */
+    getWasm(circuitName: CircuitNameString, version?: VersionString): Promise<Uint8Array>;
+}

package/dist/types/circuits/circuits.interface.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Enum representing available versions of circuit artifacts.
+ */
+export declare enum Version {
+    /**
+     * The latest version of the circuit artifacts.
+     */
+    Latest = "latest"
+}
+/**
+ * Type representing a version string, which is a string literal derived from the Version enum.
+ */
+export type VersionString = `${Version}`;
+/**
+ * Enum representing the names of available circuits.
+ */
+export declare enum CircuitName {
+    /**
+     * Circuit for commitments.
+     */
+    Commitment = "commitment",
+    /**
+     * Circuit for Merkle tree operations.
+     */
+    MerkleTree = "merkleTree",
+    /**
+     * Circuit for withdrawal operations.
+     */
+    Withdraw = "withdraw"
+}
+/**
+ * Type representing a circuit name string, which is a string literal derived from the CircuitName enum.
+ */
+export type CircuitNameString = `${CircuitName}`;
+/**
+ * Interface representing the artifacts associated with a circuit.
+ */
+export interface CircuitArtifacts {
+    /**
+     * The precompiled wasm file for the circuit.
+     * @type {Uint8Array}
+     */
+    wasm: Uint8Array;
+    /**
+     * The verification key for the circuit.
+     * @type {Uint8Array}
+     */
+    vkey: Uint8Array;
+    /**
+     * The proving key for the circuit.
+     * @type {Uint8Array}
+     */
+    zkey: Uint8Array;
+}
+/**
+ * Type representing the mapping of circuit names to their respective asset file paths.
+ */
+export type Circ2Asset = {
+    [key in CircuitName]: {
+        /**
+         * The filename of the compiled wasm file.
+         */
+        wasm: string;
+        /**
+         * The filename of the verification key file.
+         */
+        vkey: string;
+        /**
+         * The filename of the proving key file.
+         */
+        zkey: string;
+    };
+};
+/**
+ * Mapping of circuit names to their respective asset file paths.
+ * @const
+ */
+export declare const circuitToAsset: Circ2Asset;
+/**
+ * Type representing the mapping of circuit name strings to their associated circuit artifacts.
+ */
+export type Binaries = {
+    [key in CircuitNameString]: CircuitArtifacts;
+};
+/**
+ * Interface defining the methods required for managing circuits and their artifacts.
+ */
+export interface CircuitsInterface {
+    /**
+     * Downloads all artifacts for the specified version of circuits.
+     * @param {VersionString} version - The version of the artifacts to download.
+     * @returns {Promise<Binaries>} A promise that resolves to the binaries containing all circuit artifacts.
+     * @async
+     */
+    downloadArtifacts(version: VersionString): Promise<Binaries>;
+    /**
+     * Initializes the artifacts for the specified version of circuits.
+     * @param {VersionString} version - The version of the artifacts to initialize.
+     * @returns {Promise<void>} A promise that resolves when initialization is complete.
+     * @async
+     */
+    initArtifacts(version: VersionString): Promise<void>;
+    /**
+     * Retrieves the verification key for a specified circuit.
+     * @param {CircuitNameString} circuitName - The name of the circuit.
+     * @param {VersionString} [version] - The version of the artifacts (defaults to the latest).
+     * @returns {Promise<Uint8Array>} A promise that resolves to the verification key.
+     * @async
+     */
+    getVerificationKey(circuitName: CircuitNameString, version?: VersionString): Promise<Uint8Array>;
+    /**
+     * Retrieves the proving key for a specified circuit.
+     * @param {CircuitNameString} circuitName - The name of the circuit.
+     * @param {VersionString} [version] - The version of the artifacts (defaults to the latest).
+     * @returns {Promise<Uint8Array>} A promise that resolves to the proving key.
+     * @async
+     */
+    getProvingKey(circuitName: CircuitNameString, version?: VersionString): Promise<Uint8Array>;
+    /**
+     * Retrieves the wasm file for a specified circuit.
+     * @param {CircuitNameString} circuitName - The name of the circuit.
+     * @param {VersionString} [version] - The version of the artifacts (defaults to the latest).
+     * @returns {Promise<Uint8Array>} A promise that resolves to the wasm file.
+     * @async
+     */
+    getWasm(circuitName: CircuitNameString, version?: VersionString): Promise<Uint8Array>;
+}

package/dist/types/circuits/index.d.ts

@@ -0,0 +1,2 @@
+export { Circuits } from "./circuits.impl.js";
+export type { CircuitsInterface } from "./circuits.interface.js";

package/dist/types/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const SNARK_SCALAR_FIELD_STRING = "21888242871839275222246405745257275088548364400416034343698204186575808495617";
+export declare const SNARK_SCALAR_FIELD: bigint;

package/dist/types/core/bruteForce.service.d.ts

@@ -0,0 +1,61 @@
+import { Commitment, Hash, Precommitment } from "../types/commitment.js";
+/**
+ * Parameters required for brute-force commitment recovery.
+ */
+interface BruteForceRecoveryParams {
+    /** The target commitment hash to match against */
+    commitmentHash: Hash;
+    /** Defines the range of values to search within */
+    valueRange: {
+        min: number;
+        max: number;
+        step: number;
+    };
+    /** The precommitment object containing the hash, nullifier, and secret */
+    basePrecommitment: Precommitment;
+    /** The label used during commitment computation */
+    label: bigint;
+    /** Optional settings: timeout in milliseconds */
+    options?: {
+        timeout?: number;
+    };
+}
+/**
+ * The result of the brute-force commitment recovery process.
+ */
+interface RecoveryResult {
+    /** Indicates whether the recovery was successful */
+    success: boolean;
+    /** Contains the found commitment and its value if successful */
+    data?: Array<{
+        commitment: Commitment;
+        value: number;
+    }>;
+    /** Contains an error code and message if the recovery fails */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Service for brute-force recovering commitments by iterating over possible values.
+ * This method is useful when the original commitment value is lost, but the precommitment and hash are known.
+ */
+export declare class BruteForceRecoveryService {
+    /**
+     * Attempts to recover a commitment by brute-forcing through the given value range.
+     *
+     * @param params - The parameters required for the brute-force search.
+     * @returns A `Promise` resolving to a `RecoveryResult` containing either the found commitment or an error.
+     */
+    bruteForceRecoverCommitment(params: BruteForceRecoveryParams): Promise<RecoveryResult>;
+    /**
+     * Computes the Poseidon hash of a commitment.
+     */
+    private computeCommitmentHash;
+    /**
+     * Determines the number of decimal places in a given number.
+     */
+    private getDecimalPlaces;
+}
+export {};

package/dist/types/core/commitment.service.d.ts

@@ -0,0 +1,30 @@
+import { CircuitsInterface } from "../interfaces/circuits.interface.js";
+import { CommitmentProof } from "../types/commitment.js";
+/**
+ * Service responsible for handling commitment-related operations.
+ * All hash operations use Poseidon for ZK-friendly hashing.
+ */
+export declare class CommitmentService {
+    private readonly circuits;
+    constructor(circuits: CircuitsInterface);
+    /**
+     * Generates a zero-knowledge proof for a commitment using Poseidon hash.
+     *
+     * @param value - The value being committed to
+     * @param label - Label associated with the commitment
+     * @param nullifier - Unique nullifier for the commitment
+     * @param secret - Secret key for the commitment
+     * @returns Promise resolving to proof and public signals
+     * @throws {ProofError} If proof generation fails
+     */
+    proveCommitment(value: bigint, label: bigint, nullifier: bigint, secret: bigint): Promise<CommitmentProof>;
+    /**
+     * Verifies a commitment proof.
+     *
+     * @param proof - The commitment proof to verify
+     * @param publicSignals - Public signals associated with the proof
+     * @returns Promise resolving to boolean indicating proof validity
+     * @throws {ProofError} If verification fails
+     */
+    verifyCommitment({ proof, publicSignals, }: CommitmentProof): Promise<boolean>;
+}

package/dist/types/core/contracts.service.d.ts

@@ -0,0 +1,106 @@
+import { Address, Chain, Hex } from "viem";
+import { Withdrawal, WithdrawalProof } from "../types/withdrawal.js";
+import { ContractInteractions, TransactionResponse } from "../interfaces/contracts.interface.js";
+import { CommitmentProof, Hash } from "../types/commitment.js";
+export declare class ContractInteractionsService implements ContractInteractions {
+    private publicClient;
+    private walletClient;
+    private entrypointAddress;
+    private 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);
+    /**
+     * 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.
+     */
+    depositERC20(asset: Address, amount: bigint, precommitment: bigint): Promise<TransactionResponse>;
+    /**
+     * 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.
+     */
+    depositETH(amount: bigint, precommitment: bigint): Promise<TransactionResponse>;
+    /**
+     * 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.
+     */
+    withdraw(withdrawal: Withdrawal, withdrawalProof: WithdrawalProof, scope: Hash): Promise<TransactionResponse>;
+    /**
+     * 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.
+     */
+    relay(withdrawal: Withdrawal, withdrawalProof: WithdrawalProof, scope: Hash): Promise<TransactionResponse>;
+    /**
+     * 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.
+     */
+    ragequit(commitmentProof: CommitmentProof, privacyPoolAddress: Address): Promise<TransactionResponse>;
+    /**
+     * 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.
+     */
+    getScope(privacyPoolAddress: Address): Promise<bigint>;
+    /**
+     * 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.
+     */
+    getStateRoot(privacyPoolAddress: Address): Promise<bigint>;
+    /**
+     * 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.
+     */
+    getStateSize(privacyPoolAddress: Address): Promise<bigint>;
+    /**
+     * 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.
+     */
+    getScopeData(scope: bigint): Promise<{
+        poolAddress: Address;
+        assetAddress: Address;
+    }>;
+    /**
+     * 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.
+     */
+    approveERC20(spenderAddress: Address, tokenAddress: Address, amount: bigint): Promise<TransactionResponse>;
+    private formatProof;
+    private executeTransaction;
+}