diff --git a/docs/education/01-why-privacy-matters.md b/docs/education/01-why-privacy-matters.md new file mode 100644 index 0000000..91d30f3 --- /dev/null +++ b/docs/education/01-why-privacy-matters.md @@ -0,0 +1,44 @@ +# Why Privacy Matters in Crypto + +## The Transparency Problem + +Most blockchains are fully transparent. Every transaction, every balance, every interaction is visible to anyone. While this enables trustless verification, it creates serious problems: + +- **Financial surveillance** — Anyone can track your spending habits +- **Business vulnerability** — Competitors can see your transactions +- **Personal safety** — Wealth visibility makes you a target +- **Discrimination** — Transaction history can lead to financial profiling + +## Privacy ≠ Secrecy + +Privacy is not about hiding wrongdoing. It's about: + +- **Autonomy** — Control over your own financial data +- **Fungibility** — All tokens should be equal regardless of history +- **Security** — Reducing attack surface for social engineering + +## Why Stellar Needs Privacy + +Stellar is designed for real-world payments. But real-world payments require privacy: + +| Use Case | Why Privacy Matters | +|----------|-------------------| +| Salary payments | Employees shouldn't see each other's pay | +| Business transactions | Suppliers shouldn't see your margins | +| Donations | Donors may prefer anonymity | +| Medical payments | Health information should be private | + +## How PrivacyLayer Helps + +PrivacyLayer adds a privacy layer on top of Stellar using zero-knowledge proofs: + +1. **Deposit** tokens into a shielded pool +2. **Withdraw** to any address with a ZK proof +3. The **link between sender and receiver is broken** + +No one can trace which deposit corresponds to which withdrawal — while the total amounts remain verifiable. + +## Learn More + +- [How PrivacyLayer Works →](./02-how-privacylayer-works.md) +- [Understanding Zero-Knowledge Proofs →](./03-zero-knowledge-proofs.md) diff --git a/docs/education/02-how-privacylayer-works.md b/docs/education/02-how-privacylayer-works.md new file mode 100644 index 0000000..bb35ba3 --- /dev/null +++ b/docs/education/02-how-privacylayer-works.md @@ -0,0 +1,97 @@ +# How PrivacyLayer Works + +## Overview + +PrivacyLayer is a privacy pool protocol on Stellar/Soroban. It uses a fixed-denomination design with zero-knowledge proofs to break the on-chain link between depositors and recipients. + +## The Core Concept + +``` +Alice deposits 100 USDC → [Shielded Pool] → Bob withdraws 100 USDC + ↑ + No visible connection + between Alice and Bob +``` + +## Step-by-Step + +### 1. Deposit + +When you deposit: +- You create a **secret note** (nullifier + secret) +- You compute a **commitment** = Hash(nullifier, secret) +- You send tokens + commitment to the contract +- The commitment is added to a **Merkle tree** + +``` +commitment = Hash(nullifier, secret) +deposit(amount, commitment) → leaf_index +``` + +**Save your note!** You need the nullifier and secret to withdraw. + +### 2. The Merkle Tree + +All commitments are stored in an on-chain Merkle tree: +- Maximum capacity: 1,048,576 deposits +- Each deposit creates a new leaf +- A new Merkle root is computed after each deposit +- Historical roots are stored for verification + +### 3. Withdrawal + +When you withdraw: +- You generate a **zero-knowledge proof** that you know a valid note +- The proof reveals the **nullifier hash** (to prevent double-spending) +- But it does NOT reveal which deposit is yours + +``` +proof = ZK_Prove( + I know a secret note in the Merkle tree + with this nullifier hash + sending to this recipient +) +``` + +### 4. Verification + +The contract: +1. Checks the Merkle root is valid +2. Checks the nullifier hasn't been used before +3. Verifies the ZK proof +4. Sends tokens to the recipient +5. Marks the nullifier as spent + +## Privacy Guarantees + +| Property | Guarantee | +|----------|-----------| +| **Sender privacy** | Deposit cannot be linked to withdrawal | +| **Amount privacy** | Fixed denomination means all deposits look identical | +| **Double-spend protection** | Nullifier prevents using the same note twice | +| **Proof validity** | Groth16 proof ensures withdrawal is legitimate | + +## What Remains Public + +- Total deposits count +- Total withdrawals count +- Pool balance +- That a specific address deposited or received funds + +## What is Hidden + +- Which deposit matches which withdrawal +- The connection between depositor and recipient +- Individual deposit/withdrawal patterns within the pool + +## Technical Stack + +- **Smart contract:** Soroban (Rust) on Stellar +- **ZK circuits:** Noir (BN254 curve) +- **Proof system:** Groth16 +- **Hash function:** Poseidon + +## Next Steps + +- [Understanding Zero-Knowledge Proofs →](./03-zero-knowledge-proofs.md) +- [Getting Started →](./04-getting-started.md) diff --git a/docs/education/03-zero-knowledge-proofs.md b/docs/education/03-zero-knowledge-proofs.md new file mode 100644 index 0000000..26aeaef --- /dev/null +++ b/docs/education/03-zero-knowledge-proofs.md @@ -0,0 +1,97 @@ +# Understanding Zero-Knowledge Proofs + +## What is a Zero-Knowledge Proof? + +A zero-knowledge proof (ZKP) lets you prove something is true **without revealing any information** about why it's true. + +### Real-World Analogy + +Imagine you want to prove you know the password to a safe, but you don't want to tell anyone the password: + +1. Someone puts a random message inside the safe +2. You open the safe and read the message back +3. They know you have the password — but they never learned it + +## How PrivacyLayer Uses ZKPs + +When withdrawing, you need to prove: + +> "I know the secret behind one of the commitments in the Merkle tree" + +**Without revealing:** +- Which commitment is yours +- What the secret is +- When you deposited + +### The Proof Statement + +``` +I can prove that: + ✓ I know (nullifier, secret) such that + ✓ Hash(nullifier, secret) = commitment + ✓ commitment exists in the Merkle tree with root R + ✓ nullifier_hash = Hash(nullifier) + +Without revealing: + ✗ Which leaf in the tree is mine + ✗ The actual nullifier or secret values + ✗ When the deposit was made +``` + +## Groth16: The Proof System + +PrivacyLayer uses **Groth16**, a specific type of ZKP called a zk-SNARK: + +| Property | Description | +|----------|-------------| +| **Zero-knowledge** | Reveals nothing beyond the statement's truth | +| **Succinct** | Proof is small (~200 bytes) regardless of computation size | +| **Non-interactive** | Proof can be verified without interaction with the prover | +| **Argument of Knowledge** | Prover must actually know the witness (not just guess) | + +### Proof Components + +A Groth16 proof consists of three elliptic curve points: +- **A** (G1 point) — 64 bytes +- **B** (G2 point) — 128 bytes +- **C** (G1 point) — 64 bytes + +Total proof size: **256 bytes** + +### Verification + +Verification involves a single pairing check: +``` +e(A, B) = e(α, β) · e(L, γ) · e(C, δ) +``` + +This is fast (< 10ms) and can be done on-chain. + +## The BN254 Curve + +Groth16 proofs in PrivacyLayer use the **BN254** (alt-bn128) elliptic curve: +- 254-bit prime field +- Efficient pairing operations +- Widely used in Ethereum and other chains +- ~100 bits of security + +## Trusted Setup + +Groth16 requires a one-time **trusted setup** ceremony: +- Generates the proving and verifying keys +- The "toxic waste" must be destroyed +- Multi-party ceremonies ensure security (at least one honest participant) + +## Circuits in PrivacyLayer + +The ZK circuits are written in **Noir** and handle: + +1. **Commitment circuit** — Verifies Hash(nullifier, secret) = commitment +2. **Merkle proof circuit** — Verifies commitment exists in the tree +3. **Withdrawal circuit** — Combines both + public inputs + +## Further Reading + +- [Noir Language Documentation](https://noir-lang.org/) +- [Groth16 Paper](https://eprint.iacr.org/2016/260) +- [Getting Started with PrivacyLayer →](./04-getting-started.md) diff --git a/docs/education/04-getting-started.md b/docs/education/04-getting-started.md new file mode 100644 index 0000000..0eded1f --- /dev/null +++ b/docs/education/04-getting-started.md @@ -0,0 +1,79 @@ +# Getting Started with PrivacyLayer + +## Prerequisites + +- Stellar wallet with USDC (or supported token) +- Basic understanding of blockchain transactions + +## Quick Start + +### 1. Connect Your Wallet + +Connect your Stellar wallet to the PrivacyLayer interface. Supported wallets: +- Freighter +- Albedo +- xBull + +### 2. Choose a Pool + +Select a denomination pool: +- Each pool has a fixed deposit amount +- Larger pools with more deposits offer better privacy + +### 3. Deposit + +1. Click "Deposit" +2. Approve the transaction in your wallet +3. **Save your note** — this is your withdrawal key + +> ⚠️ **IMPORTANT:** If you lose your note, your funds cannot be recovered. Store it safely! + +### 4. Wait + +For maximum privacy, wait before withdrawing: +- The longer you wait, the more deposits happen after yours +- This increases your **anonymity set** +- Minimum recommended: wait for 10+ subsequent deposits + +### 5. Withdraw + +1. Enter your saved note +2. Specify the recipient address (can be any Stellar address) +3. The ZK proof is generated in your browser +4. Submit the withdrawal transaction + +### 6. Done! + +The tokens arrive at the recipient address with no visible link to your deposit. + +## Tips for Better Privacy + +| Tip | Why | +|-----|-----| +| Wait longer between deposit and withdrawal | Larger anonymity set | +| Use a fresh address for receiving | No address reuse | +| Deposit and withdraw at different times of day | Harder to correlate by timing | +| Use the same denomination as others | Blend in with the crowd | + +## Fees + +- **Deposit:** Network gas fee only +- **Withdrawal:** Network gas fee + optional relayer fee +- **Relayer:** Allows withdrawal without gas in the recipient wallet + +## Security + +- Smart contract is open-source +- ZK circuits are audited +- No admin can access or freeze individual deposits +- Nullifier system prevents double-spending + +## Need Help? + +- [API Documentation](../API.md) +- [GitHub Repository](https://github.com/ANAVHEOBA/PrivacyLayer) +- [How PrivacyLayer Works](./02-how-privacylayer-works.md) + +--- + +*Happy private transacting! 🔒* diff --git a/docs/education/README.md b/docs/education/README.md new file mode 100644 index 0000000..06b2a39 --- /dev/null +++ b/docs/education/README.md @@ -0,0 +1,14 @@ +# PrivacyLayer Education Hub + +Learn about privacy-preserving transactions, zero-knowledge proofs, and how PrivacyLayer protects your financial privacy on Stellar. + +## Contents + +1. [Why Privacy Matters in Crypto](./01-why-privacy-matters.md) +2. [How PrivacyLayer Works](./02-how-privacylayer-works.md) +3. [Understanding Zero-Knowledge Proofs](./03-zero-knowledge-proofs.md) +4. [Getting Started Guide](./04-getting-started.md) + +--- + +*Part of the PrivacyLayer documentation. Contributions welcome!*