@cheny56/zk-voting-native

@pqc-quorum/zk-voting-native

Zero-Knowledge Voting with Native PQC-Quorum Integration. Optimized for the Groth16 precompile at address 0x16.

Features

• 🚀 Native Precompile Integration - Uses Groth16 verifier at 0x16
• ⚡ Gas-Efficient - Precompile verification costs ~200k gas vs ~5M for Solidity
• 🔧 Go Prover - gnark-based proof generation
• 🔒 MiMC Hash - Compatible with gnark circuits
• 📦 Modular Design - Separate lib for circuits, tallying, and client

Installation

npm install @pqc-quorum/zk-voting-native

Go Prover (Required for proof generation)

# Build the Go prover
cd go && go build -o ../bin/zk-prover .

Quick Start

const { VotingClient, ProofGenerator } = require('@pqc-quorum/zk-voting-native');

// Connect to PQC-Quorum node
const client = new VotingClient('http://localhost:8545', privateKey);

// Cast a vote with native ZK proof
await client.castVote(voterSecret, leafIndex, voteChoice);

Table of Contents

• Overview
• Architecture
• Prerequisites
• Smart Contracts
• Go Prover
• JavaScript Client
• API Reference
• Examples
• Benchmarks
• Comparison with @pqc/zk-voting

Overview

This package provides a ZK voting system optimized for PQC-Quorum nodes with native Groth16 verification:

┌─────────────────────────────────────────────────────────────────────────────┐
│                         NATIVE ZK VOTING FLOW                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌────────────────┐     ┌────────────────┐     ┌────────────────────────┐   │
│  │ JavaScript     │     │ Go Prover      │     │ PQC-Quorum Node        │   │
│  │ Client         │     │ (gnark)        │     │                        │   │
│  └───────┬────────┘     └───────┬────────┘     └───────────┬────────────┘   │
│          │                      │                          │                 │
│          │  1. Prepare inputs   │                          │                 │
│          ├─────────────────────>│                          │                 │
│          │                      │ 2. Generate proof        │                 │
│          │                      │    (gnark Groth16)       │                 │
│          │<─────────────────────┤                          │                 │
│          │  3. Proof bytes      │                          │                 │
│          │                      │                          │                 │
│          │  4. Submit tx ──────────────────────────────────>│                │
│          │                      │                          │                 │
│          │                      │    5. Verify via 0x16 ──>│                │
│          │                      │                          │ (Precompile)   │
│          │<─────────────────────────────────────────────────│                │
│          │  6. Vote recorded    │                          │                 │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Why Native Integration?

Feature	snarkjs (Solidity)	Native (Precompile)
Verification Gas	~5,000,000	~200,000
Proof Gen Speed	~2-5 seconds	~200ms
Trusted Setup	Required	Pre-deployed
Hash Function	Poseidon	MiMC
Best For	Any EVM chain	PQC-Quorum

Prerequisites

• Node.js >= 18.0.0
• Go >= 1.21 (for proof generation)
• PQC-Quorum node with ZK precompiles enabled

Smart Contracts

Contract Overview

Contract	Address	Description
VoterRegistry	Deployed	Merkle tree of eligible voters
ZKBallot	Deployed	Main voting with precompile verification
TallyManager	Deployed	Tallying orchestration
IZKPrecompile	0x16	Native Groth16 verifier

VoterRegistry.sol

// Register voters (admin only)
function registerVoter(bytes32 commitment) external;
function registerVotersBatch(bytes32[] calldata commitments) external;
function closeRegistration() external;

// Query state
function merkleRoot() external view returns (bytes32);
function getVoterCount() external view returns (uint256);

ZKBallot.sol

// Cast vote with native ZK verification
function castVote(
    bytes calldata proof,           // Groth16 proof bytes
    bytes calldata publicInputs,    // [merkleRoot, nullifier, commitment, count]
    bytes[] calldata encryptedVote  // For homomorphic tally (optional)
) external;

// End voting
function endVoting() external;

// Query
function getTotalVotes() external view returns (uint256);
function nullifierUsed(bytes32) external view returns (bool);

Native ZK Precompile

The precompile at 0x16 provides efficient Groth16 verification:

interface IZKPrecompile {
    function verifyGroth16(
        bytes32 vkHash,        // Hash of verification key
        bytes calldata proof,   // 8 G1/G2 elements (256 bytes)
        bytes calldata inputs   // Public inputs (32 bytes each)
    ) external view returns (bool);
}

Go Prover

The Go prover uses gnark for Groth16 proof generation.

Circuit Definition

// go/circuit/vote_circuit.go
type VoteCircuit struct {
    // Private inputs
    VoterSecret    frontend.Variable
    VoterLeafIndex frontend.Variable
    MerklePath     [20]frontend.Variable
    PathIndices    [20]frontend.Variable
    VoteChoice     frontend.Variable
    VoteSalt       frontend.Variable

    // Public inputs
    MerkleRoot     frontend.Variable `gnark:",public"`
    Nullifier      frontend.Variable `gnark:",public"`
    VoteCommitment frontend.Variable `gnark:",public"`
    CandidateCount frontend.Variable `gnark:",public"`
}

Building the Prover

cd go
go mod tidy
go build -o ../bin/zk-prover .

Using the Prover

# Generate proof
./bin/zk-prover prove \
    --secret 0x1234... \
    --leaf-index 5 \
    --merkle-path 0xabc...,0xdef...,... \
    --path-indices 0,1,0,... \
    --vote-choice 2 \
    --vote-salt 0x5678... \
    --merkle-root 0x9abc... \
    --candidate-count 4

# Outputs: proof.bin, public_inputs.json

JavaScript Client

VotingClient

High-level client for the complete voting flow:

const { VotingClient } = require('@pqc-quorum/zk-voting-native');

const client = new VotingClient('http://localhost:8545', privateKey);

// Deploy contracts
await client.deployVoterRegistry();
await client.deployZKBallot(candidates, duration, vkHash);
await client.deployTallyManager();

// Admin: Register voters
await client.registerVoters([commitment1, commitment2, ...]);
await client.closeRegistration();

// Voter: Cast vote
await client.castVote({
    voterSecret: BigInt('0x...'),
    leafIndex: 5,
    voteChoice: 2,
    candidateCount: 4,
});

// Query state
const totalVotes = await client.getTotalVotes();
const candidates = await client.getCandidates();

ProofGenerator

JavaScript wrapper for the Go prover:

const { ProofGenerator } = require('@pqc-quorum/zk-voting-native');

const prover = new ProofGenerator({
    proverPath: './bin/zk-prover',
    circuitPath: './circuits/vote.r1cs',
    pkPath: './keys/proving.key',
});

// Generate proof
const { proof, publicInputs } = await prover.generateProof({
    voterSecret,
    leafIndex,
    merklePath,
    pathIndices,
    voteChoice,
    voteSalt,
    merkleRoot,
    candidateCount,
});

API Reference

VotingClient

class VotingClient {
    constructor(rpcUrl: string, privateKey: string);
    
    // Deployment
    deployVoterRegistry(): Promise<Contract>;
    deployZKBallot(
        candidates: string[],
        durationSeconds: number,
        vkHash: string
    ): Promise<Contract>;
    deployTallyManager(): Promise<Contract>;
    
    // Connect to existing
    connectVoterRegistry(address: string): void;
    connectZKBallot(address: string): void;
    connectTallyManager(address: string): void;
    
    // Admin functions
    registerVoter(commitment: string): Promise<TransactionReceipt>;
    registerVoters(commitments: string[]): Promise<TransactionReceipt>;
    closeRegistration(): Promise<TransactionReceipt>;
    
    // Voting
    castVote(params: CastVoteParams): Promise<{
        nullifier: string;
        voteCommitment: string;
        txHash: string;
    }>;
    
    // Queries
    getMerkleRoot(): Promise<string>;
    getTotalVotes(): Promise<bigint>;
    getCandidates(): Promise<Candidate[]>;
    isNullifierUsed(nullifier: string): Promise<boolean>;
    getVoteCommitments(): Promise<string[]>;
    
    // Tallying
    endVoting(): Promise<TransactionReceipt>;
    submitHomomorphicTally(tally: number[]): Promise<TransactionReceipt>;
}

interface CastVoteParams {
    voterSecret: bigint;
    leafIndex: number;
    voteChoice: number;
    candidateCount: number;
}

Lib Exports

const {
    // Crypto
    mimcHash,
    bigIntToHex32,
    hex32ToBigInt,
    
    // Merkle Tree
    MerkleTree,
    
    // Vote Proof
    generateVoteProofInputs,
    TREE_DEPTH,
    
    // Tally
    RevealTally,
    HomomorphicTally,
    PaillierCrypto,
} = require('@pqc-quorum/zk-voting-native/lib');

MerkleTree

const { MerkleTree, mimcHash } = require('@pqc-quorum/zk-voting-native/lib');

// Create tree
const tree = new MerkleTree(20); // depth 20

// Add leaves
await tree.addLeaf(commitment1);
await tree.addLeaf(commitment2);

// Get root
const root = tree.getRoot();

// Generate proof
const { pathElements, pathIndices } = await tree.generateProof(commitment, index);

Examples

Complete Voting Flow

const {
    VotingClient,
    ProofGenerator,
    MerkleTree,
    mimcHash,
    bigIntToHex32,
} = require('@pqc-quorum/zk-voting-native');

async function completeVotingExample() {
    // Setup
    const rpcUrl = 'http://localhost:8545';
    const adminKey = process.env.ADMIN_PRIVATE_KEY;
    const candidates = ['Alice', 'Bob', 'Charlie'];
    
    // Initialize client
    const client = new VotingClient(rpcUrl, adminKey);
    
    // Deploy contracts
    console.log('Deploying contracts...');
    await client.deployVoterRegistry();
    await client.deployZKBallot(candidates, 3600, VK_HASH);
    await client.deployTallyManager();
    
    // Register voters
    const voters = [];
    const tree = new MerkleTree(20);
    
    for (let i = 0; i < 10; i++) {
        const secret = BigInt(crypto.randomBytes(32).toString('hex'), 16);
        const commitment = await mimcHash(secret);
        voters.push({ secret, commitment, index: i });
        await tree.addLeaf(commitment);
    }
    
    const commitments = voters.map(v => bigIntToHex32(v.commitment));
    await client.registerVoters(commitments);
    await client.closeRegistration();
    
    console.log(`Registered ${voters.length} voters`);
    console.log(`Merkle root: ${bigIntToHex32(tree.getRoot())}`);
    
    // Cast votes
    for (const voter of voters) {
        const voteChoice = Math.floor(Math.random() * candidates.length);
        
        const result = await client.castVote({
            voterSecret: voter.secret,
            leafIndex: voter.index,
            voteChoice,
            candidateCount: candidates.length,
        });
        
        console.log(`Vote cast: ${result.txHash}`);
    }
    
    // End voting and get results
    await client.endVoting();
    const totalVotes = await client.getTotalVotes();
    console.log(`Total votes: ${totalVotes}`);
}

Local Testing with Mock Prover

const { VotingClient, MockProofGenerator } = require('@pqc-quorum/zk-voting-native');

// Use mock prover for testing (no Go required)
const client = new VotingClient(rpcUrl, privateKey, {
    proofGenerator: new MockProofGenerator(),
});

Benchmarks

Run benchmarks with:

npm run benchmark

Results (PQC-Quorum Testnet)

Operation	Time	Gas
Proof Generation	~200ms	-
On-chain Verification	-	~200,000
Vote Registration	~50ms	~45,000
Full Vote Cast	~300ms	~250,000

Comparison

Metric	Native (gnark)	snarkjs
Proof Gen	200ms	2-5s
Verify Gas	200k	5M+
Setup	Pre-deployed	Custom

Comparison

When to use which package?

Use Case	Recommended Package
PQC-Quorum node	@pqc-quorum/zk-voting-native
Any EVM chain	@pqc/zk-voting
Maximum portability	@pqc/zk-voting
Maximum performance	@pqc-quorum/zk-voting-native
No Go environment	@pqc/zk-voting

Feature Matrix

Feature	@pqc/zk-voting	@pqc-quorum/zk-voting-native
ZK System	Circom/snarkjs	gnark/Groth16
Hash Function	Poseidon	MiMC
Verification	Solidity	Precompile (0x16)
Proof Generation	JavaScript	Go
EVM Compatibility	Any	PQC-Quorum
Gas Cost	~5M	~200k
Trusted Setup	Custom	Pre-deployed
Homomorphic Tally	✓	✓
Reveal-Based Tally	✓	✓

Development

# Install dependencies
npm install

# Build Go prover
npm run compile-go

# Run example
npm run example

# Run benchmarks
npm run benchmark

License

MIT

Related Packages

• @pqc/zk-voting - Portable ZK voting with snarkjs
• @pqc-quorum/zk-client - ZK RPC client for PQC-Quorum nodes