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.
--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
- Check state:
zkgov-stats to see proposals/members count
- Check wallet:
zkgov-wallet to see balance and registration
- Register:
zkgov-register (one-time, ~0.0003 HSK gas)
- Browse:
zkgov-list-proposals → zkgov-proposal for detail
- Vote:
zkgov-vote with proposalId and choice (generates ZK proof, ~3-5s)
- 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
1---2name: zkgov3description: 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.4metadata:5 source: https://skillmd.com/skills/lord1egypt/zkgov6---78# ZKGov910ZKGov 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.1112## Install1314```bash15# MCP server (preferred — works with Claude Code, Cursor, Windsurf, VS Code)16# https://www.npmjs.com/package/@zkgov/mcp17claude mcp add zkgov npx @zkgov/mcp1819# Standalone CLI20# https://www.npmjs.com/package/@zkgov/cli21npm install -g @zkgov/cli22zkgov --help23```2425## Mode priority26271. **MCP tools first.** If tools prefixed `mcp__zkgov__*` are available, call them directly.282. **CLI fallback.** If no MCP tools are available, run `zkgov <command>` via the Bash tool.293. **`--json` flag.** Always use `--json` when calling CLI from an agent for reliable parsing.3031## When to use3233- User asks about governance proposals, voting, or on-chain governance34- User wants to create, vote on, or check proposals35- User asks about voter registration or ZK identity36- User asks about HashKey Chain governance activity37- User wants an agent to participate in governance autonomously3839## When NOT to use4041- General blockchain questions answerable from training data42- Questions about other chains or protocols43- Math, code review, or general programming tasks4445## Available tools4647### Read tools (no wallet needed)4849| MCP Tool | CLI Command | Description |50|---|---|---|51| `zkgov-stats` | `zkgov stats` | Platform stats: total proposals, members, group ID |52| `zkgov-list-proposals` | `zkgov proposals` | List all proposals with vote tallies and status |53| `zkgov-proposal` | `zkgov proposal <id>` | Full proposal detail by ID |54| `zkgov-check-voter` | `zkgov voter <address>` | Check if address is a registered voter |55| `zkgov-members` | `zkgov members` | Semaphore group info: member count, Merkle root |56| `zkgov-activity` | `zkgov activity` | Recent on-chain events with tx hashes |5758### Write tools (require wallet with HSK for gas)5960| MCP Tool | CLI Command | Description |61|---|---|---|62| `zkgov-wallet` | `zkgov wallet` | Show agent wallet: address, balance, voter status |63| `zkgov-register` | `zkgov register` | Register wallet as voter (one-time on-chain tx) |64| `zkgov-create-proposal` | `zkgov create <title>` | Create a governance proposal |65| `zkgov-vote` | `zkgov vote <id> <choice>` | Cast anonymous ZK-verified vote |66| `zkgov-finalize` | `zkgov finalize <id>` | Finalize proposal after voting period ends |6768## Wallet6970On 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.7172Override with env var: `ZKGOV_PRIVATE_KEY=0x...`7374The wallet needs testnet HSK for gas (very cheap — 0.001 gwei gas price).7576## Workflow77781. **Check state**: `zkgov-stats` to see proposals/members count792. **Check wallet**: `zkgov-wallet` to see balance and registration803. **Register**: `zkgov-register` (one-time, ~0.0003 HSK gas)814. **Browse**: `zkgov-list-proposals` → `zkgov-proposal` for detail825. **Vote**: `zkgov-vote` with proposalId and choice (generates ZK proof, ~3-5s)836. **Finalize**: `zkgov-finalize` after voting period ends (anyone can call)8485## CLI flags8687- `--json` — machine-readable output on every command88- `zkgov activity --limit 10` — limit activity events89- `zkgov create "Title" -d "Body" -p 86400 -q 3` — set period (seconds) and quorum9091## Key facts9293- **Chain**: HashKey Chain Testnet (ID: 133, RPC: https://testnet.hsk.xyz)94- **Contract**: `0xEa625841E031758786141c8b13dD1b1137C9776C`95- **Explorer**: https://testnet-explorer.hsk.xyz96- **Vote choices**: 0 = Against, 1 = For, 2 = Abstain97- **Nullifiers** prevent double-voting per proposal (hash of identity + proposalId)98- **castVote** does NOT check msg.sender — only the ZK proof matters99- Proof generation uses snarkjs WASM, takes 3-5 seconds100101## Error handling102103- "Already registered" → wallet is already a voter, skip registration104- "Nullifier" error → already voted on this proposal105- "Voting ended" → voting period has closed, try `zkgov-finalize` instead106- "Proposal does not exist" → invalid proposal ID107- Insufficient balance → wallet needs HSK for gas