Create FHEVM example projects with a single command - A comprehensive toolkit for building privacy-preserving smart contracts
npm install create-fhevm-example
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.
---
This project provides tools and examples for building privacy-preserving smart contracts using FHEVM by Zama.
- ๐ฏ 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
---
> ๐ก Recommended: Use npx create-fhevm-example - no installation needed!
``bashInteractive mode
npx create-fhevm-example
$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-counterGenerate a category bundle
npm run create:category basic ./my-basic-examplesGenerate documentation
npm run generate:docs [example] # No arg = all docs, with name = specific docShow 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-counterCreate 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 casesAnti-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 informationNPM 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 testRun all tests directly
npm run test:allQuick 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" category2. Write Contract in
contracts/
`solidity
/**
* @notice Your contract description here - this becomes the example description!
*
* @dev Technical details...
*/
contract YourExample {
// Implementation
}
` > โ ๏ธ Required:
@notice tag is mandatory for auto-discovery3. Write Tests in
test/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---