🔐 FHEVM Examples Generator

A comprehensive toolkit for creating standalone FHEVM example repositories with automated documentation generation.

---

🚀 Quick Start •
📦 NPM Package •
📚 Example Gallery •
🛠️ Automation Tools •
🔄 Maintenance •
💻 CLI Reference •
✨ Add New Example

> 📖 Technical Deep Dive: See OVERVIEW.md for architecture decisions, design patterns, and detailed module documentation.

---

Overview

This project provides tools and examples for building privacy-preserving smart contracts using FHEVM by Zama.

$3

- 🎯 33 Examples - encryption, decryption, operations, OpenZeppelin and more
- 🛠️ Interactive CLI - Modern command-line interface with beautiful prompts
- 📦 Standalone Projects - Generate, runnable Hardhat projects from any example
- 📚 Auto Documentation - GitBook-formatted documentation automatically
- 🔗 Hardhat Template - Pre-configured template with all FHEVM dependencies

---

Quick Start

> 💡 Recommended: Use npx create-fhevm-example - no installation needed!

$3

``bash


Interactive mode

npx create-fhevm-example

Quick commands

npx create-fhevm-example --example fhe-counter
npx create-fhevm-example --category basic --output ./my-project

Add example to existing Hardhat project

npx create-fhevm-example --add
`

$3

For local development and contributing:

`bash
git clone https://github.com/NecipAkgz/fhevm-example-factory.git
cd fhevm-example-factory
npm install
`

Interactive Mode:

`bash
npm run create
`





Quick Commands:

`bash


Generate a single example

npm run create:example fhe-counter ./my-fhe-counter

Generate a category bundle

npm run create:category basic ./my-basic-examples

Generate documentation

npm run generate:docs [example] # No arg = all docs, with name = specific doc

Show help

npm run help:create
`

---

📦 NPM Package

Published as create-fhevm-example on NPM, this package allows you to create FHEVM projects without cloning this repository.

Advantages:
- 🚀 No Repository Clone - Install and run directly via npx
- ⚡ Offline Capable - All files bundled, no network needed during scaffolding
- 🔧 Works Anywhere - No local dependencies or setup required
- 🎯 Production Ready - Ideal for scaffolding new dApps or integrating into existing projects

$3

`bash
npx create-fhevm-example
`





$3

`bash


Create single example

npx create-fhevm-example --example fhe-counter

Create category project

npx create-fhevm-example --category basic --output ./my-project
`

$3

Already have a Hardhat project? Inject FHEVM capabilities without starting from scratch:

`bash


Add FHEVM example to existing Hardhat project


npx create-fhevm-example --add
npx create-fhevm-example --add --target ./my-existing-project
`

This will:
- ✅ Detect your Hardhat project
- ✅ Add FHEVM dependencies to package.json
- ✅ Update hardhat.config.ts with FHEVM plugin
- ✅ Add an example contract and test of your choice
- ✅ Handle file conflicts intelligently (skip/overwrite/rename)

> Note: The --add feature is available through npx create-fhevm-example only.

---

📋 Available Examples

33 examples total - Click to expand each category:

🔐 Encryption Examples (3)

- fhe-counter - Simple encrypted counter demonstrating FHE basics
- encrypt-single-value - FHE encryption mechanism and common pitfalls
- encrypt-multiple-values - Handling multiple encrypted values in one transaction

🔓 Decryption Examples (4)

- user-decrypt-single-value - User decryption with permission requirements
- user-decrypt-multiple-values - Decrypting multiple values for a user
- public-decrypt-single-value - On-chain public decryption of a single value
- public-decrypt-multiple-values - On-chain public decryption of multiple values

➕ FHE Operations (4)

- fhe-add - Addition operations on encrypted values
- fhe-arithmetic - All arithmetic: add, sub, mul, div, rem, min, max
- fhe-comparison - All comparisons: eq, ne, gt, lt, ge, le, select
- fhe-if-then-else - Conditional operations on encrypted values

🧠 Critical Concepts (8)

- fhe-access-control - FHE.allow, FHE.allowThis, FHE.allowTransient patterns
- fhe-input-proof - Input proof validation, batched inputs
- fhe-handles - Handle creation, computation, immutability
- fhe-edge-cases - Overflow, underflow, gas benchmarks, permission edge cases

Anti-Patterns:
- control-flow - Conditional logic and loop anti-patterns with encrypted values
- permissions - Permission management mistakes (allowThis, allow, cross-contract)
- operations-gas-noise - Performance issues, side-channels, inefficient operations

🎮 Gaming (4)

- rock-paper-scissors - Encrypted moves with FHE commit-reveal pattern
- encrypted-lottery - Private lottery with encrypted ticket numbers
- encrypted-poker - Texas Hold'em with hidden hole cards
- encrypted-blackjack - Blackjack with encrypted cards and bust detection

🏛️ OpenZeppelin Integration (5)

- erc7984 - Confidential token standard (ERC7984)
- erc7984-erc20-wrapper - Wrap ERC20 into confidential ERC7984
- swap-erc7984-to-erc20 - Swap confidential to public tokens
- swap-erc7984-to-erc7984 - Fully confidential atomic swaps
- vesting-wallet - Linear vesting with encrypted amounts

🎯 Advanced Examples (6)

- blind-auction - Encrypted bids, winner computed via FHE.gt/select
- hidden-voting - Homomorphic vote tallying, private ballots
- private-payroll - Confidential salary payments with encrypted amounts
- encrypted-escrow - Secure escrow with hidden amounts until release
- private-kyc - Identity verification with predicate proofs (age, credit score)
- private-order-book - MEV-resistant trading with encrypted orders

---

🔧 Automation Tools

For local development, the repository provides automation tools:

$3

Creates a production-ready Hardhat environment tailored for a single example:

- 🏗️ Scaffolds a new clean project using the official fhevm-hardhat-template
- 📋 Copies contracts and tests from the bundled package
- ⚙️ Configures Hardhat and generates deployment scripts automatically
- 🔧 Handles contract dependencies and npm packages automatically

`bash
npm run create:example fhe-counter ./my-counter


Or use the interactive CLI:


npm run create
`

$3

Generates a unified workspace containing all examples from a specific category:

- 📦 Bundles multiple contracts into a single project
- 🧪 Consolidates all test files ensuring they run in harmony
- 🔗 Manages shared dependencies across examples automatically

`bash
npm run create:category openzeppelin ./my-oz-examples


Or use the interactive CLI:


npm run create
`

$3

Automatically builds GitBook-ready markdown files directly from your source code.

- 🔍 Extracts code snippets from Contracts and Tests
- 🔐 Auto-generates FHE API Reference (functions & types used)
- 🎨 Formats content into clean, tabbed markdown views
- 📑 Updates the documentation index (SUMMARY.md)

`bash
npm run generate:docs fhe-counter # Single example
npm run generate:docs # All examples
`

---

💻 CLI Reference

Local Development:
- npm run create - Interactive CLI
- npm run create:example [name] [path] - Generate single example
- npm run create:category [name] [path] - Generate category project
- npm run generate:docs [example] - Generate docs (all or specific)
- npm run generate:config - Auto-discover contracts and generate config
- npm run test - Test examples (interactive selection)
- npm run test:all - Test all examples directly
- npm run doctor - Validate environment, submodule status, and config integrity
- npm run help:create - Show help information

NPM Package:
- npx create-fhevm-example - Interactive mode
- npx create-fhevm-example --example - Create single example
- npx create-fhevm-example --category - Create category project
- npx create-fhevm-example --add - Add to existing Hardhat project
- npx create-fhevm-example --help - Show help

---

🔄 Maintenance & Testing

$3

Test selected examples in a unified project for fast, efficient verification:

`bash


Interactive mode - select with space, confirm with enter

npm run test

Run all tests directly

npm run test:all

Quick mode - test specific examples

npm run test fhe-counter,fhe-add
`

> 💡 Selected examples are bundled into a single project, so dependencies install once and all tests run together.

---

📂 Project Structure

📂 Click to expand

`
├── 📁 fhevm-hardhat-template/ # Base Hardhat template (git submodule)
│ ├── contracts/ # Template contract
│ ├── test/ # Template tests
│ ├── deploy/ # Deployment scripts
│ └── hardhat.config.ts # Hardhat configuration
│
├── 📁 contracts/ # All example contracts
│ ├── basic/ # Basic FHE operations
│ ├── concepts/ # Critical FHEVM concepts
│ └── openzeppelin/ # OpenZeppelin integration
│
├── 📁 test/ # All test files (mirrors contracts/)
│
├── 📁 docs/ # Generated GitBook documentation
│
├── 📁 scripts/ # CLI source code
│ ├── index.ts # Main CLI entry point
│ ├── shared/ # Shared utilities
│ │ ├── config.ts # Auto-generated example registry
│ │ ├── utils.ts # Core utilities (logging, naming)
│ │ ├── generators.ts # Template & code generation
│ │ ├── builders.ts # Project scaffolding logic
│ │ └── ui.ts # Interactive prompts
│ └── commands/ # CLI commands
│ ├── add-mode.ts # Add FHEVM to existing projects
│ ├── doctor.ts # Environment health checker
│ ├── generate-config.ts # Auto-discover contracts
│ ├── generate-docs.ts # Documentation generator
│ └── maintenance.ts # Test all examples runner
│
└── README.md # This file
`


---

🛠️ Creating a New Example

For contributors adding new examples:

1. Create Folder (if new category)

`bash
mkdir -p contracts/your-category
mkdir -p test/your-category
`

> 💡 Convention-Based Categories: Folder name becomes category name
> - contracts/gaming/ → "Gaming" category
> - contracts/defi-lending/ → "Defi Lending" category

2. Write Contract in contracts//YourExample.sol

`solidity
/**
* @notice Your contract description here - this becomes the example description!
*
* @dev Technical details...
*/
contract YourExample {
// Implementation
}
`

> ⚠️ Required: @notice tag is mandatory for auto-discovery

3. Write Tests in test//YourExample.ts

4. Generate Configuration (Auto-Discovery)

`bash
npm run generate:config # Scans contracts, extracts @notice tags
`

> 📝 Note: If your example requires external dependencies, manually add them to scripts/shared/config.ts:
>
> `typescript
> "your-example": {
> npmDependencies: {
> "@openzeppelin/contracts": "^5.4.0" // NPM packages
> },
> dependencies: [
> "contracts/mocks/SomeMock.sol" // Contract files
> ],
> }
> `

5. Test Standalone Repository
`bash
npm run create:example your-example ./test-output
cd test-output
npm install && npm run compile && npm run test
`

---

🔄 Updating FHEVM Dependencies

When @fhevm/solidity or related packages release new versions:

1. Update the submodule template:

`bash
git submodule update --remote --merge
`

2. Test all examples for compatibility:

`bash
npm run test:all
`

3. Regenerate documentation if APIs changed:
`bash
npm run generate:docs
`

---

🔗 Resources

- 📖 FHEVM Documentation
- 📚 Protocol Examples
- 🔧 Hardhat Template
- 🌐 Live dApps
- 🏛️ OpenZeppelin Confidential

---

🤝 Contributing

Contributions are welcome! When adding examples:

1. ✅ Follow existing patterns and structure
2. ✅ Include comprehensive inline comments
3. ✅ Add @notice tag to contract for auto-discovery
4. ✅ Demonstrate both correct and incorrect usage
5. ✅ Run npm run generate:config` to auto-generate configuration
6. ✅ Test generated standalone repository
7. ✅ Verify documentation renders correctly

---