Module 10: Frontend Integration

Browser (React + Relayer SDK)
    |
    |-- 1. Initialize FHE instance (fetches public key from chain)
    |-- 2. Encrypt plaintext inputs client-side
    |-- 3. Send encrypted inputs as tx params (externalEuintXX)
    |
    v
FHEVM Contract
    |
    |-- 4. FHE.fromExternal(input, inputProof) converts to euintXX
    |-- 5. Perform FHE operations
    |-- 6. Store encrypted results with ACL
    |
    v
Gateway (for decryption)
    |
    |-- 7. User requests decryption via Relayer SDK
    |-- 8. Gateway re-encrypts for user's keypair
    |-- 9. Frontend decrypts and displays

npm create vite@latest my-fhevm-app -- --template react-ts
cd my-fhevm-app
npm install @zama-fhe/relayer-sdk ethers

import { createInstance } from "@zama-fhe/relayer-sdk/web";
import { BrowserProvider } from "ethers";

let fheInstance: Awaited<ReturnType<typeof createInstance>> | null = null;

async function initFhevm(): Promise<typeof fheInstance> {
  if (fheInstance) return fheInstance;

  const provider = new BrowserProvider(window.ethereum);

  fheInstance = await createInstance({
    network: await provider.send("eth_chainId", []),
    relayerUrl: "https://gateway.zama.ai",
  });

  return fheInstance;
}

async function encryptAmount(
  amount: number,
  contractAddress: string,
  userAddress: string
) {
  const instance = await initFhevm();

  // Create an encrypted input bound to this contract and user
  const input = instance.createEncryptedInput(contractAddress, userAddress);
  input.add32(amount); // add a 32-bit encrypted value

  const encrypted = await input.encrypt();
  // encrypted.handles[0] = the encrypted handle (bytes32)
  // encrypted.inputProof = the ZK proof (bytes)
  return encrypted;
}

import { Contract, BrowserProvider } from "ethers";

const COUNTER_ABI = [
  "function increment(bytes32 encValue, bytes calldata inputProof) external",
  "function getMyCount() external view returns (uint256)",
];

async function incrementCounter(amount: number) {
  const provider = new BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();
  const userAddress = await signer.getAddress();

  const contract = new Contract(COUNTER_ADDRESS, COUNTER_ABI, signer);

  // Encrypt the amount
  const encrypted = await encryptAmount(amount, COUNTER_ADDRESS, userAddress);

  // Send the transaction with the encrypted handle and input proof
  const tx = await contract.increment(encrypted.handles[0], encrypted.inputProof);
  await tx.wait();

  console.log("Counter incremented!");
}

async function readCounter(): Promise<number> {
  const provider = new BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();
  const userAddress = await signer.getAddress();

  const contract = new Contract(COUNTER_ADDRESS, COUNTER_ABI, signer);
  const instance = await initFhevm();

  // Get the encrypted handle from the contract
  const encryptedHandle = await contract.getMyCount();

  // Request re-encryption for this user
  // The user must sign a message to prove they have ACL access
  const { publicKey, privateKey } = instance.generateKeypair();
  const eip712 = instance.createEIP712(publicKey, COUNTER_ADDRESS);
  const signature = await signer.signTypedData(
    eip712.domain,
    eip712.types,
    eip712.message
  );

  const decryptedValue = await instance.reencrypt(
    encryptedHandle,
    privateKey,
    publicKey,
    signature,
    COUNTER_ADDRESS,
    userAddress
  );

  return Number(decryptedValue);
}

// BAD: might fail if instance not ready
const encrypted = instance.createEncryptedInput(...);

// GOOD: ensure initialization
const instance = await initFhevm();
const encrypted = instance.createEncryptedInput(...);

async function connectWallet(): Promise<string> {
  if (!window.ethereum) {
    throw new Error("MetaMask not detected");
  }
  const accounts = await window.ethereum.request({
    method: "eth_requestAccounts",
  });
  return accounts[0];
}

const decryptionCache = new Map<string, number>();

async function cachedDecrypt(handle: bigint): Promise<number> {
  const key = handle.toString();
  if (decryptionCache.has(key)) {
    return decryptionCache.get(key)!;
  }
  const value = await readCounter();
  decryptionCache.set(key, value);
  return value;
}

async function handleIncrement() {
  await incrementCounter(amount);
  decryptionCache.clear(); // Invalidate cache
  await refreshCounter();
}

import { ethers, fhevm } from "hardhat";
import { FhevmType } from "@fhevm/hardhat-plugin";

// Decrypt in tests
const clear = await fhevm.userDecryptEuint(
  FhevmType.euint32,
  encryptedHandle,
  contractAddress,
  signer
);