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

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/circuits/circuits.impl.d.ts

@@ -0,0 +1,120 @@
+import { Binaries, CircuitArtifacts, CircuitNameString, CircuitsInterface, VersionString } from "./circuits.interface.js";
+interface CircuitOptions {
+    baseUrl?: string;
+    browser?: boolean;
+}
+/**
+ * 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;
+    protected readonly browser: boolean;
+    /**
+     * Constructor to initialize the Circuits class with an optional custom base URL.
+     * @param {string} [options.baseUrl] - The base URL for fetching circuit artifacts (optional).
+     * @param {boolean} [options.browser] - Controls how the circuits will be loaded, using either `fetch` if true or `fs` otherwise. Defaults to true.
+     */
+    constructor(options?: CircuitOptions);
+    /**
+     * 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>;
+}
+export {};

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

@@ -0,0 +1,129 @@
+/**
+ * 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 interface Binaries {
+    commitment: CircuitArtifacts;
+    withdraw: CircuitArtifacts;
+    merkleTree?: 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/fetchArtifacts.d.ts

@@ -0,0 +1 @@
+export declare function importFetchVersionedArtifact(isBrowser: boolean): Promise<typeof import("./fetchArtifacts.esm.js")>;

package/dist/types/circuits/fetchArtifacts.esm.d.ts

@@ -0,0 +1 @@
+export declare function fetchVersionedArtifact(artifactUrl: URL): Promise<Uint8Array>;

package/dist/types/circuits/fetchArtifacts.node.d.ts

@@ -0,0 +1 @@
+export declare function fetchVersionedArtifact(artifactUrl: URL): 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/account.service.d.ts

@@ -0,0 +1,355 @@
+import { Hash, Secret } from "../types/commitment.js";
+import { Hex } from "viem";
+import { DataService } from "./data.service.js";
+import { AccountCommitment, PoolAccount, PoolInfo, PrivacyPoolAccount } from "../types/account.js";
+import { DepositEvent, PoolEventsError, PoolEventsResult, RagequitEvent, WithdrawalEvent } from "../types/events.js";
+type AccountServiceConfig = {
+    mnemonic: string;
+    poolConcurrency?: number;
+} | {
+    account: PrivacyPoolAccount;
+    poolConcurrency?: number;
+};
+/**
+ * Service responsible for managing privacy pool accounts and their associated commitments.
+ * Handles account initialization, deposit/withdrawal tracking, and history synchronization.
+ *
+ * @remarks
+ * This service maintains the state of all pool accounts and their commitments across different
+ * chains and scopes. It uses deterministic key generation to recover account state from a mnemonic.
+ */
+export declare class AccountService {
+    private readonly dataService;
+    account: PrivacyPoolAccount;
+    private readonly logger;
+    private readonly poolConcurrency;
+    /**
+     * Creates a new AccountService instance.
+     *
+     * @param dataService - Service for fetching on-chain events
+     * @param config - Configuration for the account service (either mnemonic or existing account)
+     * @param config.mnemonic - Optional mnemonic for deterministic key generation
+     * @param config.account - Optional existing account to initialize with
+     * @param config.poolConcurrency - Optional maximum number of pools to fetch events for concurrently (default: 2)
+     *
+     * @throws {AccountError} If account initialization fails
+     */
+    constructor(dataService: DataService, config: AccountServiceConfig);
+    /**
+     * Initializes a new account from a mnemonic phrase.
+     *
+     * @param mnemonic - The mnemonic phrase to derive keys from
+     * @returns A new PrivacyPoolAccount with derived master keys
+     *
+     * @remarks
+     * This method derives two master keys from the mnemonic:
+     * 1. A master nullifier key from account index 0
+     * 2. A master secret key from account index 1
+     * These keys are used to deterministically generate nullifiers and secrets for deposits and withdrawals.
+     *
+     * @throws {AccountError} If account initialization fails
+     * @private
+     */
+    private _initializeAccount;
+    /**
+     * Generates a deterministic nullifier for a deposit.
+     *
+     * @param scope - The scope of the pool
+     * @param index - The index of the deposit
+     * @returns A deterministic nullifier for the deposit
+     * @private
+     */
+    private _genDepositNullifier;
+    /**
+     * Generates a deterministic secret for a deposit.
+     *
+     * @param scope - The scope of the pool
+     * @param index - The index of the deposit
+     * @returns A deterministic secret for the deposit
+     * @private
+     */
+    private _genDepositSecret;
+    /**
+     * Generates a deterministic nullifier for a withdrawal.
+     *
+     * @param label - The label of the commitment
+     * @param index - The index of the withdrawal
+     * @returns A deterministic nullifier for the withdrawal
+     * @private
+     */
+    private _genWithdrawalNullifier;
+    /**
+     * Generates a deterministic secret for a withdrawal.
+     *
+     * @param label - The label of the commitment
+     * @param index - The index of the withdrawal
+     * @returns A deterministic secret for the withdrawal
+     * @private
+     */
+    private _genWithdrawalSecret;
+    /**
+     * Hashes a commitment using the Poseidon hash function.
+     *
+     * @param value - The value of the commitment
+     * @param label - The label of the commitment
+     * @param precommitment - The precommitment hash
+     * @returns The commitment hash
+     * @private
+     */
+    private _hashCommitment;
+    /**
+     * Hashes a precommitment using the Poseidon hash function.
+     *
+     * @param nullifier - The nullifier for the commitment
+     * @param secret - The secret for the commitment
+     * @returns The precommitment hash
+     * @private
+     */
+    private _hashPrecommitment;
+    /**
+     * Gets all spendable commitments across all pools.
+     *
+     * @returns A map of scope to array of spendable commitments
+     *
+     * @remarks
+     * A commitment is considered spendable if:
+     * 1. It has a non-zero value
+     * 2. The account it belongs to has not been ragequit
+     */
+    getSpendableCommitments(): Map<bigint, AccountCommitment[]>;
+    /**
+     * Creates nullifier and secret for a new deposit
+     *
+     * @param scope - The scope of the pool to deposit into
+     * @param index - Optional index for deterministic generation
+     * @returns The nullifier, secret, and precommitment for the deposit
+     *
+     * @remarks
+     * If no index is provided, it uses the current number of accounts for the scope.
+     * The precommitment is a hash of the nullifier and secret, used in the deposit process.
+     */
+    createDepositSecrets(scope: Hash, index?: bigint): {
+        nullifier: Secret;
+        secret: Secret;
+        precommitment: Hash;
+    };
+    /**
+     * Creates nullifier and secret for spending a commitment
+     *
+     * @param commitment - The commitment to spend
+     * @returns The nullifier and secret for the new commitment
+     *
+     * @remarks
+     * The index used for generating the withdrawal nullifier and secret is based on
+     * the number of children the account already has, ensuring each withdrawal has
+     * a unique nullifier.
+     *
+     * @throws {AccountError} If no account is found for the commitment
+     */
+    createWithdrawalSecrets(commitment: AccountCommitment): {
+        nullifier: Secret;
+        secret: Secret;
+    };
+    /**
+     * Adds a new pool account after depositing
+     *
+     * @param scope - The scope of the pool
+     * @param value - The deposit value
+     * @param nullifier - The nullifier used for the deposit
+     * @param secret - The secret used for the deposit
+     * @param label - The label for the commitment
+     * @param blockNumber - The block number of the deposit
+     * @param txHash - The transaction hash of the deposit
+     * @returns The new pool account
+     *
+     * @remarks
+     * This method creates a new account with the deposit commitment and adds it to the
+     * pool accounts map under the specified scope. The commitment hash is calculated
+     * from the value, label, and precommitment.
+     */
+    addPoolAccount(scope: Hash, value: bigint, nullifier: Secret, secret: Secret, label: Hash, blockNumber: bigint, txHash: Hex): PoolAccount;
+    /**
+     * Adds a new commitment to the account after spending
+     *
+     * @param parentCommitment - The commitment that was spent
+     * @param value - The remaining value after spending
+     * @param nullifier - The nullifier used for spending
+     * @param secret - The secret used for spending
+     * @param blockNumber - The block number of the withdrawal
+     * @param txHash - The transaction hash of the withdrawal
+     * @returns The new commitment
+     *
+     * @remarks
+     * This method finds the account containing the parent commitment, creates a new
+     * commitment with the provided parameters, and adds it to the account's children.
+     * The new commitment inherits the label from the parent commitment.
+     *
+     * @throws {AccountError} If no account is found for the commitment
+     */
+    addWithdrawalCommitment(parentCommitment: AccountCommitment, value: bigint, nullifier: Secret, secret: Secret, blockNumber: bigint, txHash: Hex): AccountCommitment;
+    /**
+     * Adds a ragequit event to an existing pool account
+     *
+     * @param label - The label of the account to add the ragequit to
+     * @param ragequit - The ragequit event to add
+     * @returns The updated pool account
+     *
+     * @remarks
+     * When an account has a ragequit event, it can no longer be spent.
+     * This method finds the account with the matching label and attaches
+     * the ragequit event to it.
+     *
+     * @throws {AccountError} If no account is found with the given label
+     */
+    addRagequitToAccount(label: Hash, ragequit: RagequitEvent): PoolAccount;
+    /**
+     * Fetches deposit events for a given pool and returns a map of precommitments to their events for efficient lookup
+     *
+     * @param pool - The pool to fetch deposit events for
+     *
+     * @returns A map of precommitments to their events
+     */
+    getDepositEvents(pool: PoolInfo): Promise<Map<Hash, DepositEvent>>;
+    /**
+     * Fetches withdrawal events for a given pool and returns a map of spent nullifiers to their events for efficient lookup
+     *
+     * @param pool - The pool to fetch withdrawal events for
+     *
+     * @returns A map of spent nullifiers to their events
+     */
+    getWithdrawalEvents(pool: PoolInfo): Promise<Map<Hash, WithdrawalEvent>>;
+    /**
+     * Fetches ragequit events for a given pool and returns a map of ragequit labels to their events for efficient lookup
+     *
+     * @param pool - The pool to fetch ragequit events for
+     *
+     * @returns A map of ragequit labels to their events
+     */
+    getRagequitEvents(pool: PoolInfo): Promise<Map<Hash, RagequitEvent>>;
+    /**
+     * Fetches events for a given set of pools
+     *
+     * @param pools - The pools to fetch events for
+     *
+     * @returns A map of pool scopes to their events
+     */
+    getEvents(pools: PoolInfo[]): Promise<PoolEventsResult>;
+    /**
+     * Processes deposit events for a given scope and adds them to the account
+     * Deterministically generate deposit secrets and check if they match on-chain deposits
+     *
+     * @param scope - The scope of the pool
+     * @param depositEvents - The map of deposit events
+     *
+     */
+    private _processDepositEvents;
+    /**
+     * Processes withdrawal events for a given scope and adds them to the account
+     *
+     * @param scope - The scope of the pool
+     * @param withdrawalEvents - The map of withdrawal events
+     *
+     * @remarks
+     * This method performs the following steps for each pool:
+     * 1. Identifies the earliest deposit block for each scope
+     * 2. For each account, reconstructs the withdrawal history by:
+     *    - Generating nullifiers sequentially
+     *    - Matching them against on-chain events
+     *    - Adding matched withdrawals to the account state
+     *
+     * @throws {DataError} If event fetching fails
+     * @private
+     *
+     */
+    private _processWithdrawalEvents;
+    /**
+     * Processes ragequit events for a given scope and adds them to the account
+     *
+     * @param scope - The scope of the pool
+     * @param ragequitEvents - The map of ragequit events
+     *
+     * @remarks
+     * This method performs the following steps for each pool:
+     * 1. Adds ragequit events to accounts if found
+     *
+     * @throws {DataError} If event fetching fails
+     * @private
+     *
+     */
+    private _processRagequitEvents;
+    /**
+     * Initializes an AccountService instance with events for a given set of pools
+     *
+     * @param dataService - The data service to use for fetching events
+     * @param source - The source to use for initializing the account. Either a mnemonic or an existing account service instance
+     * @param pools - The pools to fetch events for
+     *
+     * @remarks
+     * This method performs the following steps for each pool:
+     * 1. Fetches deposit, withdrawal, and ragequit events for each pool
+     * 2. Processes deposit events and creates pool accounts
+     * 3. Processes withdrawal events and adds commitments to pool accounts
+     * 4. Processes ragequit events and adds ragequit to pool accounts
+     *
+     * @returns The initialized AccountService instance and array of errors if any pool events fetching fails
+     *
+     * if any pool events fetching fails, the account will be initialized without the events for that pool
+     * user can then call to this method again with the same account and missing pools to fetch the missing events
+     *
+     * @throws {AccountError} If account state reconstruction fails or if duplicate pools are found
+     */
+    static initializeWithEvents(dataService: DataService, source: {
+        mnemonic: string;
+    } | {
+        service: AccountService;
+    }, pools: PoolInfo[]): Promise<{
+        account: AccountService;
+        errors: PoolEventsError[];
+    }>;
+    /**
+     * @deprecated Use `initializeWithEvents` for instantiating an account with history reconstruction
+     * Retrieves the history of deposits and withdrawals for the given pools.
+     *
+     * @param pools - Array of pool configurations to sync history for
+     *
+     * @remarks
+     * This method performs the following steps:
+     * 1. Initializes pool accounts for each pool if they don't exist
+     * 2. For each pool, fetches deposit events and reconstructs accounts
+     * 3. Processes withdrawals and ragequits to update account state
+     *
+     * The account reconstruction is deterministic based on the master keys,
+     * allowing the full state to be recovered from on-chain events.
+     *
+     * @throws {DataError} If event fetching fails
+     * @throws {AccountError} If account state reconstruction fails
+     */
+    retrieveHistory(pools: PoolInfo[]): Promise<void>;
+    /**
+     * Processes withdrawal events for all pools and updates account state.
+     *
+     * @param pools - Array of pool configurations to process withdrawals for
+     *
+     * @remarks
+     * This method performs the following steps for each pool:
+     * 1. Identifies the earliest deposit block for each scope
+     * 2. Fetches withdrawal and ragequit events from that block
+     * 3. Maps withdrawals by nullifier hash and ragequits by label for efficient lookup
+     * 4. For each account, reconstructs the withdrawal history by:
+     *    - Generating nullifiers sequentially
+     *    - Matching them against on-chain events
+     *    - Adding matched withdrawals to the account state
+     * 5. Adds ragequit events to accounts if found
+     *
+     * @throws {DataError} If event fetching fails
+     * @private
+     */
+    private _processWithdrawalsAndRagequits;
+    /**
+     * Logs a structured diagnostic summary of the current account state.
+     * Only public, non-sensitive on-chain data is included.
+     * Call this after initializeWithEvents to produce a full dump for investigation.
+     */
+    diagnosticSummary(): void;
+}
+export {};