Relevant source files

The following files were used as context for generating this wiki page: - [packages/contracts/README.md](https://github.com/defi-wonderland/privacy-pools-core-fork/blob/main/packages/contracts/README.md) - [packages/contracts/src/contracts/Entrypoint.sol](https://github.com/defi-wonderland/privacy-pools-core-fork/blob/main/audit/entrypoint_upgrade_audit_oxorio.md) (referenced via audit and README) - [packages/contracts/src/contracts/PrivacyPool.sol](https://github.com/defi-wonderland/privacy-pools-core-fork/blob/main/packages/contracts/README.md) - [packages/contracts/src/contracts/implementations/PrivacyPoolSimple.sol](https://github.com/defi-wonderland/privacy-pools-core-fork/blob/main/packages/contracts/README.md) - [packages/contracts/src/contracts/implementations/PrivacyPoolComplex.sol](https://github.com/defi-wonderland/privacy-pools-core-fork/blob/main/packages/contracts/README.md) - [packages/contracts/test/invariants/PROPERTIES.md](https://github.com/defi-wonderland/privacy-pools-core-fork/blob/main/packages/contracts/test/invariants/PROPERTIES.md) - [audit/entrypoint_upgrade_audit_oxorio.md](https://github.com/defi-wonderland/privacy-pools-core-fork/blob/main/audit/entrypoint_upgrade_audit_oxorio.md)

# PrivacyPool Implementations PrivacyPool implementations are the core smart contracts within the Privacy Pool protocol that facilitate private asset management. The system allows users to deposit funds (Native ETH or ERC20 tokens) publicly and withdraw them privately using zero-knowledge proofs. Each supported asset is managed by a dedicated pool contract that inherits from a base privacy logic, ensuring a consistent interface for the `Entrypoint` while handling asset-specific transfer mechanics. The architecture relies on a Merkle tree-based state management system (LeanIMT) and zero-knowledge circuits to verify that a withdrawal belongs to a valid deposit commitment without revealing the original transaction. Compliance is maintained through Association Set Providers (ASP), which provide sets of approved addresses that users must prove membership in to execute a private withdrawal. Sources: [packages/contracts/README.md](), [audit/entrypoint_upgrade_audit_oxorio.md]() ## Core Architecture and Inheritance The protocol follows a hierarchical contract structure where asset-specific pools inherit shared logic for state management and privacy verification. ### Contract Hierarchy * **`State.sol`**: The foundational contract responsible for Merkle tree management, tracking used nullifiers to prevent double-spending, and mapping deposit labels to original depositors. * **`PrivacyPool.sol`**: An abstract contract that inherits from `State.sol`. It contains the core protocol logic for processing deposits, verifying withdrawal proofs, and handling the "ragequit" mechanism for non-compliant funds. * **`PrivacyPoolSimple.sol`**: A concrete implementation of `PrivacyPool` designed for native assets (e.g., ETH). It implements asset transfer logic using `payable` functions. * **`PrivacyPoolComplex.sol`**: A concrete implementation for ERC20 tokens, managing token approvals and safe transfers. Sources: [packages/contracts/README.md]() ### Inheritance Overview Diagram The following diagram illustrates the relationship between the base contracts and the specific pool implementations. ```mermaid classDiagram class State { <> +LeanIMT tree +mapping nullifiers +mapping labels +updateTree() } class PrivacyPool { <> +deposit() +withdraw() +ragequit() +verifyProof() } class PrivacyPoolSimple { <> +handleNativeTransfer() } class PrivacyPoolComplex { <> +handleERC20Transfer() } State <|-- PrivacyPool PrivacyPool <|-- PrivacyPoolSimple PrivacyPool <|-- PrivacyPoolComplex ``` Sources: [packages/contracts/README.md]() ## Protocol Operations The PrivacyPool implementations support three primary flows: Deposits, Private Withdrawals, and Emergency Exits (Ragequit). ### Deposit Flow Deposits are not made directly to the pool but are routed through the `Entrypoint` contract. The pool records the commitment in its state tree and assigns a unique label to the depositor. | Step | Action | Description | | :--- | :--- | :--- | | 1 | Generate Commitment | User generates a nullifier and secret locally. | | 2 | Entrypoint Call | User sends funds and the precommitment hash to the `Entrypoint`. | | 3 | Routing | `Entrypoint` identifies the correct pool based on the asset and forwards the deposit. | | 4 | State Update | The pool records the commitment in the LeanIMT Merkle tree and records the label. | Sources: [packages/contracts/README.md](), [audit/entrypoint_upgrade_audit_oxorio.md]() ### Withdrawal and Ragequit Logic Private withdrawals require a ZK-proof, while ragequits allow original depositors to bypass ASP verification for immediate exit. ```mermaid flowchart TD Start[User Request] --> Choice{Type?} Choice -- Private Withdrawal --> ZKProof[Generate ZK Proof] ZKProof --> ASP{Approved Set?} ASP -- Yes --> Verify[Verify Proof & Nullifier] Verify --> Execute[Transfer Funds & New Commitment] Choice -- Ragequit --> Owner{Is Original Depositor?} Owner -- Yes --> DirectExit[Withdraw Full Amount] Owner -- No --> Revert[Revert Transaction] ``` Sources: [packages/contracts/README.md]() ## Component Specifications ### Key Data Structures and State The pools maintain internal state to ensure protocol integrity and prevent double-spending. | Component | Description | Source | | :--- | :--- | :--- | | **State Tree** | A Lean Incremental Merkle Tree (LeanIMT) containing all commitments. | [packages/contracts/README.md]() | | **Root Window** | Tracks the 30 latest Merkle roots to allow for asynchronous proof generation. | [packages/contracts/README.md]() | | **Nullifier Mapping** | A mapping of used nullifiers to prevent a single commitment from being spent twice. | [packages/contracts/test/invariants/PROPERTIES.md]() | | **Label Mapping** | Maps deposit labels to the address of the original depositor. | [packages/contracts/README.md]() | ### Security Invariants The protocol is governed by several accounting and security invariants enforced at the contract level. * **No Double Spending**: A nullifier can only be spent once (checked via `usedNullifiers`). * **Balance Sheet Equilibrium**: Token balance must equal net deposits plus non-withdrawn vetting fees. * **Access Control**: Only the original depositor associated with a label can trigger a `ragequit`. * **Entrypoint Exclusive**: Pools typically process deposits only when called by the authorized `Entrypoint`. Sources: [packages/contracts/test/invariants/PROPERTIES.md](), [audit/entrypoint_upgrade_audit_oxorio.md]() ## Deployment and Registration Pools must be registered with the `Entrypoint` to become operational. The registration process defines the asset, its pool address, and fee parameters. ### Registration Parameters | Parameter | Description | | :--- | :--- | | **Asset Address** | The address of the ERC20 token (or `address(0)` for native ETH). | | **Pool Address** | The deployed address of the `PrivacyPoolSimple` or `PrivacyPoolComplex` instance. | | **Min Deposit** | The minimum amount required for a single deposit. | | **Vetting Fee** | A fee (in basis points) collected during deposit for compliance services. | | **Max Relay Fee** | The maximum fee (in basis points) a relayer can charge for processing a withdrawal. | Sources: [packages/contracts/README.md]() ## Summary The PrivacyPool implementations provide a modular and secure environment for private asset management. By separating the core privacy logic (`PrivacyPool.sol`) from the asset-specific handling (`Simple` and `Complex` versions), the protocol ensures scalability across different token types while maintaining a unified security model based on zero-knowledge proofs and LeanIMT Merkle trees. These contracts work in tandem with the `Entrypoint` and Association Set Providers to balance user privacy with regulatory compliance requirements.