ANAVHEOBA · foorttesst-oss · Mar 24, 2026
diff --git a/docs/education/01-why-privacy-matters.md 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
@@ -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
@@ -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
@@ -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
@@ -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!*