A universal SDK for building privacy-preserving decentralized applications using Fully Homomorphic Encryption (FHE) with Zama's FHEVM. Framework-agnostic and developer-friendly, designed to make confidential smart contract development simple and intuitive.
π Live Demo | π Documentation
πΉ Demo Video: demo.mp4 - Download from repository to view (streaming not supported)
GitHub Repository: https://github.com/OsbaldoSchmeler/fhevm-react-template
Example Application: https://github.com/OsbaldoSchmeler/FHEWaterResourceManager
Fully Homomorphic Encryption (FHE) is a revolutionary cryptographic technology that allows computations to be performed directly on encrypted data without decrypting it. This means:
- β Privacy-Preserving Computation - Process sensitive data while keeping it encrypted
- β Zero-Knowledge Processing - Perform calculations without revealing input values
- β Transparent Verification - Results are verifiable without exposing private data
- β Trustless Operations - No need to trust intermediaries with plaintext data
Traditional blockchain applications expose all data on-chain, creating privacy concerns. FHEVM SDK leverages Zama's FHEVM to enable:
π Private Smart Contracts
- Execute logic on encrypted data
- Keep sensitive inputs confidential
- Reveal results only to authorized parties
- Maintain privacy while ensuring verifiability
π Encrypted State Management
- Store encrypted values on-chain
- Perform operations on ciphertext
- Control decryption with permissions
- EIP-712 signature-based access
π Confidential dApp Development
- Build privacy-first applications
- No data exposure during computation
- Fair algorithms without revealing inputs
- Compliance with data protection regulations
This SDK provides access to all FHEVM capabilities:
// Encrypted data types
euint8, euint16, euint32, euint64, euint128, euint256
ebool, eaddress
// Arithmetic operations
FHE.add(), FHE.sub(), FHE.mul(), FHE.div()
// Comparison operations
FHE.eq(), FHE.ne(), FHE.gt(), FHE.gte(), FHE.lt(), FHE.lte()
// Logical operations
FHE.and(), FHE.or(), FHE.xor(), FHE.not()
// Selection and manipulation
FHE.select(), FHE.min(), FHE.max()
// Permission management
FHE.allow(), FHE.allowThis()
// Decryption
FHE.decrypt() // With EIP-712 signatureLearn More About FHE:
- Zama FHEVM: https://github.com/zama-ai/fhevm
- FHEVM Documentation: https://docs.zama.ai/fhevm
- FHE Tutorial: Getting Started with FHEVM
FHEVM SDK is a comprehensive toolkit that wraps all necessary packages and utilities for building confidential smart contracts with Zama's FHEVM. It provides:
- π― Framework-Agnostic Core - Works with Node.js, Next.js, Vue, React, or any frontend
- π¦ All-in-One Package - No scattered dependencies, everything you need in one place
- π§ wagmi-like Structure - Intuitive API familiar to web3 developers
- β‘ Quick Setup - Less than 10 lines of code to get started
- π Complete FHE Flow - Initialization, encryption, decryption, and contract interaction
- π¨ React Hooks - Ready-to-use hooks for React/Next.js applications
- π± Live Example - Working Next.js application demonstrating all features
# 1. Clone repository
git clone https://github.com/OsbaldoSchmeler/fhevm-react-template.git
cd fhevm-react-template
# 2. Install all dependencies
npm install
# 3. Start Next.js example
npm run devOpen your browser - Done! π
This is a monorepo containing the SDK and example applications:
fhevm-react-template/
βββ packages/
β βββ fhevm-sdk/ β π¦ Core SDK Package
β βββ src/
β β βββ index.ts β Main SDK (framework-agnostic)
β β βββ react.tsx β React Hooks
β β βββ core/ β Core FHEVM functionality
β β βββ hooks/ β React hooks (useFhevm, etc.)
β β βββ utils/ β Encryption/decryption utilities
β β βββ types/ β TypeScript type definitions
β β βββ adapters/ β Framework adapters (React, Vue, Node.js)
β βββ package.json
β βββ README.md
β βββ tsconfig.json
β
βββ templates/ β π Integration Templates
β βββ nextjs/ β Next.js integration guide
β βββ react/ β React integration guide
β βββ vue/ β Vue integration guide
β βββ nodejs/ β Node.js integration guide
β βββ README.md β Templates overview
β
βββ examples/
β βββ nextjs-water-management/ β π― Simple Next.js Example (Port 3000)
β β βββ pages/
β β β βββ index.tsx β Basic SDK demo
β β βββ package.json
β β
β βββ nextjs-water-resource-management/ β π Full Next.js Example (Port 3001)
β β βββ pages/
β β β βββ index.tsx β Complete water management system
β β βββ package.json
β β
β βββ water-resource-management/ β π Converted React/Next.js App (Port 3002)
β β βββ pages/
β β β βββ index.tsx β Converted from static HTML
β β βββ index.html β Original static version (preserved)
β β βββ package.json
β β
β βββ WaterResourceManager/ β π Converted React/Next.js App (Port 3003)
β β βββ pages/
β β β βββ index.tsx β Converted from static HTML
β β βββ index.html β Original static version (preserved)
β β βββ package.json
β β
β βββ nextjs-fhe-app-router/ β β App Router Example (Port 3002)
β βββ src/
β β βββ app/ β App Router pages and API routes
β β βββ components/ β React components
β β βββ lib/ β FHE utilities
β β βββ hooks/ β Custom hooks
β βββ package.json
β
βββ contracts/
β βββ WaterResourceManager.sol β Example smart contract
β
βββ docs/ β π Complete documentation
βββ demo.mp4 β Video demonstration (download to view)
βββ README.md β You are here
Works Everywhere:
// Node.js / CommonJS
const { initFHEVM, encrypt } = require('fhevm-sdk');
// ES Modules
import { initFHEVM, encrypt } from 'fhevm-sdk';
// React / Next.js
import { useFHEVM, useEncrypt } from 'fhevm-sdk/react';
// Vue (future)
import { useFHEVM } from 'fhevm-sdk/vue';Familiar to Web3 Developers:
import { useFHEVM, useEncrypt, useDecrypt } from 'fhevm-sdk/react';
function MyComponent() {
const { isReady } = useFHEVM({ network: 'sepolia' });
const { encryptUint32, isEncrypting } = useEncrypt();
const { decryptUser } = useDecrypt();
const handleSubmit = async () => {
const encrypted = await encryptUint32(1000);
await contract.submitData(encrypted);
};
return (
<button onClick={handleSubmit} disabled={!isReady || isEncrypting}>
Submit Encrypted
</button>
);
}// β
Step 1: Initialize
await initFHEVM({ network: 'sepolia', provider: window.ethereum });
// β
Step 2: Encrypt inputs
const encrypted = await encrypt.uint32(1000);
// β
Step 3: Send to contract
await contract.submitEncryptedData(encrypted);
// β
Step 4: Decrypt results (with EIP-712 signature)
const decrypted = await decrypt.user(result, { signer: wallet });Location: examples/nextjs-water-management/
A minimal Next.js example demonstrating basic FHEVM SDK usage with React hooks.
Features:
- β Basic SDK initialization
- β Simple encryption demo
- β React hooks integration
- β Clean, educational code
Run Locally:
cd examples/nextjs-water-management
npm install
npm run devVisit http://localhost:3000
Code Example:
import { useFHEVM, useEncrypt } from 'fhevm-sdk/react';
export default function WaterManagement() {
const { isReady } = useFHEVM({ network: 'sepolia' });
const { encryptUint32, isEncrypting } = useEncrypt();
const handleEncrypt = async () => {
const encrypted = await encryptUint32(1000);
// Use encrypted data in contract calls
};
return (
<button onClick={handleEncrypt} disabled={!isReady || isEncrypting}>
{isEncrypting ? 'Encrypting...' : 'Encrypt Data'}
</button>
);
}Location: examples/nextjs-water-resource-management/
A comprehensive production-ready water resource management system showcasing the complete capabilities of FHEVM SDK.
Features:
- β Full FHE Integration - Complete encryption/decryption workflow
- β Multi-Role System - Admin and region manager interfaces
- β Privacy-Preserving Operations - Encrypted water requests and allocations
- β Real-time State Management - Live blockchain monitoring
- β Comprehensive UI - Production-grade interface with Tailwind CSS
- β Type-Safe - Full TypeScript implementation
- β Error Handling - Robust error messages and loading states
Run Locally:
cd examples/nextjs-water-resource-management
npm install
npm run devVisit http://localhost:3001
Key Functionality:
Admin Functions:
- Register water management regions
- Start allocation periods with time limits
- Process encrypted allocation requests
- Emergency water allocation
- Region management
Manager Functions:
- Submit encrypted water requests
- View region status
- Check allocation results
Privacy Features:
- Encrypted water demand amounts
- Confidential justification scores
- FHE-based fair allocation
- Selective result disclosure
Code Example:
import { useFHEVM, useEncrypt } from 'fhevm-sdk/react';
export default function WaterResourceManagement() {
const { isReady } = useFHEVM({ network: 'sepolia' });
const { encryptUint32, isEncrypting } = useEncrypt();
const submitWaterRequest = async () => {
// Encrypt sensitive data using FHEVM SDK
const encryptedAmount = await encryptUint32(requestAmount);
const encryptedScore = await encryptUint32(justificationScore);
// Submit to smart contract (data remains encrypted!)
const tx = await contract.submitWaterRequest(
requestAmount,
justificationScore
);
await tx.wait();
// Other regions CANNOT see your request details!
};
return (
<button onClick={submitWaterRequest} disabled={!isReady || isEncrypting}>
{isEncrypting ? 'π Encrypting & Submitting...' : 'π Submit Encrypted Request'}
</button>
);
}Location: examples/water-resource-management/
A React/Next.js implementation of the water resource management system, converted from the original static HTML version to provide a modern, maintainable codebase.
Features:
- β Full Next.js 14 with Pages Router
- β React hooks for state management
- β TypeScript for type safety
- β Same functionality as original HTML version
- β Production-ready structure
- β Hot reload development experience
Run Locally:
cd examples/water-resource-management
npm install
npm run devVisit http://localhost:3002
Live Demo: https://fhe-water-resource-manager.vercel.app/
Note: The original index.html static version is preserved in the directory for reference.
Video File: demo.mp4 (located in repository root)
Important: The demo video must be downloaded to view. Streaming is not supported.
How to Access:
- Navigate to the GitHub repository root directory
- Locate the file named
demo.mp4 - Click "Download" or "Download raw file"
- Open with your media player (VLC, Windows Media Player, etc.)
Video Content: Complete walkthrough of FHEVM SDK usage through the water resource management examples, including:
- SDK initialization
- Privacy-preserving water allocation
- React hooks integration
- Encrypted data processing
- Admin and manager workflows
Location: examples/nextjs-fhe-app-router/
A modern Next.js 13+ App Router implementation showcasing a complete, scalable FHE architecture with API routes, custom hooks, and production-ready components.
Features:
- β Next.js 14 App Router - Modern React Server Components
- β Complete Architecture - Modular, scalable code structure
- β API Routes - RESTful endpoints for FHE operations
- β
Custom Hooks -
useFHE,useEncryption,useComputation - β UI Component Library - Reusable Button, Input, Card components
- β FHE Components - Provider, demos, key manager
- β Real-World Examples - Banking and medical use cases
- β Type-Safe - Complete TypeScript implementation
- β Production Patterns - Best practices for scalability
Run Locally:
cd examples/nextjs-fhe-app-router
npm install
npm run devVisit http://localhost:3002
Architecture Highlights:
API Endpoints:
POST /api/fhe/encrypt- Encrypt dataPOST /api/fhe/decrypt- Decrypt ciphertextPOST /api/fhe/compute- Homomorphic computationPOST /api/keys- Key generation
Custom Hooks:
// FHE initialization
const { isInitialized, initialize } = useFHE();
// Encryption with loading states
const { encryptWithSDK, encryptWithAPI, isEncrypting } = useEncryption();
// Homomorphic computation
const { compute, add, subtract, compare, result } = useComputation();Component Structure:
- UI Components:
Button,Input,Card - FHE Components:
FHEProvider,EncryptionDemo,ComputationDemo,KeyManager - Examples:
BankingExample,MedicalExample
Code Example:
import { useEncryption } from '@/hooks/useEncryption';
import { Button } from '@/components/ui/Button';
function BankingApp() {
const { encryptWithSDK, isEncrypting } = useEncryption();
const handleDeposit = async (amount: number) => {
// Encrypt sensitive data
const encrypted = await encryptWithSDK(amount, 'uint32');
// Send to contract (encrypted!)
await contract.deposit(encrypted);
};
return (
<Button onClick={() => handleDeposit(1000)} isLoading={isEncrypting}>
Deposit Confidentially
</Button>
);
}| Feature | Simple Next.js | Full Next.js | Water Resource Mgmt | App Router |
|---|---|---|---|---|
| Framework | Pages Router | Pages Router | Pages Router | App Router |
| SDK Integration | β Basic | β Complete | β Complete | β Complete |
| Production Ready | β Demo only | β Yes | β Yes | β Yes |
| Architecture | Simple | Water Management | Water Management | Full FHE Stack |
| API Routes | β No | β No | β No | β Yes |
| Custom Hooks | β No | β No | React hooks | β Yes |
| UI Components | Basic | Inline | Inline | β Library |
| Real-World Examples | β No | β Water | β Water | β Banking + Medical |
| TypeScript | β Yes | β Yes | β Yes | β Yes |
| Build Required | β Yes | β Yes | β Yes | β Yes |
| Port | 3000 | 3001 | 3002 | 3002 |
| Best For | Learning | Production App | Production App | Scalable Apps |
Recommendation:
- Just learning FHE? β Start with Simple Next.js Example
- Building a production app? β Use Full Next.js Example or Water Resource Management
- Need scalable architecture? β Use App Router Example β
import { initFHEVM } from 'fhevm-sdk';
await initFHEVM({
network: 'sepolia' | 'localhost',
provider: window.ethereum, // or ethers provider
contractAddress?: string // optional
});import { encrypt } from 'fhevm-sdk';
const encrypted32 = await encrypt.uint32(1000);
const encrypted64 = await encrypt.uint64(1000000);
const encryptedBool = await encrypt.bool(true);
const encryptedAddr = await encrypt.address('0x...');import { decrypt } from 'fhevm-sdk';
// User decryption (with EIP-712 signature)
const value = await decrypt.user(ciphertext, {
signer: wallet,
contract: contractAddress
});
// Public decryption (if permitted)
const publicValue = await decrypt.public(ciphertext);import { useFHEVM, useEncrypt, useDecrypt } from 'fhevm-sdk/react';
// Initialize SDK
const { isReady, isInitializing, error, init } = useFHEVM(config);
// Encryption with loading states
const { encryptUint32, isEncrypting, error } = useEncrypt();
// Decryption with loading states
const { decryptUser, isDecrypting, error } = useDecrypt();
// Contract interaction
const { contract, isLoading, error } = useContract({
address: '0x...',
abi: contractABI,
provider: provider
});npm install fhevm-sdk// app.tsx or page.tsx
import { useFHEVM, useEncrypt } from 'fhevm-sdk/react';
export default function MyApp() {
const { isReady } = useFHEVM({
network: 'sepolia',
provider: window.ethereum
});
const { encryptUint32 } = useEncrypt();
const handleEncrypt = async () => {
const encrypted = await encryptUint32(1000);
console.log('Encrypted:', encrypted);
};
if (!isReady) return <div>Initializing FHEVM...</div>;
return <button onClick={handleEncrypt}>Encrypt</button>;
}// MyContract.sol
import { FHE, euint32 } from "@fhevm/solidity/lib/FHE.sol";
contract MyConfidentialContract {
mapping(address => euint32) private balances;
function deposit(euint32 encryptedAmount) external {
balances[msg.sender] = encryptedAmount;
FHE.allowThis(encryptedAmount);
FHE.allow(encryptedAmount, msg.sender);
}
function getBalance() external view returns (euint32) {
return balances[msg.sender];
}
}Want to integrate FHEVM SDK into your existing project? Check out our framework-specific templates:
| Framework | Template | Description |
|---|---|---|
| Next.js | templates/nextjs/ | Complete Next.js integration guide with App Router & Pages Router examples |
| React | templates/react/ | React integration for CRA, Vite, and other React setups |
| Vue | templates/vue/ | Vue 3 integration using Composition API composables |
| Node.js | templates/nodejs/ | Backend services, CLI tools, and serverless functions |
# View Next.js template
cat templates/nextjs/README.md
# View React template
cat templates/react/README.md
# View Vue template
cat templates/vue/README.md
# View Node.js template
cat templates/nodejs/README.mdEach template includes:
- β Installation instructions
- β Configuration examples
- β Code snippets
- β Best practices
- β Links to working examples
See templates/README.md for complete overview
- Encrypted votes
- Public tallying without revealing individual choices
- Privacy-preserving governance
- Hidden bids until reveal
- Fair price discovery
- Trustless auction mechanisms
- Confidential balances
- Hidden transaction amounts
- Privacy-preserving swaps
- Dark pools
- Hidden demands (like water management)
- Fair distribution algorithms
- Privacy in supply chains
- Private credentials
- Selective disclosure
- Zero-knowledge proofs
- Compliance without exposure
- Encrypted patient records
- Privacy-preserving research
- Confidential diagnostics
| Operation | Gas Cost | Notes |
|---|---|---|
encrypt.uint32() |
~50,000 | Client-side + contract |
FHE.add() |
~75,000 | On-chain computation |
FHE.gt() |
~80,000 | Encrypted comparison |
decrypt.user() |
~30,000 | With EIP-712 signature |
β Minimize FHE operations - Cache encrypted values where possible β Batch operations - Process multiple items together β Use smallest types - euint32 vs euint64 vs euint128 β Strategic encryption - Only encrypt sensitive data
# From root
npm test
# From parent directory (smart contracts)
cd ../../
npm run test
npm run test:coverage# Start Next.js dev server
npm run dev
# Build SDK
npm run build
# Compile contracts
npm run compileNetwork: Ethereum Sepolia Testnet
Contract Address: 0x4E2c3faE5165E4d5f9E2dEcFEA50e84399157b76
Explorer: View on Etherscan
URL: https://fhe-water-resource-manager.vercel.app/ Status: β Live and operational
| Document | Description |
|---|---|
| README.md | This file - SDK overview |
| templates/ | Framework integration templates (Next.js, React, Vue, Node.js) |
| SUBMISSION.md | Competition submission summary |
| QUICK_START.md | 5-minute quick start guide |
| FINAL_CHECKLIST.md | Requirements verification |
| FILE_MANIFEST.md | Complete file listing |
| docs/ | Additional documentation |
- TypeScript - Type-safe SDK development
- Zama FHEVM - FHE smart contract library
- Ethers.js v6 - Blockchain interaction
- React - Optional hooks adapter
- Next.js 14.x - React framework
- React 18.x - UI library
- Tailwind CSS - Styling
- TypeScript - Type safety
- MetaMask - Wallet integration
- Hardhat - Smart contract framework
- Mocha/Chai - Testing
- ESLint - Code linting
- Prettier - Code formatting
FHE Confidential Water Resource Management - Privacy Water Allocation
- GitHub: https://github.com/OsbaldoSchmeler/FHEWaterResourceManager
- Live Demo: https://fhe-water-resource-manager.vercel.app/
- Description: Confidential water resource allocation platform demonstrating privacy-preserving water distribution using this SDK. Features encrypted demand submission, fair allocation algorithms on encrypted data, and role-based access control.
Zama FHEVM Documentation
- Official Docs: https://docs.zama.ai/fhevm
- GitHub: https://github.com/zama-ai/fhevm
- Tutorial: Getting Started with FHEVM
- π Hardhat Documentation: https://hardhat.org/
- π OpenZeppelin Contracts: https://docs.openzeppelin.com/
- β‘ Ethers.js Docs: https://docs.ethers.org/
- π Solidity Docs: https://docs.soliditylang.org/
We welcome contributions!
# Fork and clone
git clone https://github.com/your-fork/fhevm-react-template.git
cd fhevm-react-template
# Install dependencies
npm install
# Make changes and test
npm run dev
# Submit PRMIT License - see LICENSE file.
- Zama - For pioneering FHE technology and FHEVM
- Ethereum Community - For blockchain infrastructure
- wagmi - For API design inspiration
- Next.js - For excellent React framework
- All Contributors - For improving this SDK
GitHub Repository: https://github.com/OsbaldoSchmeler/fhevm-react-template
Example Application: https://github.com/OsbaldoSchmeler/FHEWaterResourceManager
Live Demo: https://fhe-water-resource-manager.vercel.app/
Issues: GitHub Issues
Discussions: GitHub Discussions
Video Demo: Download demo.mp4 from repository