zkWasm DApp CLI 🚀

A powerful scaffolding tool for zkWasm applications, similar to vue-cli and create-react-app, helping developers quickly create, manage, and deploy zkWasm applications.

✨ Features

Feature	Description
🎯 Quick Project Generation	Create new zkWasm projects from templates
🔍 Smart Deployment Checks	Automatic deployment readiness validation with MD5 verification
⚙️ Environment Setup	Automatic development environment configuration
📦 Multiple Templates	Support for Multiple project templates
🛠️ Development Tools	Built-in build, test, and validation tools
🚀 CI/CD Ready	Auto-generated GitHub Actions workflows
📋 Publish Management	Interactive publish script generation with error handling

🚀 Quick Start

Installation

Method	Command	Notes
Global Install	npm install -g zkwasm-dapp-cli	Recommended
Local Install	npm install zkwasm-dapp-cli	Use with npx zkwasm-dapp
From Source	git clone && npm install && npm link	Development

Create Your First Project

# Create a basic Hello World project
zkwasm-dapp create my-zkwasm-app

# Create in specific directory
zkwasm-dapp create my-app --directory ./projects

Development Workflow

cd my-zkwasm-app

# 1. Initialize development environment
zkwasm-dapp init

# 2. Install TypeScript dependencies and compile
cd ts
npm install
npx tsc
cd ..

# 3. Validate project structure
zkwasm-dapp validate

# 4. Build the application
zkwasm-dapp build

# 5. Run locally (optional)
make run

# 6. Generate and run publish script
zkwasm-dapp publish

# 7. Check deployment readiness
zkwasm-dapp check --verbose

Complete Development Process

Step	Command	Description
1. Setup	zkwasm-dapp init	Initialize development environment
2. Dependencies	cd ts && npm install && npx tsc && cd ..	Install and compile TypeScript
3. Validate	zkwasm-dapp validate	Validate project structure
4. Build	zkwasm-dapp build	Build zkWasm application
5. Test	make run	Run local service for testing
6. Publish	zkwasm-dapp publish	Generate/run publish script
7. Deploy Check	zkwasm-dapp check	Verify deployment readiness

GitHub CI/CD Deployment

For automated deployment to production platforms:

1. Switch to deployment branch:

   git checkout -b zkwasm-deploy

2. Enable GitHub Actions:

   • Navigate to repository Settings → Actions
   • Enable GitHub Actions workflows

3. Configure Container Registry:

   • Set up GitHub Container Registry (GCR) access
   • Configure package settings for container images
   • Ensure proper permissions for automated builds

4. Deploy:

   git push origin zkwasm-deploy

The CI/CD pipeline will automatically build and containerize your zkWasm application on Github Container Registry. After successful GitHub Container Registry package build, you can deploy your application using the zkWasm deployment platform at https://deployment.zkwasmhub.com/.

📋 CLI Commands

Command	Description	Usage Order
create <name>	Create new zkWasm project (Hello World template)	1st
init	Initialize development environment and tools	2nd
validate	Validate project structure and configuration	3rd (after TS setup)
build	Build zkWasm application	4th
publish	Generate/run publish script for zkWasm hub	5th
check	Check deployment readiness	6th (after publish)

Command Details

zkwasm-dapp create <project-name>

Creates a new zkWasm project with automatic setup:

Option	Description	Default
-d, --directory <dir>	Target directory	.
--skip-install	Skip automatic npm install and TypeScript compilation	false

Automatic Setup Process:

When you run zkwasm-dapp create, the CLI automatically:

1. ✅ Copies template files (Rust source, TypeScript service, configuration)
2. ✅ Installs TypeScript dependencies (npm install in ts/ directory)
3. ✅ Compiles TypeScript (npx tsc in ts/ directory)
4. ✅ Initializes Git repository
5. ✅ Sets up GitHub Actions (if selected)

⚠️ Important for Development:

The CLI automatically handles initial setup, but during development you'll need to manually reinstall/recompile when:

• Adding new npm packages to ts/package.json
• Modifying any .ts files in ts/src/
• Updating TypeScript configuration

# After adding dependencies or modifying TypeScript:
cd ts
npm install         # Only needed when adding new dependencies
npx tsc            # Needed after any TypeScript changes
cd ..

When to use --skip-install:

• When you want to review package.json before installing dependencies
• In CI/CD environments where you control dependency installation
• When you prefer to install dependencies manually
• If you're experiencing network issues during project creation

With --skip-install, you must manually run:

cd <project-name>/ts && npm install && npx tsc && cd ..

zkwasm-dapp init

Initializes the development environment by:

• Checking for required tools (Rust, wasm-pack, wasm-opt, Node.js)
• Installing missing tools automatically
• Configuring project settings
• Creating development scripts

zkwasm-dapp validate

Validates project readiness by checking:

• Directory structure completeness
• Configuration file validity
• Dependency resolution
• TypeScript compilation status

zkwasm-dapp build

Builds the complete application:

• Compiles Rust to WebAssembly
• Optimizes WASM with wasm-opt
• Generates TypeScript definitions
• Calculates MD5 hash for deployment tracking
• Copies artifacts to build directory

zkwasm-dapp check

Checks deployment readiness by validating:

• Build artifacts (WASM file, TypeScript definitions)
• File integrity (MD5 hash calculation and verification)
• zkWasm hub connectivity (image existence check via API)
• Configuration files (Cargo.toml, package.json, tsconfig.json)
• Dependencies (Rust and Node.js dependency resolution)
• Environment (required tools availability)

zkwasm-dapp publish

Generates and manages publish scripts by:

• Creating customizable publish.sh scripts
• Supporting environment variables (ZKWASM_ADDRESS, ZKWASM_PRIVATE_KEY)
• Providing migration support (optional data import from existing images)

📁 Project Templates

Current Template

Template	Use Case	Features
Basic Hello World	Learning, getting started	• Basic Rust zkWasm module • Simple TypeScript service • State management example • Settlement logic • Standard build configuration

🔧 Template System

The CLI supports a modular template system. Currently, only the Basic Hello World template is available, but you can easily add more templates:

Template File Organization

The CLI uses a organized file structure for templates:

zkwasm-starter/
├── common/                 # Common files copied to all projects
│   ├── Dockerfile.ci       # CI/CD Docker configuration
│   ├── Makefile           # Build automation
│   ├── .gitignore         # Git ignore rules
│   ├── .env.example       # Environment variables template
│   ├── rust-toolchain     # Rust toolchain specification
│   └── .github/           # GitHub Actions workflows
│       └── workflows/
├── templates/             # Template-specific files
│   └── basic/             # Basic Hello World template
│       ├── src/           # Rust source code
│       ├── ts/            # TypeScript service
│       ├── Cargo.toml.template
│       └── README.md.template
└── cli/                   # CLI implementation

Adding New Templates

Step	Action	Location
1. Define Template	Add template config to TEMPLATES object	cli/create-project.js
2. Create Template Files	Add template-specific source files	templates/<template-name>/
3. Add Template Logic	Implement template-specific generation	generateTemplatedFiles() function
4. Update CLI	Add template option back to CLI	cli/index.js

Template Structure Example

templates/
├── basic/           # Current Hello World template (uses src/)
├── advanced/        # Future: Advanced features
│   ├── src/
│   ├── ts/
│   └── config/
└── defi/           # Future: DeFi-specific features
    ├── src/
    ├── ts/
    └── contracts/

Template Configuration

// In cli/create-project.js
const TEMPLATES = {
  basic: {
    name: 'Basic zkWasm Hello World',
    description: 'Simple zkWasm application with basic functionality',
    features: ['State management', 'Settlement logic']
  },
  // Add new templates here:
  // advanced: { ... },
  // defi: { ... }
};

Template Project Structure

my-zkwasm-app/
├── src/                    # Rust source code
│   ├── lib.rs             # Main entry point
│   ├── state.rs           # State management
│   └── config.rs          # Configuration
├── ts/                     # TypeScript code
│   ├── src/               # TS source files
│   ├── package.json       # TS dependencies
│   └── tsconfig.json      # TS configuration
├── build-artifacts/       # Build outputs
├── .github/               # GitHub Actions workflows (if enabled)
│   └── workflows/
├── Cargo.toml             # Rust configuration (generated)
├── Makefile               # Build automation (from common/)
├── Dockerfile.ci          # CI/CD Docker configuration (from common/)
├── .gitignore             # Git ignore rules (from common/)
├── .env.example           # Environment variables template (from common/)
├── rust-toolchain         # Rust toolchain specification (from common/)
├── zkwasm.config.json     # zkWasm configuration (generated)
└── README.md              # Project documentation (generated)

File Sources:

• 📁 Template-specific: src/, ts/ directories from templates/basic/
• 📁 Common files: Makefile, Dockerfile.ci, .gitignore, etc. from common/
• 📄 Generated files: Cargo.toml, README.md, zkwasm.config.json using Mustache templates

⚙️ Configuration (zkwasm-dapp init)

Environment Configuration

Environment	Optimize	Use Case	Build Command
Development	false	Fast builds, debugging	cargo build --target wasm32-unknown-unknown
Production	true	Optimized builds	make build (includes wasm-opt)
Testing	false	Test features enabled	cargo build --target wasm32-unknown-unknown --features test

Note: The zkwasm-dapp build command always performs production-level compilation and generates optimized WASM files, regardless of your environment configuration. For development and testing environments, use the generated scripts in the ./scripts/ directory:

• Development/Testing builds: Use ./scripts/dev-build.sh for fast, unoptimized builds
• Production builds: Use zkwasm-dapp build or make build for optimized, deployment-ready WASM

Generate these scripts with zkwasm-dapp init command.

zkwasm.config.json

{
  "environment": "development",
  "build": {
    "target": "wasm32-unknown-unknown",
    "optimize": false,
    "outputDir": "./build-artifacts"
  },
  "deployment": {
    "autoCheck": true,
    "environment": "development"
  }
}

🔍 Deployment Checks (zkwasm-dapp check)

Check Categories

Category	Items	Status Indicators
Build Artifacts	• application_bg.wasm • application_bg.wasm.d.ts	✅ Found / ❌ Missing
WASM Integrity	• MD5 hash calculation • File size validation • Deployment history	✅ Valid / ⚠️ Duplicate / ❌ Invalid
zkWasm Hub	• Image existence check • API connectivity	✅ Available / ❌ Not found
Environment	• wasm-pack • wasm-opt • Node.js & npm	✅ Available / ❌ Missing
Configuration	• Cargo.toml • package.json • tsconfig.json	✅ Valid / ❌ Invalid

Sample Check Output

🔍 Starting deployment readiness check...

Checking build artifacts...
  ✅ application_bg.wasm (45.2 KB)
  ✅ application_bg.wasm.d.ts (2.1 KB)

Checking WASM file integrity...
  ✅ WASM MD5: EA668FE59ADD59722F3B6FCCE828FD06
  ✅ WASM Size: 46.3 KB

Checking zkWasm hub...
  ✅ Image found on zkWasm hub

📋 Summary: ✅ 8 passed, ⚠️ 0 warnings, ❌ 0 errors

🚀 Publishing (zkwasm-dapp publish)

Publish Script Configuration

Parameter	Description	Default
resturl	zkWasm hub API endpoint	https://rpc.zkwasmhub.com:8090
path	WASM file path	node_modules/zkwasm-ts-server/src/application/application_bg.wasm
circuit_size	Circuit size parameter	22
address	User wallet address	From environment or prompt
priv	Private key	From environment or prompt
description	Image description	User input
creator_paid_proof	Creator pays for proofs	false
creator_only_add_prove_task	Restrict proof creation	false
auto_submit_network_ids	Auto-submit networks	Optional
import_data_image	Migration data source	Optional

Environment Variables

Variable	Purpose
ZKWASM_ADDRESS	Wallet address for publishing
ZKWASM_PRIVATE_KEY	Private key for signing

🛠️ Development Tools

Built-in Scripts

Script	Purpose	Location
dev-build.sh	Development builds	./scripts/ (generated)
publish.sh	Publishing	./ts/ (generated)

Required Tools

Tool	Purpose	Installation
Rust	Core compilation	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
wasm-pack	WASM packaging	curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
wasm-opt	WASM optimization	brew install binaryen (macOS) sudo apt install binaryen (Ubuntu)
Node.js	TypeScript compilation	https://nodejs.org/

🔧 Troubleshooting

Common Issues

Issue	Symptoms	Solution
Build Failure	wasm-pack build fails	• Update Rust: rustup update • Add target: rustup target add wasm32-unknown-unknown
Dependency Error	npm install fails	• Clear cache: npm cache clean --force • Remove node_modules and reinstall
Environment Issues	Tools not found	• Run zkwasm-dapp init • Check PATH configuration
Check Failures	Deployment check errors	• Run zkwasm-dapp check --verbose • Validate with zkwasm-dapp validate

Platform-Specific Notes

Platform	Notes
WSL	• Use Linux versions of tools • Restart terminal after Rust installation
Windows	• Use WSL2 or Git Bash • May require administrator privileges
macOS	• Use Homebrew for binaryen • Ensure Xcode command line tools installed

🤝 Contributing

Type	Description
Bug Reports	Use GitHub Issues with bug template
Feature Requests	Use GitHub Issues with feature template
Pull Requests	Fork → Feature branch → PR
Documentation	Improve README, add examples

📄 License

MIT License - see LICENSE file for details.

📚 Documentation

Document	Description
Template System	Template structure and customization
CLI Reference	Detailed command documentation
zkWasm Development Recipe	Official comprehensive guide

---

Powered by Delphinus Lab 🚀