# Architectural Overview Document: Privacy Pools on the Ethereum Blockchain

---

## 1. Introduction

Privacy Pools aim to enhance transaction privacy on the Ethereum blockchain. Originating from a demo presented at ETH Denver, the goal is to streamline the process of generating exclusion lists and integrating the PrivacyPools.com UI with the ListDAO API.

This document is an expansion of the [original Privacy Pool Spec](https://paper.dropbox.com/doc/Shared-Privacy-Pools-Spec-v1-0doxLHuW1o6yyMKRGetNf). More information regarding privacy pools can be referenced in [this whitepaper](https://deliverypdf.ssrn.com/delivery.php?ID=626090113083013000115126087004007104014031023082031066109095073127121008106116065089099038000101119039109118030105097122030093015059068041031118011074105013105118030069092013073102098120026125002106026093072126119090124081085099071105111084066077104122&EXT=pdf&INDEX=TRUE) and [this GitHub repository](https://github.com/ameensol/privacy-pools).

### 1.1 Definitions
**Exclusion List**: A canonical list from ListDAO containing flagged deposits. Represents deposits users will typically exclude from their anonymity set.

**Inclusion List**: Lists deposit commitments considered "clean" for inclusion in users' anonymity sets.

Publishing the inclusion list merkle root hash on-chain offers better operational efficiency, given its less frequent updates compared to the exclusion list. Periodic on-the-hour updates for both lists are recommended, with special considerations for transactions occurring between these hourly marks.

---

## 2. System Overview

The Privacy Pools system primarily consists of:

- Privacy Pools Smart Contracts
- PrivacyPools.com UI (not covered in this document)
- ListDAO API

---

## 3. Components Breakdown

### 3.1. Privacy Pools Smart Contracts

- Forked from tornado cash contracts.
- Introduces an edited withdrawal function to allow ZK-proof-of-exclusion.
- Uses a new ZK circuit, distinct from tornado cash.

### 3.2. ListDAO API

#### Operation:

1. Monitors incoming deposits to the privacy pool smart contract.
- Subscribe to events on contract.
- Publish data associated with these events to a database.
3. Maintains a canonical “exclusion list”:
- New deposits are added for a week.
- Chainalysis API checks determine if deposits stay on the list.
- Cronjob pulls from Chainalysis API at periodic intervals to ensure list is up to date.
- Non-compliant withdrawals also contribute to the list.

#### Canonical Exclusion List Contains:

- Deposits from illicit sources (1-week detection period).
- All deposits within the last week.
- Non-compliant privacypools withdrawals.

The API offers:

- The canonical exclusion list.
- Periodic on-chain publication of the exclusion list's merkle root for validation.

---

## 4. System Build Tasks

### ListDAO Data Processing:

- [ ] Monitor and save all new privacy pool contract deposits.

### ListDAO Chainalysis Client:

- [ ] Develop an API client to cross-check transactions/deposit addresses.

### ListDAO List Management:

- [ ] Add deposits to the exclusion list.
- [ ] Query chainalysis for origin validation.
- [ ] Recheck uncertain origins after one week.
- [ ] Remove verified deposits post one week.
- [ ] Flag and add non-compliant withdrawals.

### ListDAO API Endpoints:

- [ ] GET /exclusion_list: Returns exclusion list addresses.
- [ ] GET /inclusion_list: Returns inclusion list addresses.
- [ ] GET /check_address: Validates inclusion/exclusion status.
- [ ] GET /check_addresses: Batch validate inclusion/exclusion status.

### ListDAO Blockchain Operations:

- [ ] Periodically post the exclusion list's recent merkle root to a smart contract.

## 5. ListDAO API Schema

#### 5.1. **Endpoints**

- **GET `/exclusion_list`**

*Description*: Returns the full exclusion list addresses for a given merkle root.

*Parameters*:
- `merkle_root` (optional): The root to fetch. If not provided, defaults to the most recent.

*Response*:
- Array of objects: `{ txhash: string, commitment: string }`

---

- **GET `/inclusion_list`**

*Description*: Returns the inclusion list addresses.

*Response*:
- Array of addresses: `[address1, address2, ...]`

---

- **GET `/check_address`**

*Description*: Validates if a given address is included or excluded.

*Parameters*:
- `address`: The address to check.
- `commitment`: The commitment to check.
- `merkle_root` (optional): The merkle root to use. If not provided, defaults to the most recent.

*Response*:
- `{ is_included: boolean }`

---

- **GET `/check_addresses`**

*Description*: Batch validate inclusion/exclusion status for addresses.

*Parameters*:
- `addresses[]`: An array of addresses to check.
- `commitments[]`: An array of commitments to check.
- `merkle_root` (optional): The merkle root to use. If not provided, defaults to the most recent.

*Response*:
- Array of booleans: `[true, false, ...]` (where `true` means included and `false` means excluded)

---

- **GET `/historical_association_by_merkle`**

*Description*: This endpoint retrieves historical association sets for a given merkle root. By providing a specific merkle root, users can see the state of associations (exclusion or inclusion) at that specific point in time.

*Parameters*:

- `merkle_root`: The merkle root for which the historical association set is desired.

*Response*:

- An object which includes:
- `merkle_root`: The provided merkle root.
- `timestamp`: The timestamp when this merkle root was generated.
- `association_set`: Array of addresses/commitments associated with this merkle root.
- `type`: Specifies whether the association set refers to "exclusion" or "inclusion".

---

#### 5.2. **Error Handling**

All endpoints should have standardized error handling, returning appropriate HTTP status codes, e.g., `404` for not found, `400` for bad request, etc. An example error response:

{
    "error": true,
    "message": "Description of what went wrong."
}

---

#### 5.3. **Security & Authorization**

To ensure the API's data integrity and prevent abuse:

- Rate-limiting should be applied.
- All endpoints could have authorization checks where relevant, perhaps via API tokens or other authentication mechanisms (sign in with Ethereum?).

---

#### 5.4. **Response Metadata**

It might be useful to include metadata in responses, especially for lists, to give context, e.g., pagination details, timestamps, etc.

{
    "data": [ ... ],
    "metadata": {
        "timestamp": "2023-10-01T12:00:00Z",
        "total_records": 100,
        ...
    }
}

---

#### 5.6. **Caching**

Given that some of these endpoints might have heavy loads or could serve similar data frequently, appropriate caching strategies should be implemented to improve performance.

---

## 6.0 TODO
- Admin UI
- ASP UI is for flagging deposits and deciding whether they belong in the association set
-