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 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-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.4---56# ZKGov78ZKGov 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.910## Install1112```bash13# MCP server (preferred — works with Claude Code, Cursor, Windsurf, VS Code)14# https://www.npmjs.com/package/@zkgov/mcp15claude mcp add zkgov npx @zkgov/mcp1617# Standalone CLI18# https://www.npmjs.com/package/@zkgov/cli19npm install -g @zkgov/cli20zkgov --help21```2223## Mode priority24251. **MCP tools first.** If tools prefixed `mcp__zkgov__*` are available, call them directly.262. **CLI fallback.** If no MCP tools are available, run `zkgov <command>` via the Bash tool.273. **`--json` flag.** Always use `--json` when calling CLI from an agent for reliable parsing.2829## When to use3031- User asks about governance proposals, voting, or on-chain governance32- User wants to create, vote on, or check proposals33- User asks about voter registration or ZK identity34- User asks about HashKey Chain governance activity35- User wants an agent to participate in governance autonomously3637## When NOT to use3839- General blockchain questions answerable from training data40- Questions about other chains or protocols41- Math, code review, or general programming tasks4243## Available tools4445### Read tools (no wallet needed)4647| MCP Tool | CLI Command | Description |48|---|---|---|49| `zkgov-stats` | `zkgov stats` | Platform stats: total proposals, members, group ID |50| `zkgov-list-proposals` | `zkgov proposals` | List all proposals with vote tallies and status |51| `zkgov-proposal` | `zkgov proposal <id>` | Full proposal detail by ID |52| `zkgov-check-voter` | `zkgov voter <address>` | Check if address is a registered voter |53| `zkgov-members` | `zkgov members` | Semaphore group info: member count, Merkle root |54| `zkgov-activity` | `zkgov activity` | Recent on-chain events with tx hashes |5556### Write tools (require wallet with HSK for gas)5758| MCP Tool | CLI Command | Description |59|---|---|---|60| `zkgov-wallet` | `zkgov wallet` | Show agent wallet: address, balance, voter status |61| `zkgov-register` | `zkgov register` | Register wallet as voter (one-time on-chain tx) |62| `zkgov-create-proposal` | `zkgov create <title>` | Create a governance proposal |63| `zkgov-vote` | `zkgov vote <id> <choice>` | Cast anonymous ZK-verified vote |64| `zkgov-finalize` | `zkgov finalize <id>` | Finalize proposal after voting period ends |6566## Wallet6768On 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.6970Override with env var: `ZKGOV_PRIVATE_KEY=0x...`7172The wallet needs testnet HSK for gas (very cheap — 0.001 gwei gas price).7374## Workflow75761. **Check state**: `zkgov-stats` to see proposals/members count772. **Check wallet**: `zkgov-wallet` to see balance and registration783. **Register**: `zkgov-register` (one-time, ~0.0003 HSK gas)794. **Browse**: `zkgov-list-proposals` → `zkgov-proposal` for detail805. **Vote**: `zkgov-vote` with proposalId and choice (generates ZK proof, ~3-5s)816. **Finalize**: `zkgov-finalize` after voting period ends (anyone can call)8283## CLI flags8485- `--json` — machine-readable output on every command86- `zkgov activity --limit 10` — limit activity events87- `zkgov create "Title" -d "Body" -p 86400 -q 3` — set period (seconds) and quorum8889## Key facts9091- **Chain**: HashKey Chain Testnet (ID: 133, RPC: https://testnet.hsk.xyz)92- **Contract**: `0xEa625841E031758786141c8b13dD1b1137C9776C`93- **Explorer**: https://testnet-explorer.hsk.xyz94- **Vote choices**: 0 = Against, 1 = For, 2 = Abstain95- **Nullifiers** prevent double-voting per proposal (hash of identity + proposalId)96- **castVote** does NOT check msg.sender — only the ZK proof matters97- Proof generation uses snarkjs WASM, takes 3-5 seconds9899## Error handling100101- "Already registered" → wallet is already a voter, skip registration102- "Nullifier" error → already voted on this proposal103- "Voting ended" → voting period has closed, try `zkgov-finalize` instead104- "Proposal does not exist" → invalid proposal ID105- Insufficient balance → wallet needs HSK for gas
Lord1Egypt