🌑 Shadow Swap - Privacy-Preserving Starknet Bridge

A cryptographically-secure atomic swap bridge between Starknet and Zcash with built-in privacy guarantees

---

📋 Overview

Shadow Swap is a decentralized bridge that enables private atomic swaps between Starknet and Zcash. Unlike traditional bridges, Shadow Swap uses advanced cryptographic techniques to hide transaction amounts and obfuscate participant identities while maintaining trustless security.

Key Features

✅ Cryptographic Privacy - Transaction amounts hidden via zero-knowledge commitments
✅ Address Obfuscation - Stealth address system protects participant identities
✅ Range Proofs - Mathematically proven amount validity without revealing values
✅ Dual Hash System - Poseidon (Starknet) + SHA256 (Zcash) compatibility
✅ Time-Locked Safety - Automatic refund after timeout with privacy preservation
✅ Production Ready - Built with Cairo 1.0 and audited cryptographic primitives

---

🔐 Privacy Guarantees

What's Hidden:

• ✅ Transaction Amounts - Cryptographically committed, never revealed on-chain
• ✅ Participant Identities - Stealth addresses break address linkability
• ✅ Cross-Chain Linkage - Different secrets prevent transaction correlation

What's Visible:

• ⚠️ HTLC Creation - Someone created a swap (but not who or how much)
• ⚠️ Settlement Events - A swap completed (but amounts remain hidden)
• ⚠️ Timelock Parameters - When refunds become available

Privacy Level: Similar to Zcash shielded transactions on Starknet

---

🚀 Quick Start

1. Install Dependencies

# Install Scarb (Cairo package manager)
curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | sh

# Install Starknet Foundry (testing framework)
curl -L https://raw.githubusercontent.com/foundry-rs/starknet-foundry/master/scripts/install.sh | sh

2. Build Contracts

scarb build

3. Run Tests

snforge test

---

🔑 Understanding the Bridge

Bridge Architecture

USER wants to swap 100 STRK → 1 ZEC

┌─────────────────────────────────────┐
│  USER (Alice)                       │
│  ├─ Starknet: Locks 100 STRK       │  ← Amount HIDDEN via commitment
│  └─ Zcash: Receives 1 ZEC          │  ← Shielded transaction
└─────────────────────────────────────┘
         │
         │ Bridge Protocol (Atomic)
         │
┌─────────────────────────────────────┐
│  BRIDGE OPERATOR (Shadow Swap)      │
│  ├─ Starknet: Claims 100 STRK      │  ← Must reveal secret
│  └─ Zcash: Sends 1 ZEC             │  ← From liquidity pool
└─────────────────────────────────────┘

Swap Flow

Starknet → Zcash:

1. User locks STRK with hidden amount (cryptographic commitment)
2. Bridge locks ZEC to user's Zcash shielded address
3. User reveals secret on Zcash, claims ZEC
4. Bridge uses secret to claim STRK on Starknet

Zcash → Starknet:

1. User locks ZEC in shielded HTLC
2. Bridge locks STRK with hidden amount
3. User reveals secret on Starknet, claims STRK
4. Bridge uses secret to claim ZEC on Zcash

---

🔒 Security Features

Cryptographic Protections

Layer	Technology	Purpose
Amount Privacy	Pedersen Commitments	Hide transaction values on-chain
Range Proofs	Bit Decomposition	Prove amount validity without revealing
Stealth Addresses	Hash-based Derivation	Break address linkability
Secure Randomness	Multi-source Entropy	Unpredictable blinding factors

Smart Contract Security

Protection	Implementation	Attack Prevented
Reentrancy Guard	OpenZeppelin Component	Reentrancy attacks
CEI Pattern	Checks-Effects-Interactions	State inconsistency
Access Control	Stealth ownership verification	Unauthorized claims
State Machine	Strict transitions	Double-spending
Timelock Validation	Min 1hr, Max 7 days	Premature/indefinite locks

See SECURITY.md for detailed analysis.

---

🧪 Testing

Comprehensive Test Suite

# Run all tests
snforge test

# Run with coverage
snforge test --coverage

# Run specific test file
snforge test --path tests/test_htlc.cairo

Test Coverage:

• ✅ Privacy commitment verification
• ✅ Range proof validation
• ✅ Stealth address ownership
• ✅ Amount hiding guarantees
• ✅ State transitions
• ✅ Access control
• ✅ Timelock boundaries
• ✅ Edge cases and attack vectors

---

For Auditors:

1. Review cryptographic primitives in stealth.cairo
2. Verify Pedersen commitment implementation
3. Check range proof bit decomposition logic
4. Audit stealth address derivation scheme
5. Test all privacy preservation edge cases

---

🏗️ Architecture

┌──────────────────────────────────────────────────────┐
│                  PRIVACY LAYER                       │
│  • Pedersen Commitments (Amount Hiding)             │
│  • Range Proofs (Validity without Disclosure)       │
│  • Stealth Addresses (Identity Obfuscation)         │
└──────────────┬───────────────────────────────────────┘
               │
┌──────────────▼───────────────────────────────────────┐
│              HTLC FACTORY                            │
│  • Deploys child HTLCs                              │
│  • Verifies range proofs                            │
│  • Enforces privacy parameters                      │
└──────────────┬───────────────────────────────────────┘
               │
┌──────────────▼───────────────────────────────────────┐
│              HTLC CONTRACT                           │
│  • Holds locked STRK (amount hidden)                │
│  • Verifies commitment on redeem/refund             │
│  • Enforces atomic swap logic                       │
└──────────────────────────────────────────────────────┘

---

📜 License

MIT License - See LICENSE file for details

---

🏆 Acknowledgments

Built with:

• Cairo 2.0 (Starknet smart contracts)
• Pedersen Hash (Native Cairo cryptography)
• OpenZeppelin Cairo Contracts (Security components)
• Starknet Foundry (Testing framework)

Inspired by:

• Zcash Protocol (Shielded transactions)
• Tornado Cash (Privacy techniques)
• Monero (Stealth addresses)

---

Built with ❤️ for a privacy-first DeFi future

---

Last Updated: November 2025 | Version 0.2.0 (Privacy Update)