github/privacy-pools-core
1
1
Fork 0
mirror of https://github.com/0xbow-io/privacy-pools-core.git synced 2026-01-09 17:37:58 -05:00
Code Issues 16 Packages Projects Releases Wiki Activity

docs: migrate from mdbook to docusaurus (#6)

Browse Source
This commit is contained in:
moebius
2025-02-21 14:29:55 +01:00
committed by GitHub
parent d9cdf8b554
commit 82fc9da0c9
80 changed files with 11913 additions and 5778 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/.gitignore vendored
View File

@@ -1 +1,20 @@
book
# Dependencies
/node_modules
# Production
/build
# Generated files
.docusaurus
.cache-loader
# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*

41
docs/README.md Normal file
View File

@@ -0,0 +1,41 @@
# Website
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
### Installation
```
$ yarn
```
### Local Development
```
$ yarn start
```
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
### Build
```
$ yarn build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.
### Deployment
Using SSH:
```
$ USE_SSH=true yarn deploy
```
Not using SSH:
```
$ GIT_USER=<Your GitHub username> yarn deploy
```
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

17
docs/book.toml
View File

@@ -1,17 +0,0 @@
[book]
title = "Privacy Pool Documentation"
description = "Private onchain money transfers"
authors = ["Wonderland"]
language = "en"
multilingual = false
src = "src"
[preprocessor.mermaid]
command = "mdbook-mermaid"
[preprocessor.katex]
after = ["links"]
[output.html]
additional-js = ["mermaid.min.js", "mermaid-init.js"]
git-repository-url = "https://github.com/defi-wonderland/privacy-pool-core"

194
docs/docs/dev-guide.md Normal file
View File

@@ -0,0 +1,194 @@
---
title: Developer Guide
---
## Prerequisites
Before you begin, ensure you have the following installed:
- Node.js (v18 or later)
- Yarn (v1.22 or later)
- Foundry (for smart contracts)
- Docker (for running the relayer)
- Circom (for zero-knowledge circuits)
## Project Structure
The project is organized as a monorepo with the following packages:
- `contracts`: Solidity smart contracts
- `circuits`: Zero-knowledge circuits in Circom
- `sdk`: TypeScript SDK for interacting with the protocol
- `relayer`: Note relayer service
## Installation
1. Clone the repository:
```bash
git clone <https://github.com/defi-wonderland/privacy-pool-core.git>
cd privacy-pool-core
```
1. Install dependencies:
```bash
yarn install
```
## Building and Testing Packages
### Contracts
The contracts package contains the Solidity smart contracts for the Privacy Pool protocol.
```bash
cd packages/contracts
# Build contracts
yarn build
# Run tests
yarn test
# Run unit tests
yarn test:unit
# Run integration tests
yarn test:integration
# Run coverage
yarn coverage
# Lint
yarn lint:check
yarn lint:fix
```
### Circuits
The circuits package contains the zero-knowledge circuits written in Circom.
```bash
cd packages/circuits
# Compile circuits
yarn compile
# Run tests
yarn test
# Run specific test suites
yarn test:merkle
yarn test:withdraw
yarn test:commitment
# Setup
yarn setup:all # Sets up all circuits
yarn setup:ptau # Generate Powers of Tau
yarn setup:withdraw # Setup withdrawal circuit
yarn setup:commitment # Setup commitment circuit
yarn setup:merkle # Setup merkle tree circuit
# Generate groth16 verifier contracts
yarn gencontract:withdraw
yarn gencontract:commitment
```
### SDK
The SDK package provides TypeScript bindings for interacting with the protocol.
```bash
cd packages/sdk
# Build SDK
yarn build
# Build with circuit artifacts
yarn build:bundle
# Run tests
yarn test
# Run coverage
yarn test:cov
# Type checking
yarn check-types
# Lint and format
yarn lint
yarn format
```
### Relayer
The relayer package provides a service for relaying notes.
```bash
cd packages/relayer
# Build
yarn build
# Start the relayer
yarn start
# Build and start
yarn build:start
# Run with TypeScript
yarn start:ts
# Docker commands
yarn docker:build
yarn docker:run
# Tests
yarn test
yarn test:cov
```
## Environment Setup
Some packages require environment variables to be set.
### Contracts
```
// packages/contracts/.env
MAINNET_RPC=
MAINNET_DEPLOYER_NAME=
SEPOLIA_RPC=
SEPOLIA_DEPLOYER_NAME=
ETHERSCAN_API_KEY=
OWNER_ADDRESS=
POSTMAN_ADDRESS=
VERIFIER_ADDRESS=
ENTRYPOINT_ADDRESS=
```
### Relayer
```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
}
}
```

7
docs/docs/hello.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Markdown page example
---
# Markdown page example
You don't need React to write simple standalone pages.

47
docs/docs/intro.md Normal file
View File

@@ -0,0 +1,47 @@
---
sidebar_position: 1
---
# Tutorial Intro
Let's discover **Docusaurus in less than 5 minutes**.
## Getting Started
Get started by **creating a new site**.
Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
### What you'll need
- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
## Generate a new site
Generate a new Docusaurus site using the **classic template**.
The classic template will automatically be added to your project after you run the command:
```bash
npm init docusaurus@latest my-website classic
```
You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
The command also installs all necessary dependencies you need to run Docusaurus.
## Start your site
Run the development server:
```bash
cd my-website
npm run start
```
The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.

56
docs/docs/layers/asp.md Normal file
View File

@@ -0,0 +1,56 @@
---
title: ASP Layer
---
### Overview - Role in the Protocol
The Association Set Provider is a crucial compliance layer that controls which deposits can be privately withdrawn from Privacy Pools. It maintains a set of approved labels and provides the data necessary for cryptographic proofs of label inclusion, bridging privacy with regulatory requirements.
### Core Responsibilities
- Manages list of approved deposit labels
- Provides inclusion proofs for withdrawals
- Enables label revocation when needed
- Maintains compliance without compromising privacy
### Integration Points
- Interacts with Entrypoint via authorized postmen
- Provides roots for withdrawal validation
- Determines withdrawal eligibility
- Enforces protocol compliance rules
## Operation - Label Management
### Root Updates
- Only authorized postmen can update roots
- Each update includes:
```solidity
struct AssociationSetData {
uint256 root; // Merkle root of approved labels
bytes32 ipfsHash; // Reference to off-chain data
uint256 timestamp; // Update timestamp
}
```
- History maintained for proof verification
- Circular buffer stores recent roots
### Set Validation
- Withdrawals require valid ASP root
- Proof must demonstrate label inclusion
- Latest root used for validation
- Failed validations trigger ragequit option
### Wind Down Process
- Labels can be removed from ASP set
- Removal triggers withdrawal restrictions
- Original depositors can ragequit
- Ensures compliant exit path
The ASP system enables Privacy Pool to maintain compliance requirements while preserving the core privacy features of the protocol through cryptographic proofs and controlled label management.

51
docs/docs/layers/contracts.md Normal file
View File

@@ -0,0 +1,51 @@
---
title: Smart Contracts Layer
---
### Contract architecture overview
The Privacy Pool protocol is built on three core contracts:
1. **Entrypoint**
- Central access point for deposits
- Manages pool registry and ASP root updates
- Handles fee collection and relay operations
- Controls protocol-wide settings
2. **Privacy Pools**
- `PrivacyPoolSimple`: Handles native asset (ETH)
- `PrivacyPoolComplex`: Handles ERC20 tokens
- Both inherit from base `PrivacyPool` and `State` contracts
3. **Verifiers**
- `CommitmentVerifier`: Validates ragequit proofs
- `WithdrawalVerifier`: Validates withdrawal proofs
- Both implement Groth16 verification
### Component interaction
- User operations flow through the Entrypoint:
- Deposits route funds to appropriate pools
- Withdrawals can be direct to the Pool or relayed through the Entrypoint
- Fees are deducted and distributed
- Privacy Pools handle:
- Asset custody and proof verification
- State tree updates
- Nullifier tracking
- Ragequit operations
- The ASP layer interacts through:
- Root updates via authorized postman
- Label verification during withdrawals
### State management basics
Each Privacy Pool maintains:
1. **Tree State**
- Lean Incremental Merkle Tree (LeanIMT) for commitments
- Dynamic depth that grows with insertions
- Cached roots for historical validation
2. **Nullifier Registry**
- Tracks spent nullifiers to prevent double-spending
3. **Deposit Records**
- Maps labels to original depositor addresses
- Tracks deposit amounts
- Enables direct recovery through ragequit

117
docs/docs/layers/contracts/entrypoint.md Normal file
View File

@@ -0,0 +1,117 @@
---
title: Entrypoint
---
The Entrypoint contract acts as the central coordinator for the Privacy Pool protocol, managing:
1. Asset-specific privacy pools
2. Deposits and withdrawal relays
3. Association Set Provider (ASP) root updates
4. Protocol fees and configurations
It follows the UUPS (Universal Upgradeable Proxy Standard) pattern and uses OpenZeppelin's AccessControl for role-based permissions.
## Key Components
### State Management
The contract maintains several key state variables:
```solidity
mapping(uint256 _scope => IPrivacyPool _pool) public scopeToPool;
mapping(IERC20 _asset => AssetConfig _config) public assetConfig;
AssociationSetData[] public associationSets;
```
- `scopeToPool`: Maps pool identifiers to their contract addresses
- `assetConfig`: Stores configurations for each supported asset
- `associationSets`: Maintains an array of ASP root data for withdrawal validations
### Access Control
Two main roles control the contract:
- `OWNER_ROLE`: Can register/remove pools and manage configurations
- `ASP_POSTMAN`: Can update ASP roots that validate withdrawals
## Core Functionality
### 1. Deposit Flow
The contract supports both native ETH and ERC20 deposits:
```solidity
function deposit(uint256 _precommitment) external payable returns (uint256 _commitment);
function deposit(IERC20 _asset, uint256 _value, uint256 _precommitment) external returns (uint256 _commitment);
```
The deposit process:
1. Validates minimum deposit amount
2. Calculates and deducts protocol fees
3. Forwards remaining funds to appropriate privacy pool
4. Returns commitment hash for future withdrawals
### 2. Withdrawal Relay
```solidity
function relay(IPrivacyPool.Withdrawal calldata _withdrawal, ProofLib.WithdrawProof calldata _proof) external nonReentrant
```
Handles private withdrawals by:
1. Verifying withdrawal proofs
2. Processing withdrawals through privacy pools
3. Distributing funds between recipient and relayer (if used)
4. Enforcing security checks on pool state
### 3. Pool Management
Provides functions for pool lifecycle management:
```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;
```
These functions allow:
- Registration of new privacy pools
- Removal of existing pools
- Configuration updates
- Graceful shutdown of pools
### 4. ASP Root Management
```solidity
function updateRoot(uint256 _root, bytes32 _ipfsHash) external returns (uint256 _index);
```
Maintains withdrawal validation data:
1. Stores new ASP roots
2. Links to IPFS data containing validation details
3. Tracks root update timestamps
### Security Features
1. **Reentrancy Protection**: Uses OpenZeppelin's ReentrancyGuard
2. **Access Control**: Role-based permissions for sensitive operations
3. **Fee Validation**: Ensures fees cannot exceed 100%
4. **Balance Verification**: Checks pool state consistency after operations
5. **Upgradability**: UUPS pattern with owner-controlled upgrades
### Fee Management
The contract handles two types of fees:
1. **Vetting Fees**: Charged on deposits, controlled by pool configuration
2. **Relay Fees**: Optional fees for relayed withdrawals
Fees can be withdrawn by the owner:
```solidity
function withdrawFees(IERC20 _asset, address _recipient) external;
```

158
docs/docs/layers/contracts/privacy-pools.md Normal file
View File

@@ -0,0 +1,158 @@
---
title: Privacy Pools
---
The PrivacyPool contract is an abstract contract that implements core privacy pool functionality for both native ETH and ERC20 tokens. It:
1. Manages commitments and nullifiers
2. Processes deposits and withdrawals
3. Handles merkle tree state
4. Validates zero-knowledge proofs
The contract extends the State base contract which manages the merkle tree and nullifier state.
## Key Components
### State Management
Inherits key state variables from the State contract:
```solidity
string public constant VERSION = '0.1.0';
uint32 public constant ROOT_HISTORY_SIZE = 30;
IEntrypoint public immutable ENTRYPOINT;
IVerifier public immutable WITHDRAWAL_VERIFIER;
IVerifier public immutable RAGEQUIT_VERIFIER;
uint256 public nonce;
bool public dead;
```
And adds pool-specific state:
```solidity
uint256 public immutable SCOPE;
address public immutable ASSET;
```
## Core Data Structures
### Withdrawal Struct
```solidity
struct Withdrawal {
address processooor; // Allowed address to process withdrawal
uint256 scope; // Unique pool identifier
bytes data; // Encoded arbitrary data used by Entrypoint
}
```
## Core Functionality
### 1. Deposit Processing
```solidity
function deposit(
address _depositor,
uint256 _value,
uint256 _precommitmentHash
) external payable onlyEntrypoint returns (uint256 _commitment)
```
The deposit flow:
1. Validates pool is active
2. Computes unique label from scope and nonce
3. Records deposit details and ragequit cooldown
4. Computes and stores commitment hash
5. Updates merkle tree state
6. Pulls funds from depositor
### 2. Withdrawal Processing
```solidity
function withdraw(
Withdrawal memory _withdrawal,
ProofLib.WithdrawProof memory _proof
) external validWithdrawal(_withdrawal, _proof)
```
Handles withdrawals by:
1. Validating withdrawal proof
2. Verifying state root and ASP root
3. Spending nullifier hash
4. Inserting new commitment
5. Transferring funds to processor
### 3. Ragequit Functionality
```solidity
function ragequit(ProofLib.RagequitProof memory _proof) external
```
Allows original depositors to:
1. Reclaim funds when ASP excludes them
2. Verify they are original depositor
3. Spend nullifier hash
4. Receive back deposited funds
### 4. Wind Down Capability
```solidity
function windDown() external onlyEntrypoint
```
Allows graceful shutdown:
1. Marks pool as dead
2. Prevents new deposits
3. Allows existing withdrawals
### Security Features
1. **Access Control**:
- `onlyEntrypoint` modifier for sensitive operations
- `validWithdrawal` modifier for proof validation
1. **Withdrawal Validation**:
```solidity
modifier validWithdrawal(Withdrawal memory _withdrawal, ProofLib.WithdrawProof memory _proof) {
// Check caller is allowed processor
if (msg.sender != _withdrawal.processooor) revert InvalidProcesooor();
// Verify context integrity
if (_proof.context() != uint256(keccak256(abi.encode(_withdrawal, SCOPE)))) {
revert ContextMismatch();
}
// Validate roots
if (!_isKnownRoot(_proof.stateRoot())) revert UnknownStateRoot();
if (_proof.ASPRoot() != ENTRYPOINT.latestRoot()) revert IncorrectASPRoot();
_;
}
```
1. **Proof Verification**:
- Validates zero-knowledge proofs using Groth16 verifiers
- Verifies nullifier hash uniqueness
- Checks commitment existence
### Asset Handling
The contract is abstract and requires implementation of two key functions:
```solidity
function _pull(address _sender, uint256 _value) internal virtual;
function _push(address _recipient, uint256 _value) internal virtual;
```
These are implemented differently for:
- Native ETH (PrivacyPoolSimple)
- ERC20 tokens (PrivacyPoolComplex)
The PrivacyPool contract provides a robust foundation for implementing privacy-preserving asset pools, with strong security guarantees and efficient state management. It's designed to be extended for specific asset types while maintaining consistent privacy and security properties.

73
docs/docs/layers/zk.md Normal file
View File

@@ -0,0 +1,73 @@
---
title: Circuit Architecture Overview
---
The Privacy Pool protocol uses three main Circom circuits:
1. **CommitmentHasher Circuit**
- Computes commitment hashes from inputs
- Generates precommitment and nullifier hashes
- Uses Poseidon hash for efficient ZK computation
2. **LeanIMTInclusionProof Circuit**
- Verifies membership in Lean Incremental Merkle Trees
- Computes path from leaf to root
- Validates hashes for each tree level
- Accommodates dynamic tree depth
3. **Withdrawal Circuit**
- Combines commitment and Merkle tree proofs
- Verifies ownership of existing commitment
- Validates new commitment creation
- Checks ASP root inclusion
## Commitments
Commitments are cryptographic primitives that allow users to commit to values while keeping them private. In Privacy Pool:
1. **Components**
- Value: The amount of assets being committed
- Label: Unique identifier from pool scope and nonce
- Nullifier: Secret value preventing double-spending
- Secret: Random value proving ownership
2. **Hash Construction**
```tsx
nullifierHash = PoseidonHash(nullifier);
precommitmentHash = PoseidonHash(nullifier, secret);
commitmentHash = PoseidonHash(value, label, precommitmentHash);
```
### Basic Proof Concepts
Privacy Pool uses Groth16 proofs with the following structure:
1. **Public Inputs**
- Values visible on-chain
- Examples: withdrawal amount, roots, context
- Used for on-chain verification
2. **Private Inputs**
- Values kept secret by the prover
- Examples: nullifiers, secrets, siblings
- Used to generate proofs
3. **Circuit Signals**
- Internal values computed during proving
- Enforce mathematical constraints
- Connect public and private inputs
### Verification Flow
1. **Proof Generation**
- User provides private and public inputs
- Circuit computes internal signals
- Generates Groth16 proof elements:
- π_A: First elliptic curve point
- π_B: Second elliptic curve point (2x2 matrix)
- π_C: Third elliptic curve point
2. **On-chain Verification**
- Contract receives proof and public signals
- Verifier performs pairing checks
- Validates against verification key
- Returns boolean indicating validity
3. **Proof Integration**
- Proofs linked to protocol operations
- Results determine state transitions
- Failed verifications revert transactions

23
docs/docs/layers/zk/commitment.md Normal file
View File

@@ -0,0 +1,23 @@
---
title: Commitment Circuit
---
The commitment circuit (`commitment.circom`) handles the creation and verification of commitments:
```cpp
template CommitmentHasher() {
signal input value; // Value being committed
signal input label; // keccak256(pool_scope, nonce)
signal input nullifier; // Unique nullifier
signal input secret; // Secret value
signal output commitment; // Final commitment hash
signal output nullifierHash; // Hashed nullifier
}
```
Key operations:
1. Nullifier hashing: `nullifierHash = Poseidon([nullifier])`
2. Precommitment: `precommitmentHash = Poseidon([nullifier, secret])`
3. Final commitment: `commitment = Poseidon([value, label, precommitmentHash])`

23
docs/docs/layers/zk/lean-imt.md Normal file
View File

@@ -0,0 +1,23 @@
---
title: LeanIMT Circuit
---
The merkle tree circuit (`merkleTree.circom`) implements efficient inclusion proofs:
```cpp
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
}
```
Key features:
- Dynamic tree depth
- Optimized batch processing
- Single-child node optimization
- Path validation

42
docs/docs/layers/zk/withdrawal.md Normal file
View File

@@ -0,0 +1,42 @@
---
title: Withdrawal Circuit
---
The withdrawal circuit (`withdraw.circom`) handles private withdrawals:
```cpp
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;
}
```
Circuit constraints:
1. Validates existing commitment in state tree
2. Verifies label inclusion in ASP tree
3. Ensures withdrawn amount is valid
4. Computes new commitment for remaining value
5. Checks the existing and new nullifier don't match
6. Verifies context matches on-chain data

44
docs/docs/overview/core-concepts.md Normal file
View File

@@ -0,0 +1,44 @@
---
title: Core Concepts
---
### Zero-knowledge proofs in Privacy Pool
Privacy Pool uses zero-knowledge proofs to demonstrate valid statements about private information without revealing that information. The protocol employs three proof types:
- **Commitment Proofs**: Verify the ownership of a commitment
- **Withdrawal Proofs**: Verify ownership and inclusion in state of a commitment
- **Merkle Proofs**: Demonstrate membership in a tree without revealing position
### Commitments and nullifiers
A PrivacyPool commitment is a note for some value deposited in a Pool composed of:
- **`value`**: The amount being committed
- **`label`**: A unique identifier derived from scope and nonce
- **`nullifier`**: A secret that prevents double-spending
- **`secret`**: A value that helps hide the nullifier
The protocol uses:
- **Commitment Hash**: `PoseidonHash(value, label, precommitmentHash)`
- **Precommitment Hash**: `PoseidonHash(nullifier, secret)`
- **Nullifier Hash**: `PoseidonHash(nullifier)`
These values enable secure state transitions while maintaining privacy.
### Basic operations
- **Deposit**
- User generates commitment components
- Deposits funds and submits commitment to pool
- Commitment is added to the state tree
- **Withdrawal**
- User proves ownership of an existing commitment
- Creates new commitment for remaining funds
- Marks previous commitment as spent
- Receives withdrawn assets
- **Ragequit**
- Original depositor proves ownership of a commitment
- Recovers full remaining deposit value
- Marks commitment as spent

38
docs/docs/overview/what-is-privacy-pools.md Normal file
View File

@@ -0,0 +1,38 @@
---
title: What is Privacy Pools?
slug: /
---
### The challenge of private transactions
On public blockchains like Ethereum, every transaction is visible to everyone. While this transparency is a core feature, it creates significant privacy challenges and risks for users . When withdrawing funds from a deposit, the link between deposit and withdrawal addresses reveals sensitive information about user behavior and relationships.
### Privacy Pools offers a solution
Privacy Pool enables private withdrawals through a combination of zero-knowledge proofs and commitment schemes. Users can deposit assets into Privacy Pools and later withdraw them, either partially or fully, without creating an on-chain link between their deposit and withdrawal addresses. The protocol uses an Association Set Provider (ASP) to maintain a set of approved deposits, ensuring regulatory compliance while preserving privacy.
### System architecture overview
Privacy Pool's architecture consists of three distinct layers:
1. **Contract Layer**
- An upgradeable Entrypoint contract that coordinates ASP-operated pools
- Asset-specific PrivacyPools that hold funds and manage state
2. **Zero-Knowledge Layer**
- Commitment circuits for secure deposit registration
- Withdrawal circuits that enable private asset withdrawals
- On-chain verifiers that validate circuit proofs
3. **Association Set Provider (ASP) Layer**
- Maintains the current set of approved deposit labels
- Updates state through authorized accounts
- Enables regulatory compliance without compromising privacy
These layers work together to create a secure privacy-preserving system: the contract layer manages assets and state, the zero-knowledge layer ensures privacy, and the ASP layer provides compliance capabilities.
### Key features and capabilities
- **Partial Withdrawals**: Users can withdraw portions of their deposits while maintaining privacy.
- **Multi-Asset Support**: Supports both native cryptocurrency and ERC20 tokens.
- **Compliance Integration**: ASP-based approval system for regulatory compliance.
- **Non-Custodial**: Users maintain control of their funds through cryptographic commitments.
- **Ragequit Mechanism**: Allows original depositors to recover funds if their funds are not approved by the ASP by **publicly** exiting the pool.

96
docs/docs/protocol/deposit.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: Deposit
---
The deposit operation is the entry point into the Privacy Pool protocol. It allows users to publicly deposit assets (ETH or ERC20 tokens) into a pool, creating a private commitment that can later be used for private withdrawals or public ragequit operations.
## Protocol Flow
```mermaid
sequenceDiagram
participant User
participant SDK
participant Entrypoint
participant Pool
Note over User: Generate random:<br/>nullifier, secret
User->>SDK: Prepare deposit
activate SDK
SDK->>SDK: Compute precommitment<br/>hash(nullifier, secret)
SDK-->>User: precommitment
deactivate SDK
alt ERC20 Deposit
User->>Entrypoint: approve(amount)
User->>Entrypoint: deposit(token, amount, precommitment)
else ETH Deposit
User->>Entrypoint: deposit{value: amount}(precommitment)
end
activate Entrypoint
Entrypoint->>Entrypoint: Deduct fees
Entrypoint->>Pool: deposit(msg.sender, value, precommitment)
deactivate Entrypoint
activate Pool
Pool->>Pool: Generate label<br/>Insert commitment
Pool-->>User: Emit Deposited(commitment, label)
deactivate Pool
Note over User: Store: nullifier, secret,<br/>label, value
```
### Commitment Structure
The deposit process creates a commitment with the following structure:
```mermaid
graph TD
A[Commitment Hash] --> B[Value]
A --> C[Label]
A --> D[Precommitment Hash]
D --> E[Nullifier]
D --> F[Secret]
```
### Parameters
| Parameter | Description |
| --------------- | ------------------------------------------------------------------------------- |
| `value` | The deposit amount after fees |
| `label` | `keccak256(scope, nonce)` where scope is pool-specific and nonce is incremental |
| `nullifier` | Random value used to create unique commitments |
| `secret` | Random value that helps secure the commitment |
| `precommitment` | Hash(nullifier, secret) |
### Deposit Steps
1. **Input Preparation**
- User generates random `nullifier` and `secret` values
- User computes `precommitment = hash(nullifier, secret)`
1. **Deposit Transaction**
- User calls Entrypoint's deposit function with asset, amount, and precommitment
- For ETH: `deposit(precommitment)` with ETH value
- For ERC20: `deposit(token, amount, precommitment)` after approval
1. **Fee Processing**
- Entrypoint calculates and retains vetting fee (configurable per pool)
- Remaining amount is forwarded to pool
1. **Commitment Generation**
- Pool generates unique `label` using scope and incremental nonce
- Computes commitment hash using value, label, and precommitment
- Inserts commitment into state Merkle tree
### Fee Structure
- Vetting fee: Configurable percentage (in basis points) taken by Entrypoint
- Example: 100 basis points = 1% fee

74
docs/docs/protocol/ragequit.md Normal file
View File

@@ -0,0 +1,74 @@
---
title: Ragequit
---
Ragequit is a safety mechanism that allows the original depositor to publicly withdraw their funds without needing ASP approval. This operation serves as a critical backup withdrawal method which ensures the ability to withdraw user funds when the label is not approved by the ASP or its approval was revoked (removed from the approved labels set).
## Protocol Flow
```mermaid
sequenceDiagram
participant User as Original Depositor
participant SDK
participant Pool
participant State as State Tree
participant RQ as RagequitVerifier
Note over User,State: User has original commitment parameters<br/>(value, label, nullifier, secret)
User->>SDK: Generate ragequit proof
activate SDK
SDK->>SDK: Compute commitment hash
SDK->>SDK: Compute precommitment hash
SDK->>SDK: Compute nullifier hash
Note over SDK: Package proof with:<br/>- Commitment hash<br/>- Value<br/>- Label
SDK-->>User: Return ragequit proof
deactivate SDK
User->>Pool: ragequit(proof)
activate Pool
Pool->>State: Check commitment exists
alt Commitment not found
Pool-->>User: Revert: InvalidCommitment
end
Pool->>Pool: Verify caller is original depositor
alt Not original depositor
Pool-->>User: Revert: OnlyOriginalDepositor
end
Pool->>RQ: Verify proof
alt Invalid proof
Pool-->>User: Revert: InvalidProof
end
Pool->>State: Mark nullifier as spent
alt Nullifier already spent
Pool-->>User: Revert: NullifierAlreadySpent
end
Pool->>User: Transfer full commitment value
Pool->>Pool: Emit Ragequit event
deactivate Pool
Note over User,State: Funds returned to original depositor<br/>Commitment permanently spent
```
### Ragequit steps
1. Check Requirements
- Must be original depositor
- Commitment must not be already spent
2. Generate Proof
3. Call the `ragequit` method with the proof
4. Finalized ragequit
- User received the full commitment amount

162
docs/docs/protocol/withdrawal.md Normal file
View File

@@ -0,0 +1,162 @@
---
title: Withdrawal
---
Privacy Pool supports two types of withdrawals:
1. **Direct Withdrawals**: User directly interacts with pool contract
2. **Relayed Withdrawals**: Withdrawal processed through a relayer for additional privacy
Both methods require zero-knowledge proofs to prove commitment ownership and maintain privacy.
### Withdrawal Types Comparison
| Aspect | Direct Withdrawal | Relayed Withdrawal |
| ------------------------ | ------------------ | --------------------------------------- |
| Privacy Level | Basic | Enhanced (different withdrawal address) |
| Gas Payment | User pays directly | Relayer pays, takes fee |
| Fee Structure | No fees | Configurable relayer fee |
| Complexity | Simpler flow | Additional fee computation |
| Front-running Protection | Context-based | Context-based |
### Protocol Flow - Direct Withdrawal
```mermaid
sequenceDiagram
participant User
participant SDK
participant Pool
participant Entrypoint
Note over User: Has: nullifier, secret,<br/>label, value
User->>SDK: Prepare withdrawal(amount)
activate SDK
Note over SDK: Generate:<br/>newNullifier, newSecret
SDK->>SDK: Compute remaining value
SDK->>SDK: Generate Withdrawal proof
SDK-->>User: withdrawalProof
deactivate SDK
User->>Pool: withdraw(withdrawal, proof)
activate Pool
Pool->>Pool: Verify processooor is recipient
Pool->>Entrypoint: Check proof uses latest ASP root
Pool->>Pool: Verify proof
Pool->>Pool: Update state<br/>Record spent nullifier
Pool->>User: Transfer amount
Pool-->>User: Emit Withdrawn
deactivate Pool
Note over User: Store new secrets<br/>for remaining balance
```
### Protocol Flow - Relayed Withdrawal
```mermaid
sequenceDiagram
participant User
participant SDK
participant Relayer
participant Entrypoint
participant Pool
Note over User: Has: nullifier, secret,<br/>label, value
User->>SDK: Prepare withdrawal(amount, relayer)
activate SDK
Note over SDK: Generate:<br/>newNullifier, newSecret
SDK->>SDK: Compute remaining value
SDK->>SDK: Generate Withdrawal proof
SDK-->>User: withdrawalProof
deactivate SDK
User->>Relayer: Submit withdrawal + proof
Relayer->>Relayer: Verify proof locally
Relayer->>Entrypoint: relay(withdrawal, proof)
activate Entrypoint
Entrypoint->>Pool: withdraw(withdrawal, proof)
activate Pool
Pool->>Pool: Verify processooor is Entrypoint
Pool->>Pool: Verify proof
Pool->>Entrypoint: Check proof uses latest ASP root
Pool->>Pool: Update state<br/>Record spent nullifier
Pool->>Entrypoint: Transfer full amount
deactivate Pool
Entrypoint->>Entrypoint: Calculate fees
Entrypoint->>User: Transfer(amount - fees)
Entrypoint->>Relayer: Pay relayer fee
Entrypoint-->>User: Emit WithdrawalRelayed
deactivate Entrypoint
Note over User: Store new secrets<br/>for remaining balance
```
### Withdrawal Data Structure
```solidity
struct Withdrawal {
address processooor; // Direct: recipient, Relayed: Entrypoint
uint256 scope; // Pool identifier
bytes data; // Direct: empty, Relayed: encoded `FeeData`
}
struct FeeData {
address recipient; // Final recipient
address feeRecipient; // Relayer address
uint256 relayFeeBPS; // Fee in basis points
}
```
## Withdrawal Steps
### Direct Withdrawal
1. **Proof Generation**
- User constructs withdrawal parameters
- Generates ZK proof of commitment ownership
- Computes new commitment for remaining value
2. **Contract Interaction**
- User submits proof to pool contract
- Pool verifies proof and context
- Updates state (nullifiers, commitments)
- Transfers assets to recipient
### Relayed Withdrawal
1. **User Steps**
- Construct withdrawal with Entrypoint as processooor
- Generate ZK proof
- Submit to relayer off-chain
2. **Relayer Steps**
- Verify proof locally
- Submit transaction to Entrypoint
- Pay gas fees
3. **Entrypoint Processing**
- Verify proof and context
- Process withdrawal through pool
- Handle fee distribution
- Transfer assets to recipient
### Context Generation
The `context` signal binds the proof to specific withdrawal parameters:
```solidity
context = uint256(keccak256(abi.encode(
withdrawal,
pool.SCOPE()
))) % SNARK_SCALAR_FIELD;
```

53
docs/docs/reference/circuits.md Normal file
View File

@@ -0,0 +1,53 @@
---
title: Circuits Interfaces
---
**`CommitmentHasher`**
Creates commitment proofs using Poseidon hash.
```
Public Inputs:
- value: Amount being committed
- label: keccak256(scope, nonce)
Private Inputs:
- nullifier: Unique nullifier for commitment
- secret: Secret for commitment
Public Outputs:
- commitment: Poseidon(value, label, Poseidon(nullifier, secret))
- precommitmentHash: Poseidon(nullifier, secret)
- nullifierHash: Poseidon(nullifier)
```
**`Withdraw`**
Validates withdrawal proofs.
```
Public Inputs:
- withdrawnValue: Amount being withdrawn
- stateRoot: Current state root
- stateTreeDepth: Current state tree depth
- ASPRoot: Latest ASP root
- ASPTreeDepth: Current ASP tree depth
- context: keccak256(scope, Withdrawal)
Private Inputs:
- label: keccak256(scope, nonce)
- existingValue: Value of existing commitment
- existingNullifier: Nullifier of existing commitment
- existingSecret: Secret of existing commitment
- newNullifier: Nullifier for new commitment
- newSecret: Secret for new commitment
- stateSiblings[]: State tree merkle proof
- stateIndex: Index in state tree
- ASPSiblings[]: ASP tree merkle proof
- ASPIndex: Index in ASP tree
Public Outputs:
- newCommitmentHash: Hash of new commitment
- existingNullifierHash: Hash of spent nullifier
```

86
docs/docs/reference/contracts.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: Contracts Interfaces
---
**`IPrivacyPool`**
Core interface for privacy pool smart contracts that handle deposits and withdrawals.
```solidity
interface IPrivacyPool {
struct Withdrawal {
address processooor; // Allowed address to process withdrawal
uint256 scope; // Unique pool identifier
bytes data; // Encoded arbitrary data for Entrypoint
}
// Core Functions
function deposit(
address depositor,
uint256 value,
uint256 precommitment
) external payable returns (uint256 commitment);
function withdraw(
Withdrawal memory w,
ProofLib.WithdrawProof memory p
) external;
function ragequit(ProofLib.RagequitProof memory p) external;
// View Functions
function SCOPE() external view returns (uint256);
function ASSET() external view returns (address);
}
```
**`IEntrypoint`**
Central registry and coordinator for privacy pools.
```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
);
}
```

101
docs/docs/reference/sdk.md Normal file
View File

@@ -0,0 +1,101 @@
---
title: SDK Utilities
---
### `PrivacyPoolSDK`
Main SDK class providing high-level protocol interaction.
```tsx
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>;
}
```
### Crypto Utilities
Core cryptographic operations.
```tsx
// 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>;
```
### Types
```tsx
interface Commitment {
hash: Hash; // Commitment hash
nullifierHash: Hash; // Hash of nullifier
preimage: {
value: bigint; // Committed value
label: bigint; // Commitment label
precommitment: {
// Precommitment data
hash: Hash; // Precommitment hash
nullifier: Secret; // Nullifier value
secret: Secret; // Secret value
};
};
}
interface WithdrawalProofInput {
withdrawalAmount: bigint; // Amount to withdraw
context: bigint; // Proof context
stateMerkleProof: {
// State tree proof
root: bigint;
leaf: bigint;
index: number;
siblings: bigint[];
};
aspMerkleProof: {
// ASP tree proof
root: bigint;
leaf: bigint;
index: number;
siblings: bigint[];
};
stateRoot: bigint; // Current state root
stateTreeDepth: number; // State tree depth
aspRoot: bigint; // Current ASP root
aspTreeDepth: number; // ASP tree depth
newSecret: bigint; // New secret
newNullifier: bigint; // New nullifier
}
```

96
docs/docusaurus.config.ts Normal file
View File

@@ -0,0 +1,96 @@
import { themes as prismThemes } from "prism-react-renderer";
import type { Config } from "@docusaurus/types";
import type * as Preset from "@docusaurus/preset-classic";
// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
const config: Config = {
title: "Privacy Pools Documentation",
tagline: "Technical documentation for Privacy Pools protocol",
favicon: "img/favicon.ico",
// Set the production url of your site here
url: "https://docs.privacypools.com",
// Set the /<baseUrl>/ pathname under which your site is served
// For GitHub pages deployment, it is often '/<projectName>/'
baseUrl: "/",
// GitHub pages deployment config.
// If you aren't using GitHub pages, you don't need these.
organizationName: "0xbow-io", // Usually your GitHub org/user name.
projectName: "privacy-pools-core", // Usually your repo name.
onBrokenLinks: "throw",
onBrokenMarkdownLinks: "warn",
markdown: {
mermaid: true,
},
themes: ["@docusaurus/theme-mermaid"],
// Even if you don't use internationalization, you can use this field to set
// useful metadata like html lang. For example, if your site is Chinese, you
// may want to replace "en" with "zh-Hans".
i18n: {
defaultLocale: "en",
locales: ["en"],
},
presets: [
[
"classic",
{
docs: {
sidebarPath: "./sidebars.ts",
routeBasePath: "/",
editUrl:
"https://github.com/0xbow-io/privacy-pools-core/tree/main/docs/",
},
blog: false,
theme: {
customCss: "./src/css/custom.css",
},
} satisfies Preset.Options,
],
],
themeConfig: {
// Replace with your project's social card
image: "img/docusaurus-social-card.jpg",
sidebar: {
autoCollapseCategories: false,
},
navbar: {
title: "Privacy Pools Documentation",
logo: {
alt: "Privacy Pools Logo",
src: "img/logo.svg",
},
items: [
{
href: "https://github.com/0xbow-io/privacy-pools-core",
label: "GitHub",
position: "right",
},
],
},
footer: {
style: "dark",
copyright: `Copyright © ${new Date().getFullYear()} 0XBOW LTD`,
},
prism: {
theme: prismThemes.github,
darkTheme: prismThemes.dracula,
additionalLanguages: ["solidity"],
},
docs: {
sidebar: {
hideable: false,
autoCollapseCategories: false,
},
},
} satisfies Preset.ThemeConfig,
};
export default config;

35
docs/mermaid-init.js
View File

@@ -1,35 +0,0 @@
(() => {
const darkThemes = ['ayu', 'navy', 'coal'];
const lightThemes = ['light', 'rust'];
const classList = document.getElementsByTagName('html')[0].classList;
let lastThemeWasLight = true;
for (const cssClass of classList) {
if (darkThemes.includes(cssClass)) {
lastThemeWasLight = false;
break;
}
}
const theme = lastThemeWasLight ? 'default' : 'dark';
mermaid.initialize({ startOnLoad: true, theme });
// Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
for (const darkTheme of darkThemes) {
document.getElementById(darkTheme).addEventListener('click', () => {
if (lastThemeWasLight) {
window.location.reload();
}
});
}
for (const lightTheme of lightThemes) {
document.getElementById(lightTheme).addEventListener('click', () => {
if (!lastThemeWasLight) {
window.location.reload();
}
});
}
})();

2186
docs/mermaid.min.js vendored
View File

File diff suppressed because one or more lines are too long

48
docs/package.json Normal file
View File

@@ -0,0 +1,48 @@
{
"name": "docs",
"version": "0.0.0",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids",
"typecheck": "tsc"
},
"dependencies": {
"@docusaurus/core": "3.7.0",
"@docusaurus/preset-classic": "3.7.0",
"@docusaurus/theme-mermaid": "^3.7.0",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"prism-react-renderer": "^2.3.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "3.7.0",
"@docusaurus/tsconfig": "3.7.0",
"@docusaurus/types": "3.7.0",
"typescript": "~5.6.2"
},
"browserslist": {
"production": [
">0.5%",
"not dead",
"not op_mini all"
],
"development": [
"last 3 chrome version",
"last 3 firefox version",
"last 5 safari version"
]
},
"engines": {
"node": ">=18.0"
}
}

74
docs/sidebars.ts Normal file
View File

@@ -0,0 +1,74 @@
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
- render a sidebar for each doc of that group
- provide next/previous navigation
The sidebars can be generated from the filesystem, or explicitly defined here.
Create as many sidebars as you want.
*/
const sidebars: SidebarsConfig = {
docs: [
{
type: "category",
label: "Overview",
collapsible: false,
items: ["overview/what-is-privacy-pools", "overview/core-concepts"],
},
{
type: "category",
label: "Protocol Components",
collapsible: false,
items: [
{
type: "category",
label: "Smart Contracts Layer",
collapsible: false,
link: {
type: "doc",
id: "layers/contracts",
},
items: [
"layers/contracts/entrypoint",
"layers/contracts/privacy-pools",
],
},
{
type: "category",
label: "Zero Knowledge Layer",
collapsible: false,
link: {
type: "doc",
id: "layers/zk",
},
items: [
"layers/zk/commitment",
"layers/zk/lean-imt",
"layers/zk/withdrawal",
],
},
"layers/asp",
],
},
{
type: "category",
collapsible: false,
label: "Using Privacy Pools",
items: ["protocol/deposit", "protocol/withdrawal", "protocol/ragequit"],
},
{
type: "category",
collapsible: false,
label: "Technical Reference",
items: ["reference/contracts", "reference/circuits", "reference/sdk"],
},
"dev-guide",
],
};
export default sidebars;

54
docs/src/SUMMARY.md
View File

@@ -1,54 +0,0 @@
# Summary
- [Overview](./introduction/overview.md)
- [Architecture](./introduction/architecture.md)
- [Key Concepts](./introduction/key-concepts.md)
- [Protocol Components](./introduction/concepts/components.md)
- [Protocol Mechanisms](./introduction/concepts/mechanisms.md)
- [Privacy Properties](./introduction/concepts/privacy.md)
- [Cryptographic Primitives](./introduction/concepts/primitives.md)
# Layers
- [Zero Knowledge](./layers/zero-knowledge/README.md)
- [Commitments](./layers/zero-knowledge/commitments.md)
- [Circuits](./layers/zero-knowledge/circuits/README.md)
- [Commitment Circuit](./layers/zero-knowledge/circuits/commitment.md)
- [Withdrawal Circuit](./layers/zero-knowledge/circuits/withdrawal.md)
- [Contracts](./layers/contracts/README.md)
- [Entrypoint](./layers/contracts/entrypoint/README.md)
- [Overview](./layers/contracts/entrypoint/overview.md)
- [Dependencies](./layers/contracts/entrypoint/dependencies.md)
- [Specification](./layers/contracts/entrypoint/specification/README.md)
- [State Variables](./layers/contracts/entrypoint/specification/state.md)
- [Data Structures](./layers/contracts/entrypoint/specification/data-structures.md)
- [Interface](./layers/contracts/entrypoint/specification/interface.md)
- [PrivacyPool](./layers/contracts/privacy-pool/README.md)
- [Overview](./layers/contracts/privacy-pool/overview.md)
- [Dependencies](./layers/contracts/privacy-pool/dependencies.md)
- [Specification](./layers/contracts/privacy-pool/specification/README.md)
- [Implementations](./layers/contracts/privacy-pool/specification/implementations.md)
- [State Variables](./layers/contracts/privacy-pool/specification/state.md)
- [Data Structures](./layers/contracts/privacy-pool/specification/data-structures.md)
- [Interface](./layers/contracts/privacy-pool/specification/interface.md)
<!---->
<!-- - [ASP](./layers/asp/README.md) -->
<!-- - [Overview](./layers/asp/overview.md) -->
<!-- - [Offchain Operation](./layers/asp/offchain-operation.md) -->
<!-- - [Wind Down](./layers/asp/wind-down.md) -->
<!---->
<!-- # Protocol Flows -->
<!---->
<!-- - [Deposit](./flows/deposit.md) -->
<!-- - [Withdrawal](./flows/withdrawal.md) -->
<!-- - [Ragequit](./flows/ragequit.md) -->
<!-- - [Running a Relayer](./flows/relayer.md) -->
<!---->
<!-- # Reference -->
<!---->
<!-- - [Glossary](./reference/glossary.md) -->
<!-- - [Deployment Addresses](./reference/deployment.md) -->

71
docs/src/components/HomepageFeatures/index.tsx Normal file
View File

@@ -0,0 +1,71 @@
import type {ReactNode} from 'react';
import clsx from 'clsx';
import Heading from '@theme/Heading';
import styles from './styles.module.css';
type FeatureItem = {
title: string;
Svg: React.ComponentType<React.ComponentProps<'svg'>>;
description: ReactNode;
};
const FeatureList: FeatureItem[] = [
{
title: 'Easy to Use',
Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
description: (
<>
Docusaurus was designed from the ground up to be easily installed and
used to get your website up and running quickly.
</>
),
},
{
title: 'Focus on What Matters',
Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
description: (
<>
Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
ahead and move your docs into the <code>docs</code> directory.
</>
),
},
{
title: 'Powered by React',
Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
description: (
<>
Extend or customize your website layout by reusing React. Docusaurus can
be extended while reusing the same header and footer.
</>
),
},
];
function Feature({title, Svg, description}: FeatureItem) {
return (
<div className={clsx('col col--4')}>
<div className="text--center">
<Svg className={styles.featureSvg} role="img" />
</div>
<div className="text--center padding-horiz--md">
<Heading as="h3">{title}</Heading>
<p>{description}</p>
</div>
</div>
);
}
export default function HomepageFeatures(): ReactNode {
return (
<section className={styles.features}>
<div className="container">
<div className="row">
{FeatureList.map((props, idx) => (
<Feature key={idx} {...props} />
))}
</div>
</div>
</section>
);
}

11
docs/src/components/HomepageFeatures/styles.module.css Normal file
View File

@@ -0,0 +1,11 @@
.features {
display: flex;
align-items: center;
padding: 2rem 0;
width: 100%;
}
.featureSvg {
height: 200px;
width: 200px;
}

187
docs/src/css/custom.css Normal file
View File

@@ -0,0 +1,187 @@
/**
* Any CSS included here will be global. The classic template
* bundles Infima by default. Infima is a CSS framework designed to
* work well for content-centric websites.
*/
/* You can override the default Infima variables here. */
:root {
/* Colors from the theme */
--ifm-color-primary: #000000;
--ifm-color-primary-dark: #262626;
--ifm-color-primary-darker: #1a1a1a;
--ifm-color-primary-darkest: #000000;
--ifm-color-primary-light: #4d4d4d;
--ifm-color-primary-lighter: #737373;
--ifm-color-primary-lightest: #999999;
/* Background and text colors */
--ifm-background-color: #ffffff;
--ifm-background-surface-color: #ffffff;
--ifm-font-color-base: #000000;
/* Code block colors */
--ifm-code-background: rgba(175, 184, 193, 0.2);
--ifm-code-font-size: 90%;
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
/* Font settings */
--ifm-font-family-base: "ibm_plex_mono", monospace;
--ifm-font-family-monospace: "ibm_plex_mono", monospace;
/* Typography scale */
--ifm-font-size-base: 1.4rem; /* 14px */
--ifm-font-size-tiny: 1rem; /* 10px */
--ifm-font-size-small: 1.2rem; /* 12px */
--ifm-font-size-medium: 1.4rem; /* 14px */
--ifm-font-size-large: 1.6rem; /* 16px */
--ifm-font-size-xl: 1.8rem; /* 18px */
--ifm-font-size-xxl: 2rem; /* 20px */
/* Heading sizes */
--ifm-h1-font-size: 2.4rem; /* 24px */
--ifm-h2-font-size: 2rem; /* 20px */
--ifm-h3-font-size: 1.8rem; /* 18px */
--ifm-h4-font-size: 1.6rem; /* 16px */
--ifm-h5-font-size: 1.4rem; /* 14px */
--ifm-h6-font-size: 1.2rem; /* 12px */
/* Border radius */
--ifm-code-border-radius: 4px;
--ifm-button-border-radius: 4px;
--ifm-card-border-radius: 0;
/* Border colors */
--ifm-color-emphasis-300: #b8bbbf;
--ifm-border-color: #000000;
}
/* For readability concerns, you should choose a lighter palette in dark mode. */
[data-theme="dark"] {
--ifm-color-primary: #ffffff;
--ifm-color-primary-dark: #b8bbbf;
--ifm-color-primary-darker: #999999;
--ifm-color-primary-darkest: #737373;
--ifm-color-primary-light: #f0f0f0;
--ifm-color-primary-lighter: #e6e6e6;
--ifm-color-primary-lightest: #ffffff;
/* Background and text colors */
--ifm-background-color: #000000;
--ifm-background-surface-color: #000000;
--ifm-font-color-base: #ffffff;
/* Code block colors */
--ifm-code-background: rgba(255, 255, 255, 0.1);
--docusaurus-highlighted-code-line-bg: rgba(255, 255, 255, 0.1);
/* Border colors */
--ifm-color-emphasis-300: #4d4d4d;
--ifm-border-color: #ffffff;
}
html {
font-size: 62.5%;
}
/* Improved code block styling */
.theme-code-block {
border: 1px solid var(--ifm-border-color);
border-radius: 0;
margin: 1rem 0;
background-color: var(--ifm-background-color);
}
.theme-code-block pre {
margin: 0;
font-family: var(--ifm-font-family-monospace);
background-color: var(--ifm-background-color) !important;
}
.prism-code {
padding: 1.5rem !important;
background-color: var(--ifm-background-color) !important;
font-size: var(--ifm-code-font-size) !important;
border-radius: 0;
}
/* Inline code styling */
code:not([class^="language-"]) {
background-color: rgba(175, 184, 193, 0.4);
border: none;
border-radius: var(--ifm-code-border-radius);
padding: 0.2rem 0.375rem;
font-size: 85%;
margin: 0 0.1rem;
font-family: var(--ifm-font-family-monospace);
font-weight: 550;
}
/* Remove background from code blocks */
.theme-code-block code {
background-color: transparent;
}
/* Code block title */
.theme-code-block > div:first-child {
background-color: var(--ifm-background-color) !important;
border-bottom: 1px solid var(--ifm-border-color);
font-family: var(--ifm-font-family-monospace);
}
/* Navbar customization */
.navbar {
border-bottom: 1px solid var(--ifm-border-color);
background-color: var(--ifm-background-color);
}
/* Sidebar customization */
.menu {
font-family: var(--ifm-font-family-base);
font-size: var(--ifm-font-size-base);
border-right: 1px solid var(--ifm-border-color);
}
/* Card customization */
.card {
border: 1px solid var(--ifm-border-color);
border-radius: 0;
background-color: var(--ifm-background-color);
}
/* Button customization */
.button {
border-radius: var(--ifm-button-border-radius);
font-weight: 500;
text-transform: none;
border: 1px solid var(--ifm-border-color);
}
/* Table customization */
.table {
border: 1px solid var(--ifm-border-color);
border-radius: 0;
}
.table th,
.table td {
border-color: var(--ifm-border-color);
}
/* Add this new section for main content styling */
.markdown {
font-size: 2rem; /* 22.4px for main content */
}
.markdown p {
font-size: 1.24rem; /* 22.4px for paragraphs */
}
.markdown li {
font-size: 1.24rem; /* 22.4px for list items */
}
/* Keep code blocks at a smaller size for readability */
.markdown code {
font-size: 1.16rem; /* 18px for code */
}

18
docs/src/flows/deposit.md
View File

@@ -1,18 +0,0 @@
# Deposit Flow
[OVERVIEW: Brief explanation of what a deposit is and its role in the privacy pool protocol]
## Process Flow
```mermaid
sequenceDiagram
```
## Step-by-Step Guide
### 1. Commitment Generation
### 2. Asset Approval (ERC20 only)
### 3. Deposit Transaction

19
docs/src/flows/ragequit.md
View File

@@ -1,19 +0,0 @@
# Ragequit Flow
[OVERVIEW: Explanation of ragequit mechanism and its purpose in the protocol]
## When to Ragequit
[SCENARIOS: List of scenarios where ragequit is appropriate]
## Process Flow
```mermaid
sequenceDiagram
```
## Step-by-Step Guide
### 1. Ragequit Proof Generation
### 2. Transaction Submission

17
docs/src/flows/relayer.md
View File

@@ -1,17 +0,0 @@
# Running a Relayer
[OVERVIEW: Introduction to relayers and their role in the protocol]
## Process Flow
```mermaid
sequenceDiagram
```
## Step-by-Step Guide
## Fee Management
### Fee Structure
[FEE_STRUCTURE: How to set and manage fees]

17
docs/src/flows/withdrawal.md
View File

@@ -1,17 +0,0 @@
# Withdrawal Flow
[OVERVIEW: Explanation of withdrawal process and its privacy implications]
## Process Flow
```mermaid
sequenceDiagram
```
## Step-by-Step Guide
### 1. Proof Generation
### 2.1. Withdraw through relayer
### 2.2. Direct Withdrawal

1
docs/src/introduction/README.md
View File

@@ -1 +0,0 @@
# Introduction

28
docs/src/introduction/architecture.md
View File

@@ -1,28 +0,0 @@
# Architecture
## System Components
The Privacy Pool protocol consists of three main layers:
1. **Zero-Knowledge Layer**: Contains the Circom circuits for generating and verifying zero-knowledge proofs. The key components are:
- `CommitmentHasher` circuit
- `LeanIMTInclusionProof` circuit
- `Withdraw` circuit
These circuits enable privacy-preserving transactions while maintaining the integrity of the system state.
2. **Contracts Layer**: Implements the core protocol logic and manages the state of the Privacy Pools. The main contracts are:
- `Entrypoint`: Serves as the main entrypoint for user interactions and manages multiple APS-operated Privacy Pools.
- `PrivacyPool`: Represents a pool for a specific asset type (ERC20 or native). Handles deposits, withdrawals, and ragequits.
- Verifiers: Contracts for verifying the zero-knowledge proofs generated by the circuits.
3. **Association Set Provider (ASP)**: An off-chain service that approves valid withdrawal labels. The ASP maintains a merkle tree of approved labels, which is periodically updated on the Entrypoint contract.
### System Actors
The actors in the Privacy Pool system are:
1. **Users**: Interact with the protocol to deposit, withdraw, and ragequit assets. Users generate zero-knowledge proofs to maintain privacy.
2. **ASP Operators**: Approves valid withdrawal labels and updates the merkle root on the Entrypoint contract.

13
docs/src/introduction/concepts/components.md
View File

@@ -1,13 +0,0 @@
# Protocol Components
## Commitments
A commitment is a cryptographic primitive that allows a user to prove ownership of value privately. In the Privacy Pool protocol, commitments are used to represent a user's ownership of value in a pool. The commitment is a hash of the owned amount, a unique label, and a secret value known only to the user.
## Association Sets
An association set is a merkle tree maintained by an off-chain service called the Association Set Provider (ASP). The ASP approves valid withdrawal labels by including them in the association set. The merkle root of the association set is periodically updated on the Entrypoint contract, allowing users to prove the validity of their withdrawal labels using merkle proofs.
## Zero-Knowledge Proofs
Zero-knowledge proofs (ZKPs) are cryptographic constructs that allow a prover to convince a verifier of the validity of a statement without revealing any additional information. In the Privacy Pool protocol, ZKPs are used to prove the validity of withdrawal and ragequit operations while preserving privacy of the users depending on the operation.

13
docs/src/introduction/concepts/mechanisms.md
View File

@@ -1,13 +0,0 @@
# Protocol Mechanisms
## Deposit Process
To deposit assets into a Privacy Pool, a user generates a commitment by depositing some amount along with a secret value to the Entrypoint. A commitment is generated on-chain which is added to appropriate pool's state merkle tree. The depositor's address and the specific deposit amount is revealed on-chain.
## Withdrawal Process
To withdraw assets from a Privacy Pool, a user generates a zero-knowledge proof that demonstrates the the ownership of some value in the pool and that the original deposit was approved by an ASP. The proof includes a merkle proof of the commitment's inclusion in the pool's state tree and a merkle proof of the label's inclusion in the ASP's association set. The recipient's address and the withdrawn amount are revealed on-chain.
## Ragequit Process
Ragequit is a withdrawal mechanism that allows users to withdraw their funds from a pool **while revealing their identity**. This allows users who have not been approved by an ASP to retrieve their funds without providing privacy. To ragequit, a user generates a zero-knowledge proof that proves the ownership a commitment and submits it to the PrivacyPool contract. The contract verifies the proof and transfers the funds to the user.

30
docs/src/introduction/concepts/primitives.md
View File

@@ -1,30 +0,0 @@
# Cryptographic Primitives
## Hash Functions
The Privacy Pool protocol uses the Poseidon hash function for various purposes, including:
- Hashing secrets
- Hashing commitments
- Building merkle trees
Poseidon is a custom hash function designed for efficient use in zero-knowledge proof systems.
## Merkle Trees
```mermaid
graph TD
R[Merkle Root] --> AB["Hash(A,B)"]
R --> CD["Hash(C,D)"]
AB --> A(Leaf A)
AB --> B(Leaf B)
CD --> C(Leaf C)
CD --> D(Leaf D)
```
The Privacy Pool protocol uses a variant of merkle trees called Lean Incremental merkle Trees (LeanIMT). LeanIMTs are designed to efficiently support insertion and updating of leaves while maintaining a minimal tree depth. They are used for the following purposes:
- Representing the state of a Privacy Pool (commitments)
- Representing the ASP's association set (approved deposit labels)
Merkle trees enable efficient verification of inclusion proofs, which are used in the withdrawal processe to prove the existance of a commitment or label without revealing the its value.

23
docs/src/introduction/concepts/privacy.md
View File

@@ -1,23 +0,0 @@
# Privacy
## Privacy Sets
In the Privacy Pool protocol, a privacy set refers to a group of users who have deposited assets into a pool. The privacy set provides anonymity for individual users, as their specific actions (deposits, withdrawals) are not directly linked to their identities.
## Anonymity
Anonymity in the Privacy Pool protocol is achieved through the use of zero-knowledge proofs. When a user withdraws from the protocol, they generate a proof that verifies the validity of their action without revealing their identity or some specific details of the transaction.
## Unlinkability
Unlinkability refers to the property that multiple transactions by the same user cannot be linked together. In the Privacy Pool protocol, this is achieved through the use of unique nullifiers for each transaction. Nullifiers are random values that are included in the zero-knowledge proofs and prevent double-spending of commitments.
## Privacy Limitations
The Privacy Pool protocol has some limitations:
- The ASP service is trusted.
- The anonymity set size is limited by the number of users in a specific pool. Smaller anonymity sets may be more susceptible to de-anonymization attacks.
- The protocol does not provide protection against network-level attacks, such as timing analysis or traffic correlation.
Users should be aware of these limitations when deciding to use the Privacy Pool protocol.

8
docs/src/introduction/key-concepts.md
View File

@@ -1,8 +0,0 @@
# Key Concepts
This page introduces the core concepts and their relationships in the Privacy Pool protocol.
- [Protocol Components](./concepts/components.md)
- [Protocol Mechanisms](./concepts/mechanisms.md)
- [Privacy Properties](./concepts/privacy.md)
- [Cryptographic Primitives](./concepts/primitives.md)

43
docs/src/introduction/overview.md
View File

@@ -1,43 +0,0 @@
# Privacy Pool Protocol Overview
Privacy Pool is a zero-knowledge protocol that enables private withdrawals of assets through validation by an Association Set Provider (ASP). The system uses an optimized incremental Merkle tree implementation and zero-knowledge proofs to maintain privacy while ensuring security.
## Key Features
### Privacy Protection
- Deposits create initially public commitments that can be spent through zero-knowledge proofs
- State transitions managed through LeanIMT (Lean Incremental Merkle Tree) optimized for gas efficiency
- Nullifier system prevents double-spending while maintaining privacy
- Optional relayer support for withdrawal processing
### Asset Support
- Native assets through `PrivacyPoolSimple` implementation
- ERC20 tokens through `PrivacyPoolComplex` implementation
- Configurable deposit minimums and protocol fees per asset
- Support for both full and partial withdrawals
### Security Guarantees
- Non-custodial design with atomic operations only
- Deposit suspension capabilities through `windDown` mechanism
- Direct withdrawal option (`ragequit`) for unapproved depositors
- Groth16 proof verification for ragequits and withdrawals
- ASP tree validation for withdrawal compliance
## Getting started
### For Users
[USER_GUIDE: Basic user guide]
### For Developers
[DEV_GUIDE: Integration overview]
### For Operators
[OPERATOR_GUIDE: Operation overview]
## Contributions

1
docs/src/layers/asp/README.md
View File

@@ -1 +0,0 @@
# ASP

21
docs/src/layers/asp/offchain-operation.md
View File

@@ -1,21 +0,0 @@
# Offchain Operation
[OVERVIEW: Introduction to ASP's offchain operations and their importance]
## Event Monitoring
### Deposit Events
[EXPLANATION: How deposits are tracked]
## Tree Management
### Tree Structure
[EXPLANATION: Tree implementation details]
### Root Calculation
[EXPLANATION: Root computation process]
## Root Updates

48
docs/src/layers/asp/overview.md
View File

@@ -1,48 +0,0 @@
# ASP Overview
[OVERVIEW: Introduction to the Association Set Provider and its role in the protocol]
## Purpose and Functionality
### Core Responsibilities
[RESPONSIBILITIES: Main tasks of the ASP]
### Privacy Enhancement
[PRIVACY_ROLE: How ASP contributes to privacy]
## Architecture
```mermaid
```
[ARCHITECTURE_DESCRIPTION: Component interaction explanation]
## Components
### Event Monitor
[EVENT_MONITOR: How events are tracked]
### Tree Manager
[TREE_MANAGER: Association set tree management]
### Storage Layer
[STORAGE: IPFS integration details]
### Root Updater
[ROOT_UPDATER: Root update mechanism]
## Data Flow
```mermaid
sequenceDiagram
```
[DATA_FLOW_DESCRIPTION: Step-by-step flow explanation]

28
docs/src/layers/asp/wind-down.md
View File

@@ -1,28 +0,0 @@
# Wind Down Process
[OVERVIEW: Introduction to the wind-down process and its importance]
## Wind Down Scenarios
### Planned Wind Down
[PLANNED_SCENARIOS: When planned wind down occurs]
### Emergency Wind Down
[EMERGENCY_SCENARIOS: Emergency situations]
## Process Flow
```mermaid
sequenceDiagram
```
[FLOW_DESCRIPTION: Detailed process explanation]
## User Impact
### Active Deposits
[ACTIVE_DEPOSITS: Impact on existing deposits]

19
docs/src/layers/contracts/README.md
View File

@@ -1,19 +0,0 @@
# Smart Contracts
The smart contracts layer provides the blockchain infrastructure for the Privacy Pool protocol, implementing the core mechanisms for private asset management. Built with modularity and security in mind, these contracts enable zero-knowledge transactions across different asset types using a flexible, upgradeable architecture that supports native and ERC20 token pools.
- [Entrypoint](./entrypoint/README.md)
- [Overview](./entrypoint/overview.md)
- [Dependencies](./entrypoint/dependencies.md)
- [Specification](./entrypoint/specification/README.md)
- [State Variables](./entrypoint/specification/state.md)
- [Data Structures](./entrypoint/specification/data-structures.md)
- [Interface](./entrypoint/specification/interface.md)
- [PrivacyPool](./privacy-pool/README.md)
- [Overview](./privacy-pool/overview.md)
- [Dependencies](./privacy-pool/dependencies.md)
- [Specification](./privacy-pool/specification/README.md)
- [Implementations](./privacy-pool/specification/implementations.md)
- [State Variables](./privacy-pool/specification/state.md)
- [Data Structures](./privacy-pool/specification/data-structures.md)
- [Interface](./privacy-pool/specification/interface.md)

8
docs/src/layers/contracts/entrypoint/README.md
View File

@@ -1,8 +0,0 @@
# Entrypoint
- [Overview](./overview.md)
- [Dependencies](./dependencies.md)
- Specification
- [State Variables](./specification/state.md)
- [Data Structures](./specification/data-structures.md)
- [Interface](./specification/interface.md)

118
docs/src/layers/contracts/entrypoint/dependencies.md
View File

@@ -1,118 +0,0 @@
# Entrypoint Dependencies
## OpenZeppelin Contracts
### Access Control
```solidity
import {AccessControlUpgradeable} from '@oz-upgradeable/access/AccessControlUpgradeable.sol';
```
Provides role-based access control mechanism with upgradeable support. Enables:
- Granular permission management
- Role-based function access
- Dynamic role assignment and revocation
### Proxy
```solidity
import {UUPSUpgradeable} from '@oz-upgradeable/proxy/utils/UUPSUpgradeable.sol';
```
Implements Universal Upgradeable Proxy Standard (UUPS):
- Allows contract logic upgrades
- Maintains contract state during upgrades
- Provides secure upgrade authorization mechanism
### Security
```solidity
import {ReentrancyGuardUpgradeable} from '@oz-upgradeable/utils/ReentrancyGuardUpgradeable.sol';
```
Protects against reentrancy attacks:
- Prevents recursive call exploitation
- Adds `nonReentrant` modifier to critical functions
- Ensures atomic transaction execution
### Token Standards
```solidity
import {IERC20} from '@oz/interfaces/IERC20.sol';
import {SafeERC20} from '@oz/token/ERC20/utils/SafeERC20.sol';
```
Enables robust ERC20 token interactions:
- Standard interface for token operations
- Safe token transfer methods
- Protection against malformed token implementations
## Internal Dependencies
### Libraries
```solidity
import {Constants} from './lib/Constants.sol';
import {ProofLib} from './lib/ProofLib.sol';
```
Internal utility libraries:
- `Constants`: Protocol-specific constant values
- `ProofLib`: Zero-knowledge proof utility functions
- Standardizes protocol-wide configurations
### Interfaces
```solidity
import {IEntrypoint} from 'interfaces/IEntrypoint.sol';
import {IPrivacyPool} from 'interfaces/IPrivacyPool.sol';
```
Defines contract interaction standards:
- `IEntrypoint`: Core protocol interaction methods
- `IPrivacyPool`: Privacy pool contract interface
- Ensures consistent contract communication
## Inheritance Structure
```mermaid
classDiagram
class Entrypoint {
+initialize(address owner, address postman)
+registerPool()
+deposit()
+relay()
}
class AccessControlUpgradeable
class UUPSUpgradeable
class ReentrancyGuardUpgradeable
Entrypoint --|> AccessControlUpgradeable
Entrypoint --|> UUPSUpgradeable
Entrypoint --|> ReentrancyGuardUpgradeable
```
### Inheritance Breakdown
- `AccessControlUpgradeable`: Role management
- `UUPSUpgradeable`: Contract upgradability
- `ReentrancyGuardUpgradeable`: Security protection
## Dependency Rationale
- Maximizes code reuse from battle-tested OpenZeppelin libraries
- Provides enterprise-grade security mechanisms
- Enables flexible, upgradeable contract architecture
- Standardizes critical protocol interactions
## Security Considerations
- All dependencies undergo extensive community audits
- Minimizes custom implementation of complex security patterns
- Leverages industry-standard smart contract libraries

104
docs/src/layers/contracts/entrypoint/overview.md
View File

@@ -1,104 +0,0 @@
# Entrypoint Contract Overview
## Purpose and Functionality
The Entrypoint contract serves as the central coordination mechanism for the Privacy Pool protocol, managing:
- Pool registration and configuration
- Cross-asset deposit and withdrawal operations
- Association Set Provider (ASP) root management
- Protocol-wide access control and governance
## Architecture
```mermaid
graph TD
A[Entrypoint Contract] --> B[Pool Registry]
A --> C[Asset Configuration]
A --> D[Association Set Management]
A --> E[Access Control]
B --> F[Native Asset Pool]
B --> G[ERC20 Asset Pools]
```
## Key Features
### Pool Management
- Register and configure privacy pools for different assets
- Set minimum deposit amounts
- Define vetting fees for each pool
- Support both native (ETH) and ERC20 token pools
### Asset Handling
- Cross-asset deposit mechanism
- Fee deduction during deposits
- Relay withdrawals across different asset types
- Maintain asset-specific pool configurations
### Access Control
- Owner role for protocol management
- Postman role for updating Association Set roots
- Role-based access to critical protocol functions
- Prevents unauthorized modifications
## Upgrade Pattern
### UUPS Implementation
- Uses UUPS (Universal Upgradeable Proxy Standard)
- Enables future protocol improvements
- Allows seamless contract upgrades
- Maintains state and storage layout
### Upgrade Process
- Only owner can authorize upgrades
- New implementation must pass compatibility checks
- Minimal disruption to existing protocol state
- Preserves all existing data and configurations
## Security Mechanisms
- Extensive access control checks
- Minimum deposit and fee enforcement
- Prevent zero-address vulnerabilities
- Strict validation of pool registration parameters
## Protocol Interactions
```mermaid
sequenceDiagram
participant User
participant Entrypoint
participant Pool
participant ASP
User->>Entrypoint: Deposit Asset
Entrypoint->>Pool: Create Commitment
Entrypoint->>ASP: Update Root
Pool-->>User: Deposit Confirmation
```
## Key Methods
- `deposit()`: Handle asset deposits
- `relay()`: Process withdrawals
- `registerPool()`: Add new privacy pools
- `updateRoot()`: Update Association Set roots
- `windDownPool()`: Disable a specific pool
## Governance Considerations
- Centralized management through owner role
- Flexible configuration of protocol parameters
- Ability to respond to emerging security requirements
- Controlled upgrade path for protocol evolution
## Performance Characteristics
- Minimal gas overhead for deposit/withdrawal
- Efficient pool and asset management
- Scalable architecture supporting multiple asset types

5
docs/src/layers/contracts/entrypoint/specification/README.md
View File

@@ -1,5 +0,0 @@
# Specification
- [State Variables](./state.md)
- [Data Structures](./data-structures.md)
- [Interface](./interface.md)

127
docs/src/layers/contracts/entrypoint/specification/data-structures.md
View File

@@ -1,127 +0,0 @@
# Entrypoint Data Structures
## Asset Configuration Structure
```solidity
struct AssetConfig {
IPrivacyPool pool;
uint256 minimumDepositAmount;
uint256 vettingFeeBPS;
}
```
### Fields Breakdown
| Field | Description |
| ---------------------- | ----------------------------------------------------------- |
| `pool` | Reference to the Privacy Pool contract for a specific asset |
| `minimumDepositAmount` | Minimum amount required for deposits |
| `vettingFeeBPS` | Vetting fee in basis points (0.01% increments) |
### Usage Patterns
- Stores configuration for each supported asset
- Enables flexible pool and fee management
- Provides granular control over deposit requirements
## Association Set Data Structure
```solidity
struct AssociationSetData {
uint256 root;
bytes32 ipfsHash;
uint256 timestamp;
}
```
### Fields Breakdown
| Field | Description |
| ----------- | ----------------------------------------------------------------- |
| `root` | Merkle root representing the Association Set Provider (ASP) state |
| `ipfsHash` | Reference to off-chain metadata |
| `timestamp` | Time of root update |
### Usage Patterns
- Tracks historical protocol state roots
- Provides verifiable, append-only record of ASP updates
- Supports off-chain data referencing
## Fee Data Structure
```solidity
struct FeeData {
address recipient;
address feeRecipient;
uint256 relayFeeBPS;
}
```
### Fields Breakdown
| Field | Description |
| -------------- | ---------------------------------------------- |
| `recipient` | Address receiving the primary withdrawal funds |
| `feeRecipient` | Address receiving relay fees |
| `relayFeeBPS` | Relay fee in basis points |
### Usage Patterns
- Manages fee distribution for relayed withdrawals
- Separates primary recipient and fee recipient
- Enables flexible fee calculation
## Withdrawal Data Structure
```solidity
struct Withdrawal {
address processooor;
uint256 scope;
bytes data;
}
```
### Fields Breakdown
| Field | Description |
| ------------- | ------------------------------------------------- |
| `processooor` | Address authorized to process the withdrawal |
| `scope` | Unique identifier for the specific privacy pool |
| `data` | Additional encoded data for withdrawal processing |
### Usage Patterns
- Defines withdrawal authorization parameters
- Supports cross-pool withdrawal mechanisms
- Provides flexible additional data encoding
## Design Principles
- Modular structure for easy extension
- Clear separation of concerns
- Minimal storage overhead
- Cryptographically secure parameter handling
## Security Considerations
- Immutable structure definitions
- Strict type safety
- Prevents unauthorized modifications
- Supports complex protocol interactions with minimal complexity
## Architectural Flexibility
These data structures enable:
- Multi-asset support
- Dynamic fee mechanisms
- Verifiable protocol state
- Extensible withdrawal processing
## Performance Characteristics
- Constant-time access to configuration
- Minimal gas overhead
- Efficient state management
- Supports complex protocol logic with lightweight structures

146
docs/src/layers/contracts/entrypoint/specification/interface.md
View File

@@ -1,146 +0,0 @@
# Entrypoint Interface Specification
## Overview
The Entrypoint contract serves as the central coordination mechanism for the Privacy Pool protocol, managing deposits, withdrawals, and pool configurations across different asset types.
## Key Design Principles
- Centralized management of privacy pool operations
- Role-based access control
- Support for both native and ERC20 assets
- Upgradeable proxy architecture
- Fee mechanism for deposits and withdrawals
## Initialization
### `initialize`
Initializes the Entrypoint contract with owner and postman roles.
```solidity
function initialize(address _owner, address _postman) external initializer
```
#### Parameters
| Name | Type | Description |
| ---------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `_owner` | `address` | Address granted the owner role, responsible for critical protocol management functions |
| `_postman` | `address` | Address granted the ASP (Association Set Provider) postman role, able to update association set roots |
#### Access Control
- Can only be called once during contract initialization
- Requires both `_owner` and `_postman` to be non-zero addresses
## Association Set Management
### `updateRoot`
Updates the Association Set Provider (ASP) root, creating a new entry in the `associationSets` array.
```solidity
function updateRoot(
uint256 _root,
bytes32 _ipfsHash
) external onlyRole(ASP_POSTMAN) returns (uint256 _index)
```
#### Parameters
| Name | Type | Description |
| ----------- | --------- | ------------------------------------------------------------------------- |
| `_root` | `uint256` | New Merkle tree root representing the latest state of the association set |
| `_ipfsHash` | `bytes32` | IPFS hash referencing additional metadata about the association set |
#### Returns
- `_index`: The index of the newly added association set
#### Requirements
- Caller must have ASP_POSTMAN role
- `_root` must be non-zero
- `_ipfsHash` must be non-zero
## Deposit Methods
### Native Asset Deposit
```solidity
function deposit(
uint256 _precommitment
) external payable returns (uint256 _commitment)
```
### ERC20 Token Deposit
```solidity
function deposit(
IERC20 _asset,
uint256 _value,
uint256 _precommitment
) external returns (uint256 _commitment)
```
#### Common Deposit Features
- Validates minimum deposit amount
- Deducts vetting fees
- Generates commitment hash
- Forwards funds to appropriate Privacy Pool
## Withdrawal Relay
### `relay`
Processes a withdrawal through a relayer, supporting complex fee and routing logic.
```solidity
function relay(
IPrivacyPool.Withdrawal calldata _withdrawal,
ProofLib.WithdrawProof calldata _proof
) external nonReentrant
```
#### Key Operations
- Verifies withdrawal proof
- Distributes funds to recipient
- Manages relay fees
- Prevents reentrancy attacks
## Pool Management Functions
### Pool Registration and Configuration
| Function | Purpose | Access Control |
| ------------------------- | -------------------------------------- | --------------- |
| `registerPool` | Add new Privacy Pool for an asset | Owner Role Only |
| `removePool` | Remove existing Privacy Pool | Owner Role Only |
| `updatePoolConfiguration` | Modify pool deposit and fee parameters | Owner Role Only |
| `windDownPool` | Irreversibly halt a pool's deposits | Owner Role Only |
## View Functions
### Mappings and Arrays
| Name | Type | Description |
| ----------------- | ---------------------------------- | ---------------------------------------- |
| `scopeToPool` | `mapping(uint256 => IPrivacyPool)` | Maps unique pool scope to pool contract |
| `assetConfig` | `mapping(IERC20 => AssetConfig)` | Stores configuration for each asset pool |
| `associationSets` | `AssociationSetData[]` | Historical record of ASP roots |
## Security Considerations
- Role-based access control prevents unauthorized actions
- Non-reentrant withdrawal relay
- Minimum deposit and fee mechanisms
- Upgradeable contract design
## Performance Characteristics
- O(1) pool lookup via mappings
- Constant-time deposit and withdrawal processing
- Flexible fee and routing mechanisms

90
docs/src/layers/contracts/entrypoint/specification/state.md
View File

@@ -1,90 +0,0 @@
# Entrypoint State Variables
## Access Control Constants
### Role Definitions
```solidity
bytes32 internal constant _OWNER_ROLE = 0x6270edb7c868f86fda4adedba75108201087268ea345934db8bad688e1feb91b;
bytes32 internal constant _ASP_POSTMAN = 0xfc84ade01695dae2ade01aa4226dc40bdceaf9d5dbd3bf8630b1dd5af195bbc5;
```
Role constants define critical access control mechanisms:
- `_OWNER_ROLE`: Highest-level administrative access
- Controls protocol configuration
- Manages pool registration and upgrades
- `_ASP_POSTMAN`: Restricted role for Association Set Provider updates
- Authorized to update root merkle trees
- Prevents unauthorized protocol state modifications
## Pool Management State
### Pool Mappings
```solidity
mapping(uint256 _scope => IPrivacyPool _pool) public scopeToPool;
```
Maps protocol-specific scopes to corresponding Privacy Pool contracts:
- Enables dynamic pool discovery
- Supports multiple asset-specific pools
- Provides flexibility in protocol architecture
### Asset Configuration
```solidity
mapping(IERC20 _asset => AssetConfig _config) public assetConfig;
```
Stores configuration for each supported asset:
- Tracks associated Privacy Pool contract
- Defines minimum deposit amounts
- Manages vetting fees for each asset type
## Association Set State
### Association Sets
```solidity
AssociationSetData[] public associationSets;
```
Maintains historical record of Association Set Provider (ASP) roots:
- Stores cryptographic roots
- Tracks IPFS hash of associated metadata
- Includes timestamp of each root update
### Structure of AssociationSetData
```solidity
struct AssociationSetData {
uint256 root; // Merkle root of the association set
bytes32 ipfsHash; // Hash referencing off-chain metadata
uint256 timestamp; // Time of root update
}
```
## Key Characteristics
- Immutable role constants ensure strict access control
- Flexible mapping-based design allows protocol extensibility
- Cryptographically secure state management
- Supports multiple asset types and pool configurations
## Security Considerations
- Role constants use deterministic hash generation
- Mappings prevent unauthorized pool or asset modifications
- Association set tracking provides verifiable protocol history
- Supports transparent, auditable protocol state changes
## Design Patterns
- Use of `mapping` for efficient lookup
- Append-only array for association set tracking
- Constant-time access to pool and asset configurations
- Separation of concerns between different protocol components

9
docs/src/layers/contracts/privacy-pool/README.md
View File

@@ -1,9 +0,0 @@
# PrivacyPool
- [Overview](./overview.md)
- [Dependencies](./dependencies.md)
- [Specification](./specification/README.md)
- [Implementations](./specification/implementations.md)
- [State Variables](./specification/state.md)
- [Data Structures](./specification/data-structures.md)
- [Interface](./specification/interface.md)

23
docs/src/layers/contracts/privacy-pool/dependencies.md
View File

@@ -1,23 +0,0 @@
# Privacy Pool Dependencies
[OVERVIEW: Overview of contract dependencies and their purposes]
## Internal Dependencies
### Libraries
```solidity
```
[LIBRARY_DESC: Internal library usage]
## Library Usage
### Lean Incremental Merkle Tree
[MERKLE_LIB: Tree functionality]
### Verifier
[VERIFIER: Proof verification]

162
docs/src/layers/contracts/privacy-pool/overview.md
View File

@@ -1,162 +0,0 @@
# Privacy Pool Overview
## Purpose and Functionality
### Core Purpose
The Privacy Pool contract provides a secure, privacy-preserving mechanism for asset withdrawals that:
- Enables confidential transactions
- Prevents transaction tracing
- Allows partial or full withdrawals
- Supports both native and ERC20 assets
### Privacy Features
Privacy is achieved through multiple sophisticated mechanisms:
- Zero-knowledge proofs for withdrawal verification
- Nullifier tracking to prevent double-spending
- Association Set Provider (ASP) root validation
- Cryptographic commitment scheme
- Incremental Merkle Tree for state management
## Architecture
```mermaid
graph TD
Entrypoint --> PrivacyPoolSimple[Privacy Pool Simple/Native Asset]
Entrypoint --> PrivacyPoolComplex[Privacy Pool Complex/ERC20]
PrivacyPoolSimple --> StateManagement[State Management]
PrivacyPoolComplex --> StateManagement
StateManagement --> LeanIMT[Lean Incremental Merkle Tree]
StateManagement --> NullifierTracking[Nullifier Tracking]
LeanIMT --> ZKVerification[Zero-Knowledge Verification]
NullifierTracking --> ZKVerification
```
## Key Components
### State Management
- Tracks deposit and commitment states
- Implements a circular buffer for root history (30 roots)
- Supports deposit cooldown and ragequit mechanisms
- Handles nullifier status tracking
### Merkle Tree Implementation
The contract uses a Lean Incremental Merkle Tree (LeanIMT) with unique properties:
- Dynamic depth
- Balanced tree construction
- Efficient insertion and proof generation
- Optimized for zero-knowledge protocols
Key Tree Properties:
- Every node with two children is a hash of left and right nodes
- Single-child nodes have the same value as their child
- Tree always builds from leaves to root
- Supports efficient membership proofs
### Zero-Knowledge Verification
- Uses Groth16 proof verification
- Validates withdrawals without revealing transaction details
- Checks:
1. Proof cryptographic integrity
2. Nullifier not previously spent
3. Commitment exists in state
4. ASP root validation
## Implementation Variants
### Simple Implementation (Native Asset)
- Handles native blockchain currency (e.g., ETH)
- Direct asset transfer mechanism
- Minimal additional complexity
- Specific error handling for native asset transfers
#### Key Characteristics
- Native asset-specific pull/push methods
- No token approval required
- Directly manages blockchain currency
### Complex Implementation (ERC20)
- Supports any ERC20 token
- Uses SafeERC20 for transfer safety
- More complex asset interaction
- Requires token approval
#### Key Characteristics
- Token-specific transfer methods
- Handles ERC20 token interactions
- Supports multiple token standards
## Contract Interactions
```mermaid
sequenceDiagram
participant User
participant Entrypoint
participant PrivacyPool
participant ASP
User->>Entrypoint: Deposit Assets
Entrypoint->>PrivacyPool: Record Commitment
Note over ASP: Validate Membership
User->>Entrypoint: Request Withdrawal
Entrypoint->>ASP: Verify Roots
ASP-->>Entrypoint: Root Validation
Entrypoint->>PrivacyPool: Process Withdrawal
PrivacyPool->>User: Transfer Assets
```
## Security Mechanisms
1. Role-Based Access Control
- Owner role for critical configurations
- Postman role for ASP root updates
- Prevents unauthorized contract modifications
2. Nullifier Prevention
- Unique nullifier per withdrawal
- Tracking prevents double-spending
- Cryptographically secure generation
3. Proof Verification
- Groth16 zero-knowledge proof validation
- Comprehensive proof checks
- Prevents fraudulent withdrawals
## Performance Considerations
- O(log n) complexity for most operations
- Batch insertion optimization
- Minimal on-chain computational overhead
- Efficient state root management
## Upgradability
- UUPS (Universal Upgradeable Proxy Standard) support
- Allows future protocol improvements
- Controlled upgrade process via owner role
## Limitations and Constraints
- Maximum tree depth of 32
- Snark scalar field constrains input values
- Requires trusted setup for zero-knowledge circuits

6
docs/src/layers/contracts/privacy-pool/specification/README.md
View File

@@ -1,6 +0,0 @@
# Specification
- [Implementations](./implementations.md)
- [State Variables](./state.md)
- [Data Structures](./data-structures.md)
- [Interface](./interface.md)

65
docs/src/layers/contracts/privacy-pool/specification/data-structures.md
View File

@@ -1,65 +0,0 @@
# Privacy Pool Data Structures
[OVERVIEW: Overview of key data structures used in the Privacy Pool contract]
## Withdrawal Structure
### Withdrawal Data
```solidity
struct Withdrawal {
address processooor;
uint256 scope;
bytes data;
}
```
#### Fields
| Field | Type | Description |
| ------------- | --------- | ----------------------------------- |
| `scope` | `uint256` | [SCOPE_DESC: Pool scope] |
| `processooor` | `address` | [PROCESSOR_DESC: Processor address] |
| `data` | `bytes` | [DATA_DESC: Additional data] |
#### Usage
[WITHDRAWAL_USAGE: How this structure is used]
## Proof Structures
### Withdrawal Proof
```solidity
struct WithdrawProof {
uint256[] ;
uint256[] proof;
}
```
#### Fields
| Field | Type | Description |
| ----- | ---- | ----------- |
#### Usage
[PROOF_USAGE: How proofs are used]
## Proof Verification
### Public Inputs
```solidity
[PUBLIC_INPUTS: Input structure]
```
[INPUT_DESC: Input validation]
### Proof Format
```solidity
[PROOF_FORMAT: Proof structure]
```
[FORMAT_DESC: Format validation]

13
docs/src/layers/contracts/privacy-pool/specification/implementations.md
View File

@@ -1,13 +0,0 @@
# Privacy Pool Implementations
[OVERVIEW: Overview of different Privacy Pool implementations]
### Inheritance
```mermaid
```
### Complex Implementation
### Simple Implementation

64
docs/src/layers/contracts/privacy-pool/specification/interface.md
View File

@@ -1,64 +0,0 @@
# Privacy Pool Interface Specification
[OVERVIEW: Overview of the Privacy Pool contract's public interface]
## Constants
### SCOPE
```solidity
uint256 public immutable SCOPE
```
[SCOPE_DESC: Scope constant description]
### ASSET
```solidity
IERC20 public immutable ASSET
```
[ASSET_DESC: Asset constant description]
## Core Operations
### deposit
```solidity
function deposit(
uint256 _commitment
) external payable
```
[DEPOSIT_DESC: Deposit functionality]
### withdraw
```solidity
function withdraw(
Withdrawal calldata _withdrawal,
WithdrawProof calldata _proof
) external
```
[WITHDRAW_DESC: Withdrawal functionality]
### ragequit
```solidity
function ragequit(
RagequitProof calldata _proof
) external
```
[RAGEQUIT_DESC: Ragequit functionality]
## Administrative Functions
### windDown
```solidity
function windDown() external
```
[WIND_DOWN_DESC: Wind down process]

52
docs/src/layers/contracts/privacy-pool/specification/state.md
View File

@@ -1,52 +0,0 @@
# Privacy Pool State Variables
The Privacy Pool contract maintains several critical state variables that are essential for its operation. These variables are defined across the `PrivacyPool` contract and its parent `State` contract. Here's an overview of the key state variables and their roles:
## Core Protocol Variables
| Variable | Type | Description |
| --------------------- | ------------- | -------------------------------------------------------------------------------------------------- |
| `SCOPE` | `uint256` | A unique identifier for the pool, computed from the contract address, chain ID, and asset address. |
| `ASSET` | `address` | The address of the asset (token) managed by this pool. |
| `ENTRYPOINT` | `IEntrypoint` | The address of the Entrypoint contract, which manages multiple pools. |
| `WITHDRAWAL_VERIFIER` | `IVerifier` | The address of the Groth16 verifier for withdrawal proofs. |
| `RAGEQUIT_VERIFIER` | `IVerifier` | The address of the Groth16 verifier for ragequit proofs. |
## State Management Variables
| Variable | Type | Description |
| ------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------- |
| `nonce` | `uint256` | A counter used to generate unique labels for deposits. |
| `dead` | `bool` | A flag indicating whether the pool is active (`false`) or has been irreversibly suspended (`true`). |
| `roots` | `mapping(uint256 => uint256)` | Stores historical Merkle tree roots, indexed by their position. |
| `currentRootIndex` | `uint32` | The index of the current (most recent) Merkle tree root. |
| `_merkleTree` | `LeanIMTData` | The internal Lean Incremental Merkle Tree data structure. |
| `nullifierHashes` | `mapping(uint256 => bool)` | Tracks spent nullifiers to prevent double-spending. |
| `deposits` | `mapping(uint256 => Deposit)` | Associates deposit labels with their corresponding deposit information. |
## Constants
| Constant | Type | Value | Description |
| ------------------- | -------- | --------- | -------------------------------------------------------------------- |
| `VERSION` | `string` | `"0.1.0"` | The semantic version of the contract. |
| `ROOT_HISTORY_SIZE` | `uint32` | `30` | The number of historical roots stored for Merkle proof verification. |
The `Deposit` struct, used in the `deposits` mapping, has the following structure:
```solidity
struct Deposit {
address depositor;
uint256 amount;
uint256 whenRagequitteable;
}
```
These state variables work together to maintain the integrity and functionality of the Privacy Pool:
- The `SCOPE`, `ASSET`, and verifier addresses ensure that each pool is uniquely identified and associated with the correct asset and proof verification mechanisms.
- The `nonce` and Merkle tree-related variables (`roots`, `currentRootIndex`, `_merkleTree`) manage the state of deposits and withdrawals in a privacy-preserving manner.
- The `nullifierHashes` mapping prevents double-spending by tracking spent commitments.
- The `deposits` mapping associates deposit labels with their original depositors, amounts, and ragequit timelock expiration, enabling the ragequit functionality.
- The `dead` flag allows for irreversibly suspending deposits to the pool while still allowing withdrawals.
Understanding these state variables is crucial for comprehending the internal workings of the Privacy Pool and how it maintains user privacy while ensuring the integrity of deposits and withdrawals.

8
docs/src/layers/zero-knowledge/README.md
View File

@@ -1,8 +0,0 @@
# Zero Knowledge Layer
The Zero Knowledge Layer of the Privacy Pool protocol encompasses the circom circuits responsible for generating and verifying zero-knowledge proofs. These proofs enable users to interact with the protocol while preserving their privacy and the confidentiality of their transactions. The Zero Knowledge Layer plays a crucial role in maintaining the anonymity and unlinkability guarantees provided by the protocol.
- [Commitments](./commitments.md)
- [Circuits](./circuits.md)
- [Commitment Circuit](./circuits/commitment.md)
- [Withdrawal Circuit](./circuits/withdrawal.md)

41
docs/src/layers/zero-knowledge/circuits.md
View File

@@ -1,41 +0,0 @@
# Circuits
## Overview
Zero-knowledge circuits form the cryptographic backbone of the Privacy Pool protocol, enabling private, verifiable financial transactions without revealing sensitive information. These circuits leverage advanced cryptographic techniques to:
- **Preserve Privacy**: Conceal transaction details while proving their validity
- **Ensure Integrity**: Cryptographically verify fund ownership and transfers
- **Prevent Double-Spending**: Create unique, non-reusable transaction proofs
### Core Circuits
The protocol implements three primary zero-knowledge circuits:
1. **Commitment Circuit**:
- Generates cryptographic commitments
- Converts deposit information into private, verifiable representations
2. **Withdrawal Circuit**:
- Enables private fund withdrawals
- Proves ownership and validates withdrawal conditions
- Creates new commitments representing remaining funds
### Technical Foundation
- **Proof System**: Groth16
- **Hash Function**: Poseidon
- **Merkle Tree**: Lean Incremental Merkle Tree (LeanIMT)
- **Field**: Snark scalar field
- **Curve**: bn128
### Key Properties
- **Zero-Knowledge**: No original transaction details are revealed
- **Non-Interactive**: Proofs can be verified without additional communication
- **Succinct**: Compact proof sizes
- **Cryptographically Secure**: Mathematically rigorous validation
These circuits represent a sophisticated approach to blockchain privacy, allowing users to transact with unprecedented confidentiality and security.

4
docs/src/layers/zero-knowledge/circuits/README.md
View File

@@ -1,4 +0,0 @@
# Circuits
- [Commitment Circuit](./commitment.md)
- [Withdrawal Circuit](./withdrawal.md)

41
docs/src/layers/zero-knowledge/circuits/circuits.md
View File

@@ -1,41 +0,0 @@
# Circuits
## Overview
Zero-knowledge circuits form the cryptographic backbone of the Privacy Pool protocol, enabling private, verifiable financial transactions without revealing sensitive information. These circuits leverage advanced cryptographic techniques to:
- **Preserve Privacy**: Conceal transaction details while proving their validity
- **Ensure Integrity**: Cryptographically verify fund ownership and transfers
- **Prevent Double-Spending**: Create unique, non-reusable transaction proofs
### Core Circuits
The protocol implements three primary zero-knowledge circuits:
1. **Commitment Circuit**:
- Generates cryptographic commitments
- Converts deposit information into private, verifiable representations
2. **Withdrawal Circuit**:
- Enables private fund withdrawals
- Proves ownership and validates withdrawal conditions
- Creates new commitments representing remaining funds
### Technical Foundation
- **Proof System**: Groth16
- **Hash Function**: Poseidon
- **Merkle Tree**: Lean Incremental Merkle Tree (LeanIMT)
- **Field**: Snark scalar field
- **Curve**: bn128
### Key Properties
- **Zero-Knowledge**: No original transaction details are revealed
- **Non-Interactive**: Proofs can be verified without additional communication
- **Succinct**: Compact proof sizes
- **Cryptographically Secure**: Mathematically rigorous validation
These circuits represent a sophisticated approach to blockchain privacy, allowing users to transact with unprecedented confidentiality and security.

50
docs/src/layers/zero-knowledge/circuits/commitment.md
View File

@@ -1,50 +0,0 @@
# Commitment Circuit
## Overview
The `CommitmentHasher` circuit is a fundamental zero-knowledge circuit responsible for proving ownership of commitments.
## Circuit Design
### High-Level Architecture
The circuit implements a hash-based commitment generation process using the Poseidon hash function. It takes private inputs representing a commitment's components and generates public outputs that can be verified without revealing the original private inputs.
## Circuit Parameters
### Inputs
| Name | Description |
| ----------- | --------------------------------------------------- |
| `value` | Value of the commitment |
| `label` | Label associated with the commitment |
| `nullifier` | Secret unique identifier to prevent double-spending |
| `secret` | Random secret |
### Outputs
| Name | Description |
| ------------------- | ----------------------------- |
| `commitment` | Hash of the entire commitment |
| `precommitmentHash` | Hash of nullifier and secret |
| `nullifierHash` | Hash of the nullifier |
## Circuit Logic
### Main Component: CommitmentHasher
The circuit follows a three-step hash generation process:
1. **Nullifier Hash Generation**
- Takes the nullifier as input
- Computes a unique hash to prevent double-spending (verified at smart contract layer)
2. **Precommitment Hash Generation**
- Combines nullifier and secret
- Creates an intermediate hash representing the commitment's private components
3. **Final Commitment Hash**
- Combines value, label, and precommitment hash
- Generates the final commitment hash

106
docs/src/layers/zero-knowledge/circuits/withdrawal.md
View File

@@ -1,106 +0,0 @@
# Withdrawal Circuit
## Overview
The Withdrawal Circuit is a critical zero-knowledge circuit that enables private withdrawals from the Privacy Pool, ensuring:
- Proof of fund ownership
- Approval by Association Set Provider
- Spending of valid commitments
- Integrity of withdrawal transactions
## Circuit Design
### High-Level Architecture
The circuit verifies a withdrawal by:
1. Proving ownership of some commitment
2. Proving existance of the commitment in the state
3. Proving ASP approval of the label
4. Proving a valid value operation (withdrawn is less or equal than current value)
## Circuit Parameters
### Public Inputs
| Name | Description |
| ---------------- | --------------------------------------------------- |
| `withdrawnValue` | Amount being withdrawn from the existing commitment |
| `stateRoot` | Current root of the state Merkle tree |
| `stateTreeDepth` | Current depth of the state tree |
| `ASPRoot` | Latest Association Set Provider root |
| `ASPTreeDepth` | Current depth of the ASP tree |
| `context` | Cryptographic context for withdrawal integrity |
### Private Inputs
| Name | Description |
| ------------------- | -------------------------------------------------------- |
| `label` | Unique identifier for the commitment |
| `existingValue` | Total value of the existing commitment |
| `existingNullifier` | Nullifier of the existing commitment |
| `existingSecret` | Secret of the existing commitment |
| `newNullifier` | Nullifier for the new commitment |
| `newSecret` | Secret for the new commitment |
| `stateSiblings` | Merkle tree sibling nodes for state tree inclusion proof |
| `stateIndex` | Index of the commitment in the state tree |
| `ASPSiblings` | Merkle tree sibling nodes for ASP tree inclusion proof |
| `ASPIndex` | Index of the label in the ASP tree |
### Outputs
| Name | Description |
| ----------------------- | --------------------------------------------- |
| `newCommitmentHash` | Hash of the new commitment after withdrawal |
| `existingNullifierHash` | Hash of the nullifier of the spent commitment |
## Circuit Logic
### Withdrawal Verification Steps
1. **Compute Existing Commitment**
- Hash the existing commitment from the privately provided preimage
2. **State Tree Inclusion Proof**
- Verify that the existing commitment is in the state tree
- Uses LeanIMT inclusion proof verification
3. **ASP Label Verification**
- Confirm the label is present in the Association Set Provider (ASP) tree
- Ensures withdrawal is approved by the ASP
4. **Value Validation**
- Check that withdrawn amount is valid
- Compute remaining value after withdrawal
- Verify both withdrawn and remaining values are within acceptable ranges
5. **New Commitment Generation**
- Create a new commitment representing the remaining balance
- Use the same label, new nullifier, and new secret
## Security Properties
- **Non-Malleability**: Impossible to modify withdrawal without knowing original secrets
- **Privacy**: No information about original commitment is revealed
- **Double-Spend Prevention**: Nullifier hash ensures each commitment can only be spent once
- **ASP Validation**: Ensures withdrawals are approved by the Association Set Provider
## Advanced Features
- Supports partial and full withdrawals
- Maintains commitment label across withdrawals
- Cryptographically secure commitment regeneration
- Flexible tree depth support
## Error Handling
Circuit will fail verification if:
- Commitment not found in state tree
- Label not found in ASP tree
- Withdrawal amount exceeds existing balance

63
docs/src/layers/zero-knowledge/commitments.md
View File

@@ -1,63 +0,0 @@
# Commitments
## Overview
A commitment in the Privacy Pool protocol is a cryptographic representation of some value owned by some user in a pool.
## Commitment Structure
### Components
A commitment consists of four primary components:
1. **Value**: The amount of value
2. **Label**: A unique identifier generated from the pool's scope and nonce when depositing
3. **Nullifier**: A unique, random secret value that prevents double-spending
4. **Secret**: A random secret value to prevent nullifier hash pre-image attacks.
### Mathematical Representation
Let the commitment be represented by the function:
$$\text{Commitment} = \text{Hash}(value, \text{label}, \text{precommitment})$$
Where:
- $\text{precommitment} = \text{Hash}(\text{nullifier}, \text{secret})$
## Security Properties
- Achieved through the use of Poseidon hash function
- Ensures the commitment cannot be modified without knowing the original secrets
- The commitment hash reveals no information about the original values
## Usage in Protocol
### In Deposits
- Generated when a user deposits funds
- Stored in the state merkle tree
- Used to track fund ownership without revealing details
### In Withdrawals
- Allows partial or full withdrawal of funds
- Generates a new commitment representing remaining balance
- Prevents double-spending through nullifier mechanism
### In Ragequit
- Enables fund recovery if label is not included in Association Set Provider (ASP)
- Allows original depositor to withdraw funds directly
## Implementation Details
### Parameter Selection
- Nullifier and secret generated randomly
- Constrained to the Snark scalar field to ensure compatibility with zero-knowledge circuits
## Security Considerations
- Always generate nullifiers and secrets using cryptographically secure random methods
- Protect the nullifier and secret to prevent unauthorized withdrawals

23
docs/src/reference/deployment.md
View File

@@ -1,23 +0,0 @@
# Deployment Addresses
## Mainnet Deployments
### Ethereum
| Contract | Address | Version |
| ------------ | ----------- | ----------- |
| [CONTRACT_1] | [ADDRESS_1] | [VERSION_1] |
| [CONTRACT_2] | [ADDRESS_2] | [VERSION_2] |
## Testnet Deployments
### Sepolia
| Contract | Address | Version |
| ------------ | ----------- | ----------- |
| [CONTRACT_1] | [ADDRESS_1] | [VERSION_1] |
| [CONTRACT_2] | [ADDRESS_2] | [VERSION_2] |
## Deployment History
### Version 0.1.0

65
docs/src/reference/glossary.md
View File

@@ -1,65 +0,0 @@
# Glossary
## Core Concepts
### Privacy Pool
[PRIVACY_POOL_DEF: Definition and purpose]
### Association Set
[ASP_DEF: Definition and role]
### Commitment
[COMMITMENT_DEF: What commitments are]
### Nullifier
[NULLIFIER_DEF: Purpose of nullifiers]
### Zero Knowledge Proof
[ZKP_DEF: ZK proof explanation]
### Merkle Tree
[MERKLE_DEF: Tree structure explanation]
### Circuit
[CIRCUIT_DEF: ZK circuit explanation]
### Relayer
[RELAYER_DEF: Relayer role]
### Deposit
[DEPOSIT_DEF: Deposit process]
### Withdrawal
[WITHDRAWAL_DEF: Withdrawal process]
### Ragequit
[RAGEQUIT_DEF: Ragequit mechanism]
### Wind Down
[WIND_DOWN_DEF: Wind down process]
### Poseidon Hash
[POSEIDON_DEF: Hash function explanation]
## Economic Terms
### Vetting Fee
[VETTING_FEE_DEF: Fee explanation]
### Relay Fee
[RELAY_FEE_DEF: Fee structure]

0
docs/static/.nojekyll vendored Normal file
View File

BIN
docs/static/img/favicon.ico vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

10
docs/static/img/logo.svg vendored Normal file
View File

@@ -0,0 +1,10 @@
<svg width="28" height="28" viewBox="0 0 28 28" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M0 0H16.8329C22.6574 0 27.3596 4.70224 27.3596 10.5267C27.3596 16.3511 22.6574 20.9802 16.8329 20.9802H13.8079V28H0V0Z" fill="url(#paint0_linear_1788_6858)"/>
<defs>
<linearGradient id="paint0_linear_1788_6858" x1="0" y1="13.997" x2="27.3596" y2="13.997" gradientUnits="userSpaceOnUse">
<stop stop-color="white"/>
<stop offset="0.7"/>
</linearGradient>
</defs>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 474 B

83
docs/theme/highlight.css vendored
View File

@@ -1,83 +0,0 @@
/*
* An increased contrast highlighting scheme loosely based on the
* "Base16 Atelier Dune Light" theme by Bram de Haan
* (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune)
* Original Base16 color scheme by Chris Kempson
* (https://github.com/chriskempson/base16)
*/
/* Comment */
.hljs-comment,
.hljs-quote {
color: #575757;
}
/* Red */
.hljs-variable,
.hljs-template-variable,
.hljs-attribute,
.hljs-attr,
.hljs-tag,
.hljs-name,
.hljs-regexp,
.hljs-link,
.hljs-name,
.hljs-selector-id,
.hljs-selector-class {
color: #d70025;
}
/* Orange */
.hljs-number,
.hljs-meta,
.hljs-built_in,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params {
color: #b21e00;
}
/* Green */
.hljs-string,
.hljs-symbol,
.hljs-bullet {
color: #008200;
}
/* Blue */
.hljs-title,
.hljs-section {
color: #0030f2;
}
/* Purple */
.hljs-keyword,
.hljs-selector-tag {
color: #9d00ec;
}
.hljs {
display: block;
overflow-x: auto;
background: #f6f7f6;
color: #000;
}
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: bold;
}
.hljs-addition {
color: #22863a;
background-color: #f0fff4;
}
.hljs-deletion {
color: #b31d28;
background-color: #ffeef0;
}

1656
docs/theme/highlight.js vendored
View File

File diff suppressed because it is too large Load Diff

8
docs/tsconfig.json Normal file
View File

@@ -0,0 +1,8 @@
{
// This file is not used in compilation. It is here just for a nice editor experience.
"extends": "@docusaurus/tsconfig",
"compilerOptions": {
"baseUrl": "."
},
"exclude": [".docusaurus", "build"]
}

9888
docs/yarn.lock Normal file
View File

File diff suppressed because it is too large Load Diff