Private Donation dApp with FHEVM

Private Donation dApp is a privacy-first donation platform built with Fully Homomorphic Encryption (FHE) technology via FHEVM. This platform enables donors to contribute to campaigns while keeping individual donation amounts completely encrypted and private.

Live Demo: priv8dono.starfrich.me

System Architecture

graph TB
    %% Client Components
    subgraph User Interface
        UI[Frontend - Next.js<br/>React + TypeScript]
        Wallet[Wallet Connection<br/>RainbowKit + wagmi]
        Forms[Campaign Forms<br/>Donation Forms]
        Dashboard[Campaign Dashboard<br/>Donor Portal]
    end

    subgraph Client-Side Logic
        FHE[FHEVM Encryption<br/>FHEVMEncryption class]
        Hooks[Custom React Hooks<br/>useDonateEncrypted<br/>useCreateCampaign<br/>useCampaignDetails]
        Zama[Zama JS SDK<br/>@zama-fhe/relayer-sdk]
    end

    %% Blockchain Layer
    subgraph Blockchain Layer
        SC[Smart Contract<br/>DonationCampaign.sol<br/>SepoliaConfig]
        BC[(Ethereum<br/>Sepolia Testnet)]
        Events[Events<br/>CampaignCreated<br/>DonationMade<br/>FundsReleased]
    end

    %% Data Storage
    subgraph On-Chain Storage
        CS[Campaign Storage<br/>Campaign structs<br/>Public donor addresses]
        ES[Encrypted Storage<br/>euint64 totalDonated<br/>ebool targetReached<br/>euint64 contributions]
        TX[Transaction Logs<br/>Public events<br/>On-chain provenance]
    end

    %% External Services
    subgraph FHEVM Infrastructure
        Oracle[Zama Oracle<br/>Decryption Callback<br/>releaseCallback function]
        FHEVM[FHEVM Network<br/>Gateway + KMS<br/>Abstracted by SDK]
    end

    %% Connections
    UI --> Wallet
    UI --> Forms
    UI --> Dashboard

    Wallet --> FHE
    Forms --> Hooks
    Dashboard --> Hooks

    Hooks --> Zama
    FHE --> Zama

    Zama -.->|Internal| FHEVM
    Zama --> SC

    SC --> BC
    SC --> CS
    SC --> ES
    SC --> Events
    Events --> TX

    SC -->|FHE.requestDecryption| Oracle
    Oracle -->|releaseCallback| SC
    Oracle -.->|Uses| FHEVM

    %% Style definitions
    classDef ui fill:#bbdefb,stroke:#0d47a1,color:#0d47a1,stroke-width:2px
    classDef logic fill:#d1c4e9,stroke:#4a148c,color:#311b92,stroke-width:2px
    classDef blockchain fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20,stroke-width:2px
    classDef storage fill:#ffe0b2,stroke:#e65100,color:#e65100,stroke-width:2px
    classDef external fill:#f8bbd0,stroke:#880e4f,color:#880e4f,stroke-width:2px

    class UI,Wallet,Forms,Dashboard ui
    class FHE,Hooks,Zama logic
    class SC,BC,Events blockchain
    class CS,ES,TX storage
    class Oracle,FHEVM external

Loading

Key Components

Frontend Layer

• Next.js React Application: Main user interface with campaign browsing, donation, and management features
• Wallet Integration: RainbowKit + wagmi for wallet connection and blockchain interactions
• FHEVM Encryption: Client-side encryption using FHEVMEncryption class
• Custom React Hooks:
  • useDonateEncrypted(): Encrypted donation submission
  • useCreateCampaign(): Campaign creation
  • useCampaignDetails(): Fetch campaign data
  • useMyContribution(): User's encrypted contributions

Smart Contract Layer

• DonationCampaign.sol: Main FHEVM contract extending SepoliaConfig
• Encrypted Types: Uses euint64 for amounts and ebool for flags
• Homomorphic Operations: FHE.add(), FHE.ge(), FHE.or() for encrypted computations
• Oracle Integration: FHE.requestDecryption() and releaseCallback() for fund release
• Event System: Comprehensive event logging (CampaignCreated, DonationMade, FundsReleased)

Data Layer

• On-Chain Storage:
  • Campaign metadata (public)
  • Donor addresses (public - stored in campaignDonors mapping)
  • Encrypted amounts (euint64 totalDonated, individual euint64 contributions)
  • Encrypted flags (ebool targetReached)
• Transaction Logging: Public events ensure transparency while amounts remain encrypted

FHEVM Infrastructure (External)

• Zama Oracle: Decryption service that calls releaseCallback() when conditions are met
• FHEVM Network: Gateway + KMS abstracted by Zama SDK (@zama-fhe/relayer-sdk)
• Key Management: Handled internally by FHEVM infrastructure

Security Features

• End-to-End Encryption: Individual donation amounts encrypted client-side using FHEVM
• Homomorphic Aggregation: Campaign totals calculated without revealing individual contributions
• Fully Homomorphic Encryption (FHE): Computations performed directly on encrypted data without decryption
• Oracle-Based Decryption: Funds only released when smart contract conditions are met
• Access Control: Granular permissions for encrypted data access via ACL system

Trust Model

• Trust Assumptions: Zama oracle for decryption, FHEVM for cryptographic correctness
• Public Transparency: Campaign metadata and events visible on-chain
• Privacy Model: Amount-private donations (not fully anonymous)
• Smart Contract Security: Reentrancy protection and input validation

Privacy Trade-offs

What is Private:

• ✅ Individual donation amounts (encrypted with euint64)
• ✅ Campaign totals remain encrypted until oracle decryption
• ✅ Homomorphic operations preserve amount confidentiality

What is Public:

• ⚠️ Donor wallet addresses are visible on-chain
• ⚠️ Transaction timestamps and gas fees are public
• ⚠️ Campaign metadata (description, target, deadline) is public

Privacy Model: This implementation provides amount-private donations, not full anonymity. While donation amounts are encrypted and private, donor addresses are recorded on-chain for contribution tracking. For full anonymity, additional privacy layers (like mixers or stealth addresses) would be required.

This architecture balances donor privacy with practical campaign management and fund distribution.

Project Structure

This setup includes:

• contracts/: Hardhat project for developing, testing, and deploying FHEVM smart contracts.
• frontend/: React-based frontend for interacting with deployed contracts.
• docs/: Documentation (see docs/README.md for details).
  Web version: starfrich.me/docs/projects/private-donation

Quick Start

Start building quickly with:

• Contracts Quick Start
• Frontend Quick Start
• FHEVM Hardhat Quick Start Tutorial