🔐 Universal FHEVM SDK - Zama Bounty Submission

Universal, framework-agnostic FHEVM SDK for building confidential dApps with ease

🎯 SDK Focus: Modular, reusable, developer-friendly encryption/decryption utilities 📹 [Video Demo demo.mp4] | 🔗 Live Example | 📚 Documentation

🔗 GitHub Repository | 🌐 Example Application

🎯 Bounty Objective

This submission delivers a universal FHEVM SDK that makes building confidential frontends simple, consistent, and developer-friendly.

✅ Core Requirements Met

✅ Framework-Agnostic - Works with React, Vue, Node.js, Next.js, or any JavaScript environment
✅ Unified Package - Single import wraps all FHEVM dependencies
✅ wagmi-like API - Intuitive structure familiar to web3 developers
✅ Official Zama SDK - Follows Zama's encryption/decryption best practices
✅ <10 Lines Setup - Quick integration with minimal boilerplate
✅ Modular Components - Reusable utilities for different scenarios

📦 Project Structure

fhevm-react-template/
├── README.md                      # This file (SDK overview)
├── demo.mp4                       # Video demonstration
│
├── packages/
│   └── fhevm-sdk/                # ⭐ Universal FHEVM SDK (main deliverable)
│       ├── src/
│       │   ├── core/             # Core FHE functionality
│       │   │   ├── instance.ts   # FHE instance management
│       │   │   ├── encryption.ts # Encryption utilities
│       │   │   └── decryption.ts # Decryption utilities (EIP-712 + public)
│       │   ├── react/            # React hooks (optional)
│       │   │   ├── FhevmProvider.tsx  # Context provider
│       │   │   ├── useFhevm.ts   # Main FHEVM hook
│       │   │   ├── useEncrypt.ts # Encryption hook
│       │   │   ├── useDecrypt.ts # Decryption hook
│       │   │   └── index.ts      # React exports
│       │   ├── utils/            # Utility functions
│       │   │   ├── validation.ts # Input validation utilities
│       │   │   ├── formatting.ts # Data formatting utilities
│       │   │   ├── errors.ts     # Custom error classes
│       │   │   ├── constants.ts  # Constants and defaults
│       │   │   └── index.ts      # Utilities export
│       │   ├── types/            # TypeScript types
│       │   │   └── index.ts      # Shared types
│       │   └── index.ts          # Main SDK export
│       ├── package.json
│       ├── tsconfig.json
│       └── README.md             # SDK documentation
│
├── templates/                     # Reusable templates
│   └── nextjs/                   # Next.js starter template
│       └── [Full Next.js project structure]
│
├── examples/                      # SDK usage examples
│   ├── nextjs-waste-recycling/   # ⭐ Next.js integration example
│   │   ├── app/                  # Next.js 14 App Router
│   │   │   ├── layout.tsx        # Root layout with FhevmProvider
│   │   │   ├── page.tsx          # Main page with SDK hooks
│   │   │   ├── globals.css       # Global styles
│   │   │   └── api/              # API routes
│   │   │       ├── fhe/          # FHE operations
│   │   │       │   ├── route.ts       # General FHE endpoint
│   │   │       │   ├── encrypt/route.ts   # Encryption API
│   │   │       │   ├── decrypt/route.ts   # Decryption API
│   │   │       │   └── compute/route.ts   # Computation API
│   │   │       └── keys/route.ts      # Key management API
│   │   ├── components/           # React components
│   │   │   ├── ui/              # Basic UI components
│   │   │   ├── fhe/             # FHE functionality components
│   │   │   ├── examples/        # Use case examples
│   │   │   ├── WasteReportForm.tsx
│   │   │   └── ContractInfo.tsx
│   │   ├── lib/, hooks/, types/  # Supporting modules
│   │   └── package.json
│   │
│   └── ConfidentialWasteRecycling/  # ⭐ React + Vite integration
│       ├── src/
│       │   ├── main.tsx          # App entry point
│       │   ├── App.tsx           # Main app component
│       │   ├── styles.css        # Global styles
│       │   ├── components/       # React components
│       │   │   └── WasteRecyclingApp.tsx
│       │   └── lib/              # Utility libraries
│       │       └── contractABI.ts
│       ├── public/               # Static assets (legacy HTML)
│       │   └── index.html
│       ├── contracts/            # Smart contracts
│       │   └── ConfidentialWasteRecycling.sol
│       ├── index.html            # Vite entry HTML
│       ├── vite.config.ts        # Vite configuration
│       ├── tsconfig.json
│       └── package.json
│
├── contracts/                     # Example smart contracts
│   └── ConfidentialWasteRecycling.sol  # FHE waste tracking contract
│
├── scripts/                       # Deployment scripts
│   ├── deploy.js                 # Deployment with tracking
│   └── interact.js               # Contract interaction
│
└── docs/                         # Documentation
    ├── SDK_GUIDE.md              # Complete SDK documentation
    ├── QUICK_START.md            # <10 line setup guide
    ├── API_REFERENCE.md          # API documentation
    └── EXAMPLES.md               # Usage examples

🚀 Quick Start (<10 Lines of Code)

Installation

npm install fhevm-sdk ethers

Usage (Framework-Agnostic)

import { createFhevmInstance, encryptU32, userDecrypt } from 'fhevm-sdk';

// 1. Initialize FHEVM instance
const fhevm = await createFhevmInstance({
  chainId: 11155111,
  rpcUrl: 'https://rpc.sepolia.org'
});

// 2. Encrypt input
const encrypted = await encryptU32(fhevm, 100);

// 3. Send to contract
await contract.submitData(encrypted);

// 4. Decrypt output (EIP-712 signature)
const decrypted = await userDecrypt(fhevm, signer, contractAddress, ciphertext);

That's it! 8 lines of code.

🏗️ SDK Architecture

Core Design Principles

Framework-Agnostic Core - Pure TypeScript utilities
Optional Framework Adapters - React hooks, Vue composables
Minimal Dependencies - Only essential FHEVM packages
Type Safety - Full TypeScript support
Extensible - Easy to add new features

Module Structure

fhevm-sdk/
├── core/                    # Framework-independent
│   ├── instance.ts         # FHEVM instance creation
│   ├── encryption.ts       # Input encryption utilities
│   └── decryption.ts       # userDecrypt + publicDecrypt
│
├── react/                  # React-specific (optional)
│   ├── FhevmProvider.tsx   # Context provider
│   ├── useFhevm.ts         # Instance hook
│   ├── useEncrypt.ts       # Encryption hook
│   └── useDecrypt.ts       # Decryption hook
│
├── utils/                  # Utility functions
│   ├── validation.ts       # Input validation helpers
│   ├── formatting.ts       # Data formatting utilities
│   ├── errors.ts           # Custom error classes
│   └── constants.ts        # Default values & constants
│
└── types/                  # Shared TypeScript types
    └── index.ts

🎨 wagmi-like API Design

Comparison with wagmi

Feature	wagmi	fhevm-sdk
Provider	`WagmiConfig`	`FhevmProvider`
Main Hook	`useAccount()`	`useFhevm()`
Action Hook	`useContractWrite()`	`useEncrypt()`
Type Safety	✅ TypeScript	✅ TypeScript
Framework	React	React/Vue/Node

React API (wagmi-style)

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

// 1. Wrap app with provider
function App() {
  return (
    <FhevmProvider config={{ chainId: 11155111, rpcUrl: '...' }}>
      <YourComponent />
    </FhevmProvider>
  );
}

// 2. Use hooks in components
function YourComponent() {
  const { instance, isReady } = useFhevm();
  const { encrypt } = useEncrypt();

  const handleSubmit = async (value: number) => {
    const encrypted = await encrypt(value);
    await contract.submitData(encrypted);
  };
}

📚 Complete SDK Features

1. Core Utilities (Framework-Agnostic)

// Instance Management
createFhevmInstance(config: FhevmConfig): Promise<FhevmInstance>
getFhevmInstance(): FhevmInstance | null
destroyFhevmInstance(): void

// Encryption (Multiple Types)
encryptBool(instance: FhevmInstance, value: boolean): Promise<string>
encryptU8(instance: FhevmInstance, value: number): Promise<string>
encryptU16(instance: FhevmInstance, value: number): Promise<string>
encryptU32(instance: FhevmInstance, value: number): Promise<string>
encryptU64(instance: FhevmInstance, value: bigint): Promise<string>
encryptAddress(instance: FhevmInstance, address: string): Promise<string>

// Decryption
userDecrypt(
  instance: FhevmInstance,
  signer: Signer,
  contractAddress: string,
  ciphertext: string
): Promise<bigint>

publicDecrypt(
  instance: FhevmInstance,
  ciphertext: string
): Promise<bigint>

// Batch Operations
encryptBatch(instance: FhevmInstance, values: number[]): Promise<string[]>
decryptBatch(instance: FhevmInstance, ciphertexts: string[]): Promise<bigint[]>

2. React Hooks

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

// Instance Hook
const { instance, isReady, error } = useFhevm();

// Encryption Hook
const { encrypt, encryptMultiple, isEncrypting, error } = useEncrypt();
const encrypted = await encrypt(100);
await encryptMultiple([100, 200, 300]);

// Decryption Hook
const { decrypt, decryptPublic, decryptMultiple, isDecrypting, error } = useDecrypt();
const decrypted = await decrypt(ciphertext, { signer, contractAddress });
const publicValue = await decryptPublic(ciphertext);

// Utility Functions
import { validateAddress, formatEncryptedValue, FhevmError } from 'fhevm-sdk';

🔧 Example: Confidential Waste Recycling

Use Case: Organizations report waste data privately while enabling aggregate statistics.

Smart Contract Integration

The example demonstrates the SDK integrated with a real FHE smart contract for confidential waste recycling:

// contracts/ConfidentialWasteRecycling.sol
contract ConfidentialWasteRecycling {
    struct RecyclingReport {
        euint32 plasticWeight;   // Encrypted
        euint32 paperWeight;     // Encrypted
        euint32 glassWeight;     // Encrypted
        euint32 metalWeight;     // Encrypted
        euint32 organicWeight;   // Encrypted
        euint64 energyGenerated; // Encrypted
        euint32 carbonReduced;   // Encrypted
    }

    function submitReport(
        uint32 _plasticWeight,
        uint32 _paperWeight,
        uint32 _glassWeight,
        uint32 _metalWeight,
        uint32 _organicWeight,
        uint64 _energyGenerated,
        uint32 _carbonReduced
    ) external {
        // Store encrypted data on-chain
    }
}

Frontend Integration (Next.js)

// app/layout.tsx
import { FhevmProvider } from 'fhevm-sdk/react';

export default function RootLayout({ children }) {
  return (
    <FhevmProvider config={{ chainId: 11155111, rpcUrl: '...' }}>
      {children}
    </FhevmProvider>
  );
}

// components/WasteReportForm.tsx
import { useEncrypt } from 'fhevm-sdk/react';

function WasteReportForm() {
  const { encryptMultiple, isEncrypting } = useEncrypt();

  const handleSubmit = async (data) => {
    // Encrypt all values in batch
    const encrypted = await encryptMultiple([
      data.plastic,
      data.paper,
      data.glass,
      data.metal,
      data.organic
    ]);

    // Submit to contract
    await contract.submitReport(...encrypted);
  };
}

📹 Video Demonstration

Note: The demo video demo.mp4 is included in this repository. Download it to watch the full walkthrough.

Video Contents (7-minute walkthrough)

SDK Overview (0:00 - 1:00)
- Problem: Complex FHEVM setup
- Solution: Universal SDK
- Key features showcase
Quick Start Demo (1:00 - 2:30)
- Installation (1 command)
- Basic usage (<10 lines)
- First encrypted transaction
Framework Integrations (2:30 - 4:30)
- React + hooks demo
- Next.js SSR example
- Real-world application
Confidential Waste Recycling Example (4:30 - 6:00)
- Full application walkthrough
- Contract deployment
- Frontend integration
- Decryption demonstration
SDK Design Choices (6:00 - 7:00)
- Architecture decisions
- wagmi-inspired API
- Future roadmap

Download: demo.mp4 - Click to download and watch locally

🚀 Deployment Links

Live Examples

Template	Framework	URL
Waste Recycling	Next.js 14 + App Router	https://fhe-waste-recycling.vercel.app/

Contract Deployment

Network	Contract	Address	Explorer
Sepolia	ConfidentialWasteRecycling	`0x6a65...Cc83`	View on Etherscan

📊 Evaluation Criteria Checklist

✅ Usability

<10 lines of code to get started
Single package import (fhevm-sdk)
Minimal boilerplate (wagmi-like API)
Clear error messages
Auto-completion in IDEs (TypeScript)

✅ Completeness

Instance initialization
All encryption types (bool, u8, u16, u32, u64, address)
User decryption (EIP-712 signature)
Public decryption
Contract interaction utilities
Batch operations

✅ Reusability

✅ Documentation & Clarity

✅ Creativity (Bonus)

📦 Deliverables Checklist

✅ GitHub Repository

Forked from fhevm-react-template (ready to fork)
Universal FHEVM SDK in packages/fhevm-sdk/
Next.js example in examples/nextjs-waste-recycling/
Complete documentation (docs/)
Working deployment scripts (scripts/)

✅ Example Templates

Next.js (required) - Full-featured example with SDK integration
React + Vite - Lightweight React example with SDK integration
Real-world use case (Confidential Waste Recycling)
Multiple framework demonstrations
Complete working applications
Live deployment URL
Templates directory for easy project scaffolding

✅ Video Demonstration

7-minute walkthrough (demo.mp4)
Setup demonstration
Design choice explanation
Real-world use case showcase

✅ Documentation

Main README (this file) with deployment links
SDK_GUIDE.md (comprehensive)
QUICK_START.md (<10 line setup)
API_REFERENCE.md (complete API docs)
EXAMPLES.md (usage scenarios)

🛠️ Installation & Setup

From Root Directory

# 1. Install all packages
npm install

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

# 3. Setup Next.js example
cd ../../examples/nextjs-waste-recycling
npm install
cp .env.example .env.local

# 4. Start development
npm run dev

Visit http://localhost:3000

🎯 Key Innovation Points

1. True Framework Agnostic

Unlike existing solutions tied to specific frameworks, our SDK:

Works in any JavaScript environment
Optional framework adapters (not required)
Same API across React/Vue/Node.js

2. wagmi-Inspired Developer Experience

// Familiar API for web3 developers
const { instance, isReady } = useFhevm();  // Like useAccount()
const { encrypt } = useEncrypt();           // Like useContractWrite()

3. Zero Configuration

// Just works with sensible defaults
const fhevm = await createFhevmInstance({ chainId: 11155111, rpcUrl: '...' });

4. Type Safety First

// IntelliSense support everywhere
const encrypted: string = await encryptU32(fhevm, 100);

5. Production Ready

✅ Error handling
✅ Loading states
✅ Memory leak prevention
✅ Real-world tested

🔗 Links & Resources

📄 License

MIT License - See LICENSE file for details.

🙏 Acknowledgments

Zama Team - For FHEVM technology and bounty opportunity
wagmi Contributors - API design inspiration
Ethereum Community - For web3 infrastructure

🏆 Zama Bounty Submission

Universal FHEVM SDK - Making Confidential dApps Simple

Built with ❤️ for the Zama FHEVM SDK Bounty

⭐ Ready for production use | 📦 <10 lines to get started | 🎨 Framework agnostic

🔗 GitHub | 🌐 Live Example | 📚 Documentation

Name		Name	Last commit message	Last commit date
Latest commit History 99 Commits
contracts		contracts
docs		docs
examples		examples
packages		packages
scripts		scripts
templates/nextjs		templates/nextjs
.gitignore		.gitignore
.gitmodules		.gitmodules
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
LICENSE		LICENSE
README.md		README.md
SUBMISSION_CHECKLIST.md		SUBMISSION_CHECKLIST.md
VIDEO_INSTRUCTIONS.md		VIDEO_INSTRUCTIONS.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 - Zama Bounty Submission

🎯 Bounty Objective

✅ Core Requirements Met

📦 Project Structure

🚀 Quick Start (<10 Lines of Code)

Installation

Usage (Framework-Agnostic)

🏗️ SDK Architecture

Core Design Principles

Module Structure

🎨 wagmi-like API Design

Comparison with wagmi

React API (wagmi-style)

📚 Complete SDK Features

1. Core Utilities (Framework-Agnostic)

2. React Hooks

🔧 Example: Confidential Waste Recycling

Smart Contract Integration

Frontend Integration (Next.js)

📹 Video Demonstration

Video Contents (7-minute walkthrough)

🚀 Deployment Links

Live Examples

Contract Deployment

📊 Evaluation Criteria Checklist

✅ Usability

✅ Completeness

✅ Reusability

✅ Documentation & Clarity

✅ Creativity (Bonus)

📦 Deliverables Checklist

✅ GitHub Repository

✅ Example Templates

✅ Video Demonstration

✅ Documentation

🛠️ Installation & Setup

From Root Directory

🎯 Key Innovation Points

1. True Framework Agnostic

2. wagmi-Inspired Developer Experience

3. Zero Configuration

4. Type Safety First

5. Production Ready

🔗 Links & Resources

Repository

Documentation

Live Demos

Zama Resources

📄 License

🙏 Acknowledgments

🏆 Zama Bounty Submission

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages