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.
▸ 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 |
### ▎Key Features
- **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
### ▎CLI Commands
| 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` |
### ▎Installation
**▸ Option A: Install via npm (recommended)**
```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)
```
### ▎Option 1: Quick Start with `create`
▸ 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.
### ▎Option 2: Quick Start for Custom Build with `build`
▸ 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.
### ▎create vs build
| | `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 |
### ▎labz create
▸ Create project from standalone templates (quick start).
```bash
labz create [template] [project-name] [options]
-o, --output 
### ▎Categories
| 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 |
### ▎Advanced Templates
| 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 |
### ▎Base Templates
▸ 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 |
### ▎Feature Modules
▸ 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 |
### ▎Example Combinations
```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
```
▸ 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 |
### ▎Usage Examples
```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
```
▸ 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
```
▸ Copy-paste examples for quick testing after cloning the repo.
### ▎Quick Create Examples **Encrypted Counter** ```bash labz create counter my-counter ``` **Blind Auction** ```bash labz create auction my-auction ``` **Private Voting** ```bash labz create voting my-voting ```
### ▎OpenZeppelin + FHE Examples **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 ```
### ▎Custom Build Examples **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 ```### ▎Run & Test ```bash cd my-counter && npm install && npx hardhat test ``` ### ▎Output Structure ▸ 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
```
```bash
cd templates/_test
npm install
npx hardhat test
```
```bash
# Generate GitBook-compatible docs
npm run docs:generate
```
↳ Output in `docs/examples/` with `SUMMARY.md` for navigation.
### ▎Prerequisites
- Node.js 18+
- pnpm 8+
### ▎Setup
```bash
pnpm install
pnpm build
```
### ▎Adding Templates
**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/
```
- [Zama FHEVM Documentation](https://docs.zama.ai/fhevm)
- [FHEVM Hardhat Template](https://github.com/zama-ai/fhevm-hardhat-template)
- [OpenZeppelin Confidential Contracts](https://github.com/OpenZeppelin/openzeppelin-confidential-contracts)
### Project Structure and Simplicity
| 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 |
### Scaffolding and Automation
| 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 |
### Required Example Templates
| 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 |
### Additional Implementations
| 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 |
### FHE Operations Coverage
| 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 |
### Documentation Strategy
| 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