Universal FHEVM SDK

Next-generation FHEVM SDK for building confidential frontends - Framework-agnostic, developer-friendly, and production-ready.

Built for the Zama FHE Bounty Challenge - A universal SDK that makes building confidential applications simple, consistent, and intuitive for all Web3 developers.

🌐 Live Demonstration

GitHub Repository: https://github.com/MacieNienow/fhevm-react-template

Example Application: https://fhe-taxi-dispatch.vercel.app/

Demo Video: demo.mp4 (Download to watch - streaming not available)

The video demonstration showcases the complete SDK integration in a real-world ride-sharing application.

🎯 Overview

This project introduces @fhevm/sdk - a universal, framework-agnostic SDK that wraps all FHEVM dependencies into a single, cohesive package with an intuitive API that Web3 developers already know.

✨ Key Features

🎯 Framework Agnostic: Works with Node.js, Next.js, React, Vue, or any JavaScript environment
📦 All-in-One Package: Single dependency wraps fhevmjs, viem, and all required libraries
🪝 Intuitive API: Familiar hooks-based interface (useFhevm, useEncrypt, usePermit)
⚡ Quick Setup: < 10 lines of code to get started with FHE
🔐 Complete FHE Flow: Initialization → Encryption → Contract Interaction → Decryption
🧩 Modular & Reusable: Clean, composable utilities adaptable to any framework
📚 Comprehensive Docs: Detailed guides, examples, and API reference
🚀 Production Ready: TypeScript, tested, and optimized for real applications

🚀 Quick Start

Installation

npm install @fhevm/sdk
# or
yarn add @fhevm/sdk
# or
pnpm add @fhevm/sdk

Basic Usage (< 10 lines)

import { createFhevmInstance, encryptValue } from '@fhevm/sdk';

// 1. Initialize FHEVM (1 line)
const fhevm = await createFhevmInstance({
  gatewayAddress: '0x79d6742b1Bf62452bfcBC6b137ed4eA1ba459a6B',
  chainId: 11155111,
});

// 2. Encrypt a value (1 line)
const encrypted = await encryptValue(42, 'euint64');

// 3. Use in contract (1 line)
await contract.write.setValue([encrypted.data]);

That's it! 🎉 You're now using FHE encryption in your application.

React Usage

import { useFhevm, useEncrypt } from '@fhevm/sdk/react';

function App() {
  const { isReady } = useFhevm({
    gatewayAddress: '0x79d6742b1Bf62452bfcBC6b137ed4eA1ba459a6B',
    chainId: 11155111,
  });

  const { encrypt } = useEncrypt('euint64');

  if (!isReady) return <div>Loading...</div>;

  return (
    <button onClick={async () => {
      const enc = await encrypt(42);
      await contract.write.setValue([enc.data]);
    }}>
      Encrypt & Submit
    </button>
  );
}

📦 What's Included

Package Structure

fhevm-react-template/
├── packages/
│   └── fhevm-sdk/              # Main SDK Package
│       ├── src/
│       │   ├── core/           # Core logic
│       │   │   └── fhevm.ts    # FhevmClient class
│       │   ├── hooks/          # React hooks
│       │   │   └── useFhevm.ts # React integration
│       │   ├── adapters/       # Framework adapters
│       │   ├── utils/          # Utility functions
│       │   │   ├── encryption.ts
│       │   │   └── decryption.ts
│       │   ├── types/          # Type definitions
│       │   ├── index.ts        # Core exports (framework-agnostic)
│       │   ├── react.ts        # React hooks exports
│       │   ├── client.ts       # FhevmClient class
│       │   ├── instance.ts     # Instance management
│       │   ├── encryption.ts   # Encryption utilities
│       │   ├── permit.ts       # EIP-712 permit signatures
│       │   ├── utils.ts        # Helper functions
│       │   └── types.ts        # TypeScript definitions
│       ├── package.json
│       ├── tsconfig.json
│       └── README.md           # SDK documentation
│
├── templates/                  # Template projects
│   └── nextjs/                 # Next.js template (symlink to examples/nextjs-example)
│
├── examples/                   # Usage examples
│   ├── nextjs-example/         # Next.js 14 + App Router + RainbowKit
│   │   ├── app/                # App Router
│   │   │   ├── page.tsx        # Main demo page
│   │   │   ├── layout.tsx      # Root layout
│   │   │   ├── providers.tsx   # FhevmProvider setup
│   │   │   └── api/            # API routes
│   │   │       └── fhe/        # FHE API endpoints
│   │   ├── components/         # React components
│   │   │   ├── ui/             # UI components
│   │   │   ├── fhe/            # FHE components
│   │   │   └── examples/       # Example components
│   │   ├── lib/                # Library code
│   │   │   ├── fhe/            # FHE integration
│   │   │   └── utils/          # Utility functions
│   │   ├── hooks/              # Custom hooks
│   │   ├── types/              # Type definitions
│   │   └── config/
│   │       └── wagmi.ts        # Wagmi configuration
│   │
│   ├── react-example/          # React 18 + Vite
│   │   ├── src/
│   │   │   ├── App.tsx         # Main app component
│   │   │   └── main.tsx        # Entry point
│   │   ├── package.json
│   │   └── vite.config.ts
│   │
│   ├── nodejs-example/         # Node.js CLI
│   │   ├── index.ts            # Server-side encryption examples
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   └── PrivateTaxiDispatch/    # Real-world React application
│       ├── src/                # React + Vite application
│       │   ├── components/     # React components
│       │   ├── App.tsx         # Main application
│       │   └── main.tsx        # Entry point
│       ├── public/             # Static assets (legacy vanilla JS in public/legacy/)
│       ├── contracts/          # Smart contract source
│       ├── vite.config.ts      # Vite configuration
│       └── package.json        # Dependencies with @fhevm/sdk
│
├── docs/                       # Documentation
│   └── API.md                  # Complete API reference
│
├── demo.mp4                    # Video demonstration
├── README.md                   # This file
├── INTEGRATION_GUIDE.md        # Integration guide
├── LICENSE                     # MIT License
└── package.json                # Monorepo configuration

🎯 SDK Integration Examples

Example 1: Next.js with React Hooks (Recommended)

The nextjs-example demonstrates complete SDK integration with modern React patterns.

Setup Provider (app/providers.tsx):

import { FhevmProvider } from '@fhevm/sdk/react';
import { WagmiProvider } from 'wagmi';
import { RainbowKitProvider } from '@rainbow-me/rainbowkit';

export function Providers({ children }) {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider>
          <FhevmProvider
            config={{
              gatewayAddress: '0x79d6742b1Bf62452bfcBC6b137ed4eA1ba459a6B',
              chainId: 11155111,
              rpcUrl: process.env.NEXT_PUBLIC_SEPOLIA_RPC_URL,
            }}
          >
            {children}
          </FhevmProvider>
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Use in Components (app/page.tsx):

import { useFhevm, useEncrypt } from '@fhevm/sdk/react';
import { useWriteContract } from 'wagmi';

export default function Home() {
  const { isReady } = useFhevm({
    gatewayAddress: '0x79d6742b1Bf62452bfcBC6b137ed4eA1ba459a6B',
    chainId: 11155111,
  });

  const { encrypt, isEncrypting } = useEncrypt('euint64');
  const { writeContract, isPending } = useWriteContract();

  const registerDriver = async (latitude: number, longitude: number) => {
    // Convert coordinates to integers (multiply by 1e6 for precision)
    const latInt = Math.floor(latitude * 1e6);
    const lonInt = Math.floor(longitude * 1e6);

    // Encrypt coordinates using @fhevm/sdk
    const [encLat, encLon] = await Promise.all([
      encrypt(latInt),
      encrypt(lonInt),
    ]);

    // Submit to contract
    await writeContract({
      address: CONTRACT_ADDRESS,
      abi: PRIVATE_TAXI_DISPATCH_ABI,
      functionName: 'registerDriver',
      args: [encLat.data, encLon.data],
    });
  };

  return (
    <button
      onClick={() => registerDriver(40.7128, -74.006)}
      disabled={!isReady || isEncrypting || isPending}
    >
      {isEncrypting || isPending ? 'Processing...' : 'Register Driver'}
    </button>
  );
}

Key Features Demonstrated:

✅ FhevmProvider for global SDK initialization
✅ useFhevm hook for ready state management
✅ useEncrypt hook with loading states
✅ Parallel encryption with Promise.all
✅ Integration with Wagmi and RainbowKit
✅ Proper error handling and UI feedback

Example 2: Private Taxi Dispatch Platform

The PrivateTaxiDispatch example showcases a complete privacy-first ride-sharing application built with React, Vite, and full @fhevm/sdk integration.

Live Demo: https://private-taxi-dispatch.vercel.app/ Contract: 0xd3cc141c38dac488bc1875140e538f0facee7b26 (Sepolia)

Core Features:

🔐 Encrypted Driver Locations: GPS coordinates encrypted with FHE (euint64)
🚗 Confidential Ride Offers: Prices remain private until accepted
⭐ Anonymous Ratings: Driver ratings computed on encrypted data
💼 Identity Protection: Both drivers and passengers remain anonymous
🔗 Smart Contract Integration: Automated matching and payments

Privacy Guarantees:

Driver locations never exposed publicly
Passenger pickup/destination coordinates remain confidential
Fare negotiations through encrypted offers
Rating systems without identity exposure
Zero-knowledge proof implementations

Example 3: Framework-Agnostic Core API

For non-React environments or server-side usage:

import { createFhevmInstance, encryptValue, FhevmClient } from '@fhevm/sdk';

// Option 1: Functional API
const fhevm = await createFhevmInstance({
  gatewayAddress: '0x79d6742b1Bf62452bfcBC6b137ed4eA1ba459a6B',
  chainId: 11155111,
});

const encrypted = await encryptValue(42, 'euint64');
console.log('Encrypted data:', encrypted.hex);

// Option 2: Class-based API
const client = new FhevmClient({
  gatewayAddress: '0x79d6742b1Bf62452bfcBC6b137ed4eA1ba459a6B',
  chainId: 11155111,
});

await client.init();
const encValue = await client.encrypt(100, 'euint32');

Use Cases:

Node.js backend services
CLI tools
Testing frameworks
Vue/Svelte/Angular applications
Serverless functions

🎯 Why This SDK?

Before (Scattered Dependencies)

// Install multiple packages
npm install fhevmjs ethers @fhevm/contracts

// Complex setup
import { createInstance } from 'fhevmjs';
import { ethers } from 'ethers';

const instance = await createInstance({ ... });
const publicKey = await getPublicKeyFromGateway(gatewayAddress);
const encrypted = instance.encrypt64(value);
// ... lots of boilerplate

After (@fhevm/sdk)

// Single package
npm install @fhevm/sdk

// Simple, consistent API
import { createFhevmInstance, encryptValue } from '@fhevm/sdk';

const fhevm = await createFhevmInstance({ gatewayAddress, chainId });
const encrypted = await encryptValue(42, 'euint64');

74% less code, 100% more clarity ✨

🔧 SDK Features

1. Framework Agnostic Core

Works everywhere JavaScript runs:

// Node.js
import { createFhevmInstance, encryptValue } from '@fhevm/sdk';

// Next.js
import { createFhevmInstance } from '@fhevm/sdk';

// React
import { useFhevm, useEncrypt } from '@fhevm/sdk/react';

// Vue (Composition API)
import { createFhevmInstance } from '@fhevm/sdk';

2. Intuitive Hooks (React)

Familiar API for Web3 developers:

const { fhevm, isLoading, error, isReady } = useFhevm(config);
const { encrypt, isEncrypting } = useEncrypt('euint64');
const { createPermitSignature, isCreating } = usePermit(contractAddress, userAddress);

3. Complete FHE Flow

Everything you need in one package:

import { FhevmClient } from '@fhevm/sdk';

const client = new FhevmClient({ gatewayAddress, chainId });
await client.init();

// Encrypt
const encrypted = await client.encrypt(42, 'euint64');

// Create permit for decryption
const permit = await client.createPermit(contractAddress, userAddress, signer);

// Re-encrypt for client-side decryption
const decrypted = await client.reencrypt(handle, contractAddress, userAddress, signature);

4. TypeScript First

Full type safety and IntelliSense:

import type {
  FhevmConfig,
  EncryptedValue,
  PermitSignature,
  EncryptedType
} from '@fhevm/sdk';

const encrypted: EncryptedValue = await encryptValue(42, 'euint64');
//    ^ Fully typed with IntelliSense

5. Batch Operations

Efficient multi-value encryption:

import { encryptBatch } from '@fhevm/sdk';

const encrypted = await encryptBatch([1, 2, 3, 4, 5], 'euint32');
await contract.write.setValues(encrypted.map(e => e.data));

📚 Documentation

Complete API Reference

Core API: packages/fhevm-sdk/README.md
React Hooks: packages/fhevm-sdk/README.md#react-hooks
Examples Directory: examples/

Examples Overview

The examples/ directory contains four comprehensive demonstrations of SDK integration:

Example	Framework	Key Features	Best For
nextjs-example	Next.js 14 + React	FhevmProvider, React hooks, RainbowKit integration	Modern React apps, recommended starting point
PrivateTaxiDispatch	React 18 + Vite	Complete privacy platform, real-world ride-sharing with FHE	Understanding FHE applications, production patterns
react-example	React 18 + Vite	Simple counter, minimal setup	Learning core concepts, quick prototyping
nodejs-example	Node.js	Server-side encryption, CLI tools	Backend services, testing, automation

Each example includes:

Complete source code with comments
Step-by-step setup instructions
Integration patterns and best practices
Real contract interactions on Sepolia testnet

Key Functions

Function	Description	Framework
`createFhevmInstance(config)`	Initialize FHEVM	All
`encryptValue(value, type)`	Encrypt a single value	All
`encryptBatch(values, type)`	Encrypt multiple values	All
`createPermit(...)`	Create EIP-712 permit	All
`reencryptValue(...)`	Re-encrypt for decryption	All
`useFhevm(config)`	Initialize hook	React
`useEncrypt(type)`	Encryption hook	React
`usePermit(...)`	Permit creation hook	React
`FhevmClient`	Class-based API	All
`FhevmProvider`	React context provider	React

Supported Encrypted Types

ebool, euint4, euint8, euint16, euint32, euint64, euint128, euint256, eaddress

🎬 Demo Video

File: demo.mp4 (Download required to watch)

Contents:

Setup (0:00-1:30): Installing @fhevm/sdk and initializing FHEVM
Basic Usage (1:30-3:00): Encrypting values and submitting to contract
React Integration (3:00-5:00): Using hooks in Next.js application
Anonymous Taxi Dispatch Demo (5:00-8:00): Complete walkthrough of example application
Framework Flexibility (8:00-10:00): Showing Vue and Node.js integration
Design Choices (10:00-12:00): Architecture and API design decisions

💡 Design Choices

1. Framework Agnostic Core

Why? FHE encryption is a universal need, not framework-specific.

How? Pure TypeScript core with framework-specific adapters.

2. Intuitive API

Why? Lower barrier to entry for Web3 developers.

How? Familiar patterns and naming conventions.

3. Single Package

Why? Reduce dependency management complexity.

How? Wrap all requirements in one package.

4. TypeScript First

Why? Type safety prevents runtime errors.

How? Complete type definitions for all APIs.

5. Minimal Setup

Why? Faster onboarding = more adoption.

How? Sensible defaults and auto-configuration.

🔗 Project Links

Example Applications

Next.js Demo: See examples/nextjs-example for complete React integration
Private Taxi Dispatch: https://private-taxi-dispatch.vercel.app/
GitHub Repository: https://github.com/MacieNienow/fhevm-react-template
Smart Contracts:
- Next.js Example: 0x9e77F5121215474e473401E9768a517DAFde1f87 (Sepolia)
- Taxi Dispatch: 0xd3cc141c38dac488bc1875140e538f0facee7b26 (Sepolia)

Resources

Zama FHEVM: docs.zama.ai
fhevmjs: github.com/zama-ai/fhevmjs
Sepolia Testnet: sepolia.dev

🛠️ Development

Setup

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

# Install dependencies
npm install

# Build SDK
cd packages/fhevm-sdk
npm run build

Running Examples

Next.js Example (Recommended)

cd examples/nextjs-example
npm install
npm run dev
# Open http://localhost:3000

Features demonstrated:

FhevmProvider setup in Next.js 14 App Router
useFhevm and useEncrypt hooks
Integration with Wagmi and RainbowKit
Encrypted driver registration
Real-time encryption status

Private Taxi Dispatch Example

cd examples/PrivateTaxiDispatch
npm install
npm run dev
# Open http://localhost:3002

Features demonstrated:

Complete privacy-first ride-sharing platform
React 18 + Vite with @fhevm/sdk integration
Driver and passenger workflows with encrypted locations
Encrypted ride offers with confidential fares
Anonymous rating system
Wagmi and wallet integration
Tab-based UI for different user roles

React Example

cd examples/react-example
npm install
npm run dev

Features demonstrated:

Simple encrypted counter
React 18 + Vite setup
Core SDK usage patterns

Node.js Example

cd examples/nodejs-example
npm install
node index.ts

Features demonstrated:

Server-side encryption
CLI integration
Backend service patterns

Testing

# Test SDK
cd packages/fhevm-sdk
npm test

# Type checking
npm run type-check

# Build
npm run build

🤝 Contributing

Contributions welcome! This SDK is designed to be community-driven.

Areas for contribution:

Vue composables (@fhevm/sdk/vue)
Svelte stores (@fhevm/sdk/svelte)
Angular services (@fhevm/sdk/angular)
Additional encrypted types
Performance optimizations

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Zama for FHEVM technology and inspiration
Ethereum Foundation for testnet infrastructure
RainbowKit for wallet integration patterns
Viem for Ethereum interactions
fhevmjs for core FHE functionality

Built for the Zama FHE Bounty Challenge 🏆

Powered by: Zama FHEVM | Network: Sepolia Testnet

Note: This SDK is a bounty submission demonstrating universal FHEVM integration. The example application showcases an anonymous taxi dispatch system with encrypted driver locations and confidential pricing. Suitable for development and testing. Additional security audits recommended for production use.

Name		Name	Last commit message	Last commit date
Latest commit History 97 Commits
docs		docs
examples		examples
packages		packages
scripts		scripts
templates/nextjs		templates/nextjs
.gitignore		.gitignore
.gitmodules		.gitmodules
INTEGRATION_GUIDE.md		INTEGRATION_GUIDE.md
LICENSE		LICENSE
README.md		README.md
SUBMISSION.md		SUBMISSION.md
demo.mp4		demo.mp4
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

Universal FHEVM SDK

🌐 Live Demonstration

🎯 Overview

✨ Key Features

🚀 Quick Start

Installation

Basic Usage (< 10 lines)

React Usage

📦 What's Included

Package Structure

🎯 SDK Integration Examples

Example 1: Next.js with React Hooks (Recommended)

Example 2: Private Taxi Dispatch Platform

Example 3: Framework-Agnostic Core API

🎯 Why This SDK?

Before (Scattered Dependencies)

After (@fhevm/sdk)

🔧 SDK Features

1. Framework Agnostic Core

2. Intuitive Hooks (React)

3. Complete FHE Flow

4. TypeScript First

5. Batch Operations

📚 Documentation

Complete API Reference

Examples Overview

Key Functions

Supported Encrypted Types

🎬 Demo Video

💡 Design Choices

1. Framework Agnostic Core

2. Intuitive API

3. Single Package

4. TypeScript First

5. Minimal Setup

🔗 Project Links

Example Applications

Resources

🛠️ Development

Setup

Running Examples

Next.js Example (Recommended)

Private Taxi Dispatch Example

React Example

Node.js Example

Testing

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages