FHEVM Cookbook Thin skills catalog for working on Zama FHEVM. Current scope: - fhevm-router: skills/fhevm-router/SKILL.md - erc7984-confidential-tokens: skills/erc7984-confidential-tokens/SKILL.md - fhe-privacy-constraints: skills/fhe-privacy-constraints/SKILL.md - fhe-acl-lifecycle: skills/fhe-acl-lifecycle/SKILL.md - fhe-control-flow: skills/fhe-control-flow/SKILL.md - fhe-encrypted-inputs: skills/fhe-encrypted-inputs/SKILL.md - fhe-user-decryption: skills/fhe-user-decryption/SKILL.md - fhe-public-decryption: skills/fhe-public-decryption/SKILL.md - fhe-security-audit: skills/fhe-security-audit/SKILL.md - fhe-compliance-patterns: skills/fhe-compliance-patterns/SKILL.md - fhe-arithmetic-ops: skills/fhe-arithmetic-ops/SKILL.md - fhe-gas-optimization: skills/fhe-gas-optimization/SKILL.md - fhe-testing: skills/fhe-testing/SKILL.md - fhe-frontend-integration: skills/fhe-frontend-integration/SKILL.md - fhe-cross-contract: skills/fhe-cross-contract/SKILL.md - fhe-confidential-governance: skills/fhe-confidential-governance/SKILL.md - fhe-defi-patterns: skills/fhe-defi-patterns/SKILL.md - fhe-custodian-omnibus: skills/fhe-custodian-omnibus/SKILL.md Raw skill URLs: - fhevm-router: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhevm-router/SKILL.md - erc7984-confidential-tokens: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/erc7984-confidential-tokens/SKILL.md - fhe-privacy-constraints: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-privacy-constraints/SKILL.md - fhe-acl-lifecycle: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-acl-lifecycle/SKILL.md - fhe-control-flow: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-control-flow/SKILL.md - fhe-encrypted-inputs: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-encrypted-inputs/SKILL.md - fhe-user-decryption: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-user-decryption/SKILL.md - fhe-public-decryption: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-public-decryption/SKILL.md - fhe-security-audit: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-security-audit/SKILL.md - fhe-compliance-patterns: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-compliance-patterns/SKILL.md - fhe-arithmetic-ops: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-arithmetic-ops/SKILL.md - fhe-gas-optimization: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-gas-optimization/SKILL.md - fhe-testing: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-testing/SKILL.md - fhe-frontend-integration: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-frontend-integration/SKILL.md - fhe-cross-contract: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-cross-contract/SKILL.md - fhe-confidential-governance: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-confidential-governance/SKILL.md - fhe-defi-patterns: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-defi-patterns/SKILL.md - fhe-custodian-omnibus: https://raw.githubusercontent.com/z-korp/zama-cookbook/main/skills/fhe-custodian-omnibus/SKILL.md What the skills cover: - fhevm-router: Classifies the task as contract, frontend, wallet, or review oriented - fhevm-router: Points to the narrowest official Zama docs page to keep open while working - fhevm-router: Calls out trust boundaries, ACL concerns, and decryption boundaries early - fhevm-router: Keeps the repo honest about current scope instead of routing to missing modules - erc7984-confidential-tokens: Frames ERC-7984 around token, caller, decryption, and proof-verification boundaries - erc7984-confidential-tokens: Calls out operator semantics instead of drifting back to ERC-20 allowance mental models - erc7984-confidential-tokens: Keeps unwrap flows honest as async decrypt-and-verify, not single-step plaintext settlement - erc7984-confidential-tokens: Maps custom designs back to the smallest OpenZeppelin confidential token module set - fhe-privacy-constraints: Separates what is public, hidden, user-readable, or only available after async decrypt - fhe-privacy-constraints: Explains why balance-based rewards and threshold checks break under confidential transfers - fhe-privacy-constraints: Forces ACL access plans to be explicit before proposing on-chain reads or enforcement - fhe-privacy-constraints: Reframes blocked mechanisms toward wrap activity, lockups, utility, or user-initiated proofs - fhe-acl-lifecycle: Explains why FHE operations return NEW handles that need fresh ACL grants - fhe-acl-lifecycle: Distinguishes allow, allowThis, and allowTransient for different trust scenarios - fhe-acl-lifecycle: Traces permission chains across multi-step encrypted computations - fhe-acl-lifecycle: Catches the #1 FHEVM bug: assuming permissions transfer to derived values - fhe-control-flow: Explains why require(ebool) does not exist and what replaces it - fhe-control-flow: Shows FHE.select as the only way to branch on encrypted conditions - fhe-control-flow: Covers silent fallback to zero and its impact on user experience - fhe-control-flow: Guides product design for non-reverting failure modes - fhe-encrypted-inputs: Explains the FHE.fromExternal(ciphertext, inputProof) ingestion pattern - fhe-encrypted-inputs: Shows how input proofs bind ciphertext to msg.sender and contract address - fhe-encrypted-inputs: Covers client-side encryption with the Zama SDK - fhe-encrypted-inputs: Prevents replay and cross-contract ciphertext injection attacks - fhe-user-decryption: Explains the off-chain reencryption flow: sign, decrypt, display - fhe-user-decryption: Shows ACL pre-grant as a prerequisite for user decryption - fhe-user-decryption: Covers EIP-712 typed signatures for reencryption authorization - fhe-user-decryption: Guides React and Next.js integration with the relayer SDK - fhe-public-decryption: Explains the two-step pattern: compute encrypted result, then finalize with proof - fhe-public-decryption: Shows FHE.makePubliclyDecryptable and relayer publicDecrypt flow - fhe-public-decryption: Covers on-chain proof verification with FHE.checkSignatures - fhe-public-decryption: Prevents the single-step unwrap bug where user-claimed plaintext bypasses FHE checks - fhe-security-audit: Provides a systematic audit checklist for FHEVM contracts - fhe-security-audit: Traces ACL permission flows across multi-step operations - fhe-security-audit: Catalogs known footguns: missing ACL, silent zero, wrong unwrap, handle reuse - fhe-security-audit: Covers arithmetic constraint verification and overflow behavior - fhe-compliance-patterns: Maps OpenZeppelin compliance modules: ObserverAccess, Freezable, Restricted, Rwa - fhe-compliance-patterns: Explains selective transparency for auditors without breaking user privacy - fhe-compliance-patterns: Covers force-transfer, pause, and encrypted freeze amount mechanics - fhe-compliance-patterns: Guides institutional adoption: how to satisfy regulators while preserving confidentiality - fhe-arithmetic-ops: Lists supported vs unsupported FHE operations with type constraints - fhe-arithmetic-ops: Explains why ciphertext-scalar is far cheaper than ciphertext-ciphertext - fhe-arithmetic-ops: Shows division requires a plaintext divisor — no encrypted denominators - fhe-arithmetic-ops: Covers euint64 overflow behavior and safe arithmetic patterns - fhe-gas-optimization: Explains 100-10,000x cost multipliers for FHE vs plaintext operations - fhe-gas-optimization: Guides ciphertext-scalar preference over ciphertext-ciphertext - fhe-gas-optimization: Shows handle reuse and ACL batching strategies to reduce gas - fhe-gas-optimization: Covers architecture decisions: keeping rates, time, and denominators public - fhe-testing: Shows @fhevm/hardhat-plugin and @fhevm/mock-utils setup for local testing - fhe-testing: Explains mocked mode vs real protocol: what each catches and misses - fhe-testing: Covers debug decrypt for inspecting encrypted values during development - fhe-testing: Guides end-to-end validation on testnet before mainnet deployment - fhe-frontend-integration: Shows @zama-fhe/react-sdk and @zama-fhe/sdk setup in React and Next.js - fhe-frontend-integration: Explains SSR boundaries: SDK must run client-side only - fhe-frontend-integration: Covers relayer SDK integration for reencryption and decryption - fhe-frontend-integration: Guides WalletConnect vs Privy auth patterns for different user bases - fhe-cross-contract: Explains how to pass encrypted handles across contract boundaries - fhe-cross-contract: Shows multi-contract ACL grant chains: allowTransient for immediate forwarding - fhe-cross-contract: Covers factory and proxy patterns that preserve encrypted state - fhe-cross-contract: Guides composable DeFi flows where encrypted values traverse multiple protocols - fhe-confidential-governance: Explains ERC7984Votes: delegation is public but voting power stays encrypted - fhe-confidential-governance: Shows private ballot casting without revealing token holdings - fhe-confidential-governance: Covers tally and reveal patterns for confidential vote counting - fhe-confidential-governance: Guides integration with existing DAO governance frameworks - fhe-defi-patterns: Shows how to build DEX routers and AMMs with confidential order flow - fhe-defi-patterns: Covers confidential vaults and lending with hidden collateral amounts - fhe-defi-patterns: Explains payment streaming with encrypted deposits and time-based release - fhe-defi-patterns: Guides operator and transfer variant selection for DeFi composability - fhe-custodian-omnibus: Explains ERC7984Omnibus for managing sub-accounts under one on-chain address - fhe-custodian-omnibus: Shows exchange deposit and withdrawal flows with encrypted amounts - fhe-custodian-omnibus: Covers per-user accounting within omnibus wallets - fhe-custodian-omnibus: Guides reconciliation and audit patterns under encrypted custodian state Machine-readable artifacts: - /llms.txt - /data/site-data.json - /data/skills.json References: - fhevm-router / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhevm-router / User decryption: https://docs.zama.ai/protocol/relayer-sdk-guides/fhevm-relayer/decryption/user-decryption - fhevm-router / Public decryption: https://docs.zama.ai/protocol/relayer-sdk-guides/fhevm-relayer/decryption/public-decryption - fhevm-router / Web app guide: https://docs.zama.ai/protocol/relayer-sdk-guides/development-guide/webapp - fhevm-router / ERC-7984 integration: https://docs.zama.ai/protocol/examples/openzeppelin-confidential-contracts/integration-guide - erc7984-confidential-tokens / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/ERC7984.md - erc7984-confidential-tokens / ERC-7984 integration: https://docs.zama.ai/protocol/examples/openzeppelin-confidential-contracts/integration-guide - erc7984-confidential-tokens / Examples: https://docs.zama.ai/protocol/examples - erc7984-confidential-tokens / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-privacy-constraints / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_PRIVACY_CONSTRAINTS.md - fhe-privacy-constraints / Examples: https://docs.zama.ai/protocol/examples - fhe-privacy-constraints / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-privacy-constraints / ERC-7984 integration: https://docs.zama.ai/protocol/examples/openzeppelin-confidential-contracts/integration-guide - fhe-acl-lifecycle / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_ACL_LIFECYCLE.md - fhe-acl-lifecycle / ACL semantics: https://docs.zama.ai/protocol/solidity-guides/smart-contract/acl - fhe-acl-lifecycle / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-control-flow / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_CONTROL_FLOW.md - fhe-control-flow / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-control-flow / Operations: https://docs.zama.ai/protocol/solidity-guides/smart-contract/operations - fhe-encrypted-inputs / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_ENCRYPTED_INPUTS.md - fhe-encrypted-inputs / Input handling: https://docs.zama.ai/protocol/solidity-guides/smart-contract/inputs - fhe-encrypted-inputs / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-user-decryption / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_USER_DECRYPTION.md - fhe-user-decryption / User decryption: https://docs.zama.ai/protocol/relayer-sdk-guides/fhevm-relayer/decryption/user-decryption - fhe-user-decryption / Relayer guides: https://docs.zama.ai/protocol/relayer-sdk-guides - fhe-public-decryption / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_PUBLIC_DECRYPTION.md - fhe-public-decryption / Public decryption: https://docs.zama.ai/protocol/relayer-sdk-guides/fhevm-relayer/decryption/public-decryption - fhe-public-decryption / Relayer guides: https://docs.zama.ai/protocol/relayer-sdk-guides - fhe-security-audit / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_SECURITY_AUDIT.md - fhe-security-audit / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-security-audit / Examples: https://docs.zama.ai/protocol/examples - fhe-compliance-patterns / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_COMPLIANCE_PATTERNS.md - fhe-compliance-patterns / ERC-7984 integration: https://docs.zama.ai/protocol/examples/openzeppelin-confidential-contracts/integration-guide - fhe-compliance-patterns / Examples: https://docs.zama.ai/protocol/examples - fhe-arithmetic-ops / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_ARITHMETIC_OPS.md - fhe-arithmetic-ops / Operations: https://docs.zama.ai/protocol/solidity-guides/smart-contract/operations - fhe-arithmetic-ops / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-gas-optimization / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_GAS_OPTIMIZATION.md - fhe-gas-optimization / Operations: https://docs.zama.ai/protocol/solidity-guides/smart-contract/operations - fhe-gas-optimization / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-testing / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_TESTING.md - fhe-testing / Testing: https://docs.zama.ai/protocol/solidity-guides/getting-started/write-contract/testing - fhe-testing / Examples: https://docs.zama.ai/protocol/examples - fhe-frontend-integration / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_FRONTEND_INTEGRATION.md - fhe-frontend-integration / Web app guide: https://docs.zama.ai/protocol/relayer-sdk-guides/development-guide/webapp - fhe-frontend-integration / Relayer guides: https://docs.zama.ai/protocol/relayer-sdk-guides - fhe-cross-contract / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_CROSS_CONTRACT.md - fhe-cross-contract / ACL semantics: https://docs.zama.ai/protocol/solidity-guides/smart-contract/acl - fhe-cross-contract / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-confidential-governance / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_CONFIDENTIAL_GOVERNANCE.md - fhe-confidential-governance / ERC-7984 integration: https://docs.zama.ai/protocol/examples/openzeppelin-confidential-contracts/integration-guide - fhe-confidential-governance / Examples: https://docs.zama.ai/protocol/examples - fhe-defi-patterns / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_DEFI_PATTERNS.md - fhe-defi-patterns / Examples: https://docs.zama.ai/protocol/examples - fhe-defi-patterns / Solidity guides: https://docs.zama.ai/protocol/solidity-guides - fhe-custodian-omnibus / Local guide: https://github.com/z-korp/zama-cookbook/blob/main/docs/FHE_CUSTODIAN_OMNIBUS.md - fhe-custodian-omnibus / ERC-7984 integration: https://docs.zama.ai/protocol/examples/openzeppelin-confidential-contracts/integration-guide - fhe-custodian-omnibus / Examples: https://docs.zama.ai/protocol/examples