Privacy Pools

https://docs.privacypools.com
Admin
Privacy Pools enables private cryptocurrency withdrawals using zero-knowledge proofs and commitment...
Tokens:19,611
Snippets:156
Trust Score:7.7
Update:8 months ago
Show doc for...
Tokens:
Raw
### Clone and Install Project Dependencies

Source: https://docs.privacypools.com/dev-guide

Instructions to clone the Privacy Pools repository and install project dependencies using Yarn.

```bash
git clone <https://github.com/0xbow-io/privacy-pools-core.git>
cd privacy-pools-core

yarn install
```

--------------------------------

### Relayer Configuration Example

Source: https://docs.privacypools.com/dev-guide

An example JSON configuration file for the relayer service, specifying network details, fee settings, and addresses.

```json
// config.example.json
{
  "fee_receiver_address": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "provider_url": "http://0.0.0.0:8545", // Anvil port
  "fee_bps": "1000",
  "signer_private_key": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
  "sqlite_db_path": "/tmp/pp_relayer.sqlite",
  "entrypoint_address": "0xa513e6e4b8f2a923d98304ec87f64353c4d5c853",
  "chain": {
    "name": "localhost",
    "id": "31337"
  },
  "withdraw_amounts": {
    "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9": 100
  }
}
```

--------------------------------

### Start Docusaurus Development Server (npm)

Source: https://docs.privacypools.com/intro

Navigates to the Docusaurus project directory and starts the local development server. The site will be available at http://localhost:3000/ and will auto-reload on changes.

```bash
cd my-website
npm run start
```

--------------------------------

### Compile and Test Circom Circuits

Source: https://docs.privacypools.com/dev-guide

Commands to compile, test, setup, and generate verifier contracts for the zero-knowledge circuits package.

```bash
cd packages/circuits

yarn compile
yarn test
yarn test:merkle
yarn test:withdraw
yarn test:commitment

yarn setup:all
yarn setup:ptau
yarn setup:withdraw
yarn setup:commitment
yarn setup:merkle

yarn gencontract:withdraw
yarn gencontract:commitment
```

--------------------------------

### Generate New Docusaurus Site (npm)

Source: https://docs.privacypools.com/intro

Creates a new Docusaurus site using the classic template and automatically installs necessary dependencies. This command can be run in any terminal environment.

```bash
npm init docusaurus@latest my-website classic
```

--------------------------------

### Build and Test Solidity Contracts

Source: https://docs.privacypools.com/dev-guide

Commands to build, test, lint, and check coverage for the Solidity smart contracts package.

```bash
cd packages/contracts

yarn build
yarn test
yarn test:unit
yarn test:integration
yarn coverage
yarn lint:check
yarn lint:fix
```

--------------------------------

### Build and Run Relayer Service

Source: https://docs.privacypools.com/dev-guide

Commands to build, start, and run the relayer service, including Docker commands and tests.

```bash
cd packages/relayer

yarn build
yarn start
yarn build:start
yarn start:ts

yarn docker:build
yarn docker:run

yarn test
yarn test:cov
```

--------------------------------

### Build and Test TypeScript SDK

Source: https://docs.privacypools.com/dev-guide

Commands to build, test, check types, lint, and format the TypeScript SDK package.

```bash
cd packages/sdk

yarn build
yarn build:bundle
yarn test
yarn test:cov
yarn check-types
yarn lint
yarn format
```

--------------------------------

### Contracts Environment Variables

Source: https://docs.privacypools.com/dev-guide

Example environment variables required for the contracts package, including RPC endpoints and API keys.

```dotenv
// packages/contracts/.env
MAINNET_RPC=
MAINNET_DEPLOYER_NAME=

SEPOLIA_RPC=
SEPOLIA_DEPLOYER_NAME=

ETHERSCAN_API_KEY=

OWNER_ADDRESS=
POSTMAN_ADDRESS=
VERIFIER_ADDRESS=
ENTRYPOINT_ADDRESS=
```

--------------------------------

### Implement Merkle Tree Inclusion Proof with LeanIMT (Circom)

Source: https://docs.privacypools.com/layers/zk/lean-imt

This Circom template implements an efficient Merkle tree inclusion proof. It takes a leaf, its index, sibling hashes, and the current tree depth as input, and outputs the computed root. It is designed for dynamic tree depths and optimized batch processing.

```circom
template LeanIMTInclusionProof(maxDepth) {
    signal input leaf;               // Leaf to prove inclusion
    signal input leafIndex;          // Index in tree
    signal input siblings[maxDepth]; // Sibling hashes
    signal input actualDepth;        // Current tree depth

    signal output out;               // Computed root
}
```

--------------------------------

### State Management in Entrypoint Contract (Solidity)

Source: https://docs.privacypools.com/layers/contracts/entrypoint

This snippet illustrates the key state variables managed by the Entrypoint contract. It includes mappings for scope-to-pool, asset configurations, and an array for association set data used in withdrawal validations.

```Solidity
mapping(uint256 _scope => IPrivacyPool _pool) public scopeToPool;
mapping(IERC20 _asset => AssetConfig _config) public assetConfig;
AssociationSetData[] public associationSets;
```

--------------------------------

### ASP Root Management in Entrypoint Contract (Solidity)

Source: https://docs.privacypools.com/layers/contracts/entrypoint

This function is responsible for maintaining withdrawal validation data by storing new ASP roots and linking them to IPFS data. It also tracks the timestamps of root updates.

```Solidity
function updateRoot(uint256 _root, bytes32 _ipfsHash) external returns (uint256 _index);
```

--------------------------------

### CommitmentHasher

Source: https://docs.privacypools.com/reference/circuits

Creates commitment proofs using Poseidon hash. It takes public inputs like value and label, and private inputs like nullifier and secret, to generate commitment, precommitmentHash, and nullifierHash.

```APIDOC
## CommitmentHasher

### Description
Creates commitment proofs using Poseidon hash.

### Method
N/A (This is a circuit interface definition, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Public Inputs
- **value** (type) - Required - Amount being committed
- **label** (type) - Required - keccak256(scope, nonce)

#### Private Inputs
- **nullifier** (type) - Required - Unique nullifier for commitment
- **secret** (type) - Required - Secret for commitment

### Public Outputs
- **commitment** (type) - Poseidon(value, label, Poseidon(nullifier, secret))
- **precommitmentHash** (type) - Poseidon(nullifier, secret)
- **nullifierHash** (type) - Poseidon(nullifier)
```

--------------------------------

### Deposit Functionality in Entrypoint Contract (Solidity)

Source: https://docs.privacypools.com/layers/contracts/entrypoint

Demonstrates the deposit functions within the Entrypoint contract, supporting both native ETH and ERC20 tokens. The process involves validation, fee deduction, fund forwarding to privacy pools, and returning a commitment hash.

```Solidity
function deposit(uint256 _precommitment) external payable returns (uint256 _commitment);
function deposit(IERC20 _asset, uint256 _value, uint256 _precommitment) external returns (uint256 _commitment);
```

--------------------------------

### Commitment Hash Construction using Poseidon

Source: https://docs.privacypools.com/layers/zk

Demonstrates the construction of commitment hashes using the Poseidon hash function. It shows how nullifierHash, precommitmentHash, and commitmentHash are computed from their respective inputs. This is a core cryptographic operation within the Privacy Pools protocol.

```plaintext
nullifierHash = PoseidonHash(nullifier);
precommitmentHash = PoseidonHash(nullifier, secret);
commitmentHash = PoseidonHash(value, label, precommitmentHash);
```

--------------------------------

### Deposit Operation

Source: https://docs.privacypools.com/protocol/deposit

Allows users to publicly deposit assets (ETH or ERC20 tokens) into a pool, creating a private commitment.

```APIDOC
## POST /websites/privacypools/deposit

### Description
This endpoint allows users to deposit assets (ETH or ERC20 tokens) into a Privacy Pool. The process involves preparing inputs, submitting a transaction, processing fees, and generating a commitment.

### Method
POST

### Endpoint
/websites/privacypools/deposit

### Parameters
#### Query Parameters
- **asset** (string) - Required - The type of asset to deposit (e.g., 'ETH' or an ERC20 token address).
- **amount** (uint256) - Required - The amount of the asset to deposit.

#### Request Body
- **nullifier** (bytes32) - Required - A random value used to create unique commitments.
- **secret** (bytes32) - Required - A random value that helps secure the commitment.
- **precommitment** (bytes32) - Required - The hash of `nullifier` and `secret`.

### Request Example
```json
{
  "nullifier": "0x...",
  "secret": "0x...",
  "precommitment": "0x..."
}
```

### Response
#### Success Response (200)
- **transactionHash** (string) - The hash of the deposit transaction.
- **commitment** (string) - The generated commitment hash.

#### Response Example
```json
{
  "transactionHash": "0xabc123...",
  "commitment": "0xdef456..."
}
```

### Error Handling
- **400 Bad Request**: Invalid input parameters or missing required fields.
- **500 Internal Server Error**: An error occurred during the deposit process.
```

--------------------------------

### ASP Root Management API

Source: https://docs.privacypools.com/layers/contracts/entrypoint

Manages Association Set Provider (ASP) roots, which are used to validate withdrawals. This includes storing new roots and linking them to IPFS data.

```APIDOC
## ASP Root Management API

### Description
Manages Association Set Provider (ASP) roots, which are used to validate withdrawals. This includes storing new roots and linking them to IPFS data.

### Method
`POST`

### Endpoint
`/websites/privacypools/entrypoint/asp/roots`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*   **`_root`** (uint256) - Required - The new ASP root value.
*   **`_ipfsHash`** (bytes32) - Required - The IPFS hash associated with the ASP root, containing validation details.

### Request Example
```json
{
  "_root": "0x...",
  "_ipfsHash": "0x..."
}
```

### Response
#### Success Response (200)
*   **`_index`** (uint256) - The index of the newly added ASP root.

#### Response Example
```json
{
  "_index": "10"
}
```
```

--------------------------------

### Pool Management Functions in Entrypoint Contract (Solidity)

Source: https://docs.privacypools.com/layers/contracts/entrypoint

Provides essential functions for managing the lifecycle of privacy pools, including registration, removal, configuration updates, and graceful shutdown.

```Solidity
function registerPool(IERC20 _asset, IPrivacyPool _pool, uint256 _minimumDepositAmount, uint256 _vettingFeeBPS) external;
function removePool(IERC20 _asset) external;
function updatePoolConfiguration(IERC20 _asset, uint256 _minimumDepositAmount, uint256 _vettingFeeBPS) external;
function windDownPool(IPrivacyPool _pool) external;
```

--------------------------------

### Commitment Circuit Operations (Conceptual)

Source: https://docs.privacypools.com/layers/zk/commitment

Illustrates the core cryptographic operations within the commitment circuit: nullifier hashing, precommitment calculation, and the final commitment generation. These operations utilize the Poseidon hash function for security.

```plaintext
1. Nullifier hashing: nullifierHash = Poseidon([nullifier])
2. Precommitment: precommitmentHash = Poseidon([nullifier, secret])
3. Final commitment: commitment = Poseidon([value, label, precommitmentHash])
```

--------------------------------

### CommitmentHasher Template Definition (Circom)

Source: https://docs.privacypools.com/layers/zk/commitment

Defines the `CommitmentHasher` template in Circom, which outlines the signals for value, label, nullifier, and secret, and outputs the commitment and nullifier hash. It serves as the blueprint for commitment and nullifier generation.

```circom
template CommitmentHasher() {
    signal input value;
    signal input label;
    signal input nullifier;
    signal input secret;

    signal output commitment;
    signal output nullifierHash;
}
```

--------------------------------

### ASP Data Structure for Root Updates (Solidity)

Source: https://docs.privacypools.com/layers/asp

Defines the data structure used for updating the Merkle root of approved labels in the Association Set Provider. This structure includes the Merkle root, a hash of off-chain data, and a timestamp, crucial for maintaining historical proof verification.

```solidity
struct AssociationSetData {
  uint256 root;        // Merkle root of approved labels
  bytes32 ipfsHash;    // Reference to off-chain data
  uint256 timestamp;   // Update timestamp
}

```

--------------------------------

### Deposit API

Source: https://docs.privacypools.com/layers/contracts/entrypoint

Handles deposits of native ETH and ERC20 tokens into privacy pools. It validates amounts, deducts fees, and forwards funds to the appropriate pool, returning a commitment hash.

```APIDOC
## Deposit API

### Description
Handles deposits of native ETH and ERC20 tokens into privacy pools. It validates amounts, deducts fees, and forwards funds to the appropriate pool, returning a commitment hash.

### Methods

#### `deposit(uint256 _precommitment)`

*   **Method**: `POST` (or `GET` if no body is expected, but `POST` is more appropriate for state-changing actions)
*   **Endpoint**: `/websites/privacypools/entrypoint/deposit`
*   **Description**: Deposits native ETH into a privacy pool.
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**:
        *   `_precommitment` (uint256) - Required - The precommitment hash for the deposit.
        *   `value` (ether) - Required - The amount of ETH to deposit.
*   **Request Example**:
    ```json
    {
      "_precommitment": "0x...",
      "value": "1000000000000000000" 
    }
    ```
*   **Response**:
    *   **Success Response (200)**:
        *   `_commitment` (uint256) - The commitment hash representing the deposit.
    *   **Response Example**:
        ```json
        {
          "_commitment": "0x..."
        }
        ```

#### `deposit(IERC20 _asset, uint256 _value, uint256 _precommitment)`

*   **Method**: `POST`
*   **Endpoint**: `/websites/privacypools/entrypoint/deposit`
*   **Description**: Deposits ERC20 tokens into a privacy pool.
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**:
        *   `_asset` (IERC20 address) - Required - The address of the ERC20 token contract.
        *   `_value` (uint256) - Required - The amount of ERC20 tokens to deposit.
        *   `_precommitment` (uint256) - Required - The precommitment hash for the deposit.
*   **Request Example**:
    ```json
    {
      "_asset": "0x...",
      "_value": "1000000000000000000",
      "_precommitment": "0x..."
    }
    ```
*   **Response**:
    *   **Success Response (200)**:
        *   `_commitment` (uint256) - The commitment hash representing the deposit.
    *   **Response Example**:
        ```json
        {
          "_commitment": "0x..."
        }
        ```
```

--------------------------------

### PrivacyPoolSDK Class for Protocol Interaction

Source: https://docs.privacypools.com/reference/sdk

The main SDK class for high-level protocol interaction within Privacy Pools. It provides methods for ragequit and withdrawal operations, including proving and verifying commitments and withdrawals. Dependencies include internal types like CommitmentProof and WithdrawalPayload.

```typescript
class PrivacyPoolSDK {
  // Ragequit Operations
  async proveCommitment(
    value: bigint,
    label: bigint,
    nullifier: bigint,
    secret: bigint,
  ): Promise<CommitmentProof>;

  async verifyCommitment(proof: CommitmentProof): Promise<boolean>;

  // Withdrawal Operations
  async proveWithdrawal(
    commitment: Commitment,
    input: WithdrawalProofInput,
  ): Promise<WithdrawalPayload>;

  async verifyWithdrawal(
    withdrawalPayload: WithdrawalPayload,
  ): Promise<boolean>;
}
```

--------------------------------

### Pool Management API

Source: https://docs.privacypools.com/layers/contracts/entrypoint

Provides functions for managing the lifecycle of privacy pools, including registration, removal, configuration updates, and graceful shutdown.

```APIDOC
## Pool Management API

### Description
Provides functions for managing the lifecycle of privacy pools, including registration, removal, configuration updates, and graceful shutdown.

### Methods

#### `registerPool(IERC20 _asset, IPrivacyPool _pool, uint256 _minimumDepositAmount, uint256 _vettingFeeBPS)`

*   **Method**: `POST`
*   **Endpoint**: `/websites/privacypools/entrypoint/pools/register`
*   **Description**: Registers a new privacy pool for a given asset.
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**:
        *   `_asset` (IERC20 address) - Required - The address of the ERC20 token contract for which the pool is being registered.
        *   `_pool` (IPrivacyPool address) - Required - The address of the privacy pool contract.
        *   `_minimumDepositAmount` (uint256) - Required - The minimum deposit amount for this pool.
        *   `_vettingFeeBPS` (uint256) - Required - The vetting fee in basis points (BPS).
*   **Request Example**:
    ```json
    {
      "_asset": "0x...",
      "_pool": "0x...",
      "_minimumDepositAmount": "1000000000000000000",
      "_vettingFeeBPS": "50" 
    }
    ```
*   **Response**:
    *   **Success Response (200)**:
        (Indicates successful registration)

#### `removePool(IERC20 _asset)`

*   **Method**: `DELETE`
*   **Endpoint**: `/websites/privacypools/entrypoint/pools/{_asset}`
*   **Description**: Removes an existing privacy pool for a given asset.
*   **Parameters**:
    *   **Path Parameters**:
        *   `_asset` (IERC20 address) - Required - The address of the ERC20 token contract whose pool is to be removed.
    *   **Query Parameters**: None
    *   **Request Body**: None
*   **Request Example**:
    (No request body, uses path parameter)
*   **Response**:
    *   **Success Response (200)**:
        (Indicates successful removal)

#### `updatePoolConfiguration(IERC20 _asset, uint256 _minimumDepositAmount, uint256 _vettingFeeBPS)`

*   **Method**: `PUT`
*   **Endpoint**: `/websites/privacypools/entrypoint/pools/{_asset}/configuration`
*   **Description**: Updates the configuration (minimum deposit amount and vetting fee) for an existing privacy pool.
*   **Parameters**:
    *   **Path Parameters**:
        *   `_asset` (IERC20 address) - Required - The address of the ERC20 token contract whose pool configuration is to be updated.
    *   **Query Parameters**: None
    *   **Request Body**:
        *   `_minimumDepositAmount` (uint256) - Required - The new minimum deposit amount.
        *   `_vettingFeeBPS` (uint256) - Required - The new vetting fee in basis points (BPS).
*   **Request Example**:
    ```json
    {
      "_minimumDepositAmount": "2000000000000000000",
      "_vettingFeeBPS": "100"
    }
    ```
*   **Response**:
    *   **Success Response (200)**:
        (Indicates successful configuration update)

#### `windDownPool(IPrivacyPool _pool)`

*   **Method**: `POST`
*   **Endpoint**: `/websites/privacypools/entrypoint/pools/winddown`
*   **Description**: Initiates the graceful shutdown of a privacy pool.
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**:
        *   `_pool` (IPrivacyPool address) - Required - The address of the privacy pool contract to wind down.
*   **Request Example**:
    ```json
    {
      "_pool": "0x..."
    }
    ```
*   **Response**:
    *   **Success Response (200)**:
        (Indicates successful initiation of wind-down)
```

--------------------------------

### Fee Management API

Source: https://docs.privacypools.com/layers/contracts/entrypoint

Provides functionality for withdrawing protocol fees collected by the Entrypoint contract.

```APIDOC
## Fee Management API

### Description
Provides functionality for withdrawing protocol fees collected by the Entrypoint contract.

### Method
`POST`

### Endpoint
`/websites/privacypools/entrypoint/fees/withdraw`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*   **`_asset`** (IERC20 address) - Required - The address of the ERC20 token for which fees are to be withdrawn.
*   **`_recipient`** (address) - Required - The address to which the fees will be sent.

### Request Example
```json
{
  "_asset": "0x...",
  "_recipient": "0x..."
}
```

### Response
#### Success Response (200)
(Indicates successful withdrawal of fees)

#### Response Example
(Empty body or a success status code)
```

--------------------------------

### Withdrawal Relay API

Source: https://docs.privacypools.com/layers/contracts/entrypoint

Handles private withdrawals by verifying withdrawal proofs, processing them through privacy pools, and distributing funds. It enforces security checks on pool state.

```APIDOC
## Withdrawal Relay API

### Description
Handles private withdrawals by verifying withdrawal proofs, processing them through privacy pools, and distributing funds. It enforces security checks on pool state.

### Method
`POST`

### Endpoint
`/websites/privacypools/entrypoint/relay`

### Parameters
#### Query Parameters
None

#### Request Body
*   **`_withdrawal`** (IPrivacyPool.Withdrawal calldata) - Required - Withdrawal details including recipient, amount, and nullifier hash.
*   **`_proof`** (ProofLib.WithdrawProof calldata) - Required - The zero-knowledge proof validating the withdrawal.

### Request Example
```json
{
  "_withdrawal": {
    "recipient": "0x...",
    "amount": "1000000000000000000",
    "nullifierHash": "0x..."
  },
  "_proof": {
    "a": ["0x...", "0x..."],
    "b": [["0x...", "0x..."], ["0x...", "0x..."]],
    "c": ["0x...", "0x..."],
    "input": ["0x...", "0x...", "0x...", "0x...", "0x...", "0x...", "0x...", "0x..."]
  }
}
```

### Response
#### Success Response (200)
No specific return value mentioned, typically indicates successful execution.

#### Response Example
(Empty body or a success status code)
```

--------------------------------

### PrivacyPoolSDK Class

Source: https://docs.privacypools.com/reference/sdk

The main SDK class providing high-level protocol interaction for Ragequit and Withdrawal Operations.

```APIDOC
## Class: PrivacyPoolSDK

### Description
Main SDK class providing high-level protocol interaction.

### Methods

#### Ragequit Operations

##### `proveCommitment`

- **Description**: Proves a commitment with the provided parameters.
- **Method**: `async proveCommitment`
- **Parameters**:
  - `value` (bigint) - Required - The value of the commitment.
  - `label` (bigint) - Required - The label of the commitment.
  - `nullifier` (bigint) - Required - The nullifier of the commitment.
  - `secret` (bigint) - Required - The secret of the commitment.
- **Returns**: `Promise<CommitmentProof>`

##### `verifyCommitment`

- **Description**: Verifies a commitment proof.
- **Method**: `async verifyCommitment`
- **Parameters**:
  - `proof` (CommitmentProof) - Required - The commitment proof to verify.
- **Returns**: `Promise<boolean>`

#### Withdrawal Operations

##### `proveWithdrawal`

- **Description**: Proves a withdrawal with the provided commitment and input.
- **Method**: `async proveWithdrawal`
- **Parameters**:
  - `commitment` (Commitment) - Required - The commitment to withdraw from.
  - `input` (WithdrawalProofInput) - Required - The input details for the withdrawal proof.
- **Returns**: `Promise<WithdrawalPayload>`

##### `verifyWithdrawal`

- **Description**: Verifies a withdrawal payload.
- **Method**: `async verifyWithdrawal`
- **Parameters**:
  - `withdrawalPayload` (WithdrawalPayload) - Required - The withdrawal payload to verify.
- **Returns**: `Promise<boolean>`
```

--------------------------------

### Crypto Utilities

Source: https://docs.privacypools.com/reference/sdk

Core cryptographic operations for generating secrets, commitments, and Merkle proofs.

```APIDOC
## Crypto Utilities

### Description
Core cryptographic operations.

### Functions

#### `generateSecrets`

- **Description**: Generates a random nullifier and secret.
- **Method**: `function generateSecrets`
- **Returns**: `{ nullifier: Secret; secret: Secret; }`

#### `getCommitment`

- **Description**: Creates a commitment with the provided parameters.
- **Method**: `function getCommitment`
- **Parameters**:
  - `value` (bigint) - Required - The value to commit.
  - `label` (bigint) - Required - The label for the commitment.
  - `nullifier` (Secret) - Required - The secret nullifier.
  - `secret` (Secret) - Required - The secret value.
- **Returns**: `Commitment`

#### `generateMerkleProof`

- **Description**: Generates a Merkle proof for a given leaf.
- **Method**: `function generateMerkleProof`
- **Parameters**:
  - `leaves` (bigint[]) - Required - The array of leaves in the Merkle tree.
  - `leaf` (bigint) - Required - The leaf for which to generate the proof.
- **Returns**: `LeanIMTMerkleProof<bigint>`
```

--------------------------------

### Context Generation for Withdrawal (Solidity)

Source: https://docs.privacypools.com/protocol/withdrawal

Illustrates how the 'context' signal is generated for withdrawal proofs. This context binds the proof to specific withdrawal parameters and the pool's scope, ensuring the proof is valid for the intended transaction. It uses keccak256 hashing and modulo SNARK_SCALAR_FIELD.

```Solidity
context = uint256(keccak256(abi.encode(
    withdrawal,
    pool.SCOPE()
))) % SNARK_SCALAR_FIELD;
```

--------------------------------

### Crypto Utilities for Commitment and Proof Generation

Source: https://docs.privacypools.com/reference/sdk

Core cryptographic operations for Privacy Pools. This includes generating nullifier and secret values, creating commitments with provided parameters, and generating Merkle proofs for leaves. These functions are essential for on-chain operations and data integrity.

```typescript
// Generate random nullifier and secret
function generateSecrets(): {
  nullifier: Secret;
  secret: Secret;
};

// Create commitment with provided parameters
function getCommitment(
  value: bigint,
  label: bigint,
  nullifier: Secret,
  secret: Secret,
): Commitment;

// Generate Merkle proof for leaf
function generateMerkleProof(
  leaves: bigint[],
  leaf: bigint,
): LeanIMTMerkleProof<bigint>;
```

--------------------------------

### Abstract Asset Pull and Push Functions

Source: https://docs.privacypools.com/layers/contracts/privacy-pools

These are abstract internal functions within the PrivacyPool contract that must be implemented by concrete child contracts. `_pull` handles retrieving assets from a sender, and `_push` handles transferring assets to a recipient. These are implemented differently for native ETH and ERC20 tokens.

```solidity
function _pull(address _sender, uint256 _value) internal virtual;
function _push(address _recipient, uint256 _value) internal virtual;
```

--------------------------------

### Ragequit Function in PrivacyPool Contract

Source: https://docs.privacypools.com/layers/contracts/privacy-pools

Allows original depositors to reclaim their funds if excluded from the Asset Pool (ASP). It verifies the depositor's identity, spends the nullifier hash, and returns the deposited funds. Requires a `RagequitProof`.

```solidity
function ragequit(ProofLib.RagequitProof memory _proof) external
```

--------------------------------

### Types

Source: https://docs.privacypools.com/reference/sdk

Defines the data structures used within the Privacy Pools SDK.

```APIDOC
## Types

### Interface: `Commitment`

#### Description
Represents a commitment hash and its associated preimage data.

#### Fields

- **`hash`** (Hash) - Required - Commitment hash.
- **`nullifierHash`** (Hash) - Required - Hash of the nullifier.
- **`preimage`** (object) - Required - Precommitment data.
  - **`value`** (bigint) - Required - Committed value.
  - **`label`** (bigint) - Required - Commitment label.
  - **`precommitment`** (object) - Required - Precommitment data.
    - **`hash`** (Hash) - Required - Precommitment hash.
    - **`nullifier`** (Secret) - Required - Nullifier value.
    - **`secret`** (Secret) - Required - Secret value.

### Interface: `WithdrawalProofInput`

#### Description
Input parameters required for generating a withdrawal proof.

#### Fields

- **`withdrawalAmount`** (bigint) - Required - Amount to withdraw.
- **`context`** (bigint) - Required - Proof context.
- **`stateMerkleProof`** (object) - Required - Proof for the state tree.
  - **`root`** (bigint) - Required - Root of the state tree.
  - **`leaf`** (bigint) - Required - Leaf value in the state tree.
  - **`index`** (number) - Required - Index of the leaf.
  - **`siblings`** (bigint[]) - Required - Siblings for the Merkle proof.
- **`aspMerkleProof`** (object) - Required - Proof for the ASP tree.
  - **`root`** (bigint) - Required - Root of the ASP tree.
  - **`leaf`** (bigint) - Required - Leaf value in the ASP tree.
  - **`index`** (number) - Required - Index of the leaf.
  - **`siblings`** (bigint[]) - Required - Siblings for the Merkle proof.
- **`stateRoot`** (bigint) - Required - Current state root.
- **`stateTreeDepth`** (number) - Required - Depth of the state tree.
- **`aspRoot`** (bigint) - Required - Current ASP root.
- **`aspTreeDepth`** (number) - Required - Depth of the ASP tree.
- **`newSecret`** (bigint) - Required - New secret for the withdrawal.
- **`newNullifier`** (bigint) - Required - New nullifier for the withdrawal.
```

--------------------------------

### Withdrawal Circuit Template in Circom

Source: https://docs.privacypools.com/layers/zk/withdrawal

The `withdraw.circom` template defines the structure and signals for a private withdrawal circuit. It takes the maximum tree depth as a parameter and specifies public and private inputs, along with output signals for commitment hashes. This circuit is used to handle the logic for private withdrawals within the system.

```circom
template Withdraw(maxTreeDepth) {
    // Public inputs
    signal input withdrawnValue;
    signal input stateRoot;
    signal input stateTreeDepth;
    signal input ASPRoot;
    signal input ASPTreeDepth;
    signal input context;

    // Private inputs
    signal input label;
    signal input existingValue;
    signal input existingNullifier;
    signal input existingSecret;
    signal input newNullifier;
    signal input newSecret;
    signal input stateSiblings[maxTreeDepth];
    signal input stateIndex;
    signal input ASPSiblings[maxTreeDepth];
    signal input ASPIndex;

    // Outputs
    signal output newCommitmentHash;
    signal output existingNullifierHash;
}

```

--------------------------------

### Withdraw

Source: https://docs.privacypools.com/reference/circuits

Validates withdrawal proofs. It takes public inputs related to the withdrawal amount and state, and private inputs including commitment details and merkle proofs, to output the new commitment hash and the hash of the spent nullifier.

```APIDOC
## Withdraw

### Description
Validates withdrawal proofs.

### Method
N/A (This is a circuit interface definition, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Public Inputs
- **withdrawnValue** (type) - Required - Amount being withdrawn
- **stateRoot** (type) - Required - Current state root
- **stateTreeDepth** (type) - Required - Current state tree depth
- **ASPRoot** (type) - Required - Latest ASP root
- **ASPTreeDepth** (type) - Required - Current ASP tree depth
- **context** (type) - Required - keccak256(scope, Withdrawal)

#### Private Inputs
- **label** (type) - Required - keccak256(scope, nonce)
- **existingValue** (type) - Required - Value of existing commitment
- **existingNullifier** (type) - Required - Nullifier of existing commitment
- **existingSecret** (type) - Required - Secret of existing commitment
- **newNullifier** (type) - Required - Nullifier for new commitment
- **newSecret** (type) - Required - Secret for new commitment
- **stateSiblings[]** (type) - Required - State tree merkle proof
- **stateIndex** (type) - Required - Index in state tree
- **ASPSiblings[]** (type) - Required - ASP tree merkle proof
- **ASPIndex** (type) - Required - Index in ASP tree

### Public Outputs
- **newCommitmentHash** (type) - Hash of new commitment
- **existingNullifierHash** (type) - Hash of spent nullifier
```

--------------------------------

### Withdrawal Relay Function in Entrypoint Contract (Solidity)

Source: https://docs.privacypools.com/layers/contracts/entrypoint

This function handles private withdrawals by verifying proofs, processing them through privacy pools, and distributing funds. It also enforces security checks on the pool state.

```Solidity
function relay(IPrivacyPool.Withdrawal calldata _withdrawal, ProofLib.WithdrawProof calldata _proof) external nonReentrant
```

--------------------------------

### Fee Withdrawal Function in Entrypoint Contract (Solidity)

Source: https://docs.privacypools.com/layers/contracts/entrypoint

Allows the owner to withdraw accumulated fees for a specified asset to a designated recipient address.

```Solidity
function withdrawFees(IERC20 _asset, address _recipient) external;
```

--------------------------------

### IEntrypoint Interface for Privacy Pools Registry and Coordination

Source: https://docs.privacypools.com/reference/contracts

The IEntrypoint interface serves as the central registry and coordinator for privacy pools. It includes functions for registering new pools, handling deposits for different asset types, and relaying withdrawal requests. It also provides view functions to query pool and asset configurations.

```Solidity
interface IEntrypoint {
    struct AssetConfig {
        IPrivacyPool pool;
        uint256 minimumDepositAmount;
        uint256 vettingFeeBPS;
    }

    struct FeeData {
        address recipient;
        address feeRecipient;
        uint256 relayFeeBPS;
    }

    // Registry Functions
    function registerPool(
        IERC20 asset,
        IPrivacyPool pool,
        uint256 minimumDepositAmount,
        uint256 vettingFeeBPS
    ) external;

    function deposit(uint256 precommitment) external payable returns (uint256);

    function deposit(
        IERC20 asset,
        uint256 value,
        uint256 precommitment
    ) external returns (uint256);

    function relay(
        IPrivacyPool.Withdrawal calldata withdrawal,
        ProofLib.WithdrawProof calldata proof
    ) external;

    // View Functions
    function scopeToPool(uint256 scope) external view returns (IPrivacyPool);
    function assetConfig(IERC20 asset) external view returns (
        IPrivacyPool pool,
        uint256 minimumDepositAmount,
        uint256 vettingFeeBPS
    );
}

```
Tokens:
Raw