ZKGov
ZKGov is a zero-knowledge governance platform on HashKey Chain testnet (chain ID 133). Voters register with Semaphore identity commitments and cast anonymous, Groth16-verified votes on governance proposals.
Install
# MCP server (preferred — works with Claude Code, Cursor, Windsurf, VS Code)
# https://www.npmjs.com/package/@zkgov/mcp
claude mcp add zkgov npx @zkgov/mcp
# Standalone CLI
# https://www.npmjs.com/package/@zkgov/cli
npm install -g @zkgov/cli
zkgov --help
Mode priority
- MCP tools first. If tools prefixed
mcp__zkgov__*are available, call them directly. - CLI fallback. If no MCP tools are available, run
zkgov <command>via the Bash tool. --jsonflag. Always use--jsonwhen calling CLI from an agent for reliable parsing.
When to use
- User asks about governance proposals, voting, or on-chain governance
- User wants to create, vote on, or check proposals
- User asks about voter registration or ZK identity
- User asks about HashKey Chain governance activity
- User wants an agent to participate in governance autonomously
When NOT to use
- General blockchain questions answerable from training data
- Questions about other chains or protocols
- Math, code review, or general programming tasks
Available tools
Read tools (no wallet needed)
| MCP Tool | CLI Command | Description |
|---|---|---|
zkgov-stats |
zkgov stats |
Platform stats: total proposals, members, group ID |
zkgov-list-proposals |
zkgov proposals |
List all proposals with vote tallies and status |
zkgov-proposal |
zkgov proposal <id> |
Full proposal detail by ID |
zkgov-check-voter |
zkgov voter <address> |
Check if address is a registered voter |
zkgov-members |
zkgov members |
Semaphore group info: member count, Merkle root |
zkgov-activity |
zkgov activity |
Recent on-chain events with tx hashes |
Write tools (require wallet with HSK for gas)
| MCP Tool | CLI Command | Description |
|---|---|---|
zkgov-wallet |
zkgov wallet |
Show agent wallet: address, balance, voter status |
zkgov-register |
zkgov register |
Register wallet as voter (one-time on-chain tx) |
zkgov-create-proposal |
zkgov create <title> |
Create a governance proposal |
zkgov-vote |
zkgov vote <id> <choice> |
Cast anonymous ZK-verified vote |
zkgov-finalize |
zkgov finalize <id> |
Finalize proposal after voting period ends |
Wallet
On first write operation, a wallet is auto-generated at ~/.zkgov/config.json (mode 0o600). The same private key derives both the EVM account and the Semaphore ZK identity.
Override with env var: ZKGOV_PRIVATE_KEY=0x...
The wallet needs testnet HSK for gas (very cheap — 0.001 gwei gas price).
Workflow
- Check state:
zkgov-statsto see proposals/members count - Check wallet:
zkgov-walletto see balance and registration - Register:
zkgov-register(one-time, ~0.0003 HSK gas) - Browse:
zkgov-list-proposals→zkgov-proposalfor detail - Vote:
zkgov-votewith proposalId and choice (generates ZK proof, ~3-5s) - Finalize:
zkgov-finalizeafter voting period ends (anyone can call)
CLI flags
--json— machine-readable output on every commandzkgov activity --limit 10— limit activity eventszkgov create "Title" -d "Body" -p 86400 -q 3— set period (seconds) and quorum
Key facts
- Chain: HashKey Chain Testnet (ID: 133, RPC: https://testnet.hsk.xyz)
- Contract:
0xEa625841E031758786141c8b13dD1b1137C9776C - Explorer: https://testnet-explorer.hsk.xyz
- Vote choices: 0 = Against, 1 = For, 2 = Abstain
- Nullifiers prevent double-voting per proposal (hash of identity + proposalId)
- castVote does NOT check msg.sender — only the ZK proof matters
- Proof generation uses snarkjs WASM, takes 3-5 seconds
Error handling
- "Already registered" → wallet is already a voter, skip registration
- "Nullifier" error → already voted on this proposal
- "Voting ended" → voting period has closed, try
zkgov-finalizeinstead - "Proposal does not exist" → invalid proposal ID
- Insufficient balance → wallet needs HSK for gas