🏦 Secure Crowd Fundinng Protocol (Foundry Edition)

A production-oriented crowdfunding smart contract built with Foundry, designed to handle real-world fund flows securely and predictably.

This project goes beyond basics — it demonstrates:

• Secure ETH handling 🔐
• Deterministic state machine design ⚙️
• Fee-based economic modeling 💰
• Audit-aware development mindset 🛡️

---

📚 Table of Contents

• 💼 Why This Project Stands Out
• 📁 Project Structure
• ⚙️ Getting Started
  • Requirements
  • Clone & Build
• 🚀 Deploying Contracts
  • 🧪 Local Deployment
  • 🌐 Testnet Deployment (Sepolia)
• 🧪 Running Tests
• 🧠 Core Contract Logic
  • 🔄 State Machine
  • 💰 Fee Model
  • 🔐 Security Considerations
• 🔗 Chainlink Integration
• 📜 Example Interactions
• 🧪 Testing Philosophy
• 🛡️ Audit Awareness
• 🧠 Concepts Covered
• 🔍 Upcoming Enhancements
• 🎯 What This Project Proves
• 🧑‍💻 About
• 📌 Notes
• 🧠 License
• ⭐ Support
• 🙏 Acknowledgment

---

💼 Why This Project Stands Out

Most crowdfunding contracts stop at “fund & withdraw”.

This protocol implements:

• ✅ State-driven lifecycle (ACTIVE → SUCCESS → FAILED)
• ✅ User refunds with fee logic
• ✅ Owner withdrawals with platform fees
• ✅ USD-denominated funding via Chainlink
• ✅ Security patterns (CEI + Reentrancy protection)

👉 Built as a real DeFi primitive, not a demo.

---

📁 Project Structure

├── src/              # Core smart contracts
├── script/           # Deployment & interaction scripts
├── test/             # Unit & edge-case tests
├── lib/              # External dependencies
└── foundry.toml      # Foundry configuration

---

⚙️ Getting Started

Requirements

• Git
• Foundry
• Node.js & NPM
• Optional: Docker

---

Clone & Build

git clone https://github.com/barnabasmunuhe/Secure-Crowd_Funding-Protocol
cd fund-me
forge install
forge build

---

🚀 Deploying Contracts

🧪 Local Deployment

forge script script/DeployFundMe.s.sol \
  --fork-url http://127.0.0.1:8545 \
  --broadcast \
  --private-key <PRIVATE_KEY>

---

🌐 Testnet Deployment (Sepolia)

forge script script/DeployFundMe.s.sol \
  --rpc-url $SEPOLIA_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify \
  --etherscan-api-key $ETHERSCAN_API_KEY

---

🧪 Running Tests

Unit Tests

forge test -vvv

Forked Tests

forge test --fork-url $SEPOLIA_RPC_URL

Coverage Report

forge coverage

---

🧠 Core Contract Logic

🔄 State Machine

ACTIVE → SUCCESS → FAILED

• ACTIVE → users can fund
• SUCCESS → owner can withdraw
• FAILED → users can refund

👉 Ensures predictable and secure behavior.

---

💰 Fee Model

• Platform Fee → applied on withdrawals
• Refund Fee → applied on user refunds

✔ Implemented using basis points (BPS)
✔ Eliminates floating-point precision errors

---

🔐 Security Considerations

• Reentrancy protection (ReentrancyGuard)
• Access control (Ownable)
• Checks → Effects → Interactions (CEI)
• Pull-based refund pattern
• No gas-heavy loops

---

🔗 Chainlink Integration

Uses Chainlink Price Feeds to:

• Convert ETH → USD
• Enforce minimum contribution threshold
• Stabilize funding logic

---

📜 Example Interactions

Fund Contract

cast send <FUNDME_ADDRESS> "fund()" \
  --value 0.1ether \
  --private-key <PRIVATE_KEY>

---

Withdraw (Owner Only)

cast send <FUNDME_ADDRESS> "ownerWithdraw(uint256)" \
  --private-key <PRIVATE_KEY>

---

Refund (User)

cast send <FUNDME_ADDRESS> "refund()" \
  --private-key <PRIVATE_KEY>

---

🧪 Testing Philosophy

This project focuses on behavior-driven testing, including:

• Funding validation
• Refund correctness (with fee deduction)
• Owner withdrawal accounting
• State transitions
• Edge cases (double refund, insufficient balance, etc.)

👉 Emphasis on financial correctness, not just coverage.

---

🛡️ Audit Awareness

During development, a critical bug was identified and resolved:

• Incorrect refund transfer logic
• Could lead to fund imbalance

✔ Fixed with correct payout calculation

👉 Demonstrates audit-level thinking and debugging discipline

---

🧠 Concepts Covered

• Fallback & receive functions
• msg.value / msg.sender
• Chainlink oracles
• Access control patterns
• Fee modeling (BPS)
• Smart contract testing (Foundry)
• Deployment scripting
• Gas analysis (forge snapshot)

---

🔍 Upcoming Enhancements

• Campaign factory (multi-project deployment)
• DAO-controlled treasury
• ERC20 funding support
• Milestone-based payouts
• Emergency pause mechanism

---

🎯 What This Project Proves

This project demonstrates:

• Real-world smart contract architecture
• Secure financial logic implementation
• Strong testing discipline
• Awareness of production risks

👉 Ready for DeFi / Smart Contract Engineering roles

---

🧑‍💻 About

Blockchain developer focused on:

• Smart contract engineering
• Protocol design
• Security & testing

---

📌 Notes

This is an evolving project focused on building production-grade Solidity systems.

Feedback, issues, and PRs are welcome.

---

🧠 License

MIT License

---

⭐ Support

If you find this useful, consider starring ⭐ the repo.

---

🙏 Acknowledgment

Built with focus, discipline, and a deep commitment to mastering smart contract engineering.