diff --git a/docs/FAQ.md b/docs/FAQ.md
new file mode 100644
index 0000000..5893dd3
--- /dev/null
+++ b/docs/FAQ.md
@@ -0,0 +1,224 @@
+# PrivacyLayer FAQ
+
+## General Questions
+
+### What is PrivacyLayer?
+PrivacyLayer is the first ZK-proof shielded pool implementation on Stellar Soroban, enabling compliance-forward private transactions using zero-knowledge proofs.
+
+### How does PrivacyLayer work?
+Users deposit fixed-denomination assets (XLM or USDC) into a shielded pool and can withdraw them to any address using zero-knowledge proofs, with no on-chain link between deposits and withdrawals.
+
+### What makes PrivacyLayer unique?
+PrivacyLayer leverages Stellar Protocol 25's native BN254 elliptic curve and Poseidon hash function cryptographic primitives, eliminating external dependencies and optimizing performance.
+
+## Technical Questions
+
+### What cryptographic primitives does PrivacyLayer use?
+PrivacyLayer uses:
+- **BN254 elliptic curve**: For efficient Groth16 proof verification
+- **Poseidon hash function**: For commitment generation (ZK-friendly)
+- **Groth16 proof system**: For zero-knowledge proofs
+- **Incremental Merkle trees**: For efficient membership proofs (depth=20)
+
+### Is PrivacyLayer secure?
+PrivacyLayer uses battle-tested cryptographic algorithms (BN254 and Poseidon) with native protocol integration. However, the implementation requires formal security audits before production use.
+
+### How does withdrawal work?
+1. Prove membership of a commitment in the Merkle tree
+2. Generate a Groth16 proof using BN254
+3. Submit proof for on-chain verification
+4. Receive funds at withdrawal address
+
+### What assets are supported?
+Currently supports XLM and USDC in fixed denominations. Additional asset support can be added through contract upgrades.
+
+### What are fixed denominations?
+Fixed denominations ensure all deposits have the same value, simplifying the ZK proof system and preventing value leakage through proofs.
+
+## Development Questions
+
+### What skills are needed to contribute?
+- Rust (for Soroban contracts)
+- Noir (for ZK circuits)
+- TypeScript (for SDK development)
+- Understanding of ZK cryptography
+
+### How do I get started with development?
+See the [Getting Started](#getting-started) section in the main README for setup instructions.
+
+### What tools are required?
+- Rust and cargo for contract development
+- Noir and nargo for circuit development
+- Stellar CLI for contract deployment
+- TypeScript/Node.js for SDK development
+
+### Can I contribute without deep ZK knowledge?
+Yes! Contributions include documentation, testing, UI development, SDK improvements, and educational content.
+
+## Usage Questions
+
+### How do I make a deposit?
+1. Generate a note with nullifier and secret
+2. Create commitment using Poseidon hash
+3. Call the deposit contract function with the commitment
+4. Assets are transferred to the shielded pool
+
+### How do I make a withdrawal?
+1. Generate a withdrawal proof using your note
+2. Submit proof to the withdrawal contract function
+3. Receive funds at specified withdrawal address
+
+### What happens if I lose my note?
+Notes contain the secret required for withdrawal. Losing a note means losing access to the deposited funds. Always backup notes securely.
+
+### Is there a maximum deposit amount?
+The system uses fixed denominations, so each deposit must match predefined amounts. Multiple deposits can be made for larger amounts.
+
+### How long does proof generation take?
+Proof generation time depends on hardware but typically ranges from seconds to minutes. Verification is fast thanks to native BN254 operations.
+
+## Compliance Questions
+
+### How is PrivacyLayer compliance-forward?
+PrivacyLayer maintains auditability through cryptographic proofs while providing transaction privacy. Organizations can verify compliance without exposing transaction details.
+
+### Can transactions be audited?
+Yes, zero-knowledge proofs can be verified to ensure compliance while keeping transaction details private.
+
+### Does PrivacyLayer support regulatory requirements?
+The system is designed to support selective disclosure and audit capabilities required by regulations.
+
+### How does PrivacyLayer prevent illicit activities?
+The shielded pool design prevents tracking but maintains cryptographic proofs for compliance verification.
+
+## Performance Questions
+
+### How efficient are the ZK proofs?
+PrivacyLayer is optimized for Stellar Protocol 25's native cryptographic primitives, making it more efficient than implementations requiring external libraries.
+
+### What is the gas cost for operations?
+Gas costs are minimized through:
+- Native BN254 operations (no WASM overhead)
+- Efficient Poseidon hash function
+- Optimized circuit design
+
+### How fast are deposits/withdrawals?
+Deposits are standard Soroban transactions. Withdrawals require proof generation (off-chain) and verification (on-chain).
+
+### What is the Merkle tree depth?
+The Merkle tree has depth 20, supporting up to 2^20 (1,048,576) commitments.
+
+## Comparison Questions
+
+### How does PrivacyLayer compare to other privacy solutions?
+PrivacyLayer differs by:
+- Using Stellar Protocol 25 native primitives
+- Designed for compliance-forward applications
+- Optimized for Soroban smart contracts
+- No external cryptographic dependencies
+
+### What advantages does PrivacyLayer have over traditional approaches?
+- Protocol-native cryptographic operations
+- No external library dependencies
+- Compliance-focused design
+- Efficient proof verification
+
+### How does it compare to Penumbra and Aztec?
+PrivacyLayer draws inspiration from these systems but is specifically designed for Stellar/Soroban with native protocol integration.
+
+## Future Questions
+
+### What features are planned?
+- Additional asset support
+- Enhanced compliance features
+- SDK improvements
+- Frontend interface development
+- Cross-chain capabilities
+
+### How can I get involved?
+- Submit issues or feature requests on GitHub
+- Contribute code, documentation, or tests
+- Create educational content
+- Participate in bounty programs
+
+### Where can I find more information?
+- [PrivacyLayer GitHub Repository](https://github.com/ANAVHEOBA/PrivacyLayer)
+- [Stellar Protocol 25 Documentation](https://stellar.org/protocol-25)
+- [Noir Language Documentation](https://noir-lang.org/docs)
+- [Soroban Documentation](https://soroban.stellar.org)
+
+## Getting Started
+
+### Prerequisites Installation
+```bash
+# Rust (for Soroban contracts)
+rustup target add wasm32-unknown-unknown
+
+# Stellar CLI
+cargo install --locked stellar-cli
+
+# Noir (for ZK circuits)
+curl -L https://raw.githubusercontent.com/noir-lang/noirup/refs/heads/main/install | bash
+noirup
+```
+
+### Building Circuits
+```bash
+cd circuits/commitment
+nargo build
+nargo test
+
+cd ../withdraw
+nargo build
+nargo test
+```
+
+### Building Contracts
+```bash
+cd contracts
+cargo build --target wasm32-unknown-unknown --release
+cargo test
+```
+
+### Testing
+```bash
+# Run all tests
+cargo test --all-features
+
+# Integration tests
+cargo test --test integration_test
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Circuit Build Failures**
+- Ensure Noir is properly installed
+- Check circuit parameters match specification
+- Verify input/output constraints
+
+**Contract Build Failures**
+- Ensure Rust and Soroban SDK are updated
+- Check WASM target availability
+- Verify BN254/Poseidon host function usage
+
+**Proof Generation Issues**
+- Verify note generation parameters
+- Check Merkle tree state synchronization
+- Ensure correct nullifier/secret usage
+
+**Verification Failures**
+- Check proof parameters match contract expectations
+- Verify BN254 pairing inputs
+- Ensure contract state matches circuit state
+
+### Getting Help
+- Check GitHub Issues for known problems
+- Review documentation and examples
+- Join community discussions
+- Contact maintainers for technical support
+
+---
+
+**Note**: This FAQ is continuously updated. Check the GitHub repository for the latest information.
\ No newline at end of file
diff --git a/docs/HACKATHON_STARTER_KIT.md b/docs/HACKATHON_STARTER_KIT.md
new file mode 100644
index 0000000..425334f
--- /dev/null
+++ b/docs/HACKATHON_STARTER_KIT.md
@@ -0,0 +1,300 @@
+# PrivacyLayer Hackathon Starter Kit 🏆
+
+> A comprehensive guide for hackathon participants to build with PrivacyLayer
+
+## Table of Contents
+1. [Quick Start](#quick-start)
+2. [Boilerplate Code](#boilerplate-code)
+3. [Example Projects](#example-projects)
+4. [Judging Criteria](#judging-criteria)
+5. [Prize Ideas](#prize-ideas)
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+```bash
+# Rust (for Soroban contracts)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+rustup target add wasm32-unknown-unknown
+
+# Stellar CLI
+cargo install --locked stellar-cli
+
+# Noir toolchain (nargo)
+curl -L https://raw.githubusercontent.com/noir-lang/noirup/refs/heads/main/install | bash
+noirup
+
+# Node.js 18+ (for SDK and frontend)
+# Use nvm: https://github.com/nvm-sh/nvm
+```
+
+### Clone and Build
+
+```bash
+# Clone the repository
+git clone https://github.com/ANAVHEOBA/PrivacyLayer.git
+cd PrivacyLayer
+
+# Build circuits
+cd circuits/commitment
+nargo build
+nargo test
+
+# Build contracts
+cd ../contracts
+cargo build --target wasm32-unknown-unknown --release
+```
+
+---
+
+## Boilerplate Code
+
+### Basic Deposit Contract
+
+```rust
+// contracts/privacy_pool/src/lib.rs (simplified example)
+use soroban_sdk::{contract, contractimpl, Address, Vec};
+
+#[contract]
+pub struct PrivacyPool;
+
+#[contractimpl]
+impl PrivacyPool {
+    /// Initialize the privacy pool
+    pub fn init(env: Env, admin: Address) {
+        // Set up initial configuration
+    }
+
+    /// Deposit funds into the privacy pool
+    /// Returns a note (nullifier + secret) that the user must save
+    pub fn deposit(env: Env, amount: i128) -> Vec<u8> {
+        // Generate nullifier and secret
+        // Create commitment
+        // Insert into Merkle tree
+        // Return note to user
+    }
+
+    /// Withdraw funds from the privacy pool
+    /// Requires a valid ZK proof
+    pub fn withdraw(env: Env, proof: Vec<u8>, recipient: Address) {
+        // Verify ZK proof
+        // Check nullifier hasn't been used
+        // Transfer funds to recipient
+    }
+}
+```
+
+### Basic Noir Circuit
+
+```noir
+// circuits/commitment/src/main.nr (simplified example)
+use dep::std;
+
+// Hash function using Poseidon
+fn hash(left: Field, right: Field) -> Field {
+    std::hash::poseidon2([left, right])
+}
+
+fn main(nullifier: Field, secret: Field) -> pub Field {
+    // Compute commitment = Poseidon(nullifier || secret)
+    hash(nullifier, secret)
+}
+```
+
+### TypeScript SDK Usage
+
+```typescript
+import { PrivacyPoolSDK } from '@privacylayer/sdk';
+
+const sdk = new PrivacyPoolSDK({
+  network: 'testnet',
+  rpcUrl: 'https://soroban-testnet.stellar.org'
+});
+
+// Deposit
+const note = await sdk.deposit({
+  amount: 100, // in stroops
+  publicKey: 'G...'
+});
+
+console.log('Save this note:', note.toString());
+
+// Withdraw
+await sdk.withdraw({
+  note: savedNote,
+  recipient: 'G...'
+});
+```
+
+---
+
+## Example Projects
+
+### Example 1: Privacy Donation Box
+
+**Description**: Create an anonymous donation system where donors can contribute to a cause without revealing their identity.
+
+**Features**:
+- Anonymous deposits
+- Privacy-preserving withdrawals by fundraiser
+- Donation counter (without revealing donors)
+
+**Difficulty**: ⭐⭐ (Beginner)
+
+**Code Location**: Create in `examples/privacy-donation/`
+
+---
+
+### Example 2: Privacy Escrow
+
+**Description**: Build an escrow service where funds are locked until conditions are met, protecting both buyer and seller.
+
+**Features**:
+- Deposit funds into privacy pool
+- Release funds upon condition fulfillment
+- Dispute resolution mechanism
+
+**Difficulty**: ⭐⭐⭐ (Intermediate)
+
+**Code Location**: Create in `examples/privacy-escrow/`
+
+---
+
+### Example 3: Private Voting System
+
+**Description**: Create a voting system where votes are anonymous but verifiable.
+
+**Features**:
+- Register voters (off-chain)
+- Cast anonymous votes via deposit/withdraw
+- Tally results without revealing individual votes
+
+**Difficulty**: ⭐⭐⭐⭐ (Advanced)
+
+**Code Location**: Create in `examples/privacy-voting/`
+
+---
+
+### Example 4: Confidential Tip Jar
+
+**Description**: A simple tipping system where users can tip content creators anonymously.
+
+**Features**:
+- Quick deposit/withdraw
+- Support multiple recipients
+- Transaction history (private to user)
+
+**Difficulty**: ⭐ (Easy)
+
+**Code Location**: Create in `examples/tip-jar/`
+
+---
+
+### Example 5: Privacy Gaming Wallet
+
+**Description**: Gaming wallet with hidden balances and anonymous transfers.
+
+**Features**:
+- Hide wallet balance
+- Anonymous transfers between players
+- Gaming-specific features (betting, rewards)
+
+**Difficulty**: ⭐⭐⭐⭐⭐ (Expert)
+
+**Code Location**: Create in `examples/gaming-wallet/`
+
+---
+
+## Judging Criteria
+
+### Technical Implementation (30%)
+
+| Criteria | Description | Points |
+|----------|-------------|--------|
+| Code Quality | Clean, well-structured, documented code | 10 |
+| Security | Proper handling of cryptographic operations | 10 |
+| Innovation | Novel approaches to privacy solutions | 10 |
+
+### Functionality (30%)
+
+| Criteria | Description | Points |
+|----------|-------------|--------|
+| Completeness | All intended features working | 15 |
+| User Experience | Easy to use, good UI/UX | 10 |
+| Error Handling | Graceful handling of edge cases | 5 |
+
+### Presentation (20%)
+
+| Criteria | Description | Points |
+|----------|-------------|--------|
+| Demo Quality | Clear, working demonstration | 10 |
+| Documentation | README, setup instructions, usage guide | 10 |
+
+### Impact (20%)
+
+| Criteria | Description | Points |
+|----------|-------------|--------|
+| Usefulness | Real-world applicability | 10 |
+| Creativity | Unique approach to privacy on Stellar | 10 |
+
+---
+
+## Prize Ideas
+
+### 🥇 First Place ($500)
+- **Best Overall Privacy Application**
+- Criteria: Most complete, innovative, and well-presented project
+
+### 🥈 Second Place ($300)
+- **Best Technical Implementation**
+- Criteria: Best code quality, security, and architecture
+
+### 🥉 Third Place ($200)
+- **Best Beginner Project**
+- Criteria: Best project by team with less than 3 months experience
+
+### 🎖️ Special Prizes
+
+| Prize | Amount | Criteria |
+|-------|--------|----------|
+| Security Champion | $150 | Best security practices and audit-ready code |
+| Community Choice | $100 | Most voted by participants |
+| Innovation Award | $150 | Most creative use of zero-knowledge proofs |
+| Quickest Start | $50 | First team to get deposit/withdraw working |
+
+---
+
+## Resources
+
+### Documentation
+- [PrivacyLayer README](../README.md)
+- [Introduction to PrivacyLayer](./introduction-to-privacy-layer.md)
+- [Understanding BN254 and Poseidon](./understanding-bn254-poseidon.md)
+- [FAQ](./FAQ.md)
+
+### Tools
+- [Noir Documentation](https://noir-lang.org/docs)
+- [Soroban SDK Docs](https://docs.rs/soroban-sdk)
+- [Stellar SDK](https://developers.stellar.org/docs)
+
+### Community
+- Discord: Join our community for help
+- GitHub Issues: Ask questions on our issue tracker
+
+---
+
+## Getting Help
+
+1. **Check Documentation**: Start with README.md and docs/
+2. **Search Issues**: Your question might already be answered
+3. **Ask in Discord**: Community and mentors are here to help
+4. **Office Hours**: Check schedule for live Q&A sessions
+
+---
+
+**Good luck and happy building!** 🏗️🔐
+
+*This Hackathon Starter Kit was created for PrivacyLayer Hackathon participants.*
diff --git a/docs/docs-index.md b/docs/docs-index.md
new file mode 100644
index 0000000..d263836
--- /dev/null
+++ b/docs/docs-index.md
@@ -0,0 +1,91 @@
+# Documentation
+
+## Educational Content
+
+### Blog Posts
+1. [Introduction to PrivacyLayer](introduction-to-privacy-layer.md) - Overview of PrivacyLayer's architecture, features, and innovation as the first ZK-proof shielded pool on Stellar Soroban.
+2. [Understanding BN254 and Poseidon Cryptographic Primitives](understanding-bn254-poseidon.md) - Technical deep dive into the cryptographic foundations of PrivacyLayer.
+
+### FAQ
+- [Complete FAQ](FAQ.md) - Comprehensive FAQ covering technical details, usage instructions, compliance considerations, performance metrics, and troubleshooting.
+
+### Video Tutorials (Planned)
+- PrivacyLayer Setup and Configuration
+- Making Private Transactions
+- Advanced ZK Proof Concepts
+
+### Infographics (Planned)
+- PrivacyLayer Architecture Diagram
+- Transaction Flow Diagram
+- Cryptographic Principles Visual Guide
+
+### Interactive Demos (Planned)
+- Live demonstration of deposit/withdrawal workflow
+- Cryptographic operations visualization
+- PrivacyLayer SDK usage examples
+
+---
+
+## Technical Documentation
+
+### Architecture
+PrivacyLayer consists of three main components:
+
+1. **Cryptographic Circuits** (Noir)
+   - Commitment Circuit
+   - Withdrawal Circuit
+   - Merkle Tree Circuit
+
+2. **Soroban Smart Contracts** (Rust)
+   - Privacy pool contract
+   - Admin functions
+   - State management
+
+3. **TypeScript SDK**
+   - Note generation
+   - Merkle tree synchronization
+   - Proof generation workflow
+
+### Cryptographic Foundation
+PrivacyLayer leverages Stellar Protocol 25's native cryptographic primitives:
+
+- **BN254 elliptic curve**: For efficient Groth16 proof verification
+- **Poseidon hash function**: For commitment generation (ZK-friendly)
+- **Groth16 proof system**: For zero-knowledge proofs
+- **Incremental Merkle trees**: For efficient membership proofs (depth=20)
+
+### Getting Started
+See the main README for installation and setup instructions.
+
+---
+
+## Content Overview
+
+### Blog Post 1: Introduction to PrivacyLayer
+This blog post provides a comprehensive overview of PrivacyLayer, explaining its purpose, architecture, and innovations as the first ZK-proof shielded pool on Stellar Soroban.
+
+### Blog Post 2: Understanding BN254 and Poseidon
+This technical deep dive explains the cryptographic primitives used by PrivacyLayer, detailing BN254 elliptic curve operations and Poseidon hash function implementations within Stellar Protocol 25.
+
+### FAQ: Comprehensive Guide
+The FAQ covers everything from basic questions to advanced technical details, including security considerations, performance metrics, and troubleshooting guides.
+
+---
+
+## Target Audience
+
+1. **Developers**: Technical implementation details, SDK usage, and cryptographic foundations.
+2. **Users**: Practical guides, FAQ, and usage instructions.
+3. **Researchers**: Cryptographic explanations, protocol details, and academic references.
+4. **Investors**: Compliance considerations, regulatory framework, and market positioning.
+
+---
+
+## Contribution Guide
+
+Feel free to contribute additional educational content:
+- Technical tutorials
+- Usage guides
+- Case studies
+- Academic papers
+- Implementation examples
\ No newline at end of file
diff --git a/docs/introduction-to-privacy-layer.md b/docs/introduction-to-privacy-layer.md
new file mode 100644
index 0000000..193fbbb
--- /dev/null
+++ b/docs/introduction-to-privacy-layer.md
@@ -0,0 +1,122 @@
+# Introduction to PrivacyLayer: Revolutionizing Privacy on Stellar Soroban
+
+## Overview
+
+PrivacyLayer is the **first ZK-proof shielded pool implementation on Stellar Soroban**, leveraging Protocol 25's native BN254 elliptic curve and Poseidon hash function cryptographic primitives. This innovative system enables compliance-forward private transactions on the Stellar network, providing users with unprecedented privacy while maintaining regulatory compliance.
+
+## What is PrivacyLayer?
+
+PrivacyLayer allows users to deposit fixed-denomination assets (XLM or USDC) into a shielded pool and later withdraw them to any address using zero-knowledge proofs. The revolutionary aspect of PrivacyLayer is that **there is no on-chain link between deposits and withdrawals**, ensuring complete privacy while preserving auditability through ZK proofs.
+
+## Core Architecture
+
+PrivacyLayer's architecture consists of three main components:
+
+### 1. Cryptographic Circuits
+- **Commitment Circuit**: Uses Poseidon hash function to generate commitments
+- **Withdrawal Circuit**: Leverages BN254 elliptic curve operations to prove membership
+- **Merkle Tree Circuit**: Incremental Merkle tree (depth=20) for efficient verification
+
+### 2. Soroban Smart Contracts
+The core privacy pool contract implements:
+- Deposit operations with commitment insertion
+- Withdrawal operations with proof verification
+- Admin functions for pool management
+- State tracking via nullifier management
+
+### 3. TypeScript SDK
+A comprehensive client SDK provides:
+- Note generation and backup
+- Merkle tree synchronization
+- Proof generation workflow
+- Integration utilities
+
+## Key Innovations
+
+### BN254 on Stellar Protocol 25
+PrivacyLayer leverages Stellar Protocol 25's native BN254 elliptic curve operations (G1/G2 add, scalar multiplication, pairing) and Poseidon/Poseidon2 hash functions. These cryptographic primitives are available as native host functions on Soroban — **no external libraries required**.
+
+### Compliance-First Design
+Unlike many privacy solutions that sacrifice compliance, PrivacyLayer is designed with regulatory considerations in mind. The system allows for:
+- Shielded transactions
+- Selective disclosure capabilities
+- Auditability through cryptographic proofs
+- Transaction transparency where required
+
+### Cross-Chain Inspiration
+PrivacyLayer draws inspiration from:
+- **Penumbra** (Cosmos ecosystem) for its privacy-first approach
+- **Aztec Network** (Ethereum) for its ZK proof architecture
+- Adapted specifically for the Stellar/Soroban ecosystem
+
+## How It Works
+
+### Deposit Flow
+1. User generates a nullifier and secret
+2. Creates commitment using Poseidon hash function
+3. Deposits fixed-denomination XLM/USDC
+4. Commitment is inserted into on-chain Merkle tree
+
+### Withdrawal Flow
+1. User proves knowledge of a commitment in the tree
+2. Generates ZK proof using Groth16 via BN254 pairing
+3. Submits proof for verification
+4. Withdraws funds to any address
+
+### Cryptographic Foundation
+- **BN254 Pairing**: Verifies Groth16 proofs on-chain
+- **Poseidon Hash**: Creates cryptographic commitments
+- **Merkle Tree**: Efficient membership proofs with depth=20
+- **Nullifier System**: Ensures one-time withdrawal per deposit
+
+## Advantages Over Traditional Approaches
+
+| Feature | Traditional Privacy | PrivacyLayer |
+|---------|---------------------|--------------|
+| **Compliance** | Often bypasses regulation | Built for compliance |
+| **ZK Technology** | Circuit-heavy implementation | Native Protocol 25 primitives |
+| **Stellar Native** | External dependencies | Pure Soroban contracts |
+| **Performance** | Heavy computational overhead | Efficient BN254/Poseidon operations |
+| **Cross-Chain** | Often limited to one chain | Inspired by multi-chain solutions |
+
+## Getting Started
+
+To start using PrivacyLayer:
+
+```bash
+# Install prerequisites
+rustup target add wasm32-unknown-unknown
+cargo install --locked stellar-cli
+curl -L https://raw.githubusercontent.com/noir-lang/noirup/refs/heads/main/install | bash
+noirup
+
+# Build circuits
+cd circuits/commitment
+nargo build
+nargo test
+
+cd ../withdraw
+nargo build
+nargo test
+
+# Build contracts
+cd contracts
+cargo build --target wasm32-unknown-unknown --release
+cargo test
+```
+
+## Conclusion
+
+PrivacyLayer represents a significant advancement in blockchain privacy technology. By leveraging Stellar Protocol 25's native cryptographic primitives and the Soroban smart contract platform, it provides a robust, compliant, and efficient privacy solution that sets new standards for on-chain transaction privacy.
+
+As privacy becomes increasingly important in the digital age, PrivacyLayer offers a practical, forward-looking solution that balances user privacy with regulatory requirements — a combination that is essential for the mainstream adoption of blockchain technology.
+
+---
+
+**Next Steps**: Learn more about BN254 and Poseidon cryptographic primitives in our next blog post, or dive into practical usage with our video tutorials.
+
+**Resources**:
+- [PrivacyLayer GitHub Repository](https://github.com/ANAVHEOBA/PrivacyLayer)
+- [Stellar Protocol 25 Documentation](https://stellar.org/protocol-25)
+- [Noir Language Documentation](https://noir-lang.org/docs)
+- [Soroban Documentation](https://soroban.stellar.org)
\ No newline at end of file
diff --git a/docs/understanding-bn254-poseidon.md b/docs/understanding-bn254-poseidon.md
new file mode 100644
index 0000000..f131755
--- /dev/null
+++ b/docs/understanding-bn254-poseidon.md
@@ -0,0 +1,210 @@
+# Understanding BN254 and Poseidon Cryptographic Primitives
+
+## Introduction
+
+PrivacyLayer leverages two cutting-edge cryptographic primitives native to Stellar Protocol 25: the BN254 elliptic curve and the Poseidon hash function. These innovations form the backbone of PrivacyLayer's zero-knowledge proof system and are key to understanding how privacy is achieved on-chain.
+
+## BN254 Elliptic Curve
+
+BN254 is a pairing-friendly elliptic curve that enables efficient Groth16 zero-knowledge proof verification on-chain. With Stellar Protocol 25, BN254 operations are available as **native host functions** within Soroban smart contracts.
+
+### What Makes BN254 Special?
+
+BN254 belongs to the Barreto-Naehrig (BN) family of curves, offering:
+
+1. **Efficient Pairings**: BN254 supports efficient cryptographic pairings required for ZK-SNARK verification
+2. **128-bit Security**: Provides adequate security for most applications
+3. **Implementation Availability**: Widely implemented across various ZK libraries
+4. **Protocol 25 Native**: Available as host functions on Soroban without external dependencies
+
+### BN254 Operations in PrivacyLayer
+
+PrivacyLayer utilizes BN254 for:
+
+```rust
+// In Soroban contract - BN254 host functions available natively
+fn verify_withdrawal_proof(proof: Proof) -> bool {
+    // Groth16 verification using BN254 pairing
+    let verification_result = bn254_pairing(
+        proof.a,
+        proof.b,
+        proof.c
+    );
+    
+    return verification_result;
+}
+```
+
+### Why BN254 over Other Curves?
+
+| Curve | Security Level | Pairing Efficiency | Protocol 25 Support |
+|-------|---------------|-------------------|---------------------|
+| BN254 | 128-bit | Excellent | ✅ Native host functions |
+| BLS12-381 | 128-bit | Good | ❌ Requires external |
+| MNT4/6 | 128-bit | Moderate | ❌ Requires external |
+| ALT-BN128 | 128-bit | Excellent | ✅ Native host functions |
+
+BN254's availability as native host functions eliminates dependency issues and reduces computational overhead.
+
+## Poseidon Hash Function
+
+Poseidon is a sponge-based hash function optimized for zero-knowledge proof applications. It's particularly efficient in arithmetic circuits used in ZK-SNARKs.
+
+### Poseidon Characteristics
+
+1. **ZK-Friendly**: Designed for efficiency in ZK circuits
+2. **Arithmetic Circuit Optimization**: Minimal gates required
+3. **Sponge Construction**: State-based design for variable-length inputs
+4. **Protocol 25 Native**: Available as Poseidon/Poseidon2 host functions
+
+### Poseidon in PrivacyLayer
+
+PrivacyLayer uses Poseidon for commitment generation:
+
+```rust
+// Generate commitment using Poseidon hash
+fn generate_commitment(nullifier: [u8; 32], secret: [u8; 32]) -> [u8; 32] {
+    let commitment = poseidon2_hash(
+        nullifier,
+        secret
+    );
+    return commitment;
+}
+```
+
+### Poseidon vs Traditional Hash Functions
+
+| Hash Function | ZK Efficiency | Gate Count | Circuit Size |
+|---------------|---------------|------------|--------------|
+| Poseidon | Excellent | ~100 gates | Small |
+| SHA-256 | Poor | ~20,000 gates | Large |
+| Keccak | Poor | ~15,000 gates | Large |
+| Blake2 | Moderate | ~5,000 gates | Medium |
+
+Poseidon's ZK-friendly design makes it ideal for privacy applications where cryptographic operations need to be proven within circuits.
+
+## Cryptographic Flow in PrivacyLayer
+
+### 1. Commitment Generation
+```
+nullifier + secret → Poseidon hash → commitment
+```
+
+### 2. Withdrawal Proof Generation
+```
+1. Prove membership in Merkle tree
+2. Generate Groth16 proof using BN254 parameters
+3. Submit proof for verification
+```
+
+### 3. On-Chain Verification
+```
+1. Contract verifies Groth16 proof using BN254 pairing
+2. Checks nullifier hasn't been used
+3. Transfers funds to withdrawal address
+```
+
+## Protocol 25 Integration
+
+Stellar Protocol 25 introduces these cryptographic primitives as native host functions:
+
+### BN254 Functions
+- `bn254_g1_add`, `bn254_g1_scalar_mul`: G1 curve operations
+- `bn254_g2_add`, `bn254_g2_scalar_mul`: G2 curve operations
+- `bn254_pairing`: Cryptographic pairing operation
+
+### Poseidon Functions
+- `poseidon_hash`, `poseidon2_hash`: ZK-friendly hash functions
+- Variable-length input support
+- Efficient sponge construction
+
+### Performance Benefits
+
+Using native host functions provides:
+- **Zero External Libraries**: No WASM imports required
+- **Direct Host Execution**: Executed by Soroban host environment
+- **Optimized Performance**: Implemented at the protocol level
+- **Gas Efficiency**: Lower computational cost than custom implementations
+
+## Practical Examples
+
+### Creating a Note (Deposit)
+
+```typescript
+// TypeScript SDK example
+import { PrivacyLayer } from '@privacylayer/sdk';
+
+const client = new PrivacyLayer();
+const note = await client.createNote({
+  amount: 1000, // Fixed denomination
+  nullifier: randomBytes(32),
+  secret: randomBytes(32)
+});
+
+// Generate commitment using Poseidon
+const commitment = await client.generateCommitment(note);
+
+// Deposit to shielded pool
+await client.deposit(commitment);
+```
+
+### Withdrawal Proof Generation
+
+```typescript
+// Create withdrawal proof
+const proof = await client.generateWithdrawalProof({
+  note,
+  treeRoot,
+  withdrawalAddress: 'new-address'
+});
+
+// Verify proof using BN254
+const isValid = await client.verifyProof(proof);
+```
+
+## Security Considerations
+
+### BN254 Security
+- 128-bit security level
+- Pairing-friendly curve design
+- Standardized across multiple ZK implementations
+- Protocol-level integration ensures correctness
+
+### Poseidon Security
+- Sponge-based construction resistant to attacks
+- ZK-friendly but maintains cryptographic security
+- Optimized for circuit implementation
+- Native implementation eliminates implementation errors
+
+### Audit Considerations
+While BN254 and Poseidon are mathematically secure, PrivacyLayer's:
+- Circuit implementation requires formal audit
+- Contract integration requires security review
+- Nullifier system requires careful design
+- Merkle tree depth (20) should be evaluated
+
+## Future Developments
+
+### Poseidon2 Improvements
+Poseidon2 offers enhanced performance characteristics:
+- Better sponge construction
+- Improved resistance to certain attacks
+- More flexible parameterization
+
+### Protocol Evolution
+Future Stellar protocol versions may add:
+- Additional cryptographic primitives
+- Enhanced performance optimizations
+- More sophisticated ZK support
+
+## Conclusion
+
+BN254 and Poseidon represent state-of-the-art cryptographic primitives for zero-knowledge proof applications. Their native integration into Stellar Protocol 25 through Soroban host functions makes PrivacyLayer uniquely positioned to provide efficient, secure privacy solutions without external dependencies.
+
+Understanding these cryptographic foundations is essential for anyone working with PrivacyLayer or developing ZK-based applications on Stellar. The combination of BN254's efficient pairing operations and Poseidon's ZK-friendly hash design creates a powerful foundation for private blockchain transactions.
+
+---
+
+**Technical Details**: For more in-depth technical analysis, see the [BN254 specification](https://stellar.org/protocol-25/cap-0074) and [Poseidon whitepaper](https://eprint.iacr.org/2019/458).
+
+**Implementation References**: PrivacyLayer's implementation can be found in the [circuits directory](https://github.com/ANAVHEOBA/PrivacyLayer/tree/main/circuits) of the GitHub repository.
\ No newline at end of file