FHEVM SDK - Universal Toolkit for Confidential dApps 🔐

Framework-agnostic FHEVM SDK with wagmi-like developer experience for building privacy-preserving applications on Zama's Fully Homomorphic Encryption Virtual Machine.

🎯 Built for the Zama Bounty Challenge - A complete, reusable SDK that makes building confidential frontends simple, consistent, and developer-friendly.

🌐 Live Example: https://fhe-pollution-monitor.vercel.app/

💻 GitHub: https://github.com/OdaTorphy/fhevm-react-template

📹 Demo Video: Download demo.mp4 to watch the full demonstration (streaming not available)

✨ Features

🎨 Framework-Agnostic - Works with React, Next.js, Vue, Node.js, or vanilla JavaScript
🔌 Wagmi-like API - Intuitive hooks and composables familiar to web3 developers
📦 All-in-One Package - Wraps all required dependencies (fhevmjs, ethers, etc.)
🚀 Quick Setup - Less than 10 lines of code to get started
🔐 Complete FHEVM Flow - Initialize, encrypt inputs, decrypt outputs, contract interaction
🧩 Modular & Reusable - Clean components for different encryption/decryption scenarios
📚 Well Documented - Comprehensive guides and code examples
🎭 TypeScript First - Full type safety with excellent IntelliSense
⚡ Zero Configuration - Sensible defaults with easy customization
🔄 EIP-712 Support - Built-in userDecrypt and publicDecrypt utilities

🚀 Quick Start

Installation

# Install the SDK
npm install fhevm-sdk

# Or with yarn
yarn add fhevm-sdk

# Or with pnpm
pnpm add fhevm-sdk

Basic Usage (< 10 lines!)

import { createFhevmClient, encrypt, decrypt } from 'fhevm-sdk';

// 1. Initialize the client
const client = await createFhevmClient({
  network: 'sepolia',
  contractAddress: '0x...'
});

// 2. Encrypt sensitive data
const encryptedValue = await encrypt(client, 42);

// 3. Decrypt results (with EIP-712 signature)
const decryptedValue = await decrypt(client, encryptedData);

🏗️ Architecture

fhevm-sdk/
├── Core Engine (framework-agnostic)
│   ├── FHEVM initialization
│   ├── Encryption utilities
│   ├── Decryption utilities (EIP-712)
│   └── Contract interaction
│
├── React Adapters
│   ├── useFhevmClient()
│   ├── useEncrypt()
│   ├── useDecrypt()
│   └── useContract()
│
├── Vue Adapters
│   ├── useFhevmClient()
│   ├── useEncrypt()
│   └── useDecrypt()
│
└── Utilities
    ├── Type converters
    ├── Network helpers
    └── Error handling

📦 Package Structure

This is a monorepo containing:

fhevm-react-template/
├── packages/
│   └── fhevm-sdk/              # Core SDK package
│       ├── src/
│       │   ├── core/           # Framework-agnostic core
│       │   │   ├── client.ts   # Main FHEVM client
│       │   │   ├── encrypt.ts  # Encryption utilities
│       │   │   ├── decrypt.ts  # Decryption utilities
│       │   │   └── types.ts    # Type definitions
│       │   ├── react/          # React hooks & provider
│       │   │   └── index.tsx   # React adapters
│       │   ├── vue/            # Vue composables
│       │   │   └── index.tsx   # Vue adapters
│       │   ├── utils/          # Utility functions
│       │   │   ├── errors.ts   # Custom error classes
│       │   │   └── helpers.ts  # Helper functions
│       │   └── index.ts        # Main entry point
│       └── package.json
│
├── templates/                   # Ready-to-use templates
│   ├── nextjs/                 # Next.js template (symbolic link)
│   └── react/                  # React template (symbolic link)
│
├── examples/
│   ├── nextjs-pollution-monitor/    # Full-featured Next.js application
│   │   ├── components/
│   │   │   ├── examples/       # Banking & Medical examples
│   │   │   ├── fhe/           # FHE components
│   │   │   └── ui/            # UI components
│   │   ├── app/               # Next.js App Router
│   │   ├── hooks/             # Custom hooks
│   │   └── lib/               # Utilities
│   ├── react-basic/                 # Minimal React setup
│   ├── node-cli/                    # Command-line encryption tool
│   └── PrivacyPollutionMonitor/     # React pollution monitor with full FHE encryption
│
├── contracts/                   # Example smart contracts
├── docs/                        # Documentation files
└── README.md                    # This file

🎯 Complete FHEVM Flow

1. Initialize FHEVM Client

import { FhevmClient } from 'fhevm-sdk';

const client = new FhevmClient({
  network: 'sepolia',
  rpcUrl: 'https://rpc.sepolia.org',
  chainId: 11155111,
  contractAddress: '0xYourContract',
  // Optional: custom gateway for decryption
  gatewayUrl: 'https://gateway.zama.ai'
});

await client.init();

2. Encrypt Inputs

// Encrypt different types
const encrypted8 = await client.encrypt8(255);
const encrypted16 = await client.encrypt16(65535);
const encrypted32 = await client.encrypt32(1000000);
const encrypted64 = await client.encrypt64(BigInt('9007199254740991'));
const encryptedBool = await client.encryptBool(true);
const encryptedAddress = await client.encryptAddress('0x...');

// Batch encryption
const batch = await client.encryptBatch({
  amount: 1000,
  threshold: 500,
  active: true
});

3. Contract Interaction

import { Contract } from 'ethers';

// Connect to contract
const contract = new Contract(
  contractAddress,
  contractABI,
  client.getSigner()
);

// Submit encrypted data
const tx = await contract.submitReport(
  encrypted64,
  encrypted8,
  encryptedBool
);

await tx.wait();

4. Decrypt Outputs (EIP-712)

// User decrypt (requires signature)
const decrypted = await client.userDecrypt(
  encryptedData,
  contractAddress
);

// Public decrypt (no signature needed)
const publicData = await client.publicDecrypt(encryptedData);

// Batch decrypt
const results = await client.decryptBatch([
  encryptedValue1,
  encryptedValue2,
  encryptedValue3
]);

🎨 React Integration

Setup Provider

import { FhevmProvider } from 'fhevm-sdk/react';

function App() {
  return (
    <FhevmProvider
      config={{
        network: 'sepolia',
        contractAddress: '0x...'
      }}
    >
      <YourApp />
    </FhevmProvider>
  );
}

Use Hooks

import { useFhevmClient, useEncrypt, useDecrypt } from 'fhevm-sdk/react';

function EncryptionComponent() {
  const client = useFhevmClient();
  const { encrypt, isEncrypting } = useEncrypt();
  const { decrypt, isDecrypting } = useDecrypt();

  const handleSubmit = async (value: number) => {
    // Encrypt
    const encrypted = await encrypt(value, 'uint64');

    // Send to contract
    const tx = await contract.submit(encrypted);
    await tx.wait();

    // Decrypt result
    const result = await decrypt(encryptedResult);
    console.log('Decrypted:', result);
  };

  return (
    <div>
      <button onClick={() => handleSubmit(42)} disabled={isEncrypting}>
        {isEncrypting ? 'Encrypting...' : 'Submit Encrypted Data'}
      </button>
    </div>
  );
}

🎭 Vue Integration

<script setup lang="ts">
import { useFhevmClient, useEncrypt, useDecrypt } from 'fhevm-sdk/vue';

const client = useFhevmClient({
  network: 'sepolia',
  contractAddress: '0x...'
});

const { encrypt, isEncrypting } = useEncrypt(client);
const { decrypt, isDecrypting } = useDecrypt(client);

const handleEncrypt = async () => {
  const encrypted = await encrypt(42, 'uint64');
  console.log('Encrypted:', encrypted);
};
</script>

<template>
  <button @click="handleEncrypt" :disabled="isEncrypting">
    {{ isEncrypting ? 'Encrypting...' : 'Encrypt Data' }}
  </button>
</template>

📋 SDK Integration Examples

This repository includes four comprehensive examples demonstrating FHEVM SDK integration across different environments:

1. Next.js Full-Featured Application

Location: examples/nextjs-pollution-monitor/ or templates/nextjs/

A complete production-ready Next.js application showcasing:

✅ Station registration with encrypted data
✅ Confidential pollution reporting (euint64)
✅ Homomorphic threshold checking
✅ EIP-712 signed decryption
✅ Role-based access control
✅ Real-time encrypted dashboard
✅ MetaMask integration
✅ Sepolia testnet deployment
✅ Banking Example: Confidential transactions
✅ Medical Example: Privacy-preserving health records

Quick Start:

cd examples/nextjs-pollution-monitor
npm install
npm run dev

Visit http://localhost:3000

See examples/nextjs-pollution-monitor/README.md for details.

2. React Basic Example

Location: examples/react-basic/ or templates/react/

A minimal React setup perfect for learning FHEVM SDK basics:

✅ Basic encryption demonstration
✅ Simple UI with loading states
✅ Error handling
✅ Educational info panel
✅ Perfect starting point for new projects

Quick Start:

cd examples/react-basic
npm install
npm run dev

Visit http://localhost:5173

See examples/react-basic/README.md for details.

3. Node.js CLI Tool

Location: examples/node-cli/

Command-line tool for FHEVM encryption operations:

✅ Command-line encryption
✅ Multiple encryption types (uint8, uint16, uint32, uint64, bool)
✅ Progress indicators
✅ Colored output
✅ Perfect for testing and automation

Quick Start:

cd examples/node-cli
npm install

# Encrypt a value
node index.js encrypt 42 --contract 0xYourContractAddress --type uint64

See examples/node-cli/README.md for details.

4. Privacy Pollution Monitor - React Edition

Location: examples/PrivacyPollutionMonitor/

A comprehensive environmental monitoring application with full FHEVM encryption:

✅ Station registration and management
✅ Encrypted pollution reporting (uint32, uint8)
✅ Multiple pollutant types (PM2.5, PM10, SO2, NOx, Ozone, etc.)
✅ Encrypted alert thresholds
✅ Real-time dashboard with statistics
✅ Full FHEVM SDK integration with React hooks
✅ Component-based architecture
✅ Production-ready React application

Quick Start:

cd examples/PrivacyPollutionMonitor
npm install
npm run dev

Visit http://localhost:3001

See examples/PrivacyPollutionMonitor/README-REACT.md for details.

Note: This example also includes a legacy static HTML version (index.html + app.js) for comparison. The React version (src/) demonstrates modern best practices with full SDK integration.

🛠️ Development

Clone and Setup

# Clone the repository
git clone https://github.com/yourusername/fhevm-react-template.git
cd fhevm-react-template

# Install all dependencies (monorepo)
npm install

# Build the SDK
npm run build:sdk

# Run tests
npm test

# Start development mode
npm run dev

Project Scripts

# Build
npm run build              # Build all packages
npm run build:sdk          # Build SDK only
npm run build:examples     # Build all examples

# Development
npm run dev                # Start all in dev mode
npm run dev:sdk            # SDK dev mode with watch
npm run dev:nextjs         # Next.js example

# Testing
npm test                   # Run all tests
npm run test:sdk           # SDK tests only
npm run test:e2e           # End-to-end tests

# Deployment
npm run deploy:contracts   # Deploy to Sepolia
npm run deploy:frontend    # Deploy Next.js to Vercel

# Linting & Formatting
npm run lint               # Lint all packages
npm run format             # Format code

📚 Documentation

Core Concepts

Getting Started - Installation and basic usage
API Reference - Complete API documentation
React Guide - React-specific integration
Vue Guide - Vue-specific integration
TypeScript Guide - Type definitions and usage

Advanced Topics

Encryption Strategies - Best practices for encrypting data
Decryption Flows - EIP-712 signatures and permissions
Contract Integration - Working with FHEVM contracts
Error Handling - Common errors and solutions
Performance - Optimization tips

Examples

React Basic - Minimal React setup for learning SDK basics
Next.js Application - Production-ready confidential monitoring system
Privacy Pollution Monitor - Comprehensive React app with full FHE encryption
Node.js CLI - Command-line encryption and testing tool

🎥 Video Demo

📹 Watch the Demo: [demo.mp4]

The video demonstrates:

SDK installation and setup (< 10 lines)
Full-featured Next.js application integration
React basic example walkthrough
Node.js CLI tool usage
Encryption and decryption flows
Multi-framework support (React, Vue, Node.js)
Design decisions and architecture

🌐 Live Deployment

🚀 Live Demo: https://fhe-pollution-monitor.vercel.app

Example Applications:

Next.js Full Application: Production-ready confidential environmental monitoring system
- Live Demo: https://fhe-pollution-monitor.vercel.app
- Contract: 0xc61a1997F87156dfC96CA14E66fA9E3A02D36358 (Sepolia)
React Basic: Minimal setup for learning
Node.js CLI: Command-line encryption tool

Smart Contract (Sepolia Testnet):

Address: 0xc61a1997F87156dfC96CA14E66fA9E3A02D36358
Network: Sepolia (Chain ID: 11155111)
Explorer: View on Etherscan

💡 Design Decisions

Why Framework-Agnostic Core?

The SDK separates core functionality from framework adapters, allowing:

✅ Use in any JavaScript environment
✅ Consistent behavior across frameworks
✅ Easy testing and maintenance
✅ Smaller bundle sizes (tree-shaking)

Why Wagmi-like API?

Web3 developers are familiar with wagmi's hook-based approach:

✅ Intuitive for React developers
✅ Composable and reusable
✅ Built-in state management
✅ TypeScript-first

Why Monorepo Structure?

Keeps SDK and examples in sync:

✅ Shared dependencies
✅ Easier testing
✅ Consistent versioning
✅ Simplified development workflow

🧩 SDK API Reference

Core Functions

// Client Management
createFhevmClient(config: FhevmConfig): Promise<FhevmClient>
FhevmClient.init(): Promise<void>
FhevmClient.getPublicKey(): Promise<string>

// Encryption
encrypt8(value: number): Promise<Uint8Array>
encrypt16(value: number): Promise<Uint8Array>
encrypt32(value: number): Promise<Uint8Array>
encrypt64(value: bigint): Promise<Uint8Array>
encryptBool(value: boolean): Promise<Uint8Array>
encryptAddress(address: string): Promise<Uint8Array>

// Decryption
userDecrypt(data: Uint8Array, contract: string): Promise<any>
publicDecrypt(data: Uint8Array): Promise<any>
decryptBatch(data: Uint8Array[]): Promise<any[]>

// Contract Helpers
getContract(address: string, abi: any): Contract
getSigner(): Signer
getProvider(): Provider

React Hooks

// Provider
<FhevmProvider config={...}>

// Hooks
useFhevmClient(): FhevmClient
useEncrypt(): { encrypt, isEncrypting, error }
useDecrypt(): { decrypt, isDecrypting, error }
useContract(address, abi): Contract
useFhevmTransaction(contract, method): { send, isLoading, error }

Vue Composables

useFhevmClient(config): FhevmClient
useEncrypt(client): { encrypt, isEncrypting, error }
useDecrypt(client): { decrypt, isDecrypting, error }
useContract(client, address, abi): Contract

🔒 Security Considerations

Client-Side Encryption

✅ Encryption happens in the browser/client
✅ Keys never leave the client
✅ Uses Zama's official fhevmjs library

EIP-712 Signatures

✅ User must sign to decrypt own data
✅ Prevents unauthorized decryption
✅ Domain-specific signatures

Best Practices

// ✅ Good: Encrypt sensitive data
const encrypted = await encrypt(socialSecurityNumber);

// ❌ Bad: Send sensitive data in plain text
await contract.submit(socialSecurityNumber); // NEVER!

// ✅ Good: Verify decryption permissions
if (await hasPermission(address)) {
  const decrypted = await decrypt(data);
}

// ✅ Good: Handle errors properly
try {
  const result = await decrypt(data);
} catch (error) {
  if (error.code === 'SIGNATURE_REQUIRED') {
    // Request user signature
  }
}

🧪 Testing

Unit Tests

npm run test:unit

Integration Tests

npm run test:integration

E2E Tests

npm run test:e2e

Coverage

npm run test:coverage

Target: >80% code coverage

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run tests: npm test
Commit: git commit -m 'feat: add amazing feature'
Push: git push origin feature/amazing-feature
Open a Pull Request

🌟 Roadmap

Phase 1 (Current) ✅

Core SDK with framework-agnostic API
React and Vue adapters
Three comprehensive examples (Next.js, React, Node.js)
Comprehensive documentation

Phase 2 (Q2 2025) 🔜

Angular support
Svelte support
CLI tools for quick scaffolding
Additional example applications

Phase 3 (Q3 2025) 🔜

Performance optimizations
Batch encryption/decryption improvements
Advanced caching strategies
Developer DevTools extension

Phase 4 (Q4 2025) 🔜

Mobile SDK (React Native)
Wallet integrations (MetaMask Snaps)
FHEVM testing utilities
Production-ready templates

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Zama - For pioneering Fully Homomorphic Encryption and the FHEVM platform
fhevmjs - Official Zama FHE library for JavaScript
wagmi - Inspiration for the hook-based API design
Viem - Modern Ethereum library patterns
Community - For feedback and contributions

📞 Support & Resources

FHEVM SDK - Making Confidential dApps Simple 🔐

Built with ❤️ for the Zama Bounty Challenge

Documentation • Examples • API Reference • Contributing

Name		Name	Last commit message	Last commit date
Latest commit History 113 Commits
contracts		contracts
docs		docs
examples		examples
packages		packages
scripts		scripts
templates		templates
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
CONTRIBUTING.md		CONTRIBUTING.md
DEMO_VIDEO.md		DEMO_VIDEO.md
DOCUMENTATION_COMPLETE.md		DOCUMENTATION_COMPLETE.md
INDEX.md		INDEX.md
LICENSE		LICENSE
NEXTJS_EXAMPLE_COMPLETE.md		NEXTJS_EXAMPLE_COMPLETE.md
README.md		README.md
SUBMISSION.md		SUBMISSION.md
TASK_COMPLETION_SUMMARY.md		TASK_COMPLETION_SUMMARY.md
VERIFICATION.md		VERIFICATION.md
demo.mp4		demo.mp4
hardhat.config.js		hardhat.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

FHEVM SDK - Universal Toolkit for Confidential dApps 🔐

✨ Features

🚀 Quick Start

Installation

Basic Usage (< 10 lines!)

🏗️ Architecture

📦 Package Structure

🎯 Complete FHEVM Flow

1. Initialize FHEVM Client

2. Encrypt Inputs

3. Contract Interaction

4. Decrypt Outputs (EIP-712)

🎨 React Integration

Setup Provider

Use Hooks

🎭 Vue Integration

📋 SDK Integration Examples

1. Next.js Full-Featured Application

2. React Basic Example

3. Node.js CLI Tool

4. Privacy Pollution Monitor - React Edition

🛠️ Development

Clone and Setup

Project Scripts

📚 Documentation

Core Concepts

Advanced Topics

Examples

🎥 Video Demo

🌐 Live Deployment

💡 Design Decisions

Why Framework-Agnostic Core?

Why Wagmi-like API?

Why Monorepo Structure?

🧩 SDK API Reference

Core Functions

React Hooks

Vue Composables

🔒 Security Considerations

Client-Side Encryption

EIP-712 Signatures

Best Practices

🧪 Testing

Unit Tests

Integration Tests

E2E Tests

Coverage

🤝 Contributing

Development Workflow

🌟 Roadmap

Phase 1 (Current) ✅

Phase 2 (Q2 2025) 🔜

Phase 3 (Q3 2025) 🔜

Phase 4 (Q4 2025) 🔜

📄 License

🙏 Acknowledgments

📞 Support & Resources

Documentation

Community

Contact

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages