ZKGov

Anonymous governance on HashKey Chain using zero-knowledge proofs. Query proposals, check voter status, register, create proposals, vote anonymously with ZK proofs, and finalize outcomes. Use whenever the user mentions ZKGov, governance proposals, anonymous voting, ZK voting, HashKey Chain governance, or anything related to on-chain voting with privacy.

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

bash

# 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

1. MCP tools first. If tools prefixed mcp__zkgov__* are available, call them directly.
2. CLI fallback. If no MCP tools are available, run zkgov <command> via the Bash tool.
3. --json flag. Always use --json when 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

1. Check state: zkgov-stats to see proposals/members count
2. Check wallet: zkgov-wallet to see balance and registration
3. Register: zkgov-register (one-time, ~0.0003 HSK gas)
4. Browse: zkgov-list-proposals → zkgov-proposal for detail
5. Vote: zkgov-vote with proposalId and choice (generates ZK proof, ~3-5s)
6. Finalize: zkgov-finalize after voting period ends (anyone can call)

CLI flags

• --json — machine-readable output on every command
• zkgov activity --limit 10 — limit activity events
• zkgov 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-finalize instead
• "Proposal does not exist" → invalid proposal ID
• Insufficient balance → wallet needs HSK for gas