From 2ae59370c71c3260be54ad2672b9548fcff0b40c Mon Sep 17 00:00:00 2001
From: asdas6wdqc <142989356+asdas6wdqc@users.noreply.github.com>
Date: Thu, 26 Mar 2026 18:03:31 +0800
Subject: [PATCH 1/3] docs: add SECURITY_BEST_PRACTICES guide

---
 docs/SECURITY_BEST_PRACTICES.md | 273 ++++++++++++++++++++++++++++++++
 1 file changed, 273 insertions(+)
 create mode 100644 docs/SECURITY_BEST_PRACTICES.md

diff --git a/docs/SECURITY_BEST_PRACTICES.md b/docs/SECURITY_BEST_PRACTICES.md
new file mode 100644
index 0000000..acfaee5
--- /dev/null
+++ b/docs/SECURITY_BEST_PRACTICES.md
@@ -0,0 +1,273 @@
+# Security Best Practices Guide
+
+> 🔐 Protect your privacy. Protect your funds. This guide covers essential security practices for using PrivacyLayer.
+
+---
+
+## Table of Contents
+
+1. [Note Management](#1-note-management)
+2. [Privacy Practices](#2-privacy-practices)
+3. [Operational Security](#3-operational-security)
+4. [Common Pitfalls](#4-common-pitfalls)
+5. [Emergency Procedures](#5-emergency-procedures)
+
+---
+
+## 1. Note Management
+
+Your note is the **only proof of your deposit**. Loss of note = permanent loss of funds. There is no recovery mechanism.
+
+### 1.1 Backup Strategies
+
+| Method | Recommended | Notes |
+|--------|-------------|-------|
+| Encrypted USB drive | ✅ Yes | Store in a secure physical location |
+| Hardware wallet (air-gapped) | ✅ Yes | Best for large amounts |
+| Encrypted cloud storage | ⚠️ Use with caution | Ensure strong encryption and 2FA |
+| Paper backup | ✅ Yes | Laminate and protect from fire/water |
+| Password manager | ⚠️ Use reputable ones | 1Password, Bitwarden, etc. |
+
+**Backup checklist:**
+- [ ] Create at least **2 independent backups** on different media
+- [ ] Verify backups are readable before relying on them
+- [ ] Periodically check backup integrity (every 6 months)
+- [ ] Store backups in **different physical locations**
+
+### 1.2 Secure Storage
+
+**DO:**
+- Store notes in an encrypted container (GPG, VeraCrypt)
+- Use strong, unique passwords for encrypted containers
+- Keep firmware and software updated
+- Use air-gapped computers for critical operations
+
+**DON'T:**
+- Store notes in plain text files
+- Keep notes in cloud-synced folders without encryption
+- Share notes via email, messaging apps, or screenshots
+- Store notes on devices connected to the internet
+
+### 1.3 Never Share Notes
+
+> ⚠️ **CRITICAL: Your note is your funds. Anyone with your note can withdraw your deposit.**
+
+**Never share your note under any circumstances.** PrivacyLayer staff will NEVER ask for your note.
+
+**Legitimate scenarios where you might share a note (use extreme caution):**
+- Withdrawal verification (only when YOU initiate the process)
+- Auditing (use read-only tools, never expose the raw note)
+
+**Red flags — STOP immediately:**
+- Anyone asking for your note to "verify" your account
+- "Support" requests requiring note access
+- Phishing attempts with privacy pool branding
+
+### 1.4 Recovery Impossibility
+
+PrivacyLayer is designed so that:
+
+- **No one** (including the development team) can recover your note
+- **No password reset** is possible
+- **No central authority** holds backup keys
+- **No KYC data** is linked to your notes
+
+This is a **feature**, not a bug. It ensures true privacy. Accept the trade-off: **you are solely responsible for your note's security.**
+
+---
+
+## 2. Privacy Practices
+
+PrivacyLayer hides the link between your deposit and withdrawal — but only if you follow these practices.
+
+### 2.1 Wait Time Between Deposit and Withdrawal
+
+| Scenario | Minimum Wait | Recommendation |
+|----------|-------------|----------------|
+| Small privacy amount | 24 hours | Wait 1–7 days for better privacy |
+| Large privacy amount | 7+ days | Wait 2–4 weeks |
+| High-risk activity | 30+ days | Extreme caution for large sums |
+
+**Why wait?** The longer the time between deposit and withdrawal, the harder it is to correlate transactions on-chain.
+
+### 2.2 Use Different Addresses
+
+Always use **fresh, unrelated addresses** for:
+
+- Deposit address (where you send funds FROM)
+- Withdrawal address (where you receive funds TO)
+
+**Best practices:**
+- Never reuse addresses
+- Use a new address for each privacy session
+- Ensure deposit and withdrawal addresses have no prior transaction history together
+- Consider using intermediate addresses for large amounts
+
+```
+❌ BAD: Deposit from A → Withdraw to B where A and B have prior transactions
+✅ GOOD: Deposit from A → Withdraw to C (no prior relationship to A)
+```
+
+### 2.3 Avoid Patterns
+
+**Transaction patterns can break privacy:**
+
+| Avoid | Instead |
+|-------|---------|
+| Regular deposits/withdrawals at set times | Vary amounts and timing |
+| Round numbers (1000 XLM, 100 USDC) | Add small random amounts |
+| Always withdrawing to the same address | Rotate withdrawal destinations |
+| Predictable deposit amounts | Use variable denominations |
+| Same-time-of-day transactions | Distribute across different times |
+
+### 2.4 Privacy Pool Parameters
+
+| Parameter | Recommended Setting |
+|-----------|-------------------|
+| Minimum deposit denomination | Follow pool's base denomination |
+| Deposit batching | Group deposits, wait between each |
+| Withdrawal frequency | Reduce frequency for large amounts |
+| Address generation | Use SDK's built-in address generation |
+
+---
+
+## 3. Operational Security
+
+### 3.1 Computer Security
+
+**Essential practices:**
+
+- Use a dedicated device for privacy pool transactions
+- Keep OS and software updated
+- Use reputable antivirus/antimalware
+- Enable firewall
+- Use hardware security keys (YubiKey, etc.) for sensitive accounts
+
+**For maximum security — Air-Gapped Setup:**
+
+```
+Internet ─ ✗ DISCONNECTED ▼
+         │
+    [USB Drive]
+         │
+   [Air-Gapped Computer]
+         │
+    [Generate & Sign Transactions]
+         │
+      [USB Drive]
+         │
+   [Online Computer]
+         │
+   [Broadcast to Stellar]
+```
+
+### 3.2 Network Privacy
+
+- **Avoid** using PrivacyLayer on public Wi-Fi
+- Use Tor or a reputable VPN for additional network privacy
+- Check for DNS leaks
+- Consider using a network-isolated setup for sensitive operations
+
+### 3.3 Smart Contract Interaction
+
+**Before interacting with PrivacyLayer:**
+
+- [ ] Verify contract address on official sources (GitHub, Stellar.expert)
+- [ ] Test with a small amount first
+- [ ] Read the contract source code if technically capable
+- [ ] Check for recent security audits
+- [ ] Monitor official channels for security announcements
+
+---
+
+## 4. Common Pitfalls
+
+### 4.1 User Errors
+
+| Mistake | Consequence | Prevention |
+|---------|-------------|------------|
+| Losing note | Permanent fund loss | Multiple encrypted backups |
+| Sharing note | Funds stolen | Never share, ever |
+| Reusing addresses | Privacy reduced | Always use fresh addresses |
+| Rushing withdrawals | Privacy broken | Wait appropriate time |
+| Ignoring denominational limits | Transaction failure | Check pool config before depositing |
+
+### 4.2 Scam Prevention
+
+**Recognize and avoid:**
+
+- ❌ Fake "PrivacyLayer support" DMs — staff will never DM you first
+- ❌ Unofficial websites mimicking PrivacyLayer
+- ❌ "Guaranteed privacy" claims — no system is 100% private
+- ❌ Requests to send funds to "verify" your wallet
+- ❌ Phishing emails with fake PrivacyLayer links
+
+**Verify official channels:**
+- GitHub: [ANAVHEOBA/PrivacyLayer](https://github.com/ANAVHEOBA/PrivacyLayer)
+- Official documentation only from these sources
+
+### 4.3 Technical Pitfalls
+
+- **Clock sync issues** — Ensure your device clock is accurate (Stellar uses UTC)
+- **Insufficient balance** — Always reserve XLM for fees (minimum ~1 XLM fee)
+- **Wrong network** — Double-check you're on Stellar mainnet/testnet
+- **Transaction timeout** — Some operations may take time; wait for confirmation
+
+---
+
+## 5. Emergency Procedures
+
+### 5.1 If Your Note is Compromised
+
+1. **ACT FAST** — If someone else has your note, they can withdraw your funds immediately
+2. Withdraw ALL funds from the compromised note immediately
+3. Generate a new note and secure it properly
+4. Report the incident (for documentation, not recovery)
+
+### 5.2 If You Lose Your Note
+
+**Unfortunately, there is no recovery path.** This is by design.
+
+**Prevention is the only solution:**
+- Follow the backup procedures in Section 1.1
+- Use the checklist to verify your backup strategy
+- Test restore procedure periodically
+
+### 5.3 Suspected Phishing/Scam
+
+1. **DO NOT** interact with the suspicious entity
+2. Verify through official channels
+3. Report to the PrivacyLayer community
+4. Share details to warn others (without exposing your sensitive data)
+
+---
+
+## Quick Reference Checklist
+
+### Before Each Transaction
+
+- [ ] Device clock synced and secure
+- [ ] Official contract address verified
+- [ ] Sufficient balance for fees + deposit
+- [ ] Fresh withdrawal address prepared
+- [ ] No public Wi-Fi or VPN concerns
+
+### Long-Term Security
+
+- [ ] 2+ encrypted backups created
+- [ ] Backups in different physical locations
+- [ ] Backup integrity verified
+- [ ] Hardware security key configured
+- [ ] No sensitive data in plain text anywhere
+
+---
+
+## Security Contacts
+
+- **Bug Bounties:** See [Bug Bounty Program](../../BugBounty.md)
+- **Security Disclosures:** Via GitHub Security Advisories
+- **Questions:** Open a GitHub Discussion (NEVER share your note)
+
+---
+
+*Last updated: 2026-03-26*

From bc4398132ad9cccdf25f6a132f6b942af1f878d1 Mon Sep 17 00:00:00 2001
From: asdas6wdqc <142989356+asdas6wdqc@users.noreply.github.com>
Date: Thu, 26 Mar 2026 19:31:39 +0800
Subject: [PATCH 2/3] docs: create docs directory

---
 docs/.gitkeep | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 docs/.gitkeep

diff --git a/docs/.gitkeep b/docs/.gitkeep
new file mode 100644
index 0000000..8d1c8b6
--- /dev/null
+++ b/docs/.gitkeep
@@ -0,0 +1 @@
+ 

From 22a9bc5ac8e76072ed24fddde0960dc01ea3021c Mon Sep 17 00:00:00 2001
From: asdas6wdqc <142989356+asdas6wdqc@users.noreply.github.com>
Date: Thu, 26 Mar 2026 19:32:35 +0800
Subject: [PATCH 3/3] docs: rewrite SECURITY_BEST_PRACTICES.md for Issue #47

---
 docs/SECURITY_BEST_PRACTICES.md | 473 ++++++++++++++++++++------------
 1 file changed, 300 insertions(+), 173 deletions(-)

diff --git a/docs/SECURITY_BEST_PRACTICES.md b/docs/SECURITY_BEST_PRACTICES.md
index acfaee5..20455b7 100644
--- a/docs/SECURITY_BEST_PRACTICES.md
+++ b/docs/SECURITY_BEST_PRACTICES.md
@@ -1,6 +1,6 @@
-# Security Best Practices Guide
+# 🛡️ PrivacyLayer Security Best Practices Guide
 
-> 🔐 Protect your privacy. Protect your funds. This guide covers essential security practices for using PrivacyLayer.
+> **Protect your privacy. Protect your funds.** This guide explains how to use PrivacyLayer safely and effectively.
 
 ---
 
@@ -9,265 +9,392 @@
 1. [Note Management](#1-note-management)
 2. [Privacy Practices](#2-privacy-practices)
 3. [Operational Security](#3-operational-security)
-4. [Common Pitfalls](#4-common-pitfalls)
-5. [Emergency Procedures](#5-emergency-procedures)
+4. [Common Mistakes](#4-common-mistakes)
+5. [Threat Model](#5-threat-model)
+6. [Emergency Procedures](#6-emergency-procedures)
 
 ---
 
 ## 1. Note Management
 
-Your note is the **only proof of your deposit**. Loss of note = permanent loss of funds. There is no recovery mechanism.
+### 1.1 What Is a Note?
 
-### 1.1 Backup Strategies
+A **note** is your secret proof of deposit. It contains two critical values:
 
-| Method | Recommended | Notes |
-|--------|-------------|-------|
-| Encrypted USB drive | ✅ Yes | Store in a secure physical location |
-| Hardware wallet (air-gapped) | ✅ Yes | Best for large amounts |
-| Encrypted cloud storage | ⚠️ Use with caution | Ensure strong encryption and 2FA |
-| Paper backup | ✅ Yes | Laminate and protect from fire/water |
-| Password manager | ⚠️ Use reputable ones | 1Password, Bitwarden, etc. |
+- **Nullifier** — a unique secret that identifies your deposit on-chain
+- **Secret** — random data used to derive your commitment
 
-**Backup checklist:**
-- [ ] Create at least **2 independent backups** on different media
-- [ ] Verify backups are readable before relying on them
-- [ ] Periodically check backup integrity (every 6 months)
-- [ ] Store backups in **different physical locations**
+Together, these form a **note** that proves you own the deposited funds. **Losing a note means losing access to those funds permanently.**
 
-### 1.2 Secure Storage
+### 1.2 Backup Strategies
 
-**DO:**
-- Store notes in an encrypted container (GPG, VeraCrypt)
-- Use strong, unique passwords for encrypted containers
-- Keep firmware and software updated
-- Use air-gapped computers for critical operations
+#### ✅ Do This
 
-**DON'T:**
-- Store notes in plain text files
-- Keep notes in cloud-synced folders without encryption
-- Share notes via email, messaging apps, or screenshots
-- Store notes on devices connected to the internet
+- **Export immediately** after every deposit. Do not rely on memory or local storage.
+- Save notes in **at least 2 separate locations**:
+  - Encrypted file on an air-gapped computer
+  - Hardware wallet seed phrase backup (if the note is incorporated into a seed phrase system)
+  - Encrypted USB drive stored in a secure physical location
+- Use **password-protected encrypted archives** (e.g., GPG symmetric encryption: `gpg --symmetric --cipher-algo AES256 note.txt`)
+- Label backups clearly so you or your trusted contacts can identify them in an emergency
 
-### 1.3 Never Share Notes
+#### ❌ Never Do This
 
-> ⚠️ **CRITICAL: Your note is your funds. Anyone with your note can withdraw your deposit.**
+- **Never** take a screenshot of your note. Screenshots sync to cloud services and can be extracted from backup files.
+- **Never** paste notes into chat apps (Telegram, Discord, email). These services log messages on servers.
+- **Never** store notes in plain text on your phone or computer.
+- **Never** send notes to yourself via email or messaging apps as a "backup."
+- **Never** share notes with anyone, including people claiming to be support staff.
 
-**Never share your note under any circumstances.** PrivacyLayer staff will NEVER ask for your note.
+### 1.3 Secure Storage
 
-**Legitimate scenarios where you might share a note (use extreme caution):**
-- Withdrawal verification (only when YOU initiate the process)
-- Auditing (use read-only tools, never expose the raw note)
-
-**Red flags — STOP immediately:**
-- Anyone asking for your note to "verify" your account
-- "Support" requests requiring note access
-- Phishing attempts with privacy pool branding
+| Storage Method | Security Level | Notes |
+|---------------|---------------|-------|
+| Hardware wallet (encrypted) | 🟢 Excellent | Best for large amounts |
+| Air-gapped computer | 🟢 Excellent | No network access |
+| Encrypted USB drive | 🟡 Good | Physical security required |
+| Password manager (encrypted) | 🟡 Good | Use a strong master password |
+| Cloud storage (encrypted by you) | 🟡 Good | Ensure encryption is client-side |
+| Plain USB drive | 🔴 Dangerous | Too easy to lose or steal |
+| Screenshot / Notes app | 🔴 Dangerous | No encryption, easy to extract |
 
 ### 1.4 Recovery Impossibility
 
-PrivacyLayer is designed so that:
+> ⚠️ **Critical:** PrivacyLayer is designed so that **no one — not even the PrivacyLayer team — can recover a lost note.**
+
+This is a fundamental property of zero-knowledge proofs:
 
-- **No one** (including the development team) can recover your note
-- **No password reset** is possible
-- **No central authority** holds backup keys
-- **No KYC data** is linked to your notes
+- The contract only stores **commitments** (hashed values), not the underlying secrets.
+- Without the original note, there is no way to generate a valid withdrawal proof.
+- There is no backdoor, no admin override, and no recovery mechanism.
+- If you lose your note, your deposited funds are **permanently unrecoverable**.
 
-This is a **feature**, not a bug. It ensures true privacy. Accept the trade-off: **you are solely responsible for your note's security.**
+**Before depositing, ensure you have a reliable backup system in place.**
 
 ---
 
 ## 2. Privacy Practices
 
-PrivacyLayer hides the link between your deposit and withdrawal — but only if you follow these practices.
-
 ### 2.1 Wait Time Between Deposit and Withdrawal
 
-| Scenario | Minimum Wait | Recommendation |
-|----------|-------------|----------------|
-| Small privacy amount | 24 hours | Wait 1–7 days for better privacy |
-| Large privacy amount | 7+ days | Wait 2–4 weeks |
-| High-risk activity | 30+ days | Extreme caution for large sums |
+The **anonymity set** (the group of deposits your transaction is mixed with) grows over time. Withdrawing immediately after depositing creates a **temporal link** that can be used to de-anonymize transactions.
+
+#### Recommended Wait Times
 
-**Why wait?** The longer the time between deposit and withdrawal, the harder it is to correlate transactions on-chain.
+| Amount Size | Minimum Wait | Recommended Wait |
+|-------------|-------------|------------------|
+| Small (< $100 equivalent) | 4 hours | 24 hours |
+| Medium ($100–$1,000) | 12 hours | 3–7 days |
+| Large (> $1,000) | 3 days | 2–4 weeks |
+
+> **Rule of thumb:** The larger your deposit relative to the pool's activity, the longer you should wait before withdrawing.
 
 ### 2.2 Use Different Addresses
 
-Always use **fresh, unrelated addresses** for:
+Always withdraw to a **fresh address** that has never been associated with your real identity:
 
-- Deposit address (where you send funds FROM)
-- Withdrawal address (where you receive funds TO)
+- **Do not** withdraw to an exchange deposit address (exchanges link all transactions to your identity via KYC).
+- **Do not** withdraw to an address you've used before in a non-private context.
+- **Do** use a brand-new Stellar account created specifically for this withdrawal.
+- **Do** consider using a sub-account if your wallet supports account creation.
 
-**Best practices:**
-- Never reuse addresses
-- Use a new address for each privacy session
-- Ensure deposit and withdrawal addresses have no prior transaction history together
-- Consider using intermediate addresses for large amounts
+#### Address Checklist Before Withdrawal
 
-```
-❌ BAD: Deposit from A → Withdraw to B where A and B have prior transactions
-✅ GOOD: Deposit from A → Withdraw to C (no prior relationship to A)
-```
+- [ ] The withdrawal address has never received funds from a KYC'd source
+- [ ] The withdrawal address has no transaction history on-chain
+- [ ] You control the private key for this address (not a custodial wallet)
+- [ ] The address is not associated with any identity-revealing service
 
 ### 2.3 Avoid Patterns
 
-**Transaction patterns can break privacy:**
+Traffic analysis can link deposits to withdrawals even with time delays:
+
+- **Avoid regular intervals.** If you deposit every Monday at 9 AM and withdraw every Tuesday, patterns emerge.
+- **Avoid round numbers.** Withdrawing exactly 100.0000000 XLM is more identifiable than 99.8472913 XLM.
+- **Avoid repeated amounts.** If you always deposit exactly 500 XLM, correlating transactions becomes easier.
+- **Vary your deposit/withdrawal sizes** to blend into the broader distribution of transactions.
 
-| Avoid | Instead |
-|-------|---------|
-| Regular deposits/withdrawals at set times | Vary amounts and timing |
-| Round numbers (1000 XLM, 100 USDC) | Add small random amounts |
-| Always withdrawing to the same address | Rotate withdrawal destinations |
-| Predictable deposit amounts | Use variable denominations |
-| Same-time-of-day transactions | Distribute across different times |
+### 2.4 Network Privacy (VPN / Tor)
 
-### 2.4 Privacy Pool Parameters
+Your IP address can be a linking vector:
 
-| Parameter | Recommended Setting |
-|-----------|-------------------|
-| Minimum deposit denomination | Follow pool's base denomination |
-| Deposit batching | Group deposits, wait between each |
-| Withdrawal frequency | Reduce frequency for large amounts |
-| Address generation | Use SDK's built-in address generation |
+- **Connect to the PrivacyLayer interface through a VPN** to prevent IP-based transaction correlation.
+- **Use Tor Browser** for maximum network-level anonymity (ensure JavaScript is enabled for the app to function).
+- **Avoid using the same VPN exit node** for both deposit and withdrawal transactions.
+- **Be aware of DNS leaks** — use `dns leak test` sites to verify your VPN is working correctly.
+
+> **Note:** PrivacyLayer itself does not log IPs, but your ISP and network infrastructure may.
 
 ---
 
 ## 3. Operational Security
 
-### 3.1 Computer Security
+### 3.1 Wallet Security
+
+Your Stellar wallet is the gateway to PrivacyLayer. Protect it accordingly:
+
+#### Hot Wallet (For Regular Use)
+
+- Use a **non-custodial wallet** (e.g.,LOBSTR, Solar Wallet, or a self-hosted Freighter).
+- Enable **all available security features**: PIN/biometric, app lock, spending limits.
+- Keep only the amount you're actively using in the hot wallet.
+- Never share your private key or seed phrase. PrivacyLayer will never ask for it.
+
+#### Cold Storage (For Large Amounts)
+
+- For amounts exceeding your personal comfort threshold, use a **hardware wallet** (Ledger, Trezor).
+- Hardware wallets keep private keys physically isolated from internet-connected devices.
+- Set up a **watch-only address** in your hot wallet to monitor your cold storage without exposing the keys.
+
+#### Seed Phrase Backup
+
+- Write your seed phrase on **paper** (laminate it for durability) or use a **metal seed phrase backup** (e.g., Cryptosteel, Billfodl).
+- Store the backup in a **secure physical location** (safe, bank deposit box).
+- **Never** take a digital photo or scan of your seed phrase.
+- **Never** store your seed phrase in a password manager that is accessed from an internet-connected device.
 
-**Essential practices:**
+### 3.2 Transaction Privacy
 
-- Use a dedicated device for privacy pool transactions
-- Keep OS and software updated
-- Use reputable antivirus/antimalware
-- Enable firewall
-- Use hardware security keys (YubiKey, etc.) for sensitive accounts
+#### On-Chain Behavior
 
-**For maximum security — Air-Gapped Setup:**
+- **Do not** transact directly from your PrivacyLayer withdrawal address. Send funds to a **intermediary address first**, then to the final destination.
+- **Break up amounts.** If you withdraw 1,000 XLM but need to pay 3 different people, split the funds through separate intermediary addresses, not from one transaction.
+- **Avoid blockchain explorers.** Paste your addresses into public block explorers as little as possible — these services can log and correlate your queries with your IP.
+
+#### Intermediary Address Pattern
 
 ```
-Internet ─ ✗ DISCONNECTED ▼
-         │
-    [USB Drive]
-         │
-   [Air-Gapped Computer]
-         │
-    [Generate & Sign Transactions]
-         │
-      [USB Drive]
-         │
-   [Online Computer]
-         │
-   [Broadcast to Stellar]
+PrivacyPool Withdrawal
+        ↓ (fresh address A)
+  Intermediary Address (1-7 days)
+        ↓ (split or mix)
+  Final Destination Addresses
 ```
 
-### 3.2 Network Privacy
+### 3.3 Metadata Protection
+
+Even if your transaction is private, metadata can betray you:
+
+- **Browser fingerprinting:** Use a dedicated browser profile or Firefox with strict privacy settings for PrivacyLayer. Avoid Chrome (Google ties everything to your account).
+- **Timezone consistency:** If your computer is set to UTC+8 but your VPN is in Germany, that mismatch is a data point.
+- **System font list:** Unusual fonts installed on your system can be used to identify you.
+- **Canvas / WebGL fingerprints:** Use privacy extensions (uBlock Origin, Canvas Blocker) to prevent fingerprinting.
+
+#### Recommended Browser Setup
 
-- **Avoid** using PrivacyLayer on public Wi-Fi
-- Use Tor or a reputable VPN for additional network privacy
-- Check for DNS leaks
-- Consider using a network-isolated setup for sensitive operations
+```
+Browser: Firefox (with Multi-Account Containers) or Tor Browser
+Extensions: uBlock Origin, Canvas Blocker, HTTPS Everywhere
+VPN: Enabled (ideally a no-log VPN provider)
+JavaScript: Enabled (required for PrivacyLayer UI)
+Cookies: Clear between sessions or use container tabs
+```
 
-### 3.3 Smart Contract Interaction
+### 3.4 Browser Fingerprinting
 
-**Before interacting with PrivacyLayer:**
+PrivacyLayer's web interface can be vulnerable to browser fingerprinting:
 
-- [ ] Verify contract address on official sources (GitHub, Stellar.expert)
-- [ ] Test with a small amount first
-- [ ] Read the contract source code if technically capable
-- [ ] Check for recent security audits
-- [ ] Monitor official channels for security announcements
+| Fingerprint Vector | Risk Level | Mitigation |
+|-------------------|-----------|-----------|
+| Canvas rendering | Medium | Use Canvas Blocker extension |
+| WebGL renderer | Medium | Disable WebGL or use privacy extension |
+| Screen resolution | Low | Use standard resolution (1920×1080) |
+| Timezone | Low | Set to UTC or match VPN location |
+| Installed fonts | Low-Medium | Use system fonts only |
+| User agent | Low | Don't customize; use defaults |
 
 ---
 
-## 4. Common Pitfalls
+## 4. Common Mistakes
+
+### 4.1 Reusing Addresses
+
+**The classic privacy mistake.** Using the same address for deposits and withdrawals creates an **on-chain link** between your identity and your private transaction.
+
+**Impact:** Even if your withdrawal is private, the public ledger will show that Address A (which may be linked to your identity) sent funds to the privacy pool, and Address B (your withdrawal address) received funds. Chain analysis firms can use this link to reduce the anonymity set dramatically.
+
+**Fix:** Always use fresh addresses for every transaction.
+
+### 4.2 Immediate Withdrawals
+
+Depositing and withdrawing the same amount within a short time window creates a **temporal correlation**.
+
+**Impact:** If you deposit 500 XLM at 10:00 AM and withdraw 500 XLM at 10:05 AM, it's trivial to infer that these are the same transaction. Chain analysis reduces the effective anonymity set to a handful of transactions.
+
+**Fix:** Always wait the recommended time before withdrawing (see Section 2.1).
+
+### 4.3 Small Anonymity Sets
+
+Withdrawing a **unique amount** when the pool has few deposits creates a trivially identifiable transaction.
 
-### 4.1 User Errors
+**Example:** If only one person deposited exactly 1,337.0000000 XLM in the past week, withdrawing that exact amount immediately identifies your transaction, regardless of wait time.
 
-| Mistake | Consequence | Prevention |
-|---------|-------------|------------|
-| Losing note | Permanent fund loss | Multiple encrypted backups |
-| Sharing note | Funds stolen | Never share, ever |
-| Reusing addresses | Privacy reduced | Always use fresh addresses |
-| Rushing withdrawals | Privacy broken | Wait appropriate time |
-| Ignoring denominational limits | Transaction failure | Check pool config before depositing |
+**Fix:** Choose deposit amounts that match common transaction sizes in the pool. Avoid odd, specific amounts.
 
-### 4.2 Scam Prevention
+### 4.4 Linking Transactions
 
-**Recognize and avoid:**
+Sending the **same amount** to and from the pool from the **same IP address** or device can create a linking vector.
 
-- ❌ Fake "PrivacyLayer support" DMs — staff will never DM you first
-- ❌ Unofficial websites mimicking PrivacyLayer
-- ❌ "Guaranteed privacy" claims — no system is 100% private
-- ❌ Requests to send funds to "verify" your wallet
-- ❌ Phishing emails with fake PrivacyLayer links
+**Impact:** Even if the on-chain transaction is private, network-level correlation can connect:
+1. Your deposit transaction (from your IP)
+2. Your withdrawal transaction (from your IP or same device)
 
-**Verify official channels:**
-- GitHub: [ANAVHEOBA/PrivacyLayer](https://github.com/ANAVHEOBA/PrivacyLayer)
-- Official documentation only from these sources
+**Fix:** Use different devices or VPNs for deposit and withdrawal. Wait between transactions. Split amounts.
 
-### 4.3 Technical Pitfalls
+### 4.5 Assuming Perfect Privacy
 
-- **Clock sync issues** — Ensure your device clock is accurate (Stellar uses UTC)
-- **Insufficient balance** — Always reserve XLM for fees (minimum ~1 XLM fee)
-- **Wrong network** — Double-check you're on Stellar mainnet/testnet
-- **Transaction timeout** — Some operations may take time; wait for confirmation
+PrivacyLayer provides **probabilistic privacy**, not absolute anonymity.
+
+- The anonymity set determines how many possible deposits your withdrawal could come from.
+- A withdraw from a pool with only 3 deposits is **83% identifiable** (1 out of 3).
+- A withdraw from a pool with 1,000 deposits is **0.1% identifiable**.
+- **The larger the pool and the longer the wait, the better your privacy.**
 
 ---
 
-## 5. Emergency Procedures
+## 5. Threat Model
+
+### 5.1 What Privacy Is Provided
+
+PrivacyLayer breaks the **on-chain link** between deposit and withdrawal addresses using zero-knowledge proofs:
+
+- ✅ The Stellar network does not know which deposit corresponds to which withdrawal
+- ✅ Block explorers cannot trace funds through the PrivacyLayer contract
+- ✅ Chain analysis firms cannot automatically link deposit and withdrawal addresses
+- ✅ There is no on-chain record of the amount, sender, or receiver within the pool
+
+### 5.2 What Privacy Is NOT Provided
+
+PrivacyLayer is not a silver bullet. The following are **NOT protected** by the protocol:
+
+- 🔴 **IP address correlation** (without additional tools like VPN/Tor)
+- 🔴 **Timing correlation** (deposits and withdrawals at the same time are linkable)
+- 🔴 **Amount correlation** (exact-amount matches reduce anonymity set)
+- 🔴 **KYC-linked addresses** (if you withdraw to a KYC'd exchange, your identity is revealed)
+- 🔴 **Browser fingerprinting** (your browser setup can identify you)
+- 🔴 **Network-level attacks** (ISP surveillance, VPN logging, exit node monitoring)
+- 🔴 **Social engineering** (you can still be tricked into revealing your note)
+
+### 5.3 Attack Scenarios
 
-### 5.1 If Your Note is Compromised
+#### Chain Analysis (Most Common Threat)
 
-1. **ACT FAST** — If someone else has your note, they can withdraw your funds immediately
-2. Withdraw ALL funds from the compromised note immediately
-3. Generate a new note and secure it properly
-4. Report the incident (for documentation, not recovery)
+An adversary (exchange, chain analysis firm, government agency) monitors the Stellar network and tries to link deposits to withdrawals.
 
-### 5.2 If You Lose Your Note
+**Mitigation:** Wait longer than the anonymity set growth curve. Split amounts. Use fresh addresses.
 
-**Unfortunately, there is no recovery path.** This is by design.
+#### Front-Running
 
-**Prevention is the only solution:**
-- Follow the backup procedures in Section 1.1
-- Use the checklist to verify your backup strategy
-- Test restore procedure periodically
+An adversary watches the mempool for PrivacyLayer deposits and tries to front-run by depositing a large amount to reduce your effective anonymity set.
 
-### 5.3 Suspected Phishing/Scam
+**Mitigation:** Split deposits across multiple transactions. Wait between deposits. Use privacy-preserving transaction submission.
 
-1. **DO NOT** interact with the suspicious entity
-2. Verify through official channels
-3. Report to the PrivacyLayer community
-4. Share details to warn others (without exposing your sensitive data)
+#### Collusion Between Depositors
+
+If multiple parties collaborate, they can share deposit data to narrow down withdrawal candidates.
+
+**Mitigation:** Assume some depositors may be adversarial. Use non-standard amounts and timing.
+
+#### Quantum Computing Threat
+
+Future quantum computers could potentially break the Groth16 zkSNARK proofs used by PrivacyLayer.
+
+**Current mitigation:** PrivacyLayer uses Stellar Protocol 25's BN254 curve. Post-quantum alternatives are an active research area. Monitor developments and consider moving funds if a quantum threat becomes practical.
+
+### 5.4 Limitations
+
+- **Fixed denominations only.** PrivacyLayer currently supports fixed-denomination deposits (e.g., 1, 10, 100 XLM). Splitting or combining denominations reveals amounts.
+- **No smart contract composability.** PrivacyLayer withdrawals cannot be automatically routed into other DeFi protocols without revealing the withdrawal address.
+- **Liquidity dependency.** Privacy is only as strong as the pool's activity. Low-liquidity pools have reduced anonymity sets.
+- **Bridge privacy.** PrivacyLayer provides privacy within the Stellar ecosystem. Bridging to other chains may reveal information.
 
 ---
 
-## Quick Reference Checklist
+## 6. Emergency Procedures
+
+### 6.1 Lost Note
 
-### Before Each Transaction
+If you have lost or accidentally deleted your note backup:
 
-- [ ] Device clock synced and secure
-- [ ] Official contract address verified
-- [ ] Sufficient balance for fees + deposit
-- [ ] Fresh withdrawal address prepared
-- [ ] No public Wi-Fi or VPN concerns
+1. **Search thoroughly** in all backup locations (encrypted drives, password managers, physical locations).
+2. **Check email archives** (if you ever emailed yourself a backup).
+3. **Check cloud storage** (Google Drive, Dropbox — if you used cloud backup, the file may still be there).
+4. **Accept the reality:** If the note is genuinely lost, the funds are **permanently unrecoverable**. No one can help you. This is by design.
 
-### Long-Term Security
+#### Prevention Checklist
 
-- [ ] 2+ encrypted backups created
-- [ ] Backups in different physical locations
-- [ ] Backup integrity verified
-- [ ] Hardware security key configured
-- [ ] No sensitive data in plain text anywhere
+- [ ] Note exported immediately after deposit
+- [ ] At least 2 physical backup copies exist
+- [ ] Backup locations are secure and independent
+- [ ] You have tested restoring from backup (try a small amount first)
+
+### 6.2 Compromised Wallet
+
+If you believe your Stellar wallet private key has been compromised:
+
+1. **Transfer all funds immediately** to a new, secure wallet (not through PrivacyLayer — that reveals your address).
+2. **Do not** use PrivacyLayer to transfer the funds — a compromised device may also be logging your PrivacyLayer activity.
+3. **Create a new wallet** on a clean, malware-free device.
+4. **Generate a new PrivacyLayer note** if you have existing deposits and still have their notes.
+
+> **Note:** If your wallet was compromised **before** you deposited into PrivacyLayer, the attacker may have sent funds directly. In this case, PrivacyLayer cannot help — the transaction is already on-chain.
+
+### 6.3 Contract Paused
+
+The PrivacyLayer contract has an **admin pause function** for emergency situations (critical vulnerability detected, governance attack, etc.).
+
+If the contract is paused:
+
+- **Deposits are disabled.** You cannot deposit new funds.
+- **Withdrawals are disabled.** You cannot withdraw existing funds during the pause.
+- **Funds remain safe.** Your funds are locked in the contract and are not at risk.
+- **Monitor official channels** for updates on unpausing and next steps.
+
+The pause function exists to protect users. In most cases, a pause means a serious issue was discovered and the team needs time to fix it. **Do not panic.** Follow official announcements.
+
+### 6.4 Support Resources
+
+> ⚠️ **警惕钓鱼:** 永远不要向"支持人员"分享你的种子短语或 note。
+
+| Resource | URL / Contact | Use Case |
+|----------|---------------|----------|
+| Official GitHub | github.com/ANAVHEOBA/PrivacyLayer | Issue tracking, bug reports |
+| PrivacyLayer Docs | `docs/USER_GUIDE.md` | Usage instructions |
+| Stellar Development Foundation | stellar.org | Soroban/Protocol updates |
+| Security Disclosures | (Check GitHub for PGP contact) | Report security vulnerabilities |
+
+**PrivacyLayer team will NEVER:**
+- Ask for your seed phrase or private key
+- Ask for your note
+- Ask you to send funds to an "official" address
+- Request remote access to your device
 
 ---
 
-## Security Contacts
+## Quick Reference Card
 
-- **Bug Bounties:** See [Bug Bounty Program](../../BugBounty.md)
-- **Security Disclosures:** Via GitHub Security Advisories
-- **Questions:** Open a GitHub Discussion (NEVER share your note)
+```
+┌─────────────────────────────────────────────────────────┐
+│                  PRIVACYLAYER — DO'S & DON'TS           │
+├─────────────────────────────────────────────────────────┤
+│ ✅ ALWAYS                                                   │
+│  - Backup notes immediately after deposit                 │
+│  - Wait before withdrawing (min 4h, rec. 24h+)           │
+│  - Use fresh addresses for every withdrawal              │
+│  - Use VPN/Tor for network-level anonymity              │
+│  - Split amounts to avoid pattern matching              │
+│  - Use non-custodial wallets                            │
+├─────────────────────────────────────────────────────────┤
+│  ❌ NEVER                                                   │
+│  - Share your note with anyone                          │
+│  - Withdraw to a KYC'd exchange address                 │
+│  - Deposit and withdraw immediately                     │
+│  - Use the same address for deposit and withdrawal      │
+│  - Use a screenshot or plain text for note storage      │
+│  - Send funds directly from PrivacyLayer to an exchange │
+└─────────────────────────────────────────────────────────┘
+```
 
 ---
 
-*Last updated: 2026-03-26*
+*Last updated: 2026-03-26 | PrivacyLayer v1.0 | For the latest version, see [github.com/ANAVHEOBA/PrivacyLayer](https://github.com/ANAVHEOBA/PrivacyLayer)*