Composable Template System for Privacy-Preserving Smart Contracts
Stop writing FHE boilerplate from scratch.
Generate production ready encrypted smart contracts in seconds with a single CLI command.
Choose from 44 standalone templates or compose custom contracts with 16 bases + 13 modules.
βΈ No installation required - run one command:
npx create-labzβΈ Or specify template and project name directly:
npx create-labz counter my-counter
npx create-labz auction my-auction
npx create-labz token my-tokenβ³ What you get:
my-project/
βββ contracts/ # FHEVM smart contract
βββ test/ # TypeScript test suite
βββ deploy/ # Deployment scripts
βββ hardhat.config.ts
βββ tsconfig.json
βββ package.json
βββ README.md
βββ .gitignore
βΈ Lab-Z provides two ways to generate FHE smart contracts:
| Command | Use Case | Templates |
|---|---|---|
labz create |
Quick start with ready-made examples | 44 standalone templates |
labz build |
Custom contracts with composable modules | 16 bases + 13 modules |
- 44 standalone templates across 9 categories (basics, encryption, decryption, acl, input-proofs, anti-patterns, handles, openzeppelin, advanced)
- 16 composable base templates for DeFi, gaming, voting, and identity
- 13 feature modules for ACL, admin, security, and FHE operations
- 9 OpenZeppelin ERC7984 + FHEVM production-ready confidential contracts
- 9-phase validation pipeline preventing incompatible module combinations
- CLI with 9 commands, interactive mode, and visual composer
| Command | Options |
|---|---|
create |
-i, --interactive --git --install --open -o, --output -l, --list -y, --yes |
build |
-i, --interactive -w, --with -t, --type --list-bases --list-modules --check --preview --dry-run -o, --output -y, --yes |
list |
-c, --category -d, --difficulty -t, --tag |
search |
-c, --category -d, --difficulty -b, --blocks -l, --limit |
info |
-c, --code -t, --test -b, --blocks |
compose |
- |
doctor |
-p, --path |
deploy |
-n, --network --verify --no-compile -y, --yes |
test |
--keep -y, --yes |
βΈ Option A: Install via npm (recommended)
npm install -g @0xflydev/labz
# β β β
# β β βββ Package name on npm registry
# β β
# β βββ Install globally (available everywhere)
# β
# βββ Node package managerβΈ Option B: Build from source
git clone https://github.com/Farukest/Lab-Z.git
cd Lab-Z
pnpm install
# β β
# β βββ Download dependencies (TypeScript, FHEVM libs, Hardhat, etc.)
# β
# βββ Package manager (npm alternative, faster)
pnpm build
# β
# βββ Compile CLI tool and core packages (enables labz commands)βΈ Use create for ready-made, tested examples - no configuration needed:
labz create --list
# β β
# β βββ Show all 44 available templates grouped by category
# β
# βββ Standalone project generator (labz = Lab-Z CLI)
labz create prediction-market my-market
# β β β
# β β βββ Your project folder name
# β β
# β βββ Template name (from --list)
# β
# βββ Standalone project generator (labz = Lab-Z CLI)
cd my-market && npm install && npx hardhat test
# β β β
# β β βββ Run the included tests
# β β
# β βββ Install dependencies
# β
# βββ Enter your new projectβ³ What you get: A complete standalone Hardhat project with contract, tests, and configuration.
CLI.RUN.mp4
βΈ Use build for composable contracts with modules:
labz build --list-bases
# β β β
# β β βββ Show 16 available base templates
# β β
# β βββ Composable contract generator
# β
# βββββββ Lab-Z CLI tool
labz build --list-modules
# β
# βββ Show 13 available feature modules
labz build auction my-auction --with acl/auction-sharing
# β β β β β
# β β β β βββ Module name (category/name format)
# β β β β
# β β β βββ Flag to add feature modules
# β β β
# β β βββ Your project folder name
# β β
# β βββ Base template name (from --list-bases)
# β
# βββββββ Lab-Z CLI tool
labz build token my-token --with acl/transient --with functions/encrypted-add
# β β
# β βββ Each --with adds another module
# β
# βββ Multiple modules can be combinedβ³ What you get: A custom contract with selected modules injected into appropriate slots.
labz create |
labz build |
|
|---|---|---|
| Source | templates/creatable/{category}/ |
templates/buildable/projects/ + templates/buildable/modules/ |
| Format | Ready .sol + .test.ts |
.tmpl templates with slots |
| Modules | No | Yes (--with acl/transient, --with functions/encrypted-add) |
| Parameters | No | Yes (--type euint64, --type euint32) |
| Best for | Learning, quick prototypes | Production, customization |
βΈ Create project from standalone templates (quick start).
labz create [template] [project-name] [options]
-o, --output <dir> # Output directory (default: current)
-l, --list # List available templates
-y, --yes # Skip prompts
-i, --interactive # Interactive mode with template selection
--git # Initialize git repository
--install # Run npm install after creation
--open # Open project in VS CodeExamples:
labz create --list # Show all 44 templates
labz create counter my-counter -y # Quick create, skip prompts
labz create -i # Interactive template selection
labz create auction my-auction --git --install # Full setup with git + depsβΈ Build custom contracts with composable modules.
labz build [base] [project-name] [options]
-w, --with <modules...> # Feature modules to include
# β
# βββ Example: labz build auction my-auction --with acl/transient -w admin/roles
# βββ Explanation: Add FHE or admin modules to customize your contract
-t, --type <type> # Encrypted type (euint8, euint32, euint64)
# β
# βββ Example: labz build token my-token --type euint64
# βββ Explanation: Set the encrypted integer size for FHE operations
-o, --output <dir> # Output directory
# β
# βββ Example: labz build auction my-auction --output ./my-projects
# βββ Explanation: Generate project in a custom folder instead of current directory
--list-bases # List available base templates
# β
# βββ Example: labz build --list-bases
# βββ Explanation: See all 16 base templates (auction, token, voting, etc.)
--list-modules # List available modules
# β
# βββ Example: labz build --list-modules
# βββ Explanation: See all 13 modules grouped by category (acl, admin, functions, etc.)
--check # Validate compatibility without generating
# β
# βββ Example: labz build auction my-auction --with acl/transient --check
# βββ Explanation: Test if your module combination is valid before generating
--preview # Preview generated code
# β
# βββ Example: labz build auction my-auction --with acl/transient --preview
# βββ Explanation: See the generated Solidity code without creating files
--dry-run # Show files without creating
# β
# βββ Example: labz build auction my-auction --dry-run
# βββ Explanation: List files that would be created without actually writing them
-i, --interactive # Interactive module selection
# β
# βββ Example: labz build auction my-auction -i
# βββ Explanation: Choose modules from a menu instead of typing --with flags
-y, --yes # Skip prompts
# β
# βββ Example: labz build auction my-auction -y
# βββ Explanation: Auto-confirm all prompts for scripting/automationβΈ List and filter available templates.
labz list [options]
# β
# βββ List and filter all templates
-c, --category <cat> # Filter by category (basics, advanced, openzeppelin...)
# β
# βββ Example: labz list --category advanced
# βββ Explanation: Show only templates in the "advanced" category
-d, --difficulty <level> # Filter by difficulty (beginner, intermediate, advanced)
# β
# βββ Example: labz list --difficulty beginner
# βββ Explanation: Filter templates by learning curve level
-t, --tag <tag...> # Filter by tags
# β
# βββ Example: labz list --tag defi privacy
# βββ Explanation: Find templates tagged with specific keywordsβΈ Search templates by keyword.
labz search <query> [options]
# β β
# β βββ Search term (e.g., "encrypted voting", "auction")
# β
# βββ Search templates by keyword
-c, --category <cat> # Filter by category
# β
# βββ Example: labz search "token" -c advanced
# βββ Explanation: Search only in a specific category
-d, --difficulty <level> # Filter by difficulty
# β
# βββ Example: labz search "voting" -d beginner
# βββ Explanation: Search only templates of a specific difficulty
-b, --blocks # Include code block matches
# β
# βββ Example: labz search "encrypted voting" -b
# βββ Explanation: Also search inside annotated code blocks
-l, --limit <n> # Limit results (default: 10)
# β
# βββ Example: labz search "auction" -l 5
# βββ Explanation: Return only first N matching templatesβΈ Show detailed template information.
labz info <template> [options]
# β β
# β βββ Template name (e.g., auction, voting, token)
# β
# βββ Show template details
-c, --code # Show contract source code
# β
# βββ Example: labz info auction -c
# βββ Explanation: Display the full Solidity contract source
-b, --blocks # Show annotated code blocks
# β
# βββ Example: labz info prediction-market -b
# βββ Explanation: Show code sections with FHE explanations
-t, --test # Show test file
# β
# βββ Example: labz info auction -t
# βββ Explanation: Display the Hardhat test file for this templateβΈ Interactive visual contract builder (terminal UI).
labz compose [contract-name]
# β β
# β βββ Optional contract name (e.g., MyContract)
# β
# βββ Visual contract builder with terminal UI
#
# βββ Explanation: Opens a terminal menu to select base + modules visually
βΈ Check FHEVM development environment.
labz doctor [options]
# β
# βββ Diagnose your FHEVM development setup
-p, --path <dir> # Project directory to check
# β
# βββ Example: labz doctor -p ./my-project
# βββ Explanation: Check a specific project directory
# Checks performed:
# - Node.js version (>=18)
# - npm installation
# - FHEVM dependencies (@fhevm/solidity, @fhevm/hardhat-plugin)
# - Hardhat config with FHEVM plugin
# - .env file and environment variables
# - node_modules installationβΈ Deploy contracts to network.
labz deploy [contract] [options]
# β β
# β βββ Contract name (auto-detect if not specified)
# β
# βββ Deploy contracts to blockchain
-n, --network <network> # Target network (default: localhost)
# β
# βββ Example: labz deploy -n sepolia
# βββ Networks: localhost, hardhat, sepolia, mainnet
--verify # Verify contract on explorer
# β
# βββ Example: labz deploy -n sepolia --verify
# βββ Explanation: Verify on Etherscan after deployment
--no-compile # Skip compilation step
# β
# βββ Example: labz deploy --no-compile
# βββ Explanation: Use existing compiled artifacts
-y, --yes # Skip confirmation prompts
# β
# βββ Example: labz deploy -n mainnet -y
# βββ Explanation: Auto-confirm for CI/CD pipelinesβΈ Test a template in a temporary directory.
labz test <template> [options]
# β β
# β βββ Template ID to test
# β
# βββ Generate, install, compile in temp folder
--keep # Keep the temporary directory after test
# β
# βββ Example: labz test counter --keep
# βββ Explanation: Preserve project for manual testing
-y, --yes # Skip confirmation prompts
# β
# βββ Example: labz test counter -y
# βββ Explanation: Auto-confirm for CI/CD pipelines| Category | Templates | Description |
|---|---|---|
| basics | 5 | counter, add, multiply, boolean, bitwise |
| encryption | 2 | encrypt single/multiple values |
| decryption | 4 | user/public decryption (single & multiple) |
| acl | 1 | FHE.allow, allowThis, allowTransient |
| input-proofs | 1 | input proof security |
| anti-patterns | 2 | common mistakes to avoid |
| handles | 4 | FHE handle lifecycle, debugging, symbolic execution |
| openzeppelin | 9 | ERC7984 confidential tokens |
| advanced | 16 | DeFi, gaming, voting, identity |
| Template | Description |
|---|---|
| prediction-market | Polymarket-style with encrypted positions |
| dark-pool | Private DEX order matching |
| sealed-tender | Sealed-bid procurement |
| auction | Blind auction with hidden bids |
| voting | Private voting with homomorphic tallying |
| quadratic-vote | Quadratic voting with encrypted credits |
| lottery | Encrypted lottery with fair randomness |
| dice-game | Provably fair dice |
| poker | Encrypted poker hands |
| mystery-box | NFT mystery box with hidden rarity |
| escrow | Private escrow with dispute resolution |
| token | Confidential ERC20-like token |
| age-gate | Age verification without revealing |
| salary-proof | Salary range proofs |
| blind-match | Private preference matching |
| batch-reveal | Multi-party batch reveal with single proof |
βΈ 16 base templates in templates/buildable/projects/:
| Category | Bases |
|---|---|
| Basic | counter, token, voting |
| DeFi | auction, escrow, dark-pool, prediction-market |
| Gaming | lottery, dice-game, mystery-box, poker |
| Governance | quadratic-vote, sealed-tender |
| Identity | age-gate, salary-proof, blind-match |
βΈ 13 modules in templates/buildable/modules/:
| Category | Modules |
|---|---|
| ACL | transient, sharing, token-sharing, auction-sharing, voting-results |
| Admin | ownable, roles |
| Security | pausable, reentrancy |
| Functions | encrypted-add, encrypted-mul, encrypted-compare |
| Events | basic |
labz build auction sealed-auction --with acl/auction-sharing --with admin/ownable
# β β β β
# β β β βββ Only owner can end auction
# β β β
# β β βββ FHE.allow() for encrypted bid sharing
# β β
# β βββ Project folder name
# β
# βββ Sealed-bid auction base template
labz build token private-erc20 --with acl/transient --with functions/encrypted-add --with admin/roles
# β β β β β
# β β β β βββ Admin can mint, operator can pause
# β β β β
# β β β βββ FHE.add() for balance operations
# β β β
# β β βββ FHE.allowTransient() temporary decrypt
# β β
# β βββ Project folder name
# β
# βββ Confidential ERC20-like token
labz build voting dao-voting --with acl/voting-results --with functions/encrypted-compare
# β β β β
# β β β βββ FHE.lt(), FHE.gt() for vote counting
# β β β
# β β βββ Share encrypted results with auditors
# β β
# β βββ Project folder name
# β
# βββ Encrypted voting system
labz build counter my-counter --with functions/encrypted-mul --with security/pausable
# β β β β
# β β β βββ Emergency pause for security
# β β β
# β β βββ FHE.mul() encrypted multiplication
# β β
# β βββ Project folder name
# β
# βββ Simple encrypted counter
labz build token erc7984-defi --with acl/token-sharing --with functions/encrypted-add --with admin/roles
# β β β β β
# β β β β βββ Role-based mint/burn permissions
# β β β β
# β β β βββ FHE.add() for confidential transfers
# β β β
# β β βββ OpenZeppelin ERC7984 compatible ACL sharing
# β β
# β βββ Project folder name
# β
# βββ OpenZeppelin-style confidential token baseβΈ Production-ready confidential contracts combining OpenZeppelin's battle-tested patterns with Zama FHEVM encryption.
| Template | OpenZeppelin | FHEVM Operations |
|---|---|---|
| erc7984-token | ERC7984, Ownable2Step | FHE.add, FHE.allow, FHE.isInitialized |
| erc7984-wrapper | ERC7984ERC20Wrapper | FHE.asEuint64, FHE.allowTransient |
| swap-erc7984-to-erc20 | Ownable, ReentrancyGuard | FHE.sub, public decryption |
| swap-erc7984-to-erc7984 | ReentrancyGuard | FHE.add, FHE.sub, FHE.allowTransient |
| lottery-erc7984 | Ownable, ReentrancyGuard | FHE.randEuint64, encrypted tickets |
| amm-erc7984 | Ownable, ReentrancyGuard | FHE.mul, FHE.div, encrypted liquidity |
| escrow-erc7984 | ReentrancyGuard | FHE.select, encrypted disputes |
| prediction-market-erc7984 | Ownable, ReentrancyGuard | FHE.add, encrypted positions |
| vesting-wallet | Ownable, ReentrancyGuard | euint128, encrypted schedules |
labz create erc7984-token my-confidential-token
# β β β
# β β βββ Your project folder name
# β β
# β βββ OpenZeppelin ERC7984 reference implementation
# β
# βββ Create standalone project (templates/creatable/openzeppelin/)
labz create erc7984-wrapper my-wrapper
# β β
# β βββ Project name
# β
# βββ Wrap existing ERC20 into confidential ERC7984
labz create amm-erc7984 private-amm
# β β
# β βββ Project name
# β
# βββ AMM with FHE-encrypted liquidity pools
cd my-confidential-token && npm install && npx hardhat test
# β β β
# β β βββ Run included tests
# β β
# β βββ Install dependencies
# β
# βββ Enter project folderβΈ The build command runs 9 validation phases before generating code:
| Phase | Check |
|---|---|
| 1 | Base Compatibility |
| 2 | Module Compatibility |
| 3 | Dependency Resolution |
| 4 | Slot Validation |
| 5 | Type Validation |
| 6 | Name Collision |
| 7 | Exclusivity |
| 8 | Size Estimation |
| 9 | Semantic Conflicts |
# Check before building
labz build token my-token --with admin/roles --with security/reentrancy --checkβΈ Copy-paste examples for quick testing after cloning the repo.
β’ Encrypted Counter
labz create counter my-counterβ’ Blind Auction
labz create auction my-auctionβ’ Private Voting
labz create voting my-voting
β’ ERC7984 Confidential Token
labz create erc7984-token my-tokenβ’ ERC20 to ERC7984 Wrapper
labz create erc7984-wrapper my-wrapperβ’ Confidential AMM
labz create amm-erc7984 my-amm
β’ Auction + FHE Sharing + Owner
labz build auction my-sealed-auction --with acl/auction-sharing --with admin/ownableβ’ Token + Encrypted Transfers + Roles
labz build token my-private-token --with acl/transient --with functions/encrypted-add --with admin/rolesβ’ Voting + FHE Compare + Results
labz build voting my-dao-vote --with functions/encrypted-compare --with acl/voting-results
cd my-counter && npm install && npx hardhat testβΈ Each command creates a folder with:
| File | Description |
|---|---|
contracts/*.sol |
Solidity contract with FHE |
test/*.test.ts |
Hardhat test file |
hardhat.config.ts |
Pre-configured for FHEVM |
package.json |
Dependencies ready |
Lab-Z/
βββ packages/
β βββ core/ # Template engine, registry, search
β βββ cli/ # Command-line interface
β βββ web/ # Web UI (Next.js)
β
βββ base-template/ # Hardhat project skeleton
β
βββ templates/
β βββ creatable/ # For `labz create` (44 standalone)
β β βββ basics/ # counter, add, multiply, boolean, bitwise
β β βββ encryption/ # single, multiple
β β βββ decryption/ # user-single, user-multiple, public-single, public-multiple
β β βββ acl/ # allow demo
β β βββ input-proofs/ # input proof security
β β βββ anti-patterns/ # common mistakes
β β βββ handles/ # handle lifecycle, debugging
β β βββ openzeppelin/ # ERC7984 examples
β β βββ advanced/ # DeFi, gaming, voting, identity
β β
β βββ buildable/ # For `labz build` (16 + 13)
β β βββ projects/ # 16 base templates (.tmpl)
β β βββ modules/ # 13 feature modules
β β βββ acl/
β β βββ admin/
β β βββ security/
β β βββ functions/
β β βββ events/
β β
β βββ _test/ # Development test environment
β
βββ scripts/
β βββ generate-docs.ts # GitBook documentation generator
β
βββ docs/ # Generated documentation
cd templates/_test
npm install
npx hardhat test# Generate GitBook-compatible docs
npm run docs:generateβ³ Output in docs/examples/ with SUMMARY.md for navigation.
- Node.js 18+
- pnpm 8+
pnpm install
pnpm buildStandalone template (for create):
templates/creatable/{category}/{name}/
βββ {Name}.sol
βββ {Name}.test.ts
βββ meta.json
Composable template (for build):
templates/buildable/projects/{name}/
βββ contracts/{Name}.sol.tmpl
βββ test/{Name}.test.ts.tmpl
βββ meta.json
templates/buildable/modules/{category}/{name}/
βββ meta.json
βββ inject/
- Issues: GitHub Issues
- Twitter: @0xflydev
- GitHub: @Farukest
| Requirement | Implementation | Status |
|---|---|---|
| Use only Hardhat | All templates use Hardhat | Complete |
| One repo per example | CLI generates standalone projects | Complete |
| Keep each repo minimal | contracts/, test/, hardhat.config.ts | Complete |
| Shared base-template | base-template/ directory | Complete |
| Generate documentation | scripts/generate-docs.ts | Complete |
| Requirement | Implementation | Status |
|---|---|---|
| CLI tool (create-fhevm-example) | labz create, labz build | Complete |
| Clone and customize template | packages/cli/src/commands/create.ts | Complete |
| Insert contract into contracts/ | Automatic during generation | Complete |
| Generate matching tests | Every template includes tests | Complete |
| Auto-generate docs from annotations | scripts/generate-docs.ts with meta.json | Complete |
| Category | Requirement | Template | Status |
|---|---|---|---|
| Basic | Simple FHE counter | basics/counter | Complete |
| Basic | Arithmetic (FHE.add, FHE.sub) | basics/add | Complete |
| Basic | Equality comparison (FHE.eq) | basics/boolean | Complete |
| Encryption | Encrypt single value | encryption/single | Complete |
| Encryption | Encrypt multiple values | encryption/multiple | Complete |
| Decryption | User decrypt single | decryption/user-single | Complete |
| Decryption | User decrypt multiple | decryption/user-multiple | Complete |
| Decryption | Public decrypt single | decryption/public-single | Complete |
| Decryption | Public decrypt multiple | decryption/public-multiple | Complete |
| Access Control | FHE.allow | acl/allow | Complete |
| Access Control | FHE.allowTransient | Included in acl templates | Complete |
| Input Proofs | Explanation and usage | input-proofs/ | Complete |
| Anti-patterns | View functions with encrypted | anti-patterns/view-encrypted | Complete |
| Anti-patterns | Missing FHE.allowThis | anti-patterns/missing-allow | Complete |
| Handles | Handle lifecycle | handles/journey | Complete |
| Handles | Symbolic execution | handles/symbolic-execution | Complete |
| OpenZeppelin | ERC7984 example | openzeppelin/erc7984-token | Complete |
| OpenZeppelin | ERC7984 to ERC20 Wrapper | openzeppelin/erc7984-wrapper | Complete |
| OpenZeppelin | Swap ERC7984 to ERC20 | openzeppelin/swap-erc7984-to-erc20 | Complete |
| OpenZeppelin | Swap ERC7984 to ERC7984 | openzeppelin/swap-erc7984-to-erc7984 | Complete |
| OpenZeppelin | Vesting Wallet | openzeppelin/vesting-wallet | Complete |
| Advanced | Blind auction | advanced/auction | Complete |
| Category | Template | Description |
|---|---|---|
| Advanced | batch-reveal | Multi-party batch reveal with single proof verification |
| Advanced | prediction-market | Polymarket-style encrypted positions |
| Advanced | dark-pool | Private DEX order matching |
| Advanced | sealed-tender | Sealed-bid procurement system |
| Advanced | quadratic-vote | Quadratic voting with encrypted credits |
| Advanced | lottery | Encrypted lottery with fair randomness |
| Advanced | dice-game | Provably fair dice game |
| Advanced | poker | Encrypted poker hands |
| Advanced | mystery-box | NFT mystery box with hidden rarity |
| Advanced | escrow | Private escrow with dispute resolution |
| OpenZeppelin | amm-erc7984 | AMM with confidential liquidity |
| OpenZeppelin | escrow-erc7984 | Confidential escrow with ERC7984 |
| OpenZeppelin | prediction-market-erc7984 | Prediction market with private bets |
| OpenZeppelin | lottery-erc7984 | Lottery using ERC7984 tokens |
| Operation | Templates Using It |
|---|---|
| FHE.asEuint64 | All encryption templates |
| FHE.add | basics/add, token, escrow |
| FHE.sub | basics/add, token |
| FHE.mul | basics/multiply |
| FHE.lt, FHE.gt, FHE.eq | basics/boolean, voting, auction |
| FHE.select | auction, voting, quadratic-vote |
| FHE.allow | acl/allow, all decryption templates |
| FHE.allowThis | All templates with storage |
| FHE.allowTransient | acl/allow, token templates |
| FHE.makePubliclyDecryptable | All public decryption templates |
| FHE.checkSignatures | All public decryption templates |
| FHE.fromExternal | All templates with input proofs |
| FHE.randEuint64 | lottery, dice-game, mystery-box |
| Requirement | Implementation |
|---|---|
| JSDoc/TSDoc comments in tests | All test files include detailed comments |
| Auto-generate markdown per repo | scripts/generate-docs.ts creates 44 markdown files |
| Tag examples into docs | meta.json with tags, categories, blocks |
| GitBook-compatible | docs/SUMMARY.md, docs/examples/*.md |
MIT License
Lab-Z - Composable FHE Smart Contract Templates
