Lab-Z CLI - Generate composable FHEVM smart contracts
npm install @0xflydev/labz
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.
labz create | Quick start with ready-made examples | 44 standalone templates |
labz build | Custom contracts with composable modules | 16 bases + 13 modules |
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 |
bash
npm install -g @0xflydev/labz
↑ ↑ ↑
│ │ └── Package name on npm registry
│ │
│ └── Install globally (available everywhere)
│
└── Node package manager
`
▸ Option B: Build from source
`bash
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)
`
$3
▸ Use create for ready-made, tested examples - no configuration needed:
`bash
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.
$3
▸ Use build for composable contracts with modules:
`bash
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.
$3
| | 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 |

$3
$3
▸ Create project from standalone templates (quick start).
`bash
labz create [template] [project-name] [options]
-o, --output # 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 Code
`
Examples:
`bash
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
`
$3
▸ Build custom contracts with composable modules.
`bash
labz build [base] [project-name] [options]
-w, --with # 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 # Encrypted type (euint8, euint32, euint64)
# ↑
# └── Example: labz build token my-token --type euint64
# └── Explanation: Set the encrypted integer size for FHE operations
-o, --output # 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
`
$3
▸ List and filter available templates.
`bash
labz list [options]
↑
└── List and filter all templates
-c, --category # Filter by category (basics, advanced, openzeppelin...)
# ↑
# └── Example: labz list --category advanced
# └── Explanation: Show only templates in the "advanced" category
-d, --difficulty # Filter by difficulty (beginner, intermediate, advanced)
# ↑
# └── Example: labz list --difficulty beginner
# └── Explanation: Filter templates by learning curve level
-t, --tag # Filter by tags
# ↑
# └── Example: labz list --tag defi privacy
# └── Explanation: Find templates tagged with specific keywords
`
$3
▸ Search templates by keyword.
`bash
labz search [options]
↑ ↑
│ └── Search term (e.g., "encrypted voting", "auction")
│
└── Search templates by keyword
-c, --category # Filter by category
# ↑
# └── Example: labz search "token" -c advanced
# └── Explanation: Search only in a specific category
-d, --difficulty # 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 # Limit results (default: 10)
# ↑
# └── Example: labz search "auction" -l 5
# └── Explanation: Return only first N matching templates
`
$3
▸ Show detailed template information.
`bash
labz info [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
`
$3
▸ Interactive visual contract builder (terminal UI).
`bash
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
`
$3
▸ Check FHEVM development environment.
`bash
labz doctor [options]
↑
└── Diagnose your FHEVM development setup
-p, --path # 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
`
$3
▸ Deploy contracts to network.
`bash
labz deploy [contract] [options]
↑ ↑
│ └── Contract name (auto-detect if not specified)
│
└── Deploy contracts to blockchain
-n, --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
`
$3
▸ Test a template in a temporary directory.
`bash
labz test [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
`
$3
$3
| 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 |
$3
| 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 |

$3
$3
▸ 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 |
$3
▸ 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 |
$3
`bash
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
`

$3
▸ 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 |
$3
`bash
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
`

$3
▸ 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 |
`bash
Check before building
labz build token my-token --with admin/roles --with security/reentrancy --check
`

$3
▸ Copy-paste examples for quick testing after cloning the repo.
$3
Encrypted Counter
`bash
labz create counter my-counter
`
Blind Auction
`bash
labz create auction my-auction
`
Private Voting
`bash
labz create voting my-voting
`
$3
ERC7984 Confidential Token
`bash
labz create erc7984-token my-token
`
ERC20 to ERC7984 Wrapper
`bash
labz create erc7984-wrapper my-wrapper
`
Confidential AMM
`bash
labz create amm-erc7984 my-amm
`
$3
Auction + FHE Sharing + Owner
`bash
labz build auction my-sealed-auction --with acl/auction-sharing --with admin/ownable
`
Token + Encrypted Transfers + Roles
`bash
labz build token my-private-token --with acl/transient --with functions/encrypted-add --with admin/roles
`
Voting + FHE Compare + Results
`bash
labz build voting my-dao-vote --with functions/encrypted-compare --with acl/voting-results
`
$3
`bash
cd my-counter && npm install && npx hardhat test
`
$3
▸ 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 |

$3
`
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
`

$3
`bash
cd templates/_test
npm install
npx hardhat test
`

$3
`bash
Generate GitBook-compatible docs
npm run docs:generate
`
↳ Output in docs/examples/ with SUMMARY.md for navigation.

$3
$3
- Node.js 18+
- pnpm 8+
$3
`bash
pnpm install
pnpm build
`
$3
Standalone 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/
``