ZKTally

Privacy-preserving, anonymously verifiable e-voting from linkable ring signatures, Paillier homomorphic encryption, and NIZK vote-correctness proofs.

ZKTally is unaudited academic software implementing a protocol from a student research paper. It has not been reviewed by professional cryptographers and must not be used for any binding election.

A ballot is the triple (ciphertexts, proofs, ring signature):

• Paillier encryption hides the vote. Tallying multiplies ciphertexts and decrypts only the aggregate, so no individual ballot is ever opened.
• A NIZK OR-proof shows the plaintext is a legal vote without revealing which one.
• A linkable ring signature proves the caster is some registered voter, and its deterministic key image makes a second ballot from the same key detectable.

Wire format: zktally/1.

Install

pip install zktally                 # no runtime dependencies
pip install "zktally[fast]"         # optional gmpy2 acceleration

Python 3.11+. The pure-stdlib path works everywhere; gmpy2 is roughly 5x faster on Paillier and must produce byte-identical results.

Library

from zktally import *

pk, sk = paillier_keygen(2048)

# Voters generate their own keys. Nothing else may generate them.
voters = [ring_keygen() for _ in range(5)]
ring = canonical_ring([v.public for v in voters])

params = ElectionParams(
    election_id=new_election_id(),
    title="Adopt the proposal?",
    ballot_type="binary", k=1, candidates=("Yes",),
    public_key=pk, trust_model="single-authority", ring=ring,
)

board = Board(params=params)
for choice, voter in zip([1, 0, 1, 1, 0], voters):
    board.append(cast_ballot(choice, params, voter, ring.index(voter.public)))

print(tally(board, sk).totals)      # (3,)

Multi-candidate elections use ballot_type="one-of-k" with k >= 2, which proves each column binary and proves the columns sum to exactly one.

Command line

zktally keygen   --bits 3072 [--threshold 3-of-5] --out keys/
zktally election new --title "…" --type binary|one-of-k --candidates a,b,c \
                     --key keys/public.json --out params.json
zktally voterkey --out voter.json                      # voter-side only
zktally register --params params.json --add voter*.json
zktally vote     --params params.json --key voter.json --choice 1 --out ballot.json
zktally board    --params params.json --add ballot*.json --out board.json
zktally verify   --board board.json [--explain]
zktally tally    --board board.json --shares s1.json,s2.json --out result.json
zktally audit    --board board.json --result result.json

zktally audit takes no secret material. It re-verifies every ballot and every partial decryption from public data alone, which is what makes public verifiability checkable rather than asserted.

Security properties

✅ achieved · ⚠️ conditional · ❌ not provided

Under trust_model="single-authority" the key holder can decrypt any individual ballot and the published total carries no proof. zktally audit reports that decryption as not proved rather than verified.

v1 uses a trusted dealer for threshold setup: that party transiently knows the factors, so ballot privacy rests on them destroying that material rather than on the threshold itself.

Development

uv venv && uv pip install -e ".[dev]"
pytest                              # full suite
pytest -m "not slow"                # skip real-parameter keygen
ruff check . && ruff format --check .
mypy
zktally vectors generate --seed 00…00 --out tests/vectors/

Test suites: unit/, property/ (Hypothesis), conformance/ (the shared vector corpus, run under both numeric backends), and tamper/ — one test per known attack, each asserting the exact rejection reason.

The corpus in tests/vectors/ is generated here and mirrored into the TypeScript port, which is validated against it. It has exactly one source; hand-editing the mirror is a CI failure.

Relationship to the paper

This implementation is normative where it and the originating paper disagree. The paper states the second OR-proof branch as a discrete-log relation that does not match its own prover, omits R_i and the ring from the ring-signature challenge, leaves the curve, hash, hash-to-curve and point encoding unpinned, and claims receipt-freeness that the construction does not provide.

License

MIT. See LICENSE.