- name
- zkgov
- description
- 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
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 --helpMode 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