🔧 Universal FHEVM SDK

A framework-agnostic frontend toolkit that helps developers run confidential dApps with ease. Built for the Zama Bounty Program - Universal FHEVM SDK Challenge.

📦 Install: pnpm add @chriswilder/fhevm-sdk | 🔗 npm: @chriswilder/fhevm-sdk

🚀 Quick Start

# Install the SDK
pnpm add @chriswilder/fhevm-sdk

# Import in your project
import { useWallet, useFhevm, useContract, useDecrypt, useEncrypt } from '@chriswilder/fhevm-sdk'

✨ Features

• ✅ Framework-agnostic - Works in React, Next.js, Vue, Node.js
• ✅ Real FHEVM functionality - EIP-712 decryption, encryption, contract interactions
• ✅ Wagmi-like API - Intuitive for web3 developers
• ✅ TypeScript support - Full type safety
• ✅ Clean architecture - Modular and extensible

🏗️ Architecture

fhevm-sdk/
├── src/
│   ├── core/                    # Framework-agnostic core
│   │   ├── fhevm.ts            # FHEVM initialization, encryption & decryption
│   │   ├── contracts.ts        # Contract interactions
│   │   └── index.ts            # Core exports
│   ├── adapters/               # Framework-specific adapters
│   │   ├── react.ts            # React hooks (useWallet, useFhevm, etc.)
│   │   ├── vue.ts              # Vue composables
│   │   ├── node.ts             # Node.js adapter (FhevmNode)
│   │   ├── useWallet.ts        # Wallet connection hook
│   │   ├── useFhevm.ts         # FHEVM instance hook
│   │   ├── useContract.ts      # Contract interaction hook
│   │   ├── useEncrypt.ts       # Encryption hook
│   │   └── useDecrypt.ts       # Decryption hook
│   ├── types/                  # TypeScript type definitions
│   └── index.ts                # Main exports
└── dist/                       # Built files (published to npm)

🔧 Core API

FHEVM Initialization

import { initializeFheInstance } from '@chriswilder/fhevm-sdk'

const fheInstance = await initializeFheInstance()

Encryption

import { createEncryptedInput, encryptValue } from '@chriswilder/fhevm-sdk'

// Create encrypted input for contract calls
const encrypted = await createEncryptedInput(contractAddress, userAddress, value)

// Or use encryptValue directly
const encryptedBytes = await encryptValue(contractAddress, userAddress, value)

Decryption

import { decryptValue, publicDecrypt } from '@chriswilder/fhevm-sdk'

// EIP-712 user decryption (requires user signature)
const decrypted = await decryptValue(encryptedBytes, contractAddress, signer)

// Public decryption (no signature required)
const publicDecrypted = await publicDecrypt(encryptedBytes)

🎯 Framework Adapters

React Hooks (Wagmi-like API)

import { useWallet, useFhevm, useContract, useEncrypt, useDecrypt } from '@chriswilder/fhevm-sdk'

function MyComponent() {
  // Wallet connection
  const { address, isConnected, connect, disconnect } = useWallet()
  
  // FHEVM instance
  const { fheInstance, isInitialized, initialize, error } = useFhevm()
  
  // Contract interactions
  const { contract, isReady, error: contractError } = useContract(contractAddress, abi)
  
  // Encryption hook
  const { encrypt, isEncrypting } = useEncrypt()
  
  // Decryption hook
  const { decrypt, isDecrypting } = useDecrypt()
  
  // Use the hooks...
}

Vue Composables

import { useWalletVue, useFhevmVue, useContractVue, useEncryptVue, useDecryptVue, useFhevmOperationsVue } from '@chriswilder/fhevm-sdk'

export default {
  setup() {
    // Wallet connection
    const { address, isConnected, connect, disconnect } = useWalletVue()
    
    // FHEVM instance
    const { fheInstance, isInitialized, initialize, error } = useFhevmVue()
    
    // Contract interactions
    const { contract, isReady, error: contractError } = useContractVue(contractAddress, abi)
    
    // Encryption composable
    const { encrypt } = useEncryptVue()
    
    // Decryption composable
    const { decrypt } = useDecryptVue()
    
    // FHEVM operations (convenience composable)
    const { executeTransaction, isBusy, message } = useFhevmOperationsVue()
    
    return { address, isConnected, connect, disconnect, fheInstance, isInitialized, initialize }
  }
}

Node.js Adapter

import { FhevmNode } from '@chriswilder/fhevm-sdk'

const fhevm = new FhevmNode()
await fhevm.initialize()

// Use FHEVM operations
const encrypted = await fhevm.encrypt(contractAddress, userAddress, value)
const decrypted = await fhevm.decrypt(encryptedBytes, contractAddress, signer)

Core Functions (Framework-agnostic)

import { 
  initializeFheInstance,
  createEncryptedInput,
  encryptValue,
  decryptValue,
  publicDecrypt,
  FhevmContract
} from '@chriswilder/fhevm-sdk'

// Initialize FHEVM
const fheInstance = await initializeFheInstance({ rpcUrl: 'https://...' })

// Encrypt a value
const encrypted = await createEncryptedInput(contractAddress, userAddress, 42)

// Decrypt a value (requires user signature)
const decrypted = await decryptValue(encryptedBytes, contractAddress, signer)

// Public decryption (no signature)
const publicValue = await publicDecrypt(encryptedBytes)

// Contract interactions
const contract = new FhevmContract(contractAddress, abi, signer)

🔐 FHEVM Features

EIP-712 User Decryption

• Authentication - User signs decryption requests
• Security - Only authorized users can decrypt
• Privacy - Encrypted data remains private

Public Decryption

• Public data - Anyone can decrypt
• Leaderboards - Public scores and rankings
• Transparency - Open data access

Encryption

• Input encryption - Encrypt values for contract interactions
• Privacy - Keep data confidential
• Security - Cryptographic protection

🛠️ Development

Build SDK

pnpm build

Test SDK

pnpm test

Lint SDK

pnpm lint

📦 Dependencies

• @zama-fhe/relayer-sdk - FHEVM SDK from Zama (v0.3.0-5)
• @fhevm/solidity - FHEVM Solidity library (v0.9.1)
• ethers - Ethereum interactions
• typescript - Type safety

🔄 FHEVM 0.9.1 Compatibility

This SDK is fully compatible with FHEVM 0.9.1 and includes:

• ✅ ZamaEthereumConfig - Updated config for Ethereum networks
• ✅ checkSignatures - Updated signature verification API
• ✅ Self-relaying decryption - Event-driven decryption pattern
• ✅ Public decryption - Support for publicly decryptable handles

🔧 Configuration

TypeScript

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node"
  }
}

Package.json

{
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./dist/index.js"
    }
  }
}

🎉 Success Metrics

• ✅ Framework-agnostic - Works in any JavaScript environment
• ✅ Real FHEVM functionality - EIP-712 decryption, encryption, contract interactions
• ✅ Wagmi-like API - Intuitive for web3 developers
• ✅ TypeScript support - Full type safety
• ✅ Clean architecture - Modular and extensible

🏆 Bounty Requirements Met

• ✅ Universal SDK - Framework-agnostic core
• ✅ Real FHEVM functionality - EIP-712 decryption, encryption, contract interactions
• ✅ Wagmi-like API - Hooks/composables for each framework
• ✅ Multiple environments - React, Next.js, Vue, Node.js
• ✅ Clean, reusable - Modular SDK structure
• ✅ Complete documentation - Clear examples and READMEs

Ready for production use! 🚀