🔐 Universal FHEVM SDK

🌐 Live Examples

🌍 Languages / Langues / 语言

📐 Architecture Overview

SDK Architecture

┌──────────────────────────────────────────────────────────────────────┐
│ Universal FHEVM SDK │
│ packages/fhevm-sdk/ │
└──────────────────────────────────────────────────────────────────────┘
 │
 ┌───────────────────────┼───────────────────────┐
 │ │ │
 ┌─────▼─────┐ ┌───────▼───────┐ ┌───────▼───────┐
 │ CORE │ │ ADAPTERS │ │ SHOWCASES │
 │src/core/ │ │src/adapters/ │ │ packages/ │
 └─────┬─────┘ └───────┬───────┘ └───────┬───────┘
 │ │ │
 ┌─────┴─────────────────────────────────────────────────────┐
 │ │
 │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
 │ │fhevm.ts │ │contracts.│ │index.ts │ │
 │ │ │ │ts │ │(exports) │ │
 │ │-initialize│ │ │ └──────────┘ │
 │ │-createEnc│ │-FhevmCon │ │
 │ │-decrypt │ │tract │ │
 │ │-publicDec│ └──────────┘ │
 │ │-test/ │ │
 │ └──────────┘ │
 │ │
 └─────────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────┐
 │ │
 ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
 │ react.ts │ │ vue.ts │ │ node.ts │
 │ │ │ │ │ │
 │useWallet │ │useWalletVue│ │FhevmNode │
 │useFhevm │ │useFhevmVue │ │(class) │
 │useContract│ │useContract │ └───────────┘
 │useEncrypt │ │useEncrypt │
 │useDecrypt │ │useDecrypt │
 │useFhevmOps│ │useFhevmOps │
 └───────────┘ └───────────┘
 
 ┌───────────────────────────────────────┐
 │ │
 ┌─────▼─────────┐ ┌─────▼─────────┐ ┌─────▼─────────┐
 │react-showcase │ │nextjs-showcase │ │ vue-showcase │
 │ │ │ │ │ │
 │App.tsx │ │page.tsx │ │App.vue │
 │FheCounter │ │components/ │ │components/ │
 │FheRatings │ │FHECounter │ │FHECounter │
 │FheVoting │ │FHERatings │ │FHERatings │
 │ │ │SimpleVoting │ │SimpleVoting │
 │ │ │test/ │ │test/ │
 └───────────────┘ └────────────────┘ └───────────────┘
 
 ┌─────────────────────────────────────────┐
 │ node-showcase │
 │ │
 │ index.ts server.ts explorer.ts │
 │ counter.ts voting.ts ratings.ts │
 │ │
 └─────────────────────────────────────────┘

Data Flow Architecture

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ react-showcase │ │ vue-showcase │ │ node-showcase │
│ │ │ │ │ │
│ App.tsx │ │ App.vue │ │ index.ts │
│ FheCounter.tsx │ │ FheCounter.vue │ │ counter.ts │
│ FheRatings.tsx │ │ FheRatings.vue │ │ voting.ts │
│ FheVoting.tsx │ │ FheVoting.vue │ │ ratings.ts │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
 │ │ │
 │ import { useWallet, │ import { useWalletVue,│ import { FhevmNode
 │ useFhevm, │ useFhevmVue } │ } from
 │ useEncrypt, │ } from │ '@fhevm-sdk'
 │ useDecrypt } │ '@fhevm-sdk' │
 │ from '@fhevm-sdk' │ │
 │ │ │
 └────────────────────────┼────────────────────────┘
 │
 ┌─────────────▼─────────────┐
 │ @fhevm-sdk/src/ │
 │ │
 │ ┌─────────────────────┐ │
 │ │ adapters/react.ts │ │
 │ │ adapters/vue.ts │ │
 │ │ adapters/node.ts │ │
 │ └──────────┬──────────┘ │
 │ │ │
 │ ┌──────────▼──────────┐ │
 │ │ core/index.ts │ │
 │ │ core/fhevm.ts │ │
 │ │ core/contracts.ts │ │
 │ └──────────┬──────────┘ │
 └──────────────┼────────────┘
 │
 ┌──────────────▼──────────────┐
 │ Zama Relayer SDK │
 │ (@zama-fhe/relayer-sdk) │
 │ │
 │ ┌──────────────────────┐ │
 │ │ createInstance() │ │
 │ │ createEncryptedInput │ │
 │ │ decryptValue() │ │
 │ │ publicDecrypt() │ │
 │ └──────────────────────┘ │
 └─────────────────────────────┘

🏗️ Project Structure

fhevm-react-template/
├── packages/
│ ├── fhevm-sdk/ # Universal FHEVM SDK Core
│ │ ├── src/
│ │ │ ├── core/ # Core FHEVM functionality
│ │ │ │ ├── fhevm.ts # FHEVM client initialization
│ │ │ │ ├── encryption.ts # Encryption operations
│ │ │ │ └── decryption.ts # Decryption operations
│ │ │ └── adapters/ # Framework-specific adapters
│ │ │ ├── react.ts # React hooks (re-exports)
│ │ │ ├── useWallet.ts # Wallet connection hook
│ │ │ ├── useFhevm.ts # FHEVM instance hook
│ │ │ ├── useContract.ts # Contract interaction hook
│ │ │ ├── useEncrypt.ts # Encryption hook
│ │ │ ├── useDecrypt.ts # Decryption hook
│ │ │ ├── useFhevmOperations.ts # Combined operations hook
│ │ │ ├── vue.ts # Vue composables
│ │ │ └── node.ts # Node.js class adapter
│ │ └── dist/ # Built output
│ │
│ ├── react-showcase/ # React Example
│ │ ├── src/
│ │ │ ├── App.tsx # Main app (uses adapters)
│ │ │ └── components/
│ │ │ ├── FheCounter.tsx # Uses useEncrypt, useDecrypt
│ │ │ ├── FheRatings.tsx # Uses useEncrypt, useDecrypt
│ │ │ └── FheVoting.tsx # Uses useEncrypt
│ │
│ ├── nextjs-showcase/ # Next.js Example
│ │ ├── app/
│ │ │ └── page.tsx # Main page (uses adapters)
│ │ └── components/ # Same as React showcase
│ │
│ ├── vue-showcase/ # Vue Example
│ │ ├── src/
│ │ │ ├── App.vue # Main app (uses composables)
│ │ │ └── components/
│ │ │ ├── FheCounter.vue # Uses useEncryptVue, useDecryptVue
│ │ │ ├── FheRatings.vue # Uses useEncryptVue, useDecryptVue
│ │ │ └── FheVoting.vue # Uses useEncryptVue
│ │
│ ├── node-showcase/ # Node.js Example
│ │ ├── src/
│ │ │ ├── index.ts # Main entry (uses FhevmNode)
│ │ │ ├── counter.ts # Counter demo
│ │ │ ├── voting.ts # Voting demo
│ │ │ └── ratings.ts # Ratings demo
│ │
│ └── hardhat/ # Smart Contracts
│ ├── contracts/ # Solidity contracts
│ └── deploy/ # Deployment scripts
│
├── pnpm-workspace.yaml # Monorepo configuration
└── README.md # This file

🔧 Adapter System

How Adapters Work

React/Next.js Adapters

import { useWallet, useFhevm, useEncrypt, useDecrypt, useContract } from '@fhevm-sdk';
function MyComponent() {
 // Wallet connection
 const { address, isConnected, chainId, connect, disconnect } = useWallet();
 
 // FHEVM instance
 const { status, initialize, isInitialized } = useFhevm();
 
 // Contract interaction
 const { contract, isReady } = useContract(contractAddress, abi);
 
 // Encryption
 const { encrypt, isEncrypting, error: encryptError } = useEncrypt();
 
 // Decryption (FHEVM 0.9.0)
 const { decrypt, publicDecrypt, decryptMultiple, isDecrypting, error: decryptError } = useDecrypt();
 
 // Usage example
 const handleIncrement = async () => {
 const encrypted = await encrypt(contractAddress, address, 1);
 await contract.increment(encrypted.encryptedData, encrypted.proof);
 };
 
 // Self-relaying decryption example (for voting)
 const handleTallyReveal = async (sessionId) => {
 const tx = await contract.requestTallyReveal(sessionId);
 const receipt = await tx.wait();
 const event = receipt.logs.find(log => {
 const parsed = contract.interface.parseLog(log);
 return parsed?.name === 'TallyRevealRequested';
 });
 const { yesVotesHandle, noVotesHandle } = contract.interface.parseLog(event).args;
 const { cleartexts, decryptionProof, values } = await decryptMultiple(
 contractAddress,
 signer,
 [yesVotesHandle, noVotesHandle]
 );
 await contract.resolveTallyCallback(sessionId, cleartexts, decryptionProof);
 };
 
 return (
 <div>
 {!isConnected && <button onClick={connect}>Connect Wallet</button>}
 {isConnected && <button onClick={handleIncrement}>Increment</button>}
 </div>
 );
}

Vue Adapters

<script setup lang="ts">
import { useWalletVue, useFhevmVue, useEncryptVue, useDecryptVue } from '@fhevm-sdk';
// Wallet connection
const { address, isConnected, chainId, connect, disconnect } = useWalletVue();
// FHEVM instance
const { status, initialize, isInitialized } = useFhevmVue();
// Encryption
const { encrypt, isEncrypting, error: encryptError } = useEncryptVue();
// Decryption (FHEVM 0.9.0)
const { decrypt, publicDecrypt, decryptMultiple, isDecrypting, error: decryptError } = useDecryptVue();
// Usage example
const handleIncrement = async () => {
 const encrypted = await encrypt.value(contractAddress, address.value, 1);
 await contract.increment(encrypted.encryptedData, encrypted.proof);
};
</script>
<template>
 <div>
 <button v-if="!isConnected" @click="connect">Connect Wallet</button>
 <button v-if="isConnected" @click="handleIncrement">Increment</button>
 </div>
</template>

Node.js Adapter

import { FhevmNode } from '@fhevm-sdk';
const fhevm = new FhevmNode({
 rpcUrl: 'https://sepolia.infura.io/v3/YOUR_KEY',
 privateKey: 'YOUR_PRIVATE_KEY',
 chainId: 11155111
});
await fhevm.initialize();
// Encrypt
const encrypted = await fhevm.encrypt(contractAddress, walletAddress, 1);
// Decrypt
const decrypted = await fhevm.decrypt(handle, contractAddress);
// Public decrypt
const publicDecrypted = await fhevm.publicDecrypt(handle);
// Execute transaction
const contract = fhevm.createContract(contractAddress, abi);
await fhevm.executeEncryptedTransaction(contract, 'increment', encrypted);

🚀 Quick Start

Option 1: NPX Packages (Recommended)

# React
npx create-fhevm-react my-app
cd my-app
npm install && npm start
# Next.js
npx create-fhevm-nextjs my-app
cd my-app
npm install && npm run dev
# Vue 
npx create-fhevm-vue my-app
cd my-app
npm install && npm run dev

Option 2: Development Environment

# 1. Clone repository
git clone https://github.com/your-username/fhevm-react-template.git
cd fhevm-react-template
# 2. Install dependencies
pnpm install
# 3. Build SDK
pnpm sdk:build
# 4. Run showcase
pnpm --filter react-showcase start # React on :3000
pnpm --filter nextjs-showcase dev # Next.js on :3001
pnpm --filter vue-showcase dev # Vue on :3003
pnpm --filter node-showcase explorer # Interactive CLI mode (recommended)
pnpm --filter node-showcase start # HTTP server mode
pnpm --filter node-showcase cli # Non-interactive CLI mode

HTTP Server Mode

# Start the HTTP server
pnpm start
# Server runs on http://localhost:3001
# Available endpoints:
# - GET / - List available endpoints
# - GET /health - Health check
# - GET /config - Get FHEVM configuration
# - POST /counter - Run counter demo
# - POST /voting - Run voting demo
# - POST /ratings - Run ratings demo
# - POST /run-all - Run all demos

# Run counter demo
Invoke-RestMethod -Uri http://localhost:3001/counter -Method POST
# Run voting demo
Invoke-RestMethod -Uri http://localhost:3001/voting -Method POST
# Get configuration
Invoke-RestMethod -Uri http://localhost:3001/config -Method GET

Non-Interactive CLI Mode

# Run all demos at once
pnpm cli
# Output includes:
# - Counter demo: Increment → Decrement → Decrypt
# - Voting demo: Create session → Vote
# - Ratings demo: Submit rating → Public decrypt stats

🛠️ Development

# Interactive CLI mode (recommended for testing)
pnpm explorer
# HTTP server mode
pnpm start
# Non-interactive CLI mode
pnpm cli
# Development mode (watch HTTP server)
pnpm dev
# Build TypeScript
pnpm build

🎯 FHEVM Explorer - Interactive Demo Experience

What the Explorer Does

Key Features

Example Session Flow

🌐 Welcome to FHEVM Explorer!
Universal FHEVM SDK - Interactive Demo Experience
 Explore the world of confidential computing on blockchain
 Experience encrypted operations with guided demos
✅ FHEVM environment ready!
 Wallet: 0xb8c81a641A4A4C47d11e5464C77EdcB9737784CC
 Balance: 0.042681970725989092 ETH
 Network: Sepolia (11155111)
? Choose your FHEVM demo:
❯ 🔢 Counter Demo - Increment/Decrement Operations
 🗳️ Voting Demo - Encrypted Voting System
 ⭐ Ratings Demo - Review Cards with Encrypted Ratings
 🔍 Test Mode - Verify Setup Only
 🎯 Run All Demos
 ❌ Exit Explorer

How to Use

# Navigate to node-showcase
cd packages/node-showcase
# Start the interactive explorer
pnpm explorer

📚 Showcase Documentation

🧪 Testing

Running Tests

# Run all showcase tests
pnpm test:showcases
# Run tests for a specific showcase
pnpm test:react # React showcase tests
pnpm test:nextjs # Next.js showcase tests
pnpm test:vue # Vue showcase tests
# Run from a specific showcase directory
cd packages/react-showcase && pnpm test
cd packages/nextjs-showcase && pnpm test
cd packages/vue-showcase && pnpm test
# Run Hardhat tests (includes all showcase tests)
pnpm hardhat:test

🏆 Key Features

✅ Framework-Agnostic Core

✅ Wagmi-like API

✅ TypeScript Support

✅ Real FHEVM Operations (0.9.0)

✅ Multiple Demo Scenarios (FHEVM 0.9.0)

🎯 Usage Examples

React Component

import { useWallet, useFhevm, useEncrypt, useDecrypt } from '@fhevm-sdk';
export default function FheCounter() {
 const { address, isConnected, connect } = useWallet();
 const { status, initialize } = useFhevm();
 const { encrypt } = useEncrypt();
 const { decrypt } = useDecrypt();
 
 useEffect(() => {
 if (isConnected && status === 'idle') {
 initialize();
 }
 }, [isConnected, status, initialize]);
 
 const handleIncrement = async () => {
 const encrypted = await encrypt(contractAddress, address, 1);
 // Execute transaction...
 };
 
 return <div>...</div>;
}

Vue Component

<script setup lang="ts">
import { useWalletVue, useFhevmVue, useEncryptVue } from '@fhevm-sdk';

const { address, isConnected, connect } = useWalletVue();
const { status, initialize } = useFhevmVue();
const { encrypt } = useEncryptVue();

watch(() => isConnected.value, (newVal) => {
 if (newVal && status.value === 'idle') {
 initialize();
 }
});
</script>
<template>
 <div>...</div>
</template>

Node.js Script

import { FhevmNode } from '@fhevm-sdk';
async function main() {
 const fhevm = new FhevmNode({ rpcUrl, privateKey, chainId });
await fhevm.initialize();
 const encrypted = await fhevm.encrypt(contractAddress, walletAddress, 1);
 const contract = fhevm.createContract(contractAddress, abi);
 await fhevm.executeEncryptedTransaction(contract, 'increment', encrypted);
}

📋 Requirements

🔗 Related Documentation

📝 License

🤝 Contributing