Skip to content

Eric-Johnson-1/HopeDAO

BranchesTags

Repository files navigation

HopeDAO

Decentralized Mutual Aid Crowdfunding DAO Platform

Transparent · Community-Governed · Milestone-Based · Gasless Onboarding

CI Tests TypeScript Prettier PRs Welcome

Solidity Foundry Next.js React Bun Hono

Base ERC-4337 OpenZeppelin Wagmi Viem License

Quick Start • Contracts • Frontend • API • Governance • Roadmap • License


HopeDAO Homepage


🔗 On-Chain
Transparency
Every donation is fully
traceable on Base L2		 🗳️ DAO
Governance
Community-driven decisions
via token voting		 📊 Milestone
Released
Funds unlock only when
milestones are verified		 ⛽ Gasless
Onboarding
ERC-4337 smart accounts
with sponsored gas		 🏅 Soulbound
Badges
ERC-1155 NFT receipts
with tiered rewards

🌟 Vision

HopeDAO solves the fundamental trust crisis in traditional crowdfunding by leveraging blockchain transparency, DAO governance, and milestone-based fund release. Every donation is traceable on-chain, every decision is community-driven, and every fund release is verified.

🏗️ Architecture

HopeDAO/                              # Turborepo monorepo (Bun)
├── apps/
│   ├── web/                          # Next.js 15 Frontend
│   │   ├── src/app/                  # Pages (Home, Explore, Campaign, Dashboard, etc.)
│   │   ├── src/components/           # Reusable UI (Button, Card, Badge, etc.)
│   │   └── src/lib/contracts/        # ABI exports + Wagmi typed hooks
│   └── api/                          # Bun + Hono Backend API
│       ├── src/routes/               # REST endpoints (6 groups: campaigns, governance, analytics, token, verifiers, health)
│       ├── src/middleware/            # Rate limiter (sliding window)
│       └── src/db/                   # Drizzle ORM schema (7 tables, PostgreSQL)
├── packages/
│   ├── contracts/                    # Solidity Smart Contracts (Foundry)
│   │   ├── src/core/                 # Campaign, CampaignFactory, Treasury
│   │   ├── src/governance/           # Governor, Timelock, VerifierRegistry
│   │   ├── src/token/                # HopeToken (ERC-20), DonationReceipt (ERC-1155 SBT)
│   │   ├── src/account/              # ERC-4337: HopeAccount, Factory, Paymaster
│   │   ├── src/libraries/            # QuadraticFunding, CampaignLib, VerificationLib
│   │   ├── test/                     # 108 tests (8 suites)
│   │   └── script/                   # DeployAll.s.sol (all 9 contracts)
│   └── tsconfig/                     # Shared TypeScript configurations
├── .github/workflows/ci.yml         # GitHub Actions CI/CD
└── turbo.json                        # Turborepo pipeline

🔗 Smart Contracts

Core Contracts

Contract Description
Campaign Individual campaign with ETH/ERC-20 donations, milestones, refunds
CampaignFactory Deploys campaigns, manages protocol parameters, fee collection
Treasury DAO treasury with daily rate limiting, guardian emergency system

Governance

Contract Description
HopeGovernor OpenZeppelin Governor with 5-day voting, 4% quorum
HopeTimelock 48-hour execution delay for governance proposals
VerifierRegistry Verifier staking (5K HOPE), reputation scoring, slashing

Tokens

Contract Description
HopeToken ERC-20 governance token with ERC20Votes + ERC20Permit (100M supply)
DonationReceipt Soulbound ERC-1155 NFTs with progressive tier badges

Account Abstraction (ERC-4337)

Contract Description
HopeAccount Smart account: OZ Account + SignerECDSA + ERC7821 batch execution + UUPS
HopeAccountFactory CREATE2 deterministic proxy deployment, address prediction pre-deployment
HopePaymaster Verifying paymaster with per-user/global daily gas limits, backend signer

Libraries

Library Description
QuadraticFunding CLR matching algorithm (quadratic formula implementation)
CampaignLib Shared enums, structs, and validation utilities
VerificationLib Reputation scoring (0-10,000 scale) and quorum checking

🛠️ Tech Stack

Layer Technology
Monorepo Turborepo + Bun
Smart Contracts Solidity 0.8.28, Foundry, OpenZeppelin v5.2.0
Account Abstraction ERC-4337 (Smart Account + Factory + Paymaster)
Frontend Next.js 15, React 19, Tailwind CSS v4, Radix UI
Wallet Wagmi v2, Viem, RainbowKit
State Zustand, TanStack Query
Backend Bun, Hono, Drizzle ORM, PostgreSQL
Animation Framer Motion
CI/CD GitHub Actions
Target Chain Base (Coinbase L2)

🚀 Quick Start

Prerequisites

Installation

# Clone the repository
git clone https://github.com/HopeDAO/HopeDAO.git
cd HopeDAO

# Install dependencies
bun install

# Copy environment files
cp .env.example .env

Smart Contracts

cd packages/contracts

# Build contracts
forge build

# Run tests (108 tests, 8 suites)
forge test -vvv

# Run with gas report
forge test --gas-report

# Format
forge fmt

# Deploy to Base Sepolia
forge script script/DeployAll.s.sol --rpc-url base_sepolia --broadcast --verify

Frontend

cd apps/web
bun dev
# Open http://localhost:3000

Backend API

cd apps/api

# Start development server
bun dev
# API available at http://localhost:3001

# Database management
bun run db:generate   # Generate migrations
bun run db:push       # Push schema to DB
bun run db:studio     # Open Drizzle Studio

Full Monorepo (Dev)

# From root directory
bun run dev

🧪 Test Results

Ran 8 test suites in 10.79ms: 108 tests passed, 0 failed, 0 skipped
Suite Tests Coverage
Campaign.t.sol 23 Campaign lifecycle, donations, milestones, refunds, edge cases
Treasury.t.sol 12 Deposits, withdrawals, daily limits, emergency, pause/unpause
VerifierRegistry.t.sol 16 Registration, staking, reputation, slashing, cooldown, access
HopeGovernor.t.sol 10 Proposals, voting, quorum, full lifecycle through timelock
HopeToken.t.sol 11+2 fuzz ERC-20, voting, permit, burn, fuzz transfer/burn
DonationReceipt.t.sol 13 Soulbound enforcement, tiers, batch restrictions
HopeAccountFactory.t.sol 9+1 fuzz CREATE2 deploy, deterministic address, dedup, pre-fund
HopePaymaster.t.sol 14 Constructor, admin, limits, pause, access control, events

🗳️ Governance Flow

Proposal → 1day delay → 5day voting (4% quorum) → 48h timelock → Execution
  1. Propose — Any holder with ≥100 HOPE can create a proposal
  2. Vote — 5-day voting period (For / Against / Abstain)
  3. Queue — Successful proposals queued in timelock
  4. Execute — After 48-hour delay, execute on-chain

💰 Campaign Lifecycle

Create → AI Screening → Verifier Review → DAO Approval → Fund → Milestone Release → Complete
  1. Create — Creator submits campaign with milestones
  2. Review — Three-tier verification (AI + Verifiers + DAO vote)
  3. Fund — Community donates ETH/ERC-20 tokens
  4. Milestone Release — Creator submits evidence → DAO approves → Funds released
  5. Complete — All milestones achieved, campaign marked complete

🔐 Security

  • OpenZeppelin v5.2.0 — Battle-tested contract implementations
  • Reentrancy Guards — Protection on all state-changing external calls
  • Pausable — Emergency pause on Treasury and Paymaster
  • Timelock — 48-hour delay on all governance actions
  • Rate Limiting — Daily withdrawal caps on Treasury + per-user gas limits on Paymaster
  • Slashing — Economic penalty for dishonest verifiers
  • UUPS Upgradeable — Smart accounts upgradeable through governance

🌐 API Endpoints

Campaigns

  • GET /api/campaigns — List with filtering, sorting, pagination
  • GET /api/campaigns/:id — Campaign details
  • GET /api/campaigns/:id/donations — Donation history
  • GET /api/campaigns/:id/milestones — Milestone status

Governance

  • GET /api/governance/proposals — List proposals
  • GET /api/governance/proposals/:id — Proposal details + votes
  • GET /api/governance/stats — Governance statistics
  • GET /api/governance/delegates — Top delegates

Analytics

  • GET /api/analytics/overview — Platform-wide stats
  • GET /api/analytics/donations/monthly — Monthly volumes
  • GET /api/analytics/categories — Category breakdown
  • GET /api/analytics/top-campaigns — Top funded campaigns
  • GET /api/analytics/treasury — Treasury health

Token

  • GET /api/token/info — HOPE token info
  • GET /api/token/holders — Top holders
  • GET /api/token/balance/:address — Balance lookup

Verifiers

  • GET /api/verifiers — List all registered verifiers
  • GET /api/verifiers/:address — Verifier details (stake, reputation)
  • GET /api/verifiers/leaderboard — Top verifiers by reputation

📁 Frontend Pages

Page Path Description
Home / Hero, features, stats, CTA
Explore /explore Campaign grid with filters and search
Campaign Detail /campaign/:id Full campaign with milestones timeline, donations
Create Campaign /campaign/create 4-step wizard (Info → Milestones → Media → Review)
Dashboard /dashboard My Donations / Campaigns / NFTs
Governance /governance Proposals, voting interface
Verify /verify Verifier dashboard: stake, reputation, pending reviews
Analytics /analytics Platform statistics, charts
About /about Mission, values, roadmap

🐳 Docker Deployment

Quick Start (Docker Compose)

# Start everything (PostgreSQL + API + Web)
docker compose up -d

# Access:
#   Web: http://localhost:3000
#   API: http://localhost:3001
#   DB:  localhost:5432

# View logs
docker compose logs -f api

# Stop all services
docker compose down

# Stop and remove data
docker compose down -v

Manual Docker Build

# Build API
docker build -t hopedao-api ./apps/api

# Build Web (pass contract addresses as build args)
docker build \
  --build-arg NEXT_PUBLIC_API_URL=https://api.hopedao.org \
  --build-arg NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_id \
  --build-arg NEXT_PUBLIC_HOPE_TOKEN_ADDRESS=0x... \
  -t hopedao-web ./apps/web

Note: The API rate limiter uses in-memory storage, which is suitable for single-instance deployments. For horizontal scaling, replace with a Redis-backed rate limiter.

🗺️ Roadmap

The following features are planned for future releases. Contributions and discussions are welcome!

♿ Accessibility (a11y)

  • Full WCAG 2.2 AA compliance across all pages
  • Keyboard navigation for all interactive components (modals, dropdowns, carousels)
  • ARIA live regions for dynamic content updates (donation confirmations, voting results)
  • Screen reader–optimized campaign cards and milestone timelines
  • High-contrast mode toggle and reduced-motion preference support
  • Focus trapping for modals, slide-over panels, and wallet connection dialogs
  • Semantic HTML audit and remediation (landmark roles, heading hierarchy)

🌍 Internationalization (i18n) & Localization

  • Multi-language support via next-intl (starting: English, Chinese)
  • RTL layout support for Arabic, Hebrew, and other RTL languages
  • Locale-aware number / currency / date formatting
  • Community-driven translation contribution workflow
  • Region-specific legal disclaimers and compliance notices

📱 Mobile & Progressive Web App

  • Progressive Web App (PWA) with offline support and push notifications
  • Native-like install experience via manifest.json
  • Mobile wallet deep-linking (MetaMask Mobile, Coinbase Wallet, Rainbow)
  • Touch-optimized gesture navigation (swipe between campaigns, pull-to-refresh)
  • Responsive email/notification templates for donation receipts

🤖 AI & Automation

  • AI-powered campaign fraud detection and risk scoring
  • Natural language campaign creation assistant (LLM-guided form filling)
  • Automated milestone evidence verification via multimodal AI
  • Smart donation matching suggestions based on donor history and preferences
  • AI-generated campaign impact summaries and progress reports

🔒 Privacy & Identity

  • Zero-knowledge proof integration for anonymous donations with verifiability
  • Decentralized Identity (DID) support for verifier and creator credentialing
  • Optional KYC/KYB integration for high-value campaigns (Worldcoin / Polygon ID)
  • Device fingerprinting for anti-sybil protection (opt-in)
  • GDPR-compliant data handling with user data export and deletion

💎 DeFi & Tokenomics

  • Yield-generating treasury strategies (Aave / Compound integration)
  • Token staking rewards for governance participation
  • Cross-chain donation support (Optimism, Arbitrum, Polygon)
  • Fiat on-ramp integration (Stripe, MoonPay) for non-crypto donors
  • Donation streaming via Superfluid (real-time continuous micro-donations)
  • Quadratic funding matching pool with periodic matching rounds

🤝 Social & Community

  • On-chain campaign endorsements and social vouching
  • Donor profile pages with donation history, badges, and impact score
  • Campaign update feed with comments and reactions
  • Referral reward system for campaign promotion
  • Integration with Farcaster / Lens Protocol for decentralized social sharing
  • DAO forum powered by Discourse or on-chain discussion threads

⚙️ DevOps & Infrastructure

  • Redis-backed rate limiting for horizontal API scaling
  • Subgraph (The Graph) for real-time on-chain data indexing
  • Automated contract verification pipeline on Basescan
  • End-to-end test suite (Playwright) covering all user flows
  • Performance monitoring and error tracking (Sentry / OpenTelemetry)
  • Blue-green / canary deployment pipeline with Kubernetes
  • Database migration CI checks and rollback automation

🏛️ Advanced Governance

  • Conviction voting for long-running campaign endorsements
  • Delegation marketplace with verifiable delegate reputation
  • Optimistic governance for low-risk treasury transfers
  • Multi-sig co-signing for high-value milestone releases
  • On-chain campaign arbitration and dispute resolution protocol
  • Retroactive public goods funding rounds (inspired by Optimism RPGF)

📜 License

MIT License — see LICENSE for details.

Built with ❤️ for humanity

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages