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#

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 ToolCLI CommandDescriptionzkgov-stats``zkgov statsPlatform stats: total proposals, members, group IDzkgov-list-proposals``zkgov proposalsList all proposals with vote tallies and statuszkgov-proposal``zkgov proposal <id>Full proposal detail by IDzkgov-check-voter``zkgov voter <address>Check if address is a registered voterzkgov-members``zkgov membersSemaphore group info: member count, Merkle rootzkgov-activity``zkgov activityRecent on-chain events with tx hashes

Write tools (require wallet with HSK for gas)#

MCP ToolCLI CommandDescriptionzkgov-wallet``zkgov walletShow agent wallet: address, balance, voter statuszkgov-register``zkgov registerRegister wallet as voter (one-time on-chain tx)zkgov-create-proposal``zkgov create <title>Create a governance proposalzkgov-vote``zkgov vote <id> <choice>Cast anonymous ZK-verified votezkgov-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