HopeChain - Transparent Giving. Real Healing.

A DeFi-powered donation platform built on Base Network that uses yield-generating vaults to create sustainable funding for cancer patients.

🌟 Overview

HopeChain is a revolutionary donation platform that combines the transparency of blockchain technology with the power of DeFi yield generation. Every USDC donation is automatically deposited into secure Morpho vaults, where it earns yield and grows over time, creating a sustainable fund for cancer patients.

Key Features

🔄 Yield Generation: Donations automatically earn interest in Morpho Protocol vaults
🎖️ Soulbound Badges: Dynamic NFTs that evolve with each donation
📊 Live Transparency: Real-time on-chain metrics and donor leaderboards
🔒 100% Transparent: Every transaction is publicly verifiable
💎 No Middlemen: Direct patient funding with zero hidden fees
🌐 Multi-Wallet Support: Coinbase Pay, WalletConnect, MetaMask, and more

🏗️ Architecture

Frontend Stack

Framework: Next.js 15 with App Router
Styling: Tailwind CSS with custom components
Web3: Wagmi v2 + Viem for blockchain interactions
UI Components: Radix UI primitives
Animations: Framer Motion
State Management: React Query (TanStack Query)

Smart Contracts

DonationVault: Core donation management and yield generation
DonationSBT: Dynamic soulbound donor badges
MockMorphoVault: Yield vault simulation (testnet)

Network

Primary: Base Network (Ethereum L2)
Testnet: Base Sepolia
Token: USDC (6 decimals)

🚀 Quick Start

Prerequisites

Node.js 18+
npm or yarn
Git

Installation

Clone the repository:

git clone https://github.com/Mr-Web3/HopeChain.git
cd hopechain

Install dependencies:

npm install
# or
yarn install

Set up environment variables: Create a .env.local file in the root directory:

# Base Sepolia RPC
NEXT_PUBLIC_BASE_SEPOLIA_RPC=https://sepolia.base.org

# Base Mainnet RPC (optional)
NEXT_PUBLIC_BASE_RPC=https://mainnet.base.org

# Coinbase Developer API Key
NEXT_PUBLIC_COINBASE_API_KEY=your_coinbase_api_key

# Neynar API Key (for Farcaster integration)
NEXT_PUBLIC_NEYNAR_API_KEY=your_neynar_api_key

# App URL (for metadata)
NEXT_PUBLIC_APP_URL=https://your-domain.com

Run the development server:

npm run dev
# or
yarn dev

Open your browser: Navigate to http://localhost:3000

📱 Pages & Features

🏠 Home Page (`/`)

Hero section with mission statement
How it works explanation
Live transparency dashboard
Top donor leaderboard
Personal story and mission

💰 Donate Page (`/donate`)

USDC donation interface
Real-time vault metrics
Donor leaderboard
Transaction status tracking
Network validation

📊 Impact Page (`/impact`)

Live statistics and metrics
Patient stories and testimonials
Research funding information
Trusted partners showcase

👤 Profile Page (`/profile`)

Personal donation history
Dynamic badge display
Donation progress tracking
Achievement system

📝 Apply Page (`/apply`)

Patient application form
Document upload system
Privacy and security notices
Application status tracking

🛠️ Development

Available Scripts

Script	Description
`npm run dev`	Start development server
`npm run build`	Build for production
`npm run start`	Start production server
`npm run lint`	Run ESLint
`npm run format`	Format code with Prettier

Project Structure

├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── auth/          # Authentication endpoints
│   │   ├── metadata/      # NFT metadata API
│   │   └── notify/        # Notification endpoints
│   ├── components/        # React components
│   │   ├── donate/        # Donation-related components
│   │   ├── profile/       # Profile components
│   │   ├── ui/            # Reusable UI components
│   │   └── wallet/        # Wallet connection components
│   ├── donate/            # Donation page
│   ├── impact/            # Impact page
│   ├── profile/           # Profile page
│   └── apply/             # Application page
├── contracts/             # Deployed contract addresses
├── lib/                   # Utility functions
├── public/                # Static assets
└── utils/                 # Helper utilities

Component Architecture

Core Components

DonationCard: Main donation interface
DonorLeaderboard: Live donor rankings
DynamicBadge: Evolving donor NFT display
NetworkAlert: Network validation warnings
UserDonationSummary: Personal donation stats

UI Components

ThemeToggle: Dark/light mode switcher
ConnectButton: Wallet connection interface
ProgressIndicator: Loading and progress states
PersonalStory: Mission and story sections

🔗 Smart Contract Integration

Contract Addresses

Contract addresses are automatically generated and stored in contracts/deployedContracts.ts:

export const deployedContracts = {
  84532: { // Base Sepolia
    DonationVault: {
      address: "0x...",
      abi: [...]
    },
    DonationSBT: {
      address: "0x...",
      abi: [...]
    },
    USDC: {
      address: "0x...",
      abi: [...]
    }
  }
}

Key Functions

Donation: donate(uint256 amount)
Vault Summary: getVaultSummary(address donor)
Donor List: getAllDonors()
SBT Minting: mintOrUpdateBadge(address donor, uint256 amount)

🎨 Styling & Theming

Design System

Colors: Custom color palette with dark/light mode support
Typography: Geist font family
Spacing: Tailwind's spacing scale
Components: Radix UI primitives with custom styling

Theme Support

Automatic dark/light mode detection
System preference respect
Manual theme toggle
Persistent theme storage

📊 Analytics & Monitoring

On-Chain Metrics

Total donated amount
Yield earned from vaults
Number of unique donors
Lives changed count
Vault balance tracking

Real-Time Updates

Automatic data refresh every 10 seconds
Transaction status monitoring
Donor leaderboard updates
Vault balance changes

🔒 Security Features

Wallet Security

Multiple wallet support
Network validation
Transaction confirmation
Error handling and recovery

Data Protection

No private key storage
Secure API endpoints
Input validation
XSS protection

🚀 Deployment

Vercel Deployment

Connect your GitHub repository to Vercel
Set environment variables in Vercel dashboard
Deploy automatically on push to main branch

Environment Variables

Required environment variables for production:

NEXT_PUBLIC_BASE_SEPOLIA_RPC
NEXT_PUBLIC_COINBASE_API_KEY
NEXT_PUBLIC_APP_URL

Custom Domain

Update the baseURI in your smart contracts to point to your custom domain:

// In Hardhat/scripts/fixBaseURI.ts
const BASE_URI = 'https://your-domain.com/api/metadata';

🧪 Testing

Unit Tests

npm run test

E2E Tests

npm run test:e2e

Type Checking

npm run type-check

📈 Performance

Optimization Features

Next.js Image optimization
Automatic code splitting
Static generation where possible
Efficient re-rendering with React Query
Optimized bundle size

Core Web Vitals

LCP: < 2.5s
FID: < 100ms
CLS: < 0.1

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow the existing code style
Add tests for new features
Update documentation
Ensure all tests pass
Follow conventional commits

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discord: Join our community
Twitter: @DecentralBros_

🙏 Acknowledgments

Base Network for the L2 infrastructure
Morpho Protocol for yield generation
Coinbase for Web3 platform support
OpenZeppelin for secure smart contract libraries
Vercel for hosting and deployment

Built with ❤️ by Decentral Bros

Transparent Giving. Real Healing. Built on Base.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
Hardhat		Hardhat
app		app
contracts		contracts
lib		lib
public		public
utils		utils
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
minikit.config.ts		minikit.config.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

Mr-Web3/HopeChain

Folders and files

Latest commit

History

Repository files navigation