fhevm-frontend

FHEVM Frontend SDK Rules

SDK Choice (NEW vs LEGACY)

Two SDK families ship from npm; both are supported.

• New high-level SDK (@zama-fhe/sdk@^3.0.0 + @zama-fhe/react-sdk@^3.0.0, node >= 22): use for confidential ERC-7984 dApps. Provides ZamaSDK orchestrator, Token API (shield / unshield / confidentialTransfer / balanceOf), session model with one-signature decrypt unlock, RelayerWeb / RelayerNode / RelayerCleartext, signer adapters (ViemSigner / EthersSigner / WagmiSigner), storage adapters, delegated decryption, activity feeds, 59 React hooks. Detail in .cursor/references/zama-sdk-overview.md and the other zama-sdk-*.md files.
• Legacy primitive SDK (@zama-fhe/[email protected] exact): use for raw createInstance / createEncryptedInput / createEIP712 against custom non-ERC-7984 confidential contracts (voting, sealed auctions). Still required as a transitive install for the contract toolchain. This file's lower sections cover its surface.

Encrypt + Decrypt Quick Reference (new SDK)

/* Encrypt user input (browser, React) - "use client" required in Next.js */
import { useEncrypt } from "@zama-fhe/react-sdk";
const { mutateAsync: encrypt } = useEncrypt();
const { handles, inputProof } = await encrypt({
  values: [{ value: 1000n, type: "euint64" }],
  contractAddress, userAddress,
});

/* Decrypt confidential token balance - one EIP-712 prompt, then silent. Returns bigint. */
const balance = await token.balanceOf();
const handle  = await token.confidentialBalanceOf();   /* raw bytes32 handle */
import { useConfidentialBalance } from "@zama-fhe/react-sdk";
const { data } = useConfidentialBalance({ tokenAddress: cUSDT });

/* Decrypt arbitrary handles (custom contract) */
await sdk.allow([contract.address]);
const values = await sdk.userDecrypt([{ handle, contractAddress: contract.address }]);
const cleartext = values[handle];   /* bare Record */

/* Public decrypt (3-step bound flow) */
import { usePublicDecrypt } from "@zama-fhe/react-sdk";
const { mutateAsync: publicDecrypt } = usePublicDecrypt();
const { clearValues } = await publicDecrypt({ handles: [handle] });