FHEVM React Template

A minimal React frontend template for building FHEVM-enabled decentralized applications (dApps). This template provides a simple development interface for interacting with FHEVM smart contracts, specifically the FHECounter.sol contract.

🚀 What is FHEVM?

FHEVM (Fully Homomorphic Encryption Virtual Machine) enables computation on encrypted data directly on Ethereum. This template demonstrates how to build dApps that can perform computations while keeping data private.

✨ Features

• 🔐 FHEVM Integration: Built-in support for fully homomorphic encryption
• ⚛️ React + Next.js: Modern, performant frontend framework
• 🎨 Tailwind CSS: Utility-first styling for rapid UI development
• 🔗 RainbowKit: Seamless wallet connection and management
• 🌐 Multi-Network Support: Works on both Sepolia testnet and local Hardhat node
• 📦 Monorepo Structure: Organized packages for SDK, contracts, and frontend

📋 Prerequinextjss

Before you begin, ensure you have:

• Node.js (v18 or higher)
• pnpm package manager
• MetaMask browser extension
• Git for cloning the repository

🛠️ Quick Start

1. Clone and Setup

# Clone the repository
git clone <repository-url>
cd fhevm-react-template

# Initialize submodules (includes fhevm-hardhat-template)
git submodule update --init --recursive

# Install dependencies
pnpm install

2. Environment Configuration

Set up your Hardhat environment variables by following the FHEVM documentation:

• MNEMONIC: Your wallet mnemonic phrase
• INFURA_API_KEY: Your Infura API key for Sepolia

3. Start Development Environment

Option A: Local Development (Recommended for testing)

# Terminal 1: Start local Hardhat node
pnpm chain
# RPC URL: http://127.0.0.1:8545 | Chain ID: 31337

# Terminal 2: Deploy contracts to localhost
pnpm deploy:localhost

# Terminal 3: Start the frontend
pnpm start

Option B: Sepolia Testnet

# Deploy to Sepolia testnet
pnpm deploy:sepolia

# Start the frontend
pnpm start

4. Connect MetaMask

1. Open http://localhost:3000 in your browser
2. Click "Connect Wallet" and select MetaMask
3. If using localhost, add the Hardhat network to MetaMask:
   • Network Name: Hardhat Local
   • RPC URL: http://127.0.0.1:8545
   • Chain ID: 31337
   • Currency Symbol: ETH

⚠️ Sepolia Production note

• In production, NEXT_PUBLIC_ALCHEMY_API_KEY must be set (see packages/nextjs/scaffold.config.ts). The app throws if missing.
• Ensure packages/nextjs/contracts/deployedContracts.ts points to your live contract addresses.
• Optional: set NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID for better WalletConnect reliability.
• Optional: add per-chain RPCs via rpcOverrides in packages/nextjs/scaffold.config.ts.

🔧 Troubleshooting

Common MetaMask + Hardhat Issues

When developing with MetaMask and Hardhat, you may encounter these common issues:

❌ Nonce Mismatch Error

Problem: MetaMask tracks transaction nonces, but when you restart Hardhat, the node resets while MetaMask doesn't update its tracking.

Solution:

1. Open MetaMask extension
2. Select the Hardhat network
3. Go to Settings → Advanced
4. Click "Clear Activity Tab" (red button)
5. This resets MetaMask's nonce tracking

❌ Cached View Function Results

Problem: MetaMask caches smart contract view function results. After restarting Hardhat, you may see outdated data.

Solution:

1. Restart your entire browser (not just refresh the page)
2. MetaMask's cache is stored in extension memory and requires a full browser restart to clear

💡 Pro Tip: Always restart your browser after restarting Hardhat to avoid cache issues.

For more details, see the MetaMask development guide.

📁 Project Structure

This template uses a monorepo structure with three main packages:

fhevm-react-template/
├── packages/
│   ├── fhevm-hardhat-template/    # Smart contracts & deployment
│   ├── fhevm-sdk/                 # FHEVM SDK package
│   └── nextjs/                      # React frontend application
└── scripts/                       # Build and deployment scripts

Key Components

🔗 FHEVM Integration (packages/nextjs/hooks/fhecounter-example/)

• useFHECounterWagmi.tsx: Example hook demonstrating FHEVM contract interaction
• Essential hooks for FHEVM-enabled smart contract communication
• Easily copyable to any FHEVM + React project

🎣 Wallet Management (packages/nextjs/hooks/helper/)

• MetaMask wallet provider hooks
• Compatible with EIP-6963 standard
• Easily adaptable for other wallet providers

🔧 Flexibility

• Replace ethers.js with Wagmi or other React-friendly libraries
• Modular architecture for easy customization
• Support for multiple wallet providers

📚 Additional Resources

Official Documentation

• FHEVM Documentation - Complete FHEVM guide
• FHEVM Hardhat Guide - Hardhat integration
• Relayer SDK Documentation - SDK reference
• Environment Setup - MNEMONIC & API keys

Development Tools

• MetaMask + Hardhat Setup - Local development
• React Documentation - React framework guide

Community & Support

• FHEVM Discord - Community support
• GitHub Issues - Bug reports & feature requests

📄 License

This project is licensed under the BSD-3-Clause-Clear License. See the LICENSE file for details.