Skip to content

Update Privacy Pools vendor file to reflect v1 deployment #92

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
0xmikemcc wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update Privacy Pools vendor file to reflect v1 deployment #92

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
04d2cb6
Update Privacy Pools vendor file and cross-references
0xmikemcc Feb 23, 2026
f4eb968
Fix Vale prose lint: reword marketing triggers, fix zk-SNARK terminology
0xmikemcc Feb 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion GLOSSARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,15 @@

### Core Privacy Concepts

**Association Set**: A defined subset of deposits in a shielded pool, constructed by an Association Set Provider (ASP) according to compliance policies (e.g., excluding sanctioned addresses). Users prove membership or exclusion in an association set during withdrawal to signal compliance without revealing their specific deposit.

**Association Set Provider (ASP)**: An entity that defines, computes, and publishes association sets for a shielded pool. ASPs apply screening rules (sanctions lists, chain analytics, KYC credentials) to classify deposits and publish the resulting set as a Merkle root that users can prove against.
Copy link
Collaborator

@Meyanis95 Meyanis95 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great!


**Commitment**: Cryptographic value computed from hidden data (for example, amount and secrets). It lets others later verify that revealed data is consistent, without learning the data from the commitment itself.

**Note**: Private record that represents ownership of some value plus the secrets needed to prove it. The note is usually stored off-chain or encrypted; on-chain you only see commitments, nullifiers and proofs.

**Nullifier**: Unique value derived from a note’s secret and revealed when the note is spent. The system stores used nullifiers to prevent double-spending without exposing which note belonged to which party.
**Nullifier**: Unique value derived from a note's secret and revealed when the note is spent. The system stores used nullifiers to prevent double-spending without exposing which note belonged to which party.

**Stealth Address**: is an address generated per transaction so that multiple payments to the same party cannot be easily linked on-chain. The recipient publishes some public information once; senders use it to derive fresh, unlinkable addresses.

Expand Down
12 changes: 11 additions & 1 deletion approaches/approach-private-payments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,15 @@
- [Shielded ERC-20 Transfers](../patterns/pattern-shielding.md) with commitment/nullifier schemes
- Higher per-transaction costs but battle-tested infrastructure

**L1 Compliance-Friendly Shielding (Privacy Pools):**
Copy link
Collaborator

@Meyanis95 Meyanis95 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest that instead of having a new category, we add an extra bullet point to the above.

  • Extends the shielded pool model with association set proofs for regulatory compliance signaling with Privacy Pools


- Extends the shielded pool model with association set proofs for regulatory compliance signaling
- Users prove their withdrawal is not linked to sanctioned or flagged deposits
- Production L1 shielded pool with built-in compliance mechanism
- [Privacy Pools](../vendors/privacypools.md) vendor documentation
- Best for: Compliance-sensitive ETH transfers where L1 security is required
- Trade-off: ETH only (v1), higher gas costs (~2M)

Check warning on line 52 in approaches/approach-private-payments.md

View workflow job for this annotation

GitHub Actions / Prose Quality (Vale) 

[vale] reported by reviewdog 🐶
[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.

Raw Output:
{"message": "[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.", "location": {"path": "approaches/approach-private-payments.md", "range": {"start": {"line": 52, "column": 18}}}, "severity": "WARNING"}

**Privacy L2 (Aztec, etc.):**

- Full **privacy** with hidden state and confidential transfers
Expand Down Expand Up @@ -113,6 +122,7 @@
**Primary Infrastructure:**

- **L1 Shielding:** [Railgun](../vendors/railgun.md) for mature UTXO-style privacy pools
- **L1 Compliant Shielding:** [Privacy Pools](../vendors/privacypools.md) for compliance-friendly shielded ETH (association set proofs)
- **Privacy L2:** [Aztec Network](../vendors/aztec.md) for native confidential transfers, [Fhenix](../vendors/fhenix.md) for FHE-based payments
- **Stateless Plasma:** [Intmax](https://www.intmax.io/) for client-side proving with minimal on-chain footprint
- **Traditional Integration:** SWIFT network adapters, ISO20022 processors
Expand Down Expand Up @@ -198,7 +208,7 @@
## Links and Notes

- **Standards:** [ERC-3643](https://eips.ethereum.org/EIPS/eip-3643), [ERC-7573](https://ercs.ethereum.org/ERCS/erc-7573), [ISO 20022](https://www.iso20022.org/), [ERC-20](https://ercs.ethereum.org/ERCS/erc-20)
- **Infrastructure:** [Railgun](https://railgun.org/), [Aztec Network](https://docs.aztec.network/), [Zama fhEVM](https://docs.zama.org/fhevm), [Intmax](https://www.intmax.io/)
- **Infrastructure:** [Railgun](https://railgun.org/), [Aztec Network](https://docs.aztec.network/), [Zama fhEVM](https://docs.zama.org/fhevm), [Intmax](https://www.intmax.io/), [Privacy Pools](https://privacypools.com)
- **Patterns:** [Stateless Plasma Privacy](../patterns/pattern-plasma-stateless-privacy.md), [TEE-Based Privacy](../patterns/pattern-tee-based-privacy.md), [Private Stablecoin Shielded Payments](../patterns/pattern-private-stablecoin-shielded-payments.md)
- **Regulatory:** [MiCA Framework](../jurisdictions/eu-MiCA.md), [SEC - GENIUS Act](../jurisdictions/us-SEC.md)
- **Related Approaches:** [Private Trade Settlement](../approaches/approach-private-trade-settlement.md), [Private Derivatives](../approaches/approach-private-derivatives.md)
1 change: 1 addition & 0 deletions patterns/pattern-l1-zk-commitment-pool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ Keep amounts/positions private on **Ethereum L1** via a **shielded pool** (commi

## See also
- pattern-dvp-erc7573.md · pattern-regulatory-disclosure-keys-proofs.md
- Privacy Pools (vendor): ../vendors/privacypools.md — production L1 implementation of this pattern with compliance extensions
Copy link
Collaborator

@Meyanis95 Meyanis95 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add a link instead?
Privacy Pools (vendor):


## See also (external)
- ERC-7573 spec: https://ercs.ethereum.org/ERCS/erc-7573
Expand Down
5 changes: 3 additions & 2 deletions patterns/pattern-shielding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Enable **confidential ERC-20 transfers** by shielding balances and transfer meta

- **Standards**: ERC-20 base; optional ERC-5564 (stealth addresses)
- **Implementations**:
- **L1/L2 contracts** (e.g., Railgun-style shielded pools).
- **L1/L2 contracts** (e.g., Railgun-style shielded pools, Privacy Pools with compliance-friendly association sets).
- **Privacy L2/app-chains** (e.g., Aztec, Zama fhEVM, Fhenix) with native shielding.
- **Wallet/KMS**: Management of shielded keys and optional viewing keys.

Expand Down Expand Up @@ -52,10 +52,11 @@ Enable **confidential ERC-20 transfers** by shielding balances and transfer meta

## Example

- Alice shields USDC into Railgun; transfers to Bob privately; regulator later verifies the transfer via Bob’s viewing key.
- Alice shields USDC into Railgun; transfers to Bob privately; regulator later verifies the transfer via Bob's viewing key.

## See also

- Railgun: https://docs.railgun.org/wiki
- Aztec docs: https://docs.aztec.network/
- Zama fhEVM: https://docs.zama.org/protocol/protocol/overview
- Privacy Pools: https://privacypools.com (compliance-friendly shielded pool with association set proofs)
Copy link
Collaborator

@Meyanis95 Meyanis95 Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description in parentheses is redundant with line 27.

92 changes: 56 additions & 36 deletions vendors/privacypools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,67 +8,87 @@

## What it is

Privacy Pools is a smart contract protocol that extends the mixer model by allowing users to prove that their withdrawals come from (or do not come from) deposits belonging to a specific **association set**.
Instead of merely unlinking deposits and withdrawals, users can provide **membership** or **exclusion** proofs, enabling them to disassociate from illicit deposits while retaining privacy within compliant sets.
Privacy Pools is a smart contract protocol deployed on Ethereum mainnet that enables private transactions with built-in compliance signaling. Users deposit into a shielded pool (commitments + nullifiers) and, on withdrawal, prove that their funds belong to (or do not belong to) a specific **association set** defined by an Association Set Provider (ASP). This creates a **separating equilibrium**: honest users can voluntarily demonstrate compliance while retaining transactional privacy.

The protocol is developed and operated by [0xbow](https://0xbow.io), with the v1 deployment live on Ethereum L1 since 2025.

## Fits with patterns (names only)

- Pattern: Private ISO 20022 Messaging & Settlement
- Pattern: ZK Shielded Balances for Derivatives
- Pattern: Shielded-Pool Atomic Swap (ZK-HTLC)
- Pattern: L1 ZK Commitment Pool
- Pattern: Shielded ERC-20 Transfers
- Pattern: Regulatory Disclosure Keys & Proofs
- Pattern: Compliance Monitoring

## Not a substitute for

- Not a full rollup or scalability solution (operates as an L1 smart contract).
- Not an identity system (needs external KYC/credential providers for association sets).
- Not a universal compliance layer (policies depend on set construction).
- Not a full rollup or scalability solution (operates as L1 smart contracts).
- Not an identity system (relies on external KYC/credential providers for association set construction).
- Not a universal compliance layer (compliance scope depends on ASP set construction and policies).
- Not a general-purpose shielded token system (v1 supports ETH only; ERC-20 support planned for v2).

Check warning on line 27 in vendors/privacypools.md

View workflow job for this annotation

GitHub Actions / Prose Quality (Vale) 

[vale] reported by reviewdog 🐶
[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.

Raw Output:
{"message": "[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.", "location": {"path": "vendors/privacypools.md", "range": {"start": {"line": 27, "column": 64}}}, "severity": "WARNING"}

## Architecture

- **Execution model**: Similar to Tornado Cash (commitments + nullifiers in a Merkle tree).
- **Association sets**: Subsets of deposits defined by a root `R_A`; users prove membership of their deposit in both the global tree and the association set.
- **Proof system**: zkSNARKs (Groth16).
- **Association Set Providers (ASPs)**: Off-chain or on-chain entities that define and publish sets (e.g. “exclude OFAC-sanctioned deposits”, “only KYC’d deposits”).
- **Data availability**: commitments and proofs recorded on-chain; full sets can be stored off-chain or on IPFS.
- **Execution model**: Commitment + nullifier scheme in a Merkle tree, similar to Tornado Cash but extended with association set verification.
- **Contract architecture**: Upgradeable proxy pattern with an Entrypoint contract routing to asset-specific pool contracts.
- Mainnet Entrypoint (Proxy): `0x6818809EefCe719E480a7526D76bD3e561526b46`
- Mainnet ETH Pool: `0xF241d57C6DebAe225c0F2e6eA1529373C9A9C9fB`
- **Association sets**: Subsets of deposits defined by a Merkle root; users prove membership of their deposit in both the global deposit tree and the association set tree.
- **Proof system**: zk-SNARKs (Groth16) — double Merkle-branch check (global root + association set root).
- **Association Set Providers (ASPs)**: Off-chain entities (currently 0xbow on Ethereum and Brevis on BNB Chain) that define, compute, and publish association sets. Sets are constructed by screening deposits against sanctions lists, chain analytics, and configurable compliance policies.
- **Relayer**: Third parties operate relayers that submit withdrawal transactions on behalf of users, preventing the withdrawal address from being linked to the depositor's gas-paying address.
- **Data availability**: Commitments and proofs recorded on-chain; association set roots published on-chain; full set data available off-chain.

## Privacy domains

- **Membership proofs**: “My withdrawal came from one of these known-good deposits.”
- **Exclusion proofs**: “My withdrawal did not come from these known-bad deposits.”
- **Bilateral direct proofs**: User can still reveal the exact link to a counterparty if required.
- **Sequential proofs**: Coins can pass through multiple hands, with re-proofing at each step.
- **Membership proofs**: "My withdrawal came from one of these known-good deposits."
- **Exclusion proofs**: "My withdrawal did not come from these known-bad deposits."
- **Bilateral direct proofs**: User can reveal the exact deposit-withdrawal link to a specific counterparty if required (e.g., for tax reporting or institutional compliance).
- **Sequential proofs**: Funds passing through multiple hands can be re-proved at each step against current association sets.
- **Viewing keys (auditor access)**: Per-account symmetric keys (XChaCha20-Poly1305, derived via HKDF) that grant read-only access to a user's shielded transaction history. Auditor data is embedded on-chain per withdrawal as an encrypted payload (tag + ciphertext), where the tag is a Poseidon hash enabling efficient event discovery without revealing the underlying data. Currently live on the StarkNet v1 deployment; EVM v1 support planned. Enables compliance teams, auditors, and institutional back-offices to verify transaction history without requiring the user's spending keys.

Check warning on line 47 in vendors/privacypools.md

View workflow job for this annotation

GitHub Actions / Prose Quality (Vale) 

[vale] reported by reviewdog 🐶
[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.

Raw Output:
{"message": "[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.", "location": {"path": "vendors/privacypools.md", "range": {"start": {"line": 47, "column": 120}}}, "severity": "WARNING"}

## Enterprise demand and use cases

- **Regulated exchanges / custodians**: accept deposits if proven not linked to sanctioned addresses.
- **Institutions**: segregate “clean” funds from illicit ones without sacrificing user privacy.
- **Policy pilots**: cited in academic and policy contexts (Vitalik Buterin, Fabian Schär, Ameen Soleimani et al., 2023 SSRN paper) as a way to align privacy with AML compliance.
- **Centralised exchanges**: Private withdrawals (users withdraw to a shielded address, breaking the on-chain link between exchange hot wallet and destination), private deposits (users deposit from shielded balance without revealing source), private P2P transfers between exchange accounts, and yield on shielded balances. Integration model ranges from additive (opt-in privacy feature) to privacy-by-default for all user transfers.
- **Wallet providers**: Shielded swaps (swap between assets without exposing portfolio), private P2P transfers and payment requests, cross-chain privacy (shield on one chain, unshield on another), and yield on idle shielded balances. SDK integration via `shield()`, `withdraw()`, `transfer()`, and `swap()` methods.
- **Institutional custody providers**: Private vendor payments, private treasury movements (move funds between operational wallets without exposing internal structure), private cross-entity settlements, private payroll, and yield on shielded reserves. Enterprise features include MPC/multisig compatibility, inverted authorisation model (spending keys held by custodian, view keys shared with compliance), hardware wallet support, key rotation and recovery, and ragequit non-custodial guarantee.
- **Compliance and audit**: View keys enable compliance teams to verify the full transaction history of a shielded account without requiring spending authority. Planned standalone auditor portal (audit.privacypools.com) for view-key-based read-only access to shielded balances and transaction graphs.

Check warning on line 54 in vendors/privacypools.md

View workflow job for this annotation

GitHub Actions / Prose Quality (Vale) 

[vale] reported by reviewdog 🐶
[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.

Raw Output:
{"message": "[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.", "location": {"path": "vendors/privacypools.md", "range": {"start": {"line": 54, "column": 245}}}, "severity": "WARNING"}
- **OTC desks**: Private settlement of large block trades without broadcasting trade direction, size, or counterparty information on-chain.
- **Policy pilots**: Cited in the Buterin, Soleimani, Schär et al. 2023 paper as the canonical model for aligning on-chain privacy with AML compliance. The v1 mainnet deployment is the production implementation of this model.

## Technical details

- Proof circuit: double Merkle-branch check (global root + association set root).
- Association set construction can follow rules:
- _Inclusion-based_: only low-risk deposits included.
- _Exclusion-based_: all except high-risk deposits.
- _Hybrid_: KYC tokens, proof-of-personhood, AI-based scoring, etc.
- Users retain the option to re-prove against updated sets or to disclose directly to a counterparty.
- **Proof circuit**: Double Merkle-branch verification — the withdrawal proof demonstrates:
1. Knowledge of a valid note (commitment preimage) in the global deposit tree.
2. Membership (or exclusion) of that note in the association set tree.
3. Correct nullifier derivation to prevent double-spending.
- **Association set construction** follows configurable rules:
- _Inclusion-based_: Only deposits passing compliance screening are included (v1 default — 0xbow screens against sanctions lists and chain analytics).

Check warning on line 65 in vendors/privacypools.md

View workflow job for this annotation

GitHub Actions / Prose Quality (Vale) 

[vale] reported by reviewdog 🐶
[IPTF.Marketing] Avoid marketing language: 'Only'. Use neutral, factual terms.

Raw Output:
{"message": "[IPTF.Marketing] Avoid marketing language: 'Only'. Use neutral, factual terms.", "location": {"path": "vendors/privacypools.md", "range": {"start": {"line": 65, "column": 24}}}, "severity": "WARNING"}
- _Exclusion-based_: All deposits except those flagged as high-risk.
- _Hybrid_: Future support for KYC tokens, proof-of-personhood, or credential-gated sets.
- **Gas costs**: Withdrawal proofs are ~2M gas due to on-chain Groth16 verification + Merkle path checks.
- **Relayer model**: Users submit withdrawal requests to a relayer, which pays gas and submits the transaction. This hides the recipient's address from being the gas payer, strengthening unlinkability.

## Strengths

- Provides a **separating equilibrium**: honest users can prove compliance, dishonest cannot.
- Flexible: different jurisdictions can define different association sets.
- Voluntary proofs: no mandatory global allowlisting or centralized backdoors.
- **Production L1 compliance-friendly shielded pool**: Sole live implementation of the association set model on Ethereum mainnet.
- **Separating equilibrium**: Honest users can prove compliance; dishonest users cannot forge association set membership proofs.
- **Flexible compliance**: Different ASPs can define different sets for different jurisdictions or policies, without requiring protocol changes.
- **Voluntary proofs**: No mandatory global allowlisting, no centralized backdoors. Users choose when and to whom they prove compliance, including optional viewing key sharing for audit purposes.
- **Aligned with academic foundation**: Direct implementation of the Buterin/Soleimani/Schär model, which has broad recognition in policy and regulatory discussions.

## Risks and open questions

- Privacy depends on **set size and accuracy**: small or poorly curated sets reduce anonymity.
- Requires trust in Association Set Providers (risk of manipulation or censorship).
- No native cross-chain support.
- Not yet deployed at large scale; governance of set definitions is unresolved.
- **Privacy depends on set size**: Small pools or narrowly defined association sets reduce the anonymity set. Pool growth is critical for privacy guarantees.
- **ETH only in v1**: No ERC-20 support yet; ERC-20 shielding planned for v2.

Check warning on line 82 in vendors/privacypools.md

View workflow job for this annotation

GitHub Actions / Prose Quality (Vale) 

[vale] reported by reviewdog 🐶
[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.

Raw Output:
{"message": "[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.", "location": {"path": "vendors/privacypools.md", "range": {"start": {"line": 82, "column": 9}}}, "severity": "WARNING"}
- **No native cross-chain support**: L1 only; no bridging to L2 shielded pools.

Check warning on line 83 in vendors/privacypools.md

View workflow job for this annotation

GitHub Actions / Prose Quality (Vale) 

[vale] reported by reviewdog 🐶
[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.

Raw Output:
{"message": "[IPTF.Marketing] Avoid marketing language: 'only'. Use neutral, factual terms.", "location": {"path": "vendors/privacypools.md", "range": {"start": {"line": 83, "column": 41}}}, "severity": "WARNING"}
- **Relayer trust**: The relayer can observe the withdrawal request (though it cannot link to the deposit without the user's secret). Relayer decentralization is a future goal.
- **Groth16 trusted setup**: Requires a ceremony for zk-SNARK parameters; the security of the proof system depends on at least one honest participant in the setup ceremony.

## Links

- [Privacy Pools GitHub](https://github.com/ameensol/privacy-pools)
- [SSRN Paper: Blockchain Privacy and Regulatory Compliance](https://ssrn.com/abstract=4563364)
- [Vitalik blog on Privacy Pools](https://vitalik.eth.limo/general/2023/09/06/privacy.html)
- [Privacy Pools Core (v1 contracts, circuits, SDK, relayer)](https://github.com/0xbow-io/privacy-pools-core)
- [Privacy Pools Website](https://privacypools.com)
- [0xbow](https://0xbow.io)
- [SSRN Paper: Blockchain Privacy and Regulatory Compliance (Buterin, Soleimani, Schär et al., 2023)](https://ssrn.com/abstract=4563364)
- [Vitalik blog: What do I think about biometric proof of personhood? (Privacy Pools context)](https://vitalik.eth.limo/general/2023/09/06/privacy.html)
- [Mainnet Entrypoint on Etherscan](https://etherscan.io/address/0x6818809EefCe719E480a7526D76bD3e561526b46)
Loading