# NustarFund - Charitable Crowdfunding Platform
A decentralized crowdfunding platform for individuals and NGOs built on Ethereum Sepolia testnet.
---
## Table of Contents
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Usage Guide](#-usage-guide)
- [Tech Stack](#-tech-stack)
- [Smart Contract](#-smart-contract)
- [Project Structure](#-project-structure)
- [API Reference](#-api-reference)
---
## Features
### Core Functionality
| Feature | Description |
|---------|-------------|
| **Web3 Integration** | Connect with MetaMask or WalletConnect |
| **Crypto Donations** | Accept SEP ETH donations on Sepolia testnet |
| **Smart Contracts** | Secure, transparent fund management |
| **Real-time Tracking** | Live campaign progress updates |
| **AI Analytics** | Success prediction & fraud detection |
| **Global Access** | Accept donations from anywhere |
### User Profiles
#### Individual Creators
- Create personal fundraising campaigns
- Set custom funding goals and deadlines
- Receive donations directly to wallet
- Track campaign performance in real-time
- Withdraw funds when goals are met
#### NGO Organizations
- Verified NGO profiles with registration details
- Add impact reports with beneficiary statistics
- Track project milestones (Pending/In Progress/Completed)
- Upload images and documentation
- Transparent fund utilization reporting
- Build trust with detailed progress updates
---
## Quick Start
### Prerequisites
- Node.js v18+ and npm
- MetaMask browser extension
- Sepolia ETH (free testnet tokens)
### Installation Steps
```bash
# 1. Clone the repository
git clone https://github.com/Krishnaaporwal/charities.git
cd charities
# 2. Install dependencies
npm install
# 3. Start development server
npm run dev
```
Visit **http://localhost:5000**
---
## Usage Guide
### For Campaign Creators
#### Creating an Individual Campaign
1. **Connect Wallet**
- Click "Connect Wallet" in navbar
- Approve MetaMask connection
2. **Navigate to Create Campaign**
- Click "Create Campaign" button
- Select "Individual / Personal Campaign"
3. **Fill Campaign Details**
- Title (5-100 characters)
- Description (20-1000 characters)
- Category (Technology, Education, Healthcare, etc.)
- Goal amount in SEP ETH
- Campaign deadline
- Optional: Image URL
4. **Pay Platform Fee**
- Fee: 0.01 SEP ETH
- Confirm transaction in MetaMask
5. **Launch Campaign**
- Campaign goes live immediately
- Appears in Explore page
#### Creating an NGO Campaign
1. **Select NGO Profile Type**
- Choose "NGO / Non-Profit Organization"
2. **Enter NGO Information**
- Organization name
- Registration number / Tax ID
- Organization description
3. **Complete Campaign Setup**
- Same as individual campaign
- Pay 0.01 SEP ETH platform fee
4. **Access Advanced Features**
- Add impact reports
- Create milestones
- Upload documentation
### For Donors
| Step | Action |
|------|--------|
| 1 | Connect your wallet (MetaMask) |
| 2 | Browse campaigns in **Explore** page |
| 3 | Click on campaign to view details |
| 4 | Click **"Donate Now"** button |
| 5 | Enter donation amount in SEP ETH |
| 6 | Confirm transaction in MetaMask |
| 7 | Receive confirmation & track donation |
### Managing Your Profile (NGO Features)
#### Reports & Updates Tab
- **Add Impact Reports**
- Report title and description
- Number of beneficiaries helped
- Funds spent tracking
- Multiple image uploads
- Document attachments
- **View Report History**
- Chronological list of all reports
- Edit and update reports
- Track fund utilization
#### Milestones Tab
| Status | Icon | Description |
|--------|------|-------------|
| Pending | | Milestone not yet started |
| In Progress | | Currently working on milestone |
| Completed | | Milestone achieved |
**Add Milestones:**
- Set milestone title and description
- Define target completion date
- Update status as you progress
- Track impact metrics
---
## Tech Stack
### Frontend Technologies
| Technology | Purpose |
|------------|---------|
| **React 18+** | UI framework with TypeScript |
| **Vite** | Fast build tool and dev server |
| **TanStack Query** | Data fetching and caching |
| **Wouter** | Lightweight routing |
| **Tailwind CSS** | Utility-first styling |
| **shadcn/ui** | Beautiful UI components |
| **ethers.js v6** | Web3 blockchain interaction |
### Backend Technologies
| Technology | Purpose |
|------------|---------|
| **Express.js** | REST API server |
| **TypeScript** | Type-safe development |
| **tsx** | TypeScript execution |
| **Zod** | Schema validation |
| **Drizzle ORM** | Database operations |
### Blockchain Stack
| Component | Details |
|-----------|---------|
| **Solidity** | v0.8.28 smart contracts |
| **Hardhat** | Development & deployment |
| **Sepolia Testnet** | Testing network |
| **Ethers.js** | Contract interaction |
### AI/ML Stack
- **Python** with Flask API
- **scikit-learn** for ML models
- **pandas** for data processing
- **numpy** for numerical operations
---
## Smart Contract
### Deployment Information
| Property | Value |
|----------|-------|
| **Network** | Sepolia Testnet (Chain ID: 11155111) |
| **Contract Address** | x5b19aE435CF4fA1DE595901380B7aA745C71afcb |
| **Platform Fee** | 0.01 SEP ETH |
| **Compiler** | Solidity 0.8.28 |
| **View on Etherscan** | [Click Here](https://sepolia.etherscan.io/address/0x5b19aE435CF4fA1DE595901380B7aA745C71afcb) |
### Contract Functions
| Function | Description | Access |
|----------|-------------|--------|
| createCampaign() | Deploy new campaign | Public (with fee) |
| donate() | Send donation to campaign | Public |
| withdrawFunds() | Withdraw raised funds | Campaign Owner Only |
| getPlatformFee() | Get current platform fee | View Function |
### Deploy Contract
```bash
# Compile contracts
npx hardhat compile
# Deploy to Sepolia
npx hardhat run scripts/deploy.js --network sepolia
# Verify on Etherscan
npx hardhat verify --network sepolia
```
---
## Get Test ETH
Get free Sepolia testnet ETH from these faucets:
| Faucet | URL | Amount |
|--------|-----|--------|
| **Sepolia Faucet** | [sepoliafaucet.com](https://sepoliafaucet.com) | 0.5 SEP ETH/day |
| **Alchemy Faucet** | [sepoliafaucet.com](https://sepoliafaucet.com) | 0.5 SEP ETH/day |
| **QuickNode** | [faucet.quicknode.com](https://faucet.quicknode.com/ethereum/sepolia) | 0.1 SEP ETH |
---
## Project Structure
```
charities/
client/ # Frontend React application
src/
components/ # UI components
campaigns/ # Campaign components
home/ # Home page sections
layout/ # Navbar, Footer
ui/ # shadcn/ui components
contexts/ # React contexts (WalletContext)
hooks/ # Custom hooks
lib/ # Utilities
smartContract.ts # Contract interaction
web3.ts # Web3 utilities
utils.ts # Helper functions
pages/ # Page components
Home.tsx
Explore.tsx
Campaign.tsx
CreateCampaign.tsx
Profile.tsx
HowItWorks.tsx
App.tsx # Main component
index.html
server/ # Backend Express server
index.ts # Entry point
routes.ts # API routes
storage.ts # Data storage
ml/ # ML services
contracts/ # Solidity contracts
EscrowDonation.sol
scripts/ # Deployment scripts
shared/ # Shared schemas
python_ml/ # Python ML models
```
---
## Key Pages & Routes
| Route | Description | Features |
|-------|-------------|----------|
| / | Home page | Featured campaigns, hero section, FAQ |
| /explore | Browse campaigns | Filter by category, search, cards view |
| /campaign/:id | Campaign details | Donate, view progress, donation history |
| /create | Create campaign | Form, AI predictions, fraud check |
| /profile | User profile | Manage campaigns, add reports/milestones |
| /how-it-works | Platform guide | Step-by-step instructions |
| /tax-info | Tax information | Donation tax guidelines |
---
## API Reference
### Campaign Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/campaigns | Get all campaigns |
| GET | /api/campaigns/:id | Get campaign by ID |
| POST | /api/campaigns | Create new campaign |
| GET | /api/campaigns/:id/donations | Get campaign donations |
### Donation Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /api/donations | Record new donation |
### NGO Report Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/ngo-reports?campaignId=:id | Get reports for campaign |
| POST | /api/ngo-reports | Create new report |
| GET | /api/ngo-reports/:id | Get report by ID |
### NGO Milestone Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/ngo-milestones?campaignId=:id | Get milestones |
| POST | /api/ngo-milestones | Create milestone |
| GET | /api/ngo-milestones/:id | Get milestone by ID |
### AI Features
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /api/predict-success | Get campaign success prediction |
| POST | /api/check-fraud | Check fraud risk score |
---
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| MetaMask not connecting | Ensure MetaMask is unlocked
Refresh page
Check you're on Sepolia network |
| Transaction failing | Check sufficient SEP ETH balance
Verify gas price settings
Wait for pending transactions |
| Campaign not appearing | Wait 1-2 seconds for update
Refresh explore page
Check network connection |
| Server won't start | Check port 5000 is available
Run
pm install again
Check Node.js version (18+) |
---
## Contributing
We welcome contributions! Please follow these steps:
1. Fork the repository
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open Pull Request
---
## Author
**Krishna Porwal**
- GitHub: [@Krishnaaporwal](https://github.com/Krishnaaporwal)
- Repository: [charities](https://github.com/Krishnaaporwal/charities)
---
## Acknowledgments
- **OpenZeppelin** - Secure smart contract libraries
- **Ethers.js** - Web3 integration
- **shadcn/ui** - Beautiful UI components
- **Hardhat** - Smart contract development
- **Ethereum Community** - Testnet infrastructure
---
