Building a more accountable future on Base
🌐 Live Demo • 📖 Documentation • 🚀 Quick Start • 💡 Features • 🤝 Contributing
- Overview
- Key Features
- Why Base?
- Tech Stack
- Live Demo
- Getting Started
- Smart Contracts
- Architecture
- Security
- Contributing
- License
Transparent Charity Tracker is a production-ready decentralized application (dApp) that revolutionizes charity transparency by leveraging blockchain technology on Base L2. Every donation, milestone, and fund release is recorded immutably on-chain, ensuring complete accountability and trust.
Traditional charity platforms lack transparency. Donors lose track of funds once they leave their bank account, leading to:
- ❌ Donor fatigue and distrust
- ❌ Lack of accountability
- ❌ No way to verify fund usage
- ❌ Limited donor engagement
✅ Immutable Tracking: Every dollar (ETH/USDC) tracked on-chain from donation to expenditure
✅ Milestone Governance: Funds locked in smart contracts, released only after donor approval
✅ Weighted Voting: Donors vote based on contribution amount (1 token = 1 vote)
✅ Radical Transparency: All receipts and impact reports hashed on-chain via IPFS
✅ Low Fees: Built on Base L2 for affordable transactions
✅ Social Discovery: Farcaster Mini App integration for viral growth
- Multi-Token Donations: Support for ETH and ERC20 tokens (USDC, etc.)
- Milestone-Based Funding: Projects broken into verifiable milestones
- Weighted Voting System: Donors vote on milestone releases based on contribution weight
- NGO Verification: Only verified NGOs can create projects
- Real-Time Updates: React Query for efficient data fetching and caching
- Emergency Controls: Pausable contracts with owner controls
- Farcaster Mini App: Native integration for social discovery and viral growth
- Base L2 Benefits: Ultra-low fees, fast transactions, Ethereum security
- Modern Web3 Stack: Wagmi v3, Viem, latest React patterns
- Responsive Design: Works seamlessly on desktop and mobile
- Wallet Integration: MetaMask, WalletConnect, and more
- Network Switching: Automatic Base network detection and switching
- Error Handling: Comprehensive error messages and recovery flows
- On-Chain Records: All transactions permanently recorded
- Donation History: Complete donation tracking per project
- Milestone Tracking: Real-time milestone status and voting progress
- Project Analytics: Funding progress, donor counts, and more
We chose Base as our platform because:
- Ultra-Low Fees: Perfect for micro-donations and frequent transactions
- Ethereum Security: Inherits security from Ethereum mainnet
- Fast Transactions: Near-instant confirmation times
- Growing Ecosystem: Active community and strong developer support
- Farcaster Integration: Native social layer for discovery and engagement
- OP Stack: Built on proven, open-source technology
- Framework: Next.js 16.1 (App Router, React Server Components)
- Web3: Wagmi v3 + Viem
- Styling: Tailwind CSS v4
- State Management: Zustand v5
- Data Fetching: TanStack Query v5
- UI Components: Custom components with Headless UI
- Notifications: React Hot Toast
- Language: Solidity ^0.8.24
- Framework: Foundry
- Security: OpenZeppelin Contracts (ReentrancyGuard, Pausable, Ownable)
- Testing: Comprehensive Foundry test suite
- Deployment: Vercel (Frontend), Base Mainnet (Contracts)
- RPC: Base RPC endpoints
- IPFS: For milestone proofs and receipts (future)
- Farcaster Mini App SDK: Social discovery and engagement
- WalletConnect: Multi-wallet support
- Etherscan: Contract verification
- Frontend: https://tranct.netlify.app 🚀
- Base Sepolia Testnet: https://sepolia.basescan.org/address/0x46c17579afF1635b9d983603ED0b4A1c0823bF3d
- Base Mainnet:
0x9E61018e304f6Cb911ca76132748CFb2AD6B3176
Base Sepolia (Testnet):
- CharityTracker:
0x46c17579afF1635b9d983603ED0b4A1c0823bF3d - NGO Registry:
0xc7b93b317634c08D14D806057F9B4C0EB9E62059
Base Mainnet:
- Node.js 18+ and npm/yarn/pnpm
- Web3 Wallet (MetaMask, Coinbase Wallet, etc.)
- Base Sepolia ETH (for testing) - Get from Base Sepolia Faucet
- Git
- Clone the repository:
git clone <repository-url>
cd tct- Install dependencies:
npm install
# or
yarn install
# or
pnpm install- Set up environment variables:
cp .env.example .env.localEdit .env.local with your configuration:
# Application
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Base Network
NEXT_PUBLIC_CHAIN_ID=84532 # 84532 for Base Sepolia, 8453 for Base Mainnet
NEXT_PUBLIC_BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
# Or use a dedicated provider: https://www.alchemy.com/base
# Contracts
NEXT_PUBLIC_CHARITY_TRACKER_ADDRESS=0x46c17579afF1635b9d983603ED0b4A1c0823bF3d
# WalletConnect (Optional but recommended)
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id_here
# Get from: https://cloud.reown.com/
# USDC Token (Optional)
NEXT_PUBLIC_USDC_ADDRESS=0x036CbD53842c5426634e7929541eC2318f3dCF7e- Run the development server:
npm run dev
# or
yarn dev
# or
pnpm dev- Open http://localhost:3000 in your browser
See the contract README for detailed instructions on:
- Building and testing contracts
- Deploying to Base networks
- Running tests
- Gas optimization
- CharityTracker.sol: Main contract handling projects, donations, voting, and fund releases
- NGO Registry: Verified NGO management system
- ✅ Reentrancy protection (OpenZeppelin ReentrancyGuard)
- ✅ Pausable for emergency situations
- ✅ Owner-only functions for NGO management
- ✅ Milestone-based fund locking
- ✅ Weighted voting system (>50% quorum)
- ✅ Multi-token support (ETH + ERC20)
- Comprehensive test coverage
- OpenZeppelin battle-tested contracts
- CEI (Checks-Effects-Interactions) pattern
- Custom errors for gas efficiency
- Access control mechanisms
See contract documentation for more details.
app/
├── page.tsx # Home page with project listing
├── project/
│ ├── [id]/ # Project detail page
│ └── create/ # Create project page
├── ngo/
│ ├── dashboard/ # NGO dashboard
│ └── register/ # NGO registration
├── admin/
│ └── ngos/ # Admin panel for NGO management
└── donate/
└── [id]/ # Donation page
components/
├── project/ # Project-related components
├── donation/ # Donation components
├── web3/ # Web3 wallet components
└── ui/ # Reusable UI components
hooks/
├── useProject.ts # Project data fetching
├── useDonation.ts # Donation logic
├── useVoting.ts # Voting logic
└── useNGO.ts # NGO verification
contracts/
├── CharityTracker.sol # Main contract
├── interfaces/ # Contract interfaces
├── libraries/ # Shared libraries
└── types/ # Data structures
- Reentrancy Protection: OpenZeppelin ReentrancyGuard
- Access Control: Owner-only functions for critical operations
- Pausable: Emergency pause functionality
- Input Validation: Comprehensive checks on all inputs
- Gas Optimization: Custom errors, packed structs
- Upgrade Path: Designed for future upgradeability
- ✅ Internal security review completed
- ✅ OpenZeppelin contracts used (audited)
- ⏳ External audit planned
If you discover a security vulnerability, please email [security@yourdomain.com] instead of using the issue tracker.
- Smart Contract Documentation
- Base Builder Ranking Strategy
- NGO Registration Flow
- Wallet Connection Setup
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
- Follow TypeScript best practices
- Write tests for new features
- Update documentation
- Follow the existing code style
- Add comments for complex logic
- Smart contract development and testing
- Frontend application (Next.js)
- Wallet integration (Wagmi v3)
- NGO registration system
- Donation system (ETH + ERC20)
- Voting system
- Milestone management
- Admin panel
- Farcaster Mini App integration
- Mainnet deployment
- Production frontend deployment
- IPFS integration for milestone proofs
- Analytics dashboard
- Mobile app (React Native)
- Additional token support
- Governance token
- Staking mechanisms
- Multi-language support
- Total Projects: [Update with live data]
- Total Donations: [Update with live data]
- Active NGOs: [Update with live data]
- Total Votes Cast: [Update with live data]
- Stars: [Update]
- Forks: [Update]
- Contributors: [Update]
- Base for the amazing L2 platform
- OpenZeppelin for secure contract libraries
- Wagmi for excellent Web3 React hooks
- Farcaster for social infrastructure
- The entire Web3 community for inspiration and support
This project is licensed under the MIT License - see the LICENSE file for details.
- Website: https://tranct.netlify.app
- Documentation: [Update with your docs URL]
- Twitter/X: @YourHandle
- Discord: Your Discord
- GitHub: Your Repo
If you find this project useful, please consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs
- 💡 Suggesting new features
- 🤝 Contributing code
- 📢 Sharing with others