ZecKit

A toolkit for Zcash Regtest development

Project Status

Current Milestone: M3 Complete - GitHub Action & CI

What Works Now

M1 - Foundation

Zebra regtest node in Docker
Health check automation
Basic smoke tests
Project structure and documentation

M2 - Shielded Transactions

zeckit CLI tool with automated setup
On-chain shielded transactions via ZingoLib
Faucet API with actual blockchain broadcasting
Backend toggle (lightwalletd or Zaino)
Automated mining with coinbase maturity
Unified Address (ZIP-316) support
Shield transparent funds to Orchard
Shielded send (Orchard to Orchard)

M3 - GitHub Action ✅

Reusable GitHub Action for CI (E2E Tests + Smoke Tests)
Two-node Zebra Regtest cluster (miner + sync)
Full E2E golden flow: fund → shield → shielded send verified on-chain
7-test smoke suite passing in CI
Artifact upload on failure for easy triage
Continuous block mining (1 block / 15s) during tests

M4 - Docs & Quickstarts (Next)

"2-minute local start" guide
"5-line CI setup" snippet for other repos
Compatibility matrix (Zebra / Zaino versions)
Demo video

Quick Start

Prerequisites

OS: Linux (Ubuntu 22.04+), WSL2, or macOS with Docker Desktop 4.34+
Docker: Engine 24.x + Compose v2
Rust: 1.70+ (for building CLI)
Resources: 2 CPU cores, 4GB RAM, 5GB disk

Installation

# Clone repository
git clone https://github.com/Zecdev/ZecKit.git
cd ZecKit

# Build CLI (one time)
cd cli
cargo build --release
cd ..

# Start devnet with Zaino (recommended - faster)
./cli/target/release/zeckit up --backend zaino

# OR start with lightwalletd
./cli/target/release/zeckit up --backend lwd

# Wait for services to be ready (2-3 minutes)
# Zebra will auto-mine blocks in the background

# Run test suite
./cli/target/release/zeckit test

Verify It's Working

# Check faucet has funds
curl http://localhost:8080/stats

# Response:
# {
#   "current_balance": 600+,
#   "transparent_balance": 100+,
#   "orchard_balance": 500+,
#   "faucet_address": "uregtest1...",
#   ...
# }

# Test shielded send
curl -X POST http://localhost:8080/send \
  -H "Content-Type: application/json" \
  -d '{
    "address": "uregtest1h8fnf3vrmswwj0r6nfvq24nxzmyjzaq5jvyxyc2afjtuze8tn93zjqt87kv9wm0ew4rkprpuphf08tc7f5nnd3j3kxnngyxf0cv9k9lc",
    "amount": 0.05,
    "memo": "Test transaction"
  }'

# Returns TXID from blockchain

CLI Usage

Start Services

# With Zaino (recommended - faster sync)
./cli/target/release/zeckit up --backend zaino

# With Lightwalletd
./cli/target/release/zeckit up --backend lwd

What happens:

Zebra starts in regtest mode with auto-mining
Backend (Zaino or Lightwalletd) connects to Zebra
Faucet wallet initializes with deterministic seed
Blocks are mined automatically, faucet receives coinbase rewards
Faucet auto-shields transparent funds to Orchard pool
Ready for shielded transactions

First startup: Takes 2-3 minutes for initial sync
Subsequent startups: About 30 seconds (uses existing data)

Stop Services

./cli/target/release/zeckit down

Run Test Suite

./cli/target/release/zeckit test

Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ZecKit - Running Smoke Tests
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  [0/7] Cluster synchronization... WARN (non-fatal) Sync node lagging: Miner=217 Sync=0
  [1/7] Zebra RPC connectivity (Miner)... PASS
  [2/7] Faucet health check... PASS
  [3/7] Faucet address retrieval... PASS
  [4/7] Wallet sync capability... PASS
  [5/7] Wallet balance and shield... PASS
  [6/7] Shielded send (E2E)... PASS

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Tests passed: 7
  Tests failed: 0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ All smoke tests PASSED!

Switch Backends

# Stop current backend
./cli/target/release/zeckit down

# Start different backend
./cli/target/release/zeckit up --backend lwd

# Or back to Zaino
./cli/target/release/zeckit up --backend zaino

Fresh Start

# Stop services
./cli/target/release/zeckit down

# Remove all data
docker volume rm zeckit_zebra-data zeckit_zaino-data zeckit_faucet-data

# Start fresh
./cli/target/release/zeckit up --backend zaino

Test Suite

Automated Tests

The zeckit test command runs 7 tests:

Test	What It Validates
0. Cluster Sync	Sync node height vs miner (warn-only)
1. Zebra RPC	Miner node RPC is live
2. Faucet Health	Faucet service is healthy
3. Address Retrieval	Can get unified + transparent addresses
4. Wallet Sync	Wallet can sync with blockchain
5. Shield Funds	Transparent → Orchard shielding works
6. Shielded Send	E2E golden flow: Orchard → Orchard

Manual Testing

# Check service health
curl http://localhost:8080/health

# Get wallet addresses
curl http://localhost:8080/address

# Check balance
curl http://localhost:8080/stats

# Sync wallet
curl -X POST http://localhost:8080/sync

# Shield transparent funds to Orchard
curl -X POST http://localhost:8080/shield

# Send shielded transaction
curl -X POST http://localhost:8080/send \
  -H "Content-Type: application/json" \
  -d '{
    "address": "uregtest1...",
    "amount": 0.05,
    "memo": "Test payment"
  }'

Faucet API

Base URL

http://localhost:8080

Endpoints

GET /health

Check service health

curl http://localhost:8080/health

Response:

{
  "status": "healthy"
}

GET /stats

Get wallet statistics

curl http://localhost:8080/stats

Response:

{
  "current_balance": 681.24,
  "transparent_balance": 125.0,
  "orchard_balance": 556.24,
  "faucet_address": "uregtest1h8fnf3vrmsw...",
  "network": "regtest",
  "wallet_backend": "zingolib",
  "version": "0.3.0",
  "total_requests": 5,
  "total_sent": 0.25,
  "uptime_seconds": 1234
}

GET /address

Get faucet addresses

curl http://localhost:8080/address

Response:

{
  "unified_address": "uregtest1h8fnf3vrmswwj0r6nfvq24nxzmyjzaq5jvyxyc2afjtuze8tn93zjqt87kv9wm0ew4rkprpuphf08tc7f5nnd3j3kxnngyxf0cv9k9lc",
  "transparent_address": "tmBsTi2xWTjUdEXnuTceL7fecEQKeWaPDJd"
}

POST /sync

Sync wallet with blockchain

curl -X POST http://localhost:8080/sync

Response:

{
  "status": "synced",
  "message": "Wallet synced with blockchain"
}

POST /shield

Shield transparent funds to Orchard pool

curl -X POST http://localhost:8080/shield

Response:

{
  "status": "shielded",
  "txid": "86217a05f36ee5a7...",
  "transparent_amount": 156.25,
  "shielded_amount": 156.2499,
  "fee": 0.0001,
  "message": "Shielded 156.2499 ZEC from transparent to orchard (fee: 0.0001 ZEC)"
}

POST /send

Send shielded transaction (Orchard to Orchard)

curl -X POST http://localhost:8080/send \
  -H "Content-Type: application/json" \
  -d '{
    "address": "uregtest1...",
    "amount": 0.05,
    "memo": "Payment for services"
  }'

Response:

{
  "status": "sent",
  "txid": "a8a51e4ed52562ce...",
  "to_address": "uregtest1...",
  "amount": 0.05,
  "memo": "Payment for services",
  "new_balance": 543.74,
  "orchard_balance": 543.74,
  "timestamp": "2026-02-05T05:41:22Z",
  "message": "Sent 0.05 ZEC from Orchard pool"
}

Architecture

See specs/architecture.md for detailed system architecture, component interactions, and data flows.

What Makes This Different

Shielded Transactions

Unlike other Zcash dev tools that only do transparent transactions, ZecKit supports:

Unified Addresses (ZIP-316) - Modern address format
Orchard Pool - Latest shielded pool (NU5+)
Auto-shielding - Transparent to Orchard conversion
Shielded sends - True private transactions
Memo support - Encrypted messages

Backend Flexibility

Toggle between two light client backends:

Zaino (Rust) - Faster, better error messages
Lightwalletd (Go) - Traditional, widely used

Both work with the same wallet and faucet.

Deterministic Wallet

Same seed across restarts
Predictable addresses for testing
No manual configuration needed

Troubleshooting

Common Issues

Tests failing after restart

# Wait for auto-mining to complete
sleep 60

# Run tests again
./cli/target/release/zeckit test

Insufficient balance errors

# Check if mining is happening
curl -s http://localhost:8232 -X POST \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"1.0","id":"1","method":"getblockcount","params":[]}' | jq .result

# Should be increasing every 30-60 seconds

Need fresh start

./cli/target/release/zeckit down
docker volume rm zeckit_zebra-data zeckit_zaino-data zeckit_faucet-data
./cli/target/release/zeckit up --backend zaino

Verify Mining

# Check block count (should increase)
curl -s http://localhost:8232 -X POST \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"1.0","id":"1","method":"getblockcount","params":[]}' | jq .result

# Check mempool
curl -s http://localhost:8232 -X POST \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"1.0","id":"1","method":"getrawmempool","params":[]}' | jq

Project Goals

Why ZecKit?

Zcash ecosystem needs a standard way to:

Test shielded transactions locally - Most tools only support transparent
Support modern addresses (UAs) - ZIP-316 unified addresses
Toggle backends easily - Compare lightwalletd vs Zaino
Catch breakage early - Automated E2E tests in CI

Roadmap

M1 - Foundation (Complete)

Zebra regtest setup
Basic health checks
Docker orchestration

M2 - Transactions (Complete)

Shielded transaction support
Unified addresses
Auto-shielding workflow
Backend toggle
Comprehensive tests

M3 - GitHub Action ✅ (Complete)

Reusable CI action running on every push
E2E golden flow verified in CI
Full 7-test smoke suite

Technical Details

Wallet Implementation

Library: Zingolib (Rust)
Address Type: Unified (Orchard + Transparent)
Seed: Deterministic (same across restarts)
Storage: /var/zingo (persisted in Docker volume)

Mining

Miner: Zebra internal miner
Block Time: 30-60 seconds
Coinbase: Goes to faucet's transparent address
Auto-shield: Faucet automatically shields to Orchard

Network

Mode: Regtest (isolated test network)
Ports:
- 8232: Zebra RPC
- 8080: Faucet API
- 9067: Backend (Zaino/LWD)

Contributing

Contributions welcome. Please:

Fork and create feature branch
Test locally with both backends
Run: ./cli/target/release/zeckit test
Ensure all 7 tests pass (test 0 is warn-only)
Open PR with clear description

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Community: Zcash Forum

License

Dual-licensed under MIT OR Apache-2.0

Acknowledgments

Built by: Dapps over Apps team

Thanks to:

Zcash Foundation (Zebra)
Electric Coin Company (Lightwalletd)
Zingo Labs (Zingolib and Zaino)
Zcash community

Last Updated: March 8, 2026 Status: M3 Complete — CI passing (7/7 tests) ✅

Name		Name	Last commit message	Last commit date
.github		.github
cli		cli
docker		docker
docs		docs
fixtures		fixtures
specs		specs
zeckit-faucet		zeckit-faucet
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE-APACHE		LICENSE-APACHE
LICENSE-MIT		LICENSE-MIT
README.md		README.md
action.yml		action.yml
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation

ZecKit

Project Status

What Works Now

Quick Start

Prerequisites

Installation

Verify It's Working

CLI Usage

Start Services

Stop Services

Run Test Suite

Switch Backends

Fresh Start

Test Suite

Automated Tests

Manual Testing

Faucet API

Base URL

Endpoints

GET /health

GET /stats

GET /address

POST /sync

POST /shield

POST /send

Architecture

What Makes This Different

Shielded Transactions

Backend Flexibility

Deterministic Wallet

Troubleshooting

Common Issues

Verify Mining

Project Goals

Why ZecKit?

Roadmap

Technical Details

Wallet Implementation

Mining

Network

Contributing

Support

License

Acknowledgments

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages