Government · Voting · Registration · Universal verifiability · Bring-your-own-identity
A complete design for running a public election on Quidnug:
voter registration, poll books, ballot anonymity, universal
verifiability, and instant recount, with no central database
anyone has to trust, no proprietary voting machine, and a
paper-ballot fallback that cryptographically matches the
digital record.
This README covers the protocol-level semantics. The
companion docs cover the operational story that turns this
design into a deployable system:
integration.md, how the design
composes on top of the three architectural pillars (QDPs
0012 / 0013 / 0014). The governance, multi-jurisdictional
federation, and operational topology layers this README
only sketches.
operations.md, deployment at five
scales (pilot to federal), capacity planning, election-day
operations, incident response, cost analysis.
If you’re new to Quidnug as a whole, read
../ARCHITECTURE.md first, it
places the elections use case in the broader protocol
context. Elections is the most complex worked example of a
coordination-archetype use case; its depth of trust-edge
semantics and multi-party governance pushes the protocol
harder than any other use case in the library.
The problem
US elections today are run on a patchwork of systems:
Voter registration databases sit in each state’s SOS
office. The voter has to trust that the DB hasn’t been edited,
corrupted, or subjected to a data-entry error.
Poll books at each precinct are either printed that morning
(static, can’t be rechecked during the day) or “electronic poll
books” running vendor software the public cannot audit.
Voting machines run closed-source firmware. Public’s ability
to verify their behavior is negligible.
Counting is done by proprietary tabulation software. Recounts
require physical re-scanning of paper ballots on the same
machines, i.e. re-running the same vendor software.
The public audit story is “trust the bipartisan election
boards and approved vendors.” Which is reasonable but obviously
not cryptographically verifiable.
Independent observers, candidates losing close races, and
ordinary citizens have no technical path to:
Personally verify the voter roll is correct.
Know that poll books at a specific precinct match the authorized
voter list.
Verify their own vote was recorded as cast and counted as
recorded.
Recount an election themselves without waiting for officials.
Audit a single ballot from paper through to final tally.
Quidnug’s primitives, signed trust edges, per-signer monotonic
nonces, guardian-recoverable keys, per-observer relational trust,
and public append-only event streams, map directly onto what an
election protocol needs. This document specifies a complete
design.
Design principles
Before the mechanics, here’s what the design commits to:
Property
Commitment
Secret ballot
No party can correlate a specific cast vote with the voter who cast it, not even the election authority.
Universal verifiability
Any member of the public can cryptographically verify the tally from primary data. No special access.
Individual verifiability
Every voter can verify their own vote was counted as they intended, from their own records.
Eligibility verification
Only registered voters can cast ballots; every ballot cast traces to an eligibility attestation.
One voter, one vote
Cryptographic double-vote prevention; no “poll worker discovers it later.”
Bring-your-own-identity
Voter’s cryptographic identity is generated by the voter, not issued by the authority.
Paper-ballot parity
Every digital vote has a paper-ballot equivalent printed at cast time and deposited in a ballot box.
Recount on demand
Anyone, candidate, journalist, citizen, can run a full recount in seconds from the public chain.
Coercion resistance
(Trade-off, addressed in §11.) A voter should not be able to cryptographically prove to a third party how they voted.
Tamper-evident audit
Every protocol action is signed and append-only; after-the-fact edits leave evidence.
These aren’t aspirations. Each maps to specific mechanisms below.
The 5 quid types in an election
Quidnug elections use five distinct kinds of quids. Keeping them
separate is what gives the design its properties.
1. Election Authority Quid (election-authority-*)
The government body running the election. Examples:
election-authority-williamson-county-tx-2026-nov
election-authority-state-of-ohio-2028-primary
Each election is its own quid, a new quid per election cycle
rather than one persistent “elections office” quid. This scopes
authority cleanly: a fresh election’s keys can’t be used to
manipulate a prior election’s records.
Under QDP-0012 Domain Governance,
the authority’s authority-to-act is expressed through two
distinct mechanisms that the original version of this document
conflated. Both are needed; they do different things.
Governor quorum for the election’s domains (QDP-0012): the
humans / institutions authorized to vote on changes to the
consortium roster + parameters of the election’s domain tree.
Typically:
Chief election official (e.g., county clerk)
State Secretary of State office
Bipartisan oversight board (one D-aligned, one R-aligned, one independent)
Panel of independent election observers (League of Women Voters, etc.)
Recommended structure: 7 governors with weighted votes, 5-of-7
weighted quorum for routine governance actions, unanimous for
UPDATE_GOVERNORS. Notice period 72 hours normally; with a
pre-negotiated 1-hour emergency-notice clause active during the
week of the election for REMOVE_VALIDATOR actions against
compromised consortium members. See
integration.md §2 for the concrete setup.
Guardian quorum per governor key (QDP-0002): each individual
governor’s cryptographic identity has its own M-of-N guardian
set for recovering a lost or compromised key. Guardians are
independent parties trusted for that specific role (spouse,
lawyer, federal monitor, state ethics officer, etc.), not the
same people as the governor quorum. Losing a governor’s key
doesn’t lose their position, guardians rotate the key to a
fresh one, typically over a 24-hour time-lock.
The two mechanisms serve different purposes: governor quorum
authorizes policy changes; guardian quorum recovers individual
keys. Elections need both.
2. Voter Registration Quid (VRQ)
One per registered voter. Generated by the voter, not issued
by the authority (this is the Bring-Your-Own-Quid principle).
Voter generates a keypair on their device (phone, hardware
token, or at a voter-registration kiosk under their control).
The quid ID is sha256(voter's public key)[:16].
Voter keeps the private key; the authority never sees it.
VRQ attributes (public):
precinctID
registeredParty (for primary elections)
registrationYear
Nothing else, no SSN, no address, no DOB on-chain.
Real-world identity (name, address, DOB) is held off-chain by
the election authority in a separate secure database, mapped
one-way to the VRQ. Queries like “is this quid registered?” are
public; queries like “what is this quid’s name?” require the
off-chain DB and legitimate access.
3. Ballot Quid (BQ)
One per voter per election, but generated fresh at voting
time, not persistent.
Anonymous by construction.
No on-chain link to the VRQ it corresponds to.
Voter generates it locally; the authority signs a blind
attestation that it is eligible to vote (see §6 below).
The BQ is how the voter actually votes. It casts trust edges to
candidates/options.
4. Contest Quid
One per contest on the ballot. A “contest” is a single voting
decision.
One per candidate or ballot option. Candidates are real quids
(generated by the candidate themselves when they filed candidacy);
ballot options like “YES” and “NO” on propositions are
well-known quids per jurisdiction (e.g.,
option-yes-williamson-2026 and option-no-williamson-2026).
A write-in candidate’s quid can be issued on-the-spot by a voter
who specifies a name; write-ins are flagged differently in the
tally.
Domain hierarchy
Everything election-related lives under a carefully-scoped
namespace:
Each domain has its own consortium (the election authority
observer organizations running physical nodes that produce
blocks; see QDP-0012
for the cache-replica / consortium-member / governor role
separation). Consortium membership is granted by on-chain
ADD_VALIDATOR governance transactions signed by the governor
quorum, not self-declared, new operators join the consortium
by policy action, not by spinning up a node.
Vote edges in contests.us-senate only count if the edge
signer (the BQ) has a valid ballot issuance in
ballot-issuance. This eligibility check is cryptographic and
runs at tally time; nothing in the consortium can bypass it.
Cache replicas (typically precinct polling-place devices
plus any observer / journalist / candidate running a mirror)
trust the consortium, mirror the agreed chain locally, serve
reads, and relay transactions, but do not produce blocks.
This keeps the number of block-producing nodes small and
governance-controlled while letting the read-serving
infrastructure scale out cheaply.
Replacing the voter registration system
Today’s voter registration is a centralized state database. In
Quidnug it’s a public, append-only set of trust edges from the
election authority to voter quids.
Registration flow (Bring-Your-Own-Quid)
Step 1. Voter generates a quid
────────────────────────────────
On their phone, hardware token, or at a voter-registration
kiosk they physically control:
$ quidnug-voter generate
Your quid ID: a1b2c3d4e5f67890
Save your private key: <securely stored locally>
The voter's private key never leaves their device.
Step 2. Voter visits a registrar
────────────────────────────────
Brings: driver's license / passport / other identity document.
Registrar verifies real-world identity.
Registrar enters into their internal system:
- Name, DOB, address (off-chain DB)
- Voter's quid ID (from QR code / NFC from voter's device)
- Precinct (derived from address)
- Party affiliation (if applicable)
Step 3. Registrar issues the registration
────────────────────────────────
The election authority's signing service emits a trust edge:
The voter did not need to visit the registrar's website or
trust their proprietary portal. Any Quidnug node has the same
answer.
How bring-your-own-quid defends against malfeasance
Because the voter generates the quid, the authority cannot:
Assign a voter a quid they control (and vote as that voter).
If the authority tried, the voter would detect it, their
registered quid wouldn’t match the public key they generated.
Silently change a voter’s quid (de-registering them).
Any modification to the registration trust edge requires the
authority’s current-epoch signature. A change without a
corresponding event on the voter’s stream is auditable.
Deny registration arbitrarily. If the authority refuses to
issue the trust edge, the voter has a cryptographic record of
their attempt (they submitted their quid and ID) and the
refusal is visible to observers.
The authority CAN legitimately deny registration for cause
(ineligibility, duplicate), but that denial is documented as
a signed event, not a silent database omission.
Anyone can count registered voters
Terminal window
# Anyone, from any Quidnug node with visibility into the domain:
This number matches the authority’s count, because it is the
authority’s count. There is no separate “authoritative database”
that could disagree.
Replacing poll books
A poll book is the per-precinct list of voters authorized to cast
ballots at that precinct. In Quidnug, this is not a separate
document, it’s a query against the registration trust edges
filtered by precinct.
Terminal window
# Poll book for precinct 042, as used by a poll worker's tablet
This returns every VRQ registered at precinct 042. The poll
worker’s tablet caches this for the morning and refreshes
throughout the day via push gossip (QDP-0005). Unlike printed
poll books, the digital poll book reflects late registrations
and corrections in real time.
Check-in at the polling place
When a voter arrives:
Step 1. Voter identifies themselves
Shows driver's license or other ID.
Poll worker looks up off-chain by name → retrieves associated
VRQ (e.g., "voter-a1b2c3d4e5f67890").
Alternative: voter scans a QR code from their wallet app that
contains their VRQ ID + a freshly-signed challenge proving they
hold the private key.
Step 2. Poll worker's tablet verifies eligibility
Queries the local Quidnug node:
"Does voter-a1b2c3d4e5f67890 have a registration trust edge in
precinct 042 for this election, and is it active?"
Additionally checks:
"Does this VRQ have a `voter.voted` event for this election?"
If yes → voter has already voted; reject (or route to provisional
if they claim otherwise).
Step 3. Poll worker emits a check-in event
(ONLY a "voted" flag, reveals nothing about what they voted for)
The voter.checked-in event is public but only reveals the
fact of voting, not the contents. This is equivalent to the
“I voted” sticker and the public fact of showing up to the polls.
Some jurisdictions prefer not to record even this; the protocol
supports both modes via an election-authority config flag.
Ballot anonymity: the blind-signature issuance flow
This is the critical piece. The voter is already publicly
checked-in. Now we need them to cast a vote that cannot be
correlated with their VRQ, while still proving the vote is
authorized.
The mechanism is a blind signature: the election authority
signs an attestation that a specific Ballot Quid (BQ) is
authorized to vote, but the authority never learns which BQ it
signed.
Cryptographic primer (blind signature, in plain language)
Think of a blind signature as an opaque envelope with carbon
paper inside.
Voter writes their BQ’s ID on a piece of paper, seals it in
the envelope.
Authority signs the outside of the envelope. The signature
bleeds through the carbon paper onto the BQ ID inside.
Voter opens the envelope. Their BQ ID now has the authority’s
signature on it, but the authority never saw the ID itself.
Cryptographically: voter generates BQ ID bq_id, picks a random
blinding factor r, computes blind(bq_id, r) = commitment.
Authority signs commitment. Voter computes
unblind(signature, r) = valid-signature(bq_id). Authority’s
signature is on bq_id but they never saw bq_id unblinded.
Quidnug uses ECDSA P-256; blind signatures on ECDSA curves are
well-studied (RSA blind signatures are the classical form;
Schnorr and EC variants exist). An election-authority node runs
a Ballot Issuance Service that implements the blind-signature
protocol.
Ballot issuance flow
Step 1. Voter's device generates a fresh BQ
Happens inside the voting booth or on the voter's phone in a
private polling place kiosk.
$ quidnug-voter-booth generate-ballot-quid
BQ ID: ballot-Xz7mN2pQ8rK4vL9t
BQ private key: <stored locally, in voter's wallet app>
Voter may generate multiple BQs, one per contest, or one per
election, depending on jurisdiction. Using separate BQs per
This is a valid authority signature on the BQ_ID that nobody
else has ever seen, including the authority.
Step 5. Voter's BQ now has its eligibility attestation
Locally, the voter's device builds:
BQ "identity transaction":
quidId: "ballot-Xz7mN2pQ8rK4vL9t"
publicKey: <BQ's public key>
creator: "election-authority-williamson-2026-nov"
attributes:
electionId: ...
contestId: "contests.us-senate"
issuanceEpoch: 0
signature_from_authority: <unblinded_sig>
This identity transaction can be submitted to a Quidnug node
to register the BQ. The authority's signature verifies as
normally, they signed it, even though they don't know they did.
Why this works
Anonymity: The authority signed the commitment but not the
BQ ID. Anyone (including the authority, a subpoena’d authority,
a hacked authority) cannot correlate BQs back to VRQs. The
blinding factor is only on the voter’s device.
Uniqueness: The authority saw the VRQ + contest combination
and the nullifier. If the voter tries to request another ballot
for the same contest, the nullifier is already seen → rejected.
One ballot per (VRQ, contest).
Authority compromise-resistant: Even if the authority’s
signing key is stolen and the attacker tries to forge ballots,
they can’t retroactively attach themselves to an already-cast
BQ. Rotation + invalidation of the compromised epoch are
standard Quidnug responses.
Mail-in / absentee variant
Same flow. Voter receives a mail-in ballot packet that contains:
A URL / QR to the issuance service.
Instructions to generate a BQ on their home computer.
Their identity challenge (based on registered info).
The blind-signature flow happens over HTTPS. Voter casts votes
online, then prints a paper confirmation that gets mailed back
(see §9 Paper-ballot parity).
Casting a vote: “trust” as the voting primitive
Once the voter has a BQ with an authority-signed eligibility
attestation, casting a vote is a trust edge from the BQ to a
candidate.
When the tally engine counts trust edges in a contest’s domain,
it applies these checks for each edge:
Truster must be a valid BQ. The truster quid’s identity
transaction must be signed by the election authority’s key
for this election. (Rules out random people trying to vote
as imaginary BQs.)
BQ must have a ballot.issued event on a VRQ. Wait, no,
the BQ has no link to a VRQ. What the tally verifies is that
the BQ’s identity transaction carries a valid authority
signature (the unblinded one from issuance). That’s the
eligibility proof.
One trust edge per BQ per contest (for plurality) / edges
match the contest’s voting method (for ranked / approval).
Domain matches the contest.
Signed with the BQ’s private key and well-formed.
If any check fails → the edge doesn’t count.
Paper-ballot parity
Digital-only voting is a hard sell, and rightly so. The design
gives every digital vote a paper-ballot counterpart.
At the in-person polling place
Voting booth has a printer. When the voter finishes casting their
BQ’s trust edges (steps above), the booth:
Prints a paper ballot with:
The voter’s BQ ID printed as QR + human-readable hex.
A table of contests and the votes cast.
The authority’s signed issuance attestation as QR.
A ballot sequence number.
The voter reviews the paper ballot.
Voter drops the ballot into a physical ballot box.
At the end of the day, the physical ballot box is opened and
every paper ballot is hand-scanned (or can be hand-verified
visually). Each paper ballot has a BQ ID. Cross-verification:
Every scanned paper BQ ID should have a matching set of trust
edges in the digital chain.
Every digital BQ that voted should have a matching paper
ballot in the box.
Any mismatch is a discovered discrepancy, investigated per
jurisdiction procedure.
Because the BQ is pseudonymous (anonymous to the authority, but
the voter’s own device can identify their own ballot), the voter
can privately verify the paper ballot in the box matches their
digital vote (by retrieving their own BQ ID).
What this gives us that pure-paper doesn’t
Traditional paper ballots: counted by hand or by the same
proprietary tabulator each time. A recount re-counts the same
pile of paper by the same process.
Quidnug paper ballots: every paper ballot has a public
digital counterpart. A recount can be done by:
Re-scanning paper and comparing to digital.
Re-running the digital tally from the chain (takes seconds).
Comparing two digital tallies from two independent Quidnug
nodes (they should agree exactly).
Hand-counting paper per standard procedures.
All four should agree. Disagreement points to a specific
discrepancy that can be investigated, not “the machine said so.”
What this gives us that pure-digital doesn’t
A skilled attacker could, in principle, compromise enough
validators or gossip nodes to attempt to manipulate the digital
record. The paper ballots are the ground truth:
If every paper ballot cross-references a digital record, and
the digital tally matches paper hand-count, the election is
verified.
If they disagree, the paper wins. The digital chain is a
convenience layer for instant tally, not the ultimate record.
Counting and recounts
This is where Quidnug shines. A recount is a trivial query.
Official initial tally
Pollclose time. The election authority runs the tally from its
own view of the chain:
Terminal window
# Pseudocode, actual implementation in §Implementation
Any member of the public with access to a Quidnug node serving
this election’s domain can run the exact same query. The node
returns the same edges. The grouping produces the same counts.
Terminal window
# From a citizen's laptop running a read-only Quidnug node
$# The result is deterministic given the chain state. Independent
$# nodes will produce byte-identical tallies.
Candidate recounts: the losing candidate’s team runs their
own Quidnug node, fetches the chain, and tallies themselves.
No “wait for the Secretary of State to authorize a recount.”
No “re-feed paper through the same tabulator.”
Multiple-node agreement: by running the tally on 10 independent
Quidnug nodes, the candidate’s team verifies the chain itself
hasn’t been tampered with. If 10 nodes agree on 51,039 for Jones,
that’s cryptographic evidence of the network consensus, not
“the SOS said so.”
Discovered discrepancies
If a candidate’s independent tally disagrees with the authority’s
declared result, that’s a major red flag. Two causes:
Chain tampering somewhere, investigated via cross-node
comparison. Quidnug’s K-of-K bootstrap (QDP-0008) and cross-
node gossip (QDP-0005) make undetected tampering hard.
Tally-method interpretation differences, contest-specific
rules (e.g., how ranked-choice instant-runoff handles
exhausted ballots) should be explicit in the contest’s
attributes. Any ambiguity is a contest-specification bug.
Individual voter verification
Every voter can verify, from their own records, that their vote
was cast and counted as they intended.
After voting, the voter’s device retains:
Their BQ ID(s) and private key(s).
The authority’s issuance attestation.
A local record of the trust edges they cast (which candidates,
which contests).
Confirms the authority’s tally included those edges.
Knows this from reading the public chain, no special portal
required.
Coercion-resistance trade-off
The same verifiability that lets a voter check their own vote
can also be misused by a coercer: “Show me your BQ private key
so I can verify you voted the way I told you to.”
Mitigations (any jurisdiction can choose their level):
Do-nothing mitigation: accept that coercion happens, rely
on criminal penalties + witness protection + ballot-booth
privacy. This is what most current systems do.
Multiple-ballot receipts: voter’s device generates N
plausible BQs, only one of which is cast. Voter can show the
coercer any of the N, so the coercer can’t distinguish the
real vote from the decoys. Requires careful UI design.
Revocable ballots: voter can re-cast later, only the last
ballot counts. Coercion pressure is limited to final deadline.
Trade-off: operational complexity + late-vote issues.
Homomorphic voting (future research): the tally is computed
over encrypted ballots; individual ballots are never revealed.
Voter’s receipt shows only “my ballot was counted” but not
what it was. Requires protocol extension beyond Quidnug’s
current primitives.
The v1 recommended approach: mechanism #2 (multiple decoy BQs)
combined with mechanism #1 (legal protections). Decoy BQs don’t
cast votes, they’re generated for receipt-freeness only. The
voter’s actual cast BQ is chosen privately.
Party affiliation and primaries
US primary elections are party-scoped. Registered Democrats vote
in the Democratic primary; registered Republicans in the
Republican primary; unaffiliated voters (in some states) get to
choose.
In Quidnug:
Party-scoped trust edges
The voter’s registration trust edge includes a registeredParty
attribute:
Unaffiliated voter in open-primary state → they pick at issuance; their choice is recorded in an event, the issuance proceeds on that party's side
This enforces party-appropriate voting at the cryptographic level
not just “the UI doesn’t show you the other party’s contests.”
Party-change during the year
Voter can change party affiliation between elections. This
updates their registration trust edge (authority issues a new
edge with a higher nonce and the new party attribute). Old
edges are historical record; current attribute governs primary
eligibility.
Ballot measures, judges, local offices
All of these are just contests.
Proposition: contest with candidates = option-yes and
option-no quids.
Retention-judge question: same (yes/no pair).
School board (single-winner plurality): contest with 4
candidate quids.
Ranked-choice mayoral: contest with votingMethod: ranked-choice-irv.
Multi-member city council (vote-for-three): contest with
votingMethod: approval and maxApproved: 3.
The voting primitive (trust edges from BQ to options) is the
same. The contest’s votingMethod attribute dictates how the
tally engine interprets the edges.
Write-in candidates
A voter wants to write in “Mickey Mouse” for Sheriff. The
voting booth:
Displays a write-in field.
Voter types “Mickey Mouse.”
Booth generates a one-off write-in candidate quid:
candidate-write-in-williamson-2026-sheriff-<hash of name>
Identity transaction registers the write-in with attribute
isWriteIn: true, writtenName: "Mickey Mouse".
Trust edge from BQ → write-in quid casts the vote.
At tally, the election authority:
Groups trust edges by trustee as usual.
Flags write-in trustees separately in the results.
If a write-in candidate receives enough votes to potentially
win or qualify for further consideration, the name is reviewed
for consistency (normalizing “Mickey Mouse” vs. “Mike E. Mouse”).
Push gossip (QDP-0005): real-time propagation of events
across precincts, state, and observer nodes.
K-of-K bootstrap (QDP-0008): fresh observer nodes seed from
a quorum of trusted precinct + state nodes.
Fork-block (QDP-0009): coordinate protocol changes between
elections (e.g., “all 2028 elections must use version 2 of
ballot format”).
Lazy epoch probe (QDP-0007): detect stale authority-key
signatures at cross-jurisdiction boundaries.
Relational trust: observers can personalize their trust in
precinct validators.
Value delivered
Dimension
Today
Quidnug
Voter verifies they’re registered
State website + call-back
Public chain query in 1 second
Voter verifies their own vote
Not possible
Private record + chain query
Public verifies voter roll
FOIA request
Public chain query
Public does a recount
Not possible
Run a query
Candidate recount
Official process, weeks
Independent tally from chain, seconds
Cross-precinct verification
State aggregation (trust SOS)
Any node sees all precincts
Tamper detection
Paper audit after-the-fact
Immediate cross-node discrepancy detection
Voter identity forgery resistance
Database controls
Cryptographic (authority-signed trust edge)
Double-voting resistance
Poll-book check (same day)
Nullifier-enforced cryptographically
Ballot issuance transparency
”Trust the vendor”
Signed issuance events, per-VRQ, auditable
Cost of audit
Per-jurisdiction audit firms
Zero, any citizen can run the same queries
What’s in this folder
The elections use case is the most detailed in the library.
Six files cover the full lifecycle from design to go-live:
README.md, this document. Protocol-level
semantics: quid types, trust edges as votes, blind
signatures, paper parity, recount, etc.
architecture.md, data model, domain
hierarchy, event schemas, sequence diagrams.
implementation.md, concrete API
flows for each role (voter, registrar, poll worker, tally
engine).
integration.md, how the election
design composes on top of the three architectural pillars
(QDPs 0012 Domain Governance, 0013 Network Federation,
0014 Node Discovery + Sharding). Fills in the governance,
multi-jurisdictional federation, and operational topology
layers that this README only sketches.
operations.md, deployment topology at
five scales (pilot to federal), capacity planning, election-
day operations playbook, incident response, cost analysis.
launch-checklist.md, sequential
T-180 through T+30 go-live checklist. Use this as the
actual project plan.
../dns-replacement/, similar
multi-jurisdictional federated governance pattern; the DNS use
case’s TLD-governance-with-delegation mirrors state-delegates-
to-county in elections.
Architecture orientation (start here if you’re new):
../ARCHITECTURE.md, single-doc tour
of the protocol, the three pillars, and how every use case
fits the same pattern. Elections is the most complex worked
example.
../BUILDING-A-USE-CASE.md,
the six-phase recipe for designing a use case. Elections was
designed following this pattern.
Open research questions (future QDPs)
Blind-signature protocol specification. Quidnug’s native
ECDSA P-256 doesn’t directly support blind signatures. Options:
add RSA-based issuance as an auxiliary protocol, or use
EC-Schnorr-style blind signatures (requires protocol
extension). Needs a QDP.
Homomorphic tallying for full receipt-freeness, could be
a future QDP that adds Paillier or ElGamal ciphertext vote
encoding, with tallying in the ciphertext space.
Voter’s private-key recovery, if a voter loses their VRQ
key, how do they re-register? Guardian-recovery-for-voters
needs an opinionated design.
These don’t prevent a production deployment; the core flow works
with v1 Quidnug plus the blind-signature auxiliary. They’d make
successive versions stronger.
Architecture
Data model, components, sequence diagrams.
Architecture: Elections on Quidnug
Detailed data model, protocol flows, and component breakdown.
Assumes familiarity with README.md.
Participating components
A production election deployment involves these Quidnug node
roles:
ObserverPanel []string// League of Women Voters, etc.
Quorumfloat64// e.g., 0.7 (5-of-7 weighted)
NoticeBlocksint64// e.g., 1440 (~72h at 3-minute blocks)
EmergencyClausebool// if true, REMOVE_VALIDATOR gets 1h notice
// during active voting week
}
// Each individual governor ALSO has a personal guardian set
// (QDP-0002) for recovering their own key if lost/compromised.
// These are separate humans from the governor quorum above;
// typically chosen per-governor for their life context
// (spouse, lawyer, federal monitor, etc.).
type GovernorGuardians struct {
GovernorQuidstring
Guardians []string// quids of the guardian humans/orgs
Thresholduint16// e.g., 3-of-5
RecoveryDelay time.Duration // e.g., 24h typical
}
Two-layer key-resilience model. The governor quorum is the
policy layer, it changes the authority’s validator set,
domain parameters, delegation scopes. The per-governor
guardian quorums are the key-recovery layer, each governor
individually can recover a lost key without waiting for quorum
agreement. Both layers are needed; one without the other
leaves obvious failure modes (losing a key = stuck, losing a
policy vote = stuck).
Voter Registration Quid (VRQ)
type VoterRegistrationQuid struct {
QuidIDstring// sha256 of voter's public key, 16 hex chars
PublicKeystring// voter-generated ECDSA P-256 public key
Creatorstring// voter's own quid (self-issued)
Attributesstruct {
// NOTE: No real-world PII on-chain.
// Precinct is public; matched off-chain to name+address
// by the authority's secure registration DB.
}
}
The VRQ exists before the registration trust edge. The edge
is what grants eligibility; the quid is the voter’s identity.
Voter Registration Trust Edge (the “registration record”)
// Issued by election authority after identity verification.
// The signature on this identity transaction is the
// UNBLINDED authority signature from the blind-signature flow.
AuthoritySignaturestring
}
Critical property: the authority’s signature here is
cryptographically valid (verifies against authority’s public
key) but the authority never saw the raw QuidID. This is the
mechanism by which eligibility is proven while anonymity is
preserved.
Nullifier scheme, one subtle point. The nullifier prevents
the voter from requesting multiple ballots for the same contest.
It’s derived deterministically:
Only the voter (holding VRQ private key) can compute it.
The same voter for the same contest always gets the same
nullifier.
The authority stores all seen nullifiers per contest. Second
request with the same nullifier is rejected. The nullifier
itself doesn’t reveal the voter’s identity (it’s a hash,
appears random to observers).
Vote casting
Inside the booth, voter makes selections on touchscreen UI:
US Senate: ● Jane Smith ○ Bob Jones ○ Carol Li
Governor: ○ Alice Wang ● Dan Chen ○ (no vote)
Proposition 5: ● YES ○ NO
Voter confirms. Device emits:
For each vote:
TRUST transaction from BQ to candidate/option:
For US Senate vote:
truster: ballot-Xz7m... (BQ for us-senate contest)
This is the one non-standard-Quidnug piece. The authority’s
Ballot Issuance Service implements a blind-signature scheme
against the authority’s issuance key.
Options for implementation
Option A (Recommended): RSA blind signatures as auxiliary
Authority maintains a separate RSA keypair for blind signatures.
The public key is published in the authority’s attributes. Each
issuance key is short-lived (per election); expired keys are
retired (another election.issuance-key-retired event).
More aligned with Quidnug’s P-256 family, but Schnorr blind
signatures have known concurrency attacks that need careful
protocol design (blind Schnorr requires ROS-hard setup or
alternatives like Okamoto-Schnorr).
The issuance service
type IssuanceService struct {
authorityQuidstring
authorityPrivateKey ecdsa.PrivateKey // for Quidnug signatures
blindSigPrivateKey rsa.PrivateKey // for blind sigs
ledger*NonceLedger
nullifierStoremap[string]map[string]bool// contest → nullifier → seen
}
func (s *IssuanceService) IssueBallot(req IssueRequest) (*IssueResponse, error) {
// Verify request signed with VRQ's private key.
if!s.verifyVRQSig(req) {
returnnil, ErrBadVRQSignature
}
// Check VRQ is registered for this election.
if!s.isRegistered(req.VRQ, req.ElectionID) {
returnnil, ErrNotRegistered
}
// Check VRQ has checked in (or is otherwise eligible, mail, early vote).
The nullifier store is in-memory per issuance epoch; persisted
out to snapshots for audit purposes. It’s small (one entry per
voter per contest → ~hundreds of thousands of entries per
county-wide election).
Scale estimates
Mid-size US county election:
200,000 registered voters
100,000 actual turnout (50%)
20 contests per ballot
50 precincts
Workload:
Registration edges: 200K (one-time, during registration period)
Poll-book lookups: 100K (one per voter check-in)
Ballot.issued events: 100K × 20 = 2M (one per voter per contest)
Elections are an unusually adversarial domain: nation-state-level
adversaries, insider threats at every layer, voter coercion,
social engineering at massive scale, and legal/reputation
consequences for any detected flaw. This document is
correspondingly detailed.
Assets, ordered by criticality
Election integrity, the certified result must reflect
the votes actually cast.
Ballot secrecy, no party should learn how any specific
voter voted.
Voter eligibility enforcement, only eligible voters
cast valid votes; no double voting.
Public verifiability, any citizen should be able to
independently confirm the result.
Voter registration integrity, the voter roll must
reflect eligible citizens, not attacker-controlled quids.
Attack. Attacker has compromised the election authority’s
signing key and uses it to retroactively forge trust edges (fake
votes) or re-sign the tally with altered numbers.
Mitigations.
Append-only chain. Trust edges and events are written to
the Quidnug blockchain. Attacker can’t “modify” existing
edges, they can only add new ones. Observers see additions.
Guardian-based authority recovery (QDP-0002), authority’s
own key is rotatable via multi-party quorum. A compromised key
is invalidated via AnchorInvalidation; subsequent signatures
at the compromised epoch are rejected.
Independent tally by observers. Observer nodes (media,
parties) run their own tally queries. An attacker adding fake
edges has to add them to every observer’s chain, requiring
compromising the gossip network, which requires
orders-of-magnitude more resources.
Paper-ballot cross-verification. Any discrepancy between
paper and digital is flagged. Paper wins. An attacker adding
fake digital votes has to also stuff matching paper ballots
into physical boxes, physical access required.
Merkle root snapshots. At polls-close time, a snapshot of
the voter roll and ballot issuance is published. Later
manipulation is detectable by comparing.
Residual risk. A coordinated attacker with authority-key
compromise + network-level control + physical ballot-stuffing
could manipulate an election. This is a “sovereign-scale”
attack requiring massive resources. Quidnug doesn’t make this
easier; it provides more evidence paths than current systems.
A2. Insider adds forged registrations
Attack. Corrupt insider at the authority adds fake trust
edges for non-existent voters, allowing fake ballots later.
Mitigations.
Public registration count. Anyone can count registered
voters per precinct. Unusual growth (e.g., Precinct 42 gains
5000 voters in a week) is visible.
Registration domain rate-limits. Fork-block (QDP-0009) can
establish per-week / per-month registration caps per
jurisdiction. Attempts to exceed require explicit fork-block
signoff.
Cross-reference with off-chain voter file. State SOS’s
voter file comes from DMV + Social Security death index + etc.
Discrepancies between on-chain count and SOS file flagged.
Periodic audit events. Scheduled audit.registration-check
events from independent observers comparing on-chain vs. SOS.
Residual risk. Insider + compromised oversight could sneak in
forgeries. Normal audit processes (already required by state
law) apply.
A3. Vote-changing attack after the polls close
Attack. After polls close, attacker (with authority access)
modifies trust edges to change votes.
Mitigations.
Trust edges are append-only, attacker can only add new
edges, not modify. A new edge from the same BQ would show up
as a duplicate in the tally → flagged.
Per-BQ anchor nonce ensures only one valid first-vote from
a given BQ; subsequent trust edges with the same nonce are
rejected by the ledger.
Paper ballot cross-check catches any anomaly.
Independent observer tallies lock in the result within
minutes of polls closing.
A4. Tally algorithm manipulation
Attack. The election authority publishes a “tally” that
doesn’t correctly reflect the chain state (e.g., counting edges
wrong).
Mitigations.
Tally algorithm is publicly specified in contest
attributes. Any observer can re-run it.
Open-source tally tools make the logic auditable.
Authority’s published tally is a signed event, if it
differs from independent computation, the challenge is
specific and on the record.
Category B: Ballot secrecy attacks
B1. Authority learns who voted for whom
Attack. Corrupt authority operator tries to correlate BQs
back to VRQs to identify voters.
Mitigations.
Blind signature during ballot issuance, authority never
sees the unblinded BQ ID. This is a cryptographic guarantee:
the correlation is mathematically unrecoverable without the
voter’s blinding factor (held only on voter’s device).
Even authority-level access to the Issuance Service’s logs
doesn’t reveal BQ IDs.
Residual risk. The blind signature’s security relies on the
cryptographic hardness assumption (RSA + secure blinding). A
flaw in the blind-signature implementation would be catastrophic.
Mitigated by using well-audited implementations and by
multiple-BQ-per-voter design (breaking any one BQ’s anonymity
only reveals one contest, not the whole ballot).
B2. Traffic analysis to correlate check-in with ballot cast
Attack. Observer of network traffic correlates “voter X
checked in at 10:15” with “BQ ABC appeared at 10:17.”
Mitigations.
Mix-network batching, ballot issuance events are
processed in batches, not in real-time order. Multiple voters’
issuance requests are shuffled before publication.
Delay randomization, BQ publication to the chain is
randomly delayed within a short window.
Tor-style anonymity for BQ submissions (optional), voter
submits votes through an anonymizing relay.
Polling-place processing, all voters at precinct 42 check
in publicly but their BQs are processed together in a batch;
observer sees many BQs appear “at once” without per-voter
timing.
Residual risk. A very-well-resourced observer (e.g., ISP-
level traffic inspection) with network position could in theory
correlate. Mitigation: defense-in-depth with mix networks + Tor.
B3. Coercion via BQ private key
Attack. Coercer demands voter’s BQ private key to verify
they voted “correctly.”
Mitigations (layered).
Legal, criminal penalties for vote buying.
Decoy BQs, voter’s device can generate N plausible BQs;
voter shows any to a coercer. Only the voter knows which was
actually cast.
Revocable ballots (where legal), voter may re-cast up to
deadline; final vote counts. Coercer can verify an initial
vote but voter can change later.
Physical private voting booth, coercer can’t accompany
voter into booth.
Residual risk. Perfect coercion resistance is an open
research problem. Current protocol gives better defense-in-depth
than paper-based voting.
Category C: Voter impersonation
C1. Stolen VRQ private key
Attack. Attacker steals a voter’s VRQ private key and
attempts to vote as them.
Mitigations.
Physical check-in at polling place, in-person voters
must show physical ID matching the VRQ’s registered voter.
An attacker with VRQ key but not the ID can’t check in.
Online voting (where enabled) requires additional
authentication (biometric, SMS-based second factor),
application-layer but standard.
Voter alert, if voter notices their checked-in event
when they haven’t voted, they can file a dispute immediately.
Guardian recovery of VRQ, voter can rotate their VRQ via
guardians, invalidating the stolen key.
Residual risk. Stolen key + stolen ID = impersonation
possible. Same threat level as current ID-based voting.
C2. Registration of non-existent voters
Attack. Attacker creates fake quids and registers them.
Mitigations.
Registration requires in-person or online ID verification.
Authority’s registrar is the check.
Duplicate detection via off-chain voter file.
Public registration count, unusual growth is flagged.
Monotonic nonces on registration edges prevent simple
replay.
Category D: Double voting
D1. Voter attempts to vote at two polling places
Attack. Voter checks in at precinct 42, then drives to
precinct 43.
Mitigation. Push gossip (QDP-0005) propagates the
voter.checked-in event from 42 to every other precinct within
seconds. At 43, the lookup finds the prior check-in → reject.
Residual risk. Narrow window during network partition. If
precincts are offline-isolated for some time, a voter could
theoretically double-check-in. Mitigation: precinct nodes refuse
check-in if they haven’t seen a heartbeat from the authority in
1 minute.
D2. Voter requests multiple ballots for same contest
Attack. Voter tries to trick the Issuance Service into
signing multiple BQs for the same contest.
Mitigation.Nullifier, derived from voter’s VRQ +
contest ID. Same voter + same contest → same nullifier. Second
request rejected.
D3. Authority issues duplicate ballots
Attack. Corrupt issuance operator manually creates extra BQ
identity transactions for a compromised voter, inflating their
vote count.
Mitigation. Each BQ identity transaction has an authority
signature. The authority’s signing key is monitored; unusual
signing patterns visible in push-gossip traffic. Observer nodes
can count the per-VRQ ballot issuances (via public
ballot.issued events). A VRQ with ballot.issued events
exceeding the contest count is anomalous.
Category E: Infrastructure attacks
E1. DDoS on authority node on election day
Attack. Flood the authority’s issuance service to prevent
voters from getting ballots.
Mitigations.
Standard DDoS mitigations (CloudFlare-style).
Issuance service horizontally scaled across precincts,
attack on one precinct doesn’t affect others.
Paper ballot fallback, if issuance service is down, voters
cast paper ballots directly; these are later reconciled.
E2. Network partition between precincts
Attack. Attacker cuts network links between precincts.
Mitigations.
Push gossip resumes when network heals.
Paper ballot fallback.
Precinct-local tally possible in isolation; state-level
aggregate later.
E3. Voting booth software compromise
Attack. Supply-chain attack on the open-source voting booth
application.
Mitigations.
Open-source + reproducible builds, anyone can verify the
running binary.
Multiple independent implementations encouraged.
Paper ballot cross-check is the backstop. Compromised
booth software produces votes; paper ballot’s human-readable
version ground-truths.
Category F: Denial of service via legal process
F1. Authority compelled to hand over keys
Attack. State actor compels election authority to hand
over signing keys.
Mitigations.
Multi-party guardian set, no single person has the keys.
HSM-protected, keys can’t be “handed over” in practice
(HSMs only sign, don’t export).
Guardian-set rotation under legal duress, new guardians
replace any compelled ones.
Residual risk. Sufficiently broad legal compulsion defeats
distributed trust. No protocol helps here; this is a
jurisdictional problem.
Attack scenarios, end-to-end
Scenario 1: “Attacker wants to add 50,000 fake votes for Candidate X”
Elections integration with the three architectural pillars
How the elections use case composes on top of the three
architectural QDPs (0012 Domain Governance, 0013 Network
Federation, 0014 Node Discovery + Sharding). Written as a
companion to README.md +
architecture.md, which predate the
pillars and describe the election semantics without
addressing the larger protocol architecture.
The original elections design (README.md, architecture.md)
specifies the election semantics: quid types, trust edges as
votes, blind-signature ballot issuance, paper-ballot parity,
universal recount. It’s complete at the “what events get
signed” layer.
What it doesn’t specify, because the relevant QDPs landed
later, is how the system is deployed, governed, and
discovered:
Who exactly are the governors for the election’s domains?
The original doc has “Guardian set” for the authority quid but
uses pre-QDP-0012 vocabulary that conflates guardians with
governance quorum.
What runs the blocks, and at what scale? Precinct-level
polling places, county-wide counting, state-wide
certification: this is a sharding question the original doc
hand-waves.
How do federal elections federate across state-run
infrastructure? Pre-QDP-0013, the original doc implicitly
assumed one giant network; realistically every jurisdiction
runs its own.
How do voters’ clients find the right nodes for their
precinct? The original doc assumes a central api.quidnug
endpoint; per QDP-0014 this should be explicit.
This document fills those gaps.
2. QDP-0012 Domain Governance, the election authority as a governor
2.1 The mental model update
In the original doc, the “Election Authority Quid” is
described as a quid with a guardian set. Under QDP-0012 we
separate three roles more precisely:
Role
Who, for elections
Governor
The humans / institutions authorized to vote on changes to the election’s domain consortium + parameters. Typically: chief election official, state SoS office, bipartisan oversight board, independent observers.
Consortium member (validator)
The physical nodes that produce blocks for the election’s domains. Typically operated by the authority + observer organizations, in geographically diverse locations.
Cache replica
Every precinct polling-place device, every observer’s laptop, every journalist’s monitor, any node that mirrors the agreed chain for reading but doesn’t produce blocks.
Guardian
(Orthogonal to governance.) The specific quorum that can recover a compromised governor’s key via QDP-0002.
Any one human might hold two or three of these hats. The
chief election official is typically a governor AND operates
one of the consortium-member nodes. But the roles are
independently defined.
2.2 Governance structure for a county election
For elections.williamson-county-tx.2026-nov:
Domain: elections.williamson-county-tx.2026-nov
governors:
county-clerk-quid weight=2
state-sos-tx-quid weight=2
r-party-observer-quid weight=1
d-party-observer-quid weight=1
lwv-observer-quid weight=1 # League of Women Voters
governanceQuorum: 0.7 # 5 of 7 weighted votes
notice period: 72 hours # longer than reviews; election-critical
(~423 precincts, each running a precinct-local cache-only node)
(plus any observer / journalist / candidate running a mirror)
Five block-producing consortium members, three of which must
agree (2/3 quorum) for a block to reach Trusted on any
observer. Seven governors with weighted votes; 5-of-7 needed
to mutate anything (add a validator, remove one, etc.).
Every governor has a separate guardian quorum (QDP-0002). The
chief election official’s guardian quorum might be: spouse,
business partner, state ethics officer, federal monitor,
lawyer. Losing the chief’s key doesn’t lose the election’s
authority, guardians can rotate.
2.3 Governance actions during an election cycle
With QDP-0012’s transactions, these become first-class, on-chain
events:
Action
Governance transaction
Notice
Install a new validator (e.g. add a third observer org mid-cycle)
ADD_VALIDATOR
72h
Remove a compromised validator
REMOVE_VALIDATOR
72h (but see emergency path below)
Change the blocking threshold
SET_TRUST_THRESHOLD
72h
Add a new precinct domain
child domain registration + DELEGATE_CHILD
72h
Change the oversight composition (replace an observer)
UPDATE_GOVERNORS
7 days, unanimous
Emergency: suspected compromised node
REMOVE_VALIDATOR with expedited notice
1 hour by pre-negotiated emergency clause
Emergency clause. For the week of the election, a
pre-negotiated emergency governance track allows 1-hour notice
periods on REMOVE_VALIDATOR actions signed by a full quorum
(5-of-7 weighted). This lets the oversight board remove a
compromised node the same day a breach is detected, without
waiting three days. The emergency clause itself is installed
via a standard 72h SET_EMERGENCY_WINDOW governance action
before election day.
2.4 Domain tree as governance hierarchy
Each sub-domain of the election can have its own governance
scope or inherit from the parent:
elections.williamson-county-tx.2026-nov (governed by
the root
county-level
quorum)
├── registration (inherits)
├── poll-book.precinct-001 (inherits, or
│ delegated to
│ the precinct
│ judges for
│ operational
│ signing?)
├── ballot-issuance (inherits)
├── contests.us-senate (inherits)
├── contests.governor (inherits)
└── audit (inherits,
possibly
delegated to
post-election
audit firm)
For most sub-domains, inherit-from-parent is correct, the
county authority governs everything uniformly. For audit, a
post-election delegation to an independent auditor (via
DELEGATE_CHILD) lets the auditor publish findings on-chain
with their own quorum, which is stronger proof than having the
county authority publish them.
In the US, elections are administered at the county level, but
contests span multiple levels:
County races (e.g. county commissioner), county authority
runs the show.
State races (governor, US senator), state-wide tally is
the sum of county-level results.
Federal races (US president), multi-state aggregation
with Electoral College complications.
If each county runs its own Quidnug network (which is the
natural deployment), how does the state get a view across all
counties? How does a federal election observer verify totals
without trusting every county’s infrastructure individually?
3.2 The federation topology
Each jurisdiction runs its own network. Parent jurisdictions
(state, federal) federate trust-lookups against the child
jurisdictions’ networks:
┌──────────────────────────┐
│ FEDERAL NETWORK │
│ (elections.us.2028-pres)│
│ federates with: │
│ - all 50 state nets │
│ - reputation via │
│ `TRUST_IMPORT` │
└─────────────┬────────────┘
│ federates
┌───────────┼───────────┐
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ STATE NET (TX) │ │ STATE NET (CA) │
│ state SoS │ │ state SoS │
│ governs │ │ governs │
│ federates with: │ │ federates with: │
│ - 254 counties │ │ - 58 counties │
└────────┬────────┘ └────────┬────────┘
│ federates │
┌─────┼─────┐ ┌────┼────┐
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌─────────┐┌─────────┐
│ COUNTY │ │ COUNTY │ │ COUNTY ││ COUNTY │
│ Williams │ │ Travis │ │ LA ││ SF │
│ own net │ │ own net │ │ own net ││ own net │
│ own │ │ own │ │ own ││ own │
│ conso. │ │ conso. │ │ conso. ││ conso. │
└──────────┘ └──────────┘ └─────────┘└─────────┘
Each level operates its own Quidnug network, own consortium,
own governors, own chain. Parent levels federate to their
children for cross-jurisdictional reads.
3.3 What federation actually means for elections
Three distinct federation scenarios:
Scenario A: State publishes per-county totals at tally time.
The state SoS network queries each county’s network at
certification time, importing the signed tally events into the
state-level chain via TRUST_IMPORT. Any observer can verify:
The state-level tally event has M-of-N state governor
signatures.
Each imported county tally has its originating county’s
consortium signatures.
The import chain is intact (no county’s tally was dropped
or altered at import time).
No observer has to trust the state’s claim about a county’s
total; they can fetch the county’s own signed tally directly
and compare.
Scenario B: Voter registered in one county, voting in another.
A voter registers in County A, then moves to County B before
the election. County B needs to verify their registration.
Instead of a faxed form, County B’s network configures County
A’s network as an external_trust_source in the
elections.us.<year>.registration domain. When County B’s
ballot-issuance flow needs to verify a voter’s registration,
it can fetch the registration record directly from County A
with cryptographic proof.
This replaces a currently-fragile state DMV “motor voter”
interstate data-exchange system with a signed, auditable
cross-network lookup.
Scenario C: Federal observer runs a national recount.
An NGO or news organization wants to compile a national
tally. They run a single node that federates with all 50
state networks (or, via state → county transitivity, all
~3000 county networks). Their node’s discovery API answers
“what is the total vote count for president, from each
state’s chain, aggregated?” All cryptographic, all signed by
the originating jurisdictions, all runnable from anyone’s
laptop.
A certified election monitor (League of Women Voters, etc.)
has trust edges from multiple state authorities in their
respective observers.elections.* domains. Federal-election
observation trusts the union of these.
A precinct election judge with years of clean operation
(no disputed close-outs, no irregularity reports) accumulates
reputation in their county’s domain. When they move to
another county, their reputation travels via TRUST_IMPORT.
Post-election auditing firms accumulate multi-jurisdictional
reputation the same way. Hiring an auditor becomes a
reputation-weighted decision, not just a procurement
checklist.
None of this requires a new primitive, it’s QDP-0013’s
federation mechanisms applied to the election domain.
in operators.elections.williamson-county-tx.2026-nov.precincts
At election-day scale for a medium county: ~5 validator nodes
(the consortium), ~10 dedicated cache nodes (for fast
check-in queries), ~500 precinct-device cache replicas, plus
an unknown number of observer / journalist nodes.
4.2 Node advertisements
Each node publishes a signed NODE_ADVERTISEMENT declaring:
Endpoints, where it’s reachable.
Supported domains, which parts of the tree this node
serves (registration, poll-book.precinct-042, etc.).
Expiration, short TTL (6 hours at election launch; 1
hour during the active voting day so dead nodes age out
fast).
Precinct devices publish “cache-only” advertisements scoped
to their own precinct’s poll-book + ballot-issuance domains.
The authority’s primary validators publish “validator +
archive” advertisements scoped to the full tree.
4.3 Discovery for voters + poll workers + observers
The voter’s phone app or the poll worker’s device uses the
QDP-0014 discovery API:
# Poll worker checks in a voter at precinct 042:
GET /api/v2/discovery/domain/elections.williamson-county-tx.2026-nov.poll-book.precinct-042
Returns:
- block tip for this precinct's domain
- consortium members authorized to serve this domain
- cache replicas currently reachable
- endpoints, sorted by region (local precinct first)
Poll worker's device picks the local precinct cache (lowest
latency) for the actual check-in query.
Observers run their own nodes and hit api.<authority>.gov
(the authority’s api gateway). The gateway routes to
appropriate backend nodes via the same discovery logic, they
don’t need to know physical topology.
4.4 Sharding patterns for elections
Combinations:
Geographic, nodes deployed in every precinct + county
seat + state-level backup.
Domain-tree, heavy-traffic domains (poll-book during
voting hours, ballot-issuance, contest streams) get more
cache nodes; lightly-touched domains (certification, audit)
get fewer.
Capability, validators are few (5-9 per jurisdiction);
cache nodes scale horizontally; archive nodes are 2-3 per
jurisdiction for post-election audit.
Network federation, some state nodes also act as
federation bridges to county networks; some federal nodes
federate to all 50 states.
Example sharding for election day at a major county:
Reads back own records for verification (individual
verifiability).
This is exactly QDP-0014’s “lightweight participation”
pattern (§14 of QDP-0014). Voters get full cryptographic
participation with zero infrastructure. An election with 10
million voters doesn’t require 10 million nodes, it requires
1 authority + ~500 precinct caches + 5-9 validator
consortium members.
4.6 Per-domain quid index for precinct lookups
The QDP-0014 per-domain quid index is load-bearing for one
specific election flow: “is this voter registered in this
precinct?”
Returns: every quid with a VOTER_REGISTERED event in the
domain within the window. The poll-book device paginates
through to build its local precinct roll at polling-place
opening.
Alternatively, a precinct’s poll book is scoped to a child
domain (poll-book.precinct-042), and the registration
authority issues REGISTERED_IN_PRECINCT events to that
domain, making per-precinct lookups trivial.
5. Well-known discovery for elections
Every election authority publishes a
.well-known/quidnug-network.json file (per QDP-0014 §7)
that serves as the cold-start entry point for all
participants.
Voter apps, observer software, and federated state networks
all fetch this file first, pin the operator pubkey, and use
it to verify everything they see afterwards.
The file is also mirrored publicly on the
elections.williamson-county-tx.gov website’s landing page
so anyone can verify the declared governors + consortium
before trusting the election output.
6. Federated-network scenario: US presidential election
Putting all three pillars together for the hardest case.
6.1 Network topology
Federal network (elections.us.2028-pres), governed
by a narrow consortium (FEC? bipartisan federal electors
board?, policy question, not technical). Light; mostly
contains an imports sub-tree that pulls per-state
certifications.
50 state networks, each governed by its SoS +
legislative oversight + federal monitor. Each state-level
network contains aggregated per-county totals.
~3000 county networks, each governed by the county
election authority as described above.
6.2 Data flow, election night
23:00 EST counties begin closing polls
23:30 EST county authorities publish signed TALLY events
on their own chains
00:00 EST state-level networks run scheduled federated
aggregation jobs:
- fetch each county's latest TALLY event via
the federation API
- verify signatures against the county's
governor pubkeys (pinned from each county's
well-known file)
- aggregate and sign a STATE_AGGREGATION event
on the state's own chain
01:00 EST federal-level network aggregates per-state:
- federated fetch of each state's
STATE_AGGREGATION event
- verify + sum + emit FEDERAL_TALLY event
(this is not "official certification", that
follows Electoral-College + canvassing rules.
it's the auditable cryptographic aggregation.)
At every level, the aggregated output carries cryptographic
proof of every input it incorporates. Anyone with a laptop
can redo the federation walk and confirm the aggregation is
correct. The chain IS the audit trail, the post-election
audit becomes a replay of the chain, not a parallel manual
verification exercise.
6.3 Recount at federal level
“Candidate X contests the presidential result.”
Candidate X’s lawyer runs the aggregation from a cold
laptop:
The CLI federates across all 50 state networks, fetches
all county tallies, verifies every signature, and prints:
Total per candidate.
State-level breakdowns.
Any county whose tally signature fails verification
(red-flagged for manual review).
If the candidate disputes a specific county’s tally:
quidnug-cli elections county-detail \
--county williamson-county-tx \
--year 2028-nov \
--contest us-president
Returns the full per-ballot vote edge list for the
contest, cryptographically tied to ballot issuances,
which are tied to voter registrations. Every vote is
independently verifiable from primary data.
No waiting for the county to re-scan ballots. No vendor
software rerunning on the same counts. The recount is
an O(n) read of the public chain.
Compare to 2020 Arizona, where the Cyber Ninjas ballot audit
took months and cost millions. Under this design, the same
audit is a few hours of laptop time and costs the
electricity to run it.
7. Governance changes mid-cycle
Elections don’t happen on schedule; unexpected events force
governance changes. Three scenarios the original design didn’t
formalize:
7.1 A governor is unavailable on election day
A governor has a heart attack, loses their phone, gets
arrested, doesn’t matter. Their key is unavailable.
Quorum math matters: the election’s 5-of-7 quorum still
functions with 6 available governors. One missing governor
can’t block actions. If TWO become unavailable simultaneously,
the remaining 5 can still act.
Guardian recovery (QDP-0002) for a lost key takes ~24h at
minimum. For election-day issues, this isn’t fast enough,
but because the quorum is resilient, it doesn’t need to be.
7.2 A consortium node is compromised election night
An observer’s node is detected publishing inconsistent blocks.
Election-night IR team confirms compromise.
Governor quorum signs REMOVE_VALIDATOR with the
pre-negotiated 1h emergency-notice clause.
In 1 hour, the validator is removed; the remaining 4 nodes
continue at 3-of-4 threshold.
Post-incident: the REMOVE_VALIDATOR tx + incident-report
event on the audit domain give a complete public record.
The 1-hour window isn’t zero, but a compromised single node
out of 5 can’t unilaterally produce accepted blocks anyway,
the 3-of-5 threshold means it needs collusion. The emergency
removal is about cleaning up, not stopping in-progress harm.
7.3 The whole consortium is compromised
Extremely unlikely (would require ~all 5 node operators
independently compromised) but design for it.
The answer is federation (QDP-0013). If the county’s
consortium is untrustworthy, the state SoS network refuses to
federate with that county’s results. The county’s chain is
still there, still verifiable, but loses its legitimacy at
the aggregation layer. The state can run an emergency
paper-ballot audit at the county level using the county’s own
paper ballots (QDP-0013 doesn’t require the county’s
electronic consortium to cooperate, the paper ballots are in
a physical lockbox the state has access to).
This is why paper-ballot parity is non-negotiable: it’s the
fallback when the digital consortium is worst-case
compromised. The cryptographic design makes that fallback
almost never needed, but it’s there.
8. Operational readings
For actually running an election on this architecture:
operations.md, deployment topology,
capacity planning, election-day operations playbook,
incident response. How to stand up the authority + observer
node infrastructure at any scale.
“Guardian set” vs “governor quorum.” The README §1
“Election Authority Quid” section describes a
requireGuardianRotation: true model. Under QDP-0012,
guardians (QDP-0002 recovery) and governors (QDP-0012
voting) are separate. Each governor has their own
guardian quorum; the election authority as a whole has a
governor quorum.
Domain validators. README §domain-hierarchy says “Each
domain has its own validators (the election authority +
observers).” Under QDP-0012, this means the consortium
members for each domain, who must be added via
ADD_VALIDATOR governance transactions, not just declared
ad-hoc.
No mention of cache replicas. The existing design
implicitly assumes every precinct device is a full-fledged
node. With QDP-0012 + QDP-0014, precinct devices are
cache replicas (read-only, much cheaper to deploy). This
is a material cost reduction for large-county deployments.
No federation story. The existing design is
single-jurisdiction. Real elections span jurisdictions.
§3 above fills this gap.
Discovery is implicit. The existing design says “hit
the api gateway.” QDP-0014 makes this discoverable + signed
cache-friendly + shardable.
These corrections don’t invalidate the existing design, they
layer on top, making the deployment story complete. Treat this
integration document as the authoritative ops-layer companion
to the semantics layer in README.md + architecture.md.
Operations
Runbooks, observability, incident response.
Elections operations
Deployment topology, capacity planning, election-day
operations, and incident response for running a Quidnug-
based election at any scale from precinct-only pilot to
federated presidential general.
Read
README.md for the election semantics,
architecture.md for the data model,
integration.md for the architectural-
pillar integration. This document assumes you’ve internalized
those.
200+ (federal consortium + federated to 50 states + 3k counties)
$50k-250k
2-4 year launch
The protocol is the same at every scale; only topology and
operational rigor change. This document gives you a
capacity-planning and deployment recipe for each.
2. Deployment architecture per scale
2.1 Pilot (student body, HOA, office election)
Simplest possible deployment:
┌─────────────────────┐
│ Your laptop (WSL) │
│ ┌───────────────┐ │
│ │ quidnug node │ │ port :8087
│ │ (validator + │ │
│ │ archive + │ │
│ │ cache) │ │
│ └───────────────┘ │
└──────────┬──────────┘
│ cloudflared tunnel
▼
https://vote.your-org.example
│
│ voters hit this URL
│ from their phones
▼
[voter phones / browsers]
One node. One operator quid (you). Maybe one observer key on
a friend’s laptop for two-person control. No physical
infrastructure beyond a laptop and a Cloudflare tunnel.
Governance: 1-of-1 governor (you). Consortium: your node.
Cache: your node. Everyone connects direct to your URL.
Launch time: an afternoon. Follows the home-operator-plan
exactly, with “elections” swapped for “reviews.”
2.2 Small municipal (town council, school board)
Three nodes, two physical sites:
┌──────────────────────┐ ┌──────────────────────┐
│ Town clerk machine │ │ Observer laptop │
│ (data center or │ │ (town hall WAN │
│ home broadband │ │ or LTE) │
│ via CF tunnel) │ │ │
│ validator+archive │ │ validator │
└──────────┬───────────┘ └──────────┬───────────┘
│ │
│ gossip │
└──────────────────────────┘
│
│
┌───────────▼───────────┐
│ Cache-only VPS │
│ ($5/mo on Oracle │
│ Free Tier) │
│ cache+bootstrap │
└───────────────────────┘
│
│ discovery api
▼
voters + poll workers
Three-node consortium, 2-of-3 quorum (so either the clerk or
an observer + the cache VPS can produce a block; the observer
alone can’t, preserving check-and-balance).
Per-precinct check-in: each precinct’s polling place has a
laptop or iPad running a cache-only profile that syncs from
the VPS. Operates in polling-place LAN mode during the day,
syncs to the VPS at regular intervals. At polls close,
precinct device publishes POLLS_CLOSED events.
to precinct-001) to precinct-002) to precinct-423)
~15 dedicated nodes + ~423 precinct devices. The precinct
devices are cheap (iPad or small laptop); the dedicated
tier uses proper server hardware.
Dedicated cache tier is a new pattern for this scale. They
serve nearly all read traffic (poll-book lookups,
ballot-issuance verification, observer queries). The
consortium validators only handle writes (registrations,
ballots cast, tally events). This separation prevents
election-day read traffic from overwhelming the
block-producing nodes.
Launch time: 3-6 months of planning + deploy + test +
training + dry-run + legal sign-off + poll-worker cert.
State consortium produces aggregation events. County networks
produce per-county tallies. State federates down to
counties via QDP-0013. State-level cache tier serves state-
wide queries (state-level candidate totals, statewide prop
counts).
Launch time: 1-2 years. State-wide rollout is a
multi-year project involving every county’s adoption + new
legal framework + vendor transition.
2.5 Federal (US presidential general)
Three-tier federated network of networks (see
integration.md §3.2 for the diagram).
Federal consortium is deliberately minimal, its only job is
aggregation, so 3-5 nodes with 2-of-3 quorum is enough. Most
of the federal network’s operational weight is in the
federation configuration: pinning 50 state networks’ operator
pubkeys, maintaining well-known file mirrors, running
aggregation jobs.
3. Hardware specification
By role.
3.1 Validator node (consortium member)
Produces blocks. Modest load but critical uptime.
Requirement
Minimum
Recommended
CPU
2 cores
4 cores
RAM
4 GB
8 GB
Disk
50 GB SSD
200 GB NVMe
Disk IOPS
2k
10k
Network
100 Mbps
1 Gbps
Uptime SLO
99.5%
99.9%
At county scale: a single Hetzner CX41 ($10/mo) comfortably
handles the validator role. For state scale: a dedicated VM
with burstable CPU. For federal: a small physical server in a
certified data center.
3.2 Cache node
Scales with read volume. Easy to horizontally add more.
Requirement
Small county
Large county
CPU
2 cores
8 cores
RAM
4 GB
16 GB
Disk
100 GB SSD
500 GB SSD
Network
100 Mbps
1 Gbps
Uptime SLO
99% (redundant; one down is fine)
99.5%
Target: 5k-20k read QPS per cache node. If election-day
peak exceeds that, add more cache nodes (QDP-0014
discovery auto-routes).
3.3 Archive node
Stores full history. Rarely queried in real-time; used for
post-election audit + forensics.
Requirement
Per year’s elections
CPU
2 cores
RAM
8 GB
Disk
1-4 TB (post-election data can be moved to cold storage)
Network
10 Mbps (low real-time; high for audit days)
Uptime SLO
99%
At least 2 archive nodes per jurisdiction, geographically
diverse, ideally hosted by different governance entities
(one by the state, one by an observer org).
3.4 Precinct device (cache-only)
The thing a poll worker hands a voter.
Requirement
Value
CPU
Any reasonable phone / tablet / laptop CPU
RAM
2 GB
Disk
8 GB (of which ~1 GB is the precinct’s local cache)
Battery
8+ hours (polling-place day)
Network
Primary: LTE or precinct wifi; fallback: none (offline operation for 4h)
Supported hardware
iPad Pro (recommended), Surface Go, Chromebook, Linux laptop
Security
Secure enclave for storing the precinct device’s node key
Critical: must degrade gracefully when network is out.
Precinct device runs as a cache node with a large local cache
so offline queries (check-in verification) still work. Votes
cast offline queue locally + sync on reconnection with full
cryptographic integrity.
4. Capacity planning
4.1 Transaction volume estimates
For a county-scale election with 500k registered voters:
Phase
Events
Duration
Rate
Pre-election (registration period, 90 days)
500k
90 days
~6k/day = ~0.07/s
Early voting (14 days)
100k-150k
14 days
~10k/day = ~0.12/s
Election day
350k
12 hours
~30k/hour = ~8/s
Peak hour (noon lunch rush)
75k in 1 hour
1 hour
21/s
Tally + certification
~100
1-7 days
negligible
8/s sustained, 21/s peak. The node’s default rate limit at
100k/min (which is what we configured for the reviews demo)
is way more than enough. The real constraint is storage
(500k registrations + 350k ballots + vote events = ~2M events,
~500MB at ~250 bytes/event) and validator throughput for
block production.
At a 60-second block interval, a county election never
generates more than 50 transactions per block during peak
hours, comfortable margin.
4.2 Read load estimates
Much higher than write load, because every interaction
generates reads.
Query
Per voter
Per day (election day)
Voter checks their own registration
2-5
500k × 3 = 1.5M
Poll worker checks in voter
1
350k
Voter checks their own vote (individual verifiability)
1-3
350k × 2 = 700k
Observer queries
10k-100k per observer
varies
Journalist / candidate queries
100k-1M total
varies
Total
3M-5M
3-5 million reads per day on election day. Distributed
across 10 cache nodes: 300-500k per node per day, or 3-6 QPS
per node. Trivial. CDN edge caching of idempotent GETs
further reduces origin load.
4.3 Spike handling
Traffic isn’t uniform. Expect:
Opening of polls (6-7am): ~5x normal read load for 30
minutes as poll workers come online.
Lunch rush (11am-1pm): ~3x normal voter traffic.
Pre-close (6-7pm): ~4x normal traffic as commuters
arrive after work.
Post-close (7-10pm): ~10x normal observer / journalist
traffic as tallies publish.
Cloudflare edge cache handles most of this. Origin load
stays reasonable. Rate-limiting on the node side is set to
allow 10x normal volume so bursts don’t cause legitimate
requests to fail.
5-20 vote edges (depending on contests): ~500 bytes each = 2.5k-10k
1-3 verification events: ~300 bytes each = ~1k
Per voter per election: ~4-12 KB on-chain.
County of 500k voters, full election: ~2-6 GB of on-chain
data. Over 10 years of elections: ~20-60 GB per county.
Archive nodes handle this easily. Cache nodes keep only
hot state (current + recent elections) which is much
smaller.
5. Election-day operations playbook
5.1 T-30 minutes: final check
Terminal window
# Health check every consortium member
fornodeinauthority-primaryauthority-backupobserver-robserver-dobserver-lwv; do
Monitoring dashboard shows traffic per precinct, with
alerts for any precinct that’s processing 0 check-ins
more than 30 minutes after open.
5.3 During voting day
Continuous monitoring for:
Check-in rate per precinct. Anomalies (e.g., 10x
surge) may indicate attempted ballot-stuffing.
Ballot-issuance rate, should equal check-in rate.
Vote-cast rate, should equal ballot-issuance rate
within an hour (voters finish marking).
Block-tier distribution, every validator’s block
count should be roughly equal. Asymmetry may indicate
one validator falling behind or failing.
Consortium agreement rate, percentage of blocks
accepted as Trusted by all consortium members. Should
be 100%; below 99% is a warning.
Failed tx rate, should be near-zero. Spike
indicates either attack or bug.
Dashboard at status.elections.<county>.gov publishes:
Total registered voters who’ve voted (turnout live).
Per-precinct turnout rates.
Any precinct with alerts.
5.4 Polls close (typically 7pm local)
Each precinct’s chief judge signs a POLLS_CLOSED event
with final local totals + cryptographic hash of paper
ballots (confirming paper = digital).
Consortium waits 30 minutes for straggler tx from
precincts with poor connectivity to gossip through.
Tally computation runs:
Sum all vote edges per contest.
Emit CONTEST_TALLY_PRELIMINARY event per contest,
signed by the consortium.
Publish preliminary results to the status dashboard +
the official website.
5.5 Post-close (7-10pm)
Observer teams run their own independent recounts
(anyone can; see §5.6).
Any discrepancies trigger paper-ballot comparison
(procedure in
implementation.md §7).
Candidates who dispute results receive fine-grained
per-ballot drill-down access (still cryptographically
tied to paper).
5.6 T+24 hours: certification
After a 24-hour observer-review window:
County canvassing board meets + certifies.
Authority publishes CERTIFIED event to the tally
domain with full quorum signatures.
Results federate to the state network via TRUST_IMPORT.
Certified totals become official.
6. Incident response
Scenarios + response protocols.
6.1 A consortium node goes offline during voting
Detection: health check fails, or validator’s block
participation rate drops.
Response:
Remaining consortium continues (3-of-5 quorum preserved
as long as 4 are up).
IR team investigates the failing node; bring back up if
possible.
If recovery > 2 hours, consider emergency
REMOVE_VALIDATOR (via the 1h-emergency-notice clause
from integration.md §7.2).
Publish NODE_DEGRADED event to the audit domain
explaining what happened; public transparency reduces
legitimacy risk.
6.2 Precinct device compromised
Detection: precinct device publishing invalid events,
duplicate check-ins, or just stopped responding.
Response:
Chief judge at the precinct switches to paper-only
check-in (manual poll book).
Compromised device is removed; paper check-ins get
cryptographically bridged at a later point.
IR team investigates the compromised device:
What was its node key’s scope? (Just the precinct’s
poll-book domain, per QDP-0014.)
Any tx published under the key are flagged for extra
verification.
Revoke the device’s node-quid via an operator-attestation
TRUST edge update.
Because the precinct device only holds a cache-only key
scoped to one precinct, the blast radius is bounded.
6.3 Suspected registration fraud
Detection: an observer notices a voter registration that
seems suspicious (address doesn’t exist, voter is deceased, etc.).
Response:
Observer publishes a REGISTRATION_CHALLENGE event.
Authority investigates within 24h.
If fraudulent: publish REGISTRATION_REVOKED event
(stops future ballot issuance).
If voter already cast a ballot: flag for paper-ballot
verification at tally time.
Legal referral to prosecutor for follow-up.
The challenge/revocation mechanism is cryptographic +
auditable: no silent changes.
6.4 Network partition / DDoS / outage
Detection: ISP connectivity fails, DDoS floods the
gateway, Cloudflare incident.
Response:
Gateway failover to backup DNS entries.
Precinct devices operate in local-cache mode; sync
deferred.
If outage exceeds 30 minutes, chief election officer
extends voting hours per statutory authority; publishes
VOTING_HOURS_EXTENDED event.
Post-incident, publish full timeline on audit domain.
7. Security discipline
7.1 Key custody per role
Role
Key custody
Governor (human)
HSM or YubiKey. Paper backup in a physical vault. QDP-0002 guardian quorum for recovery.
Consortium member node
HSM-backed signing on dedicated hardware. Daily health check.
Precinct device
Secure-enclave-generated key, locked to the precinct domain. Device returns to sealed storage between elections.
Voter VRQ
Voter’s own custody (phone secure enclave, YubiKey, paper).
Voter BQ
Ephemeral; generated per ballot, discarded after cast.
7.2 Pre-election hardening
All software audited by an independent firm (publish the
audit report).
All nodes on isolated networks during voting hours; no
outbound traffic except to the consortium + CDN.
Admin access logs on the audit domain (every console
login is an on-chain event).
Disaster-recovery drill ~30 days before election.
7.3 Election-day rules
No governance changes during active voting (except
emergency REMOVE_VALIDATOR).
No node key rotation during voting.
No software updates between polls-open and polls-close.
All governors + consortium operators on-call until
certification.
8. Cost
By scale.
8.1 Small municipal (under $500 total)
1 VPS @ $6/mo × 12 = $72
Backup storage @ $1/mo × 12 = $12
Domain rental = $10/yr
Total: ~$100/yr
Plus one-time: legal sign-off (~$3k if you’re buying it
commercial; $0 if municipal legal already does it).
8.2 County (mid-size)
5 validators @ $20/mo each = $100/mo = $1200/yr
10 cache @ $10/mo = $100/mo = $1200/yr
2 archive @ $50/mo = $100/mo = $1200/yr
Domain + TLS + CDN free tier = $0
Monitoring (Grafana Cloud free tier) = $0
Total: ~$3600/yr
Plus one-time: precinct devices (~$500 each × 423 = $211k)
but these already exist for traditional electronic
poll books, so usually not incremental.
8.3 State
9 state validators @ $100/mo = $900/mo = $11k/yr
40 state caches @ $50/mo = $2000/mo = $24k/yr
Monitoring paid tier = $5k/yr
Legal + audit = $100k/yr
Operations staff (2 FTEs) = $250k/yr
Total: ~$400k/yr
8.4 Federal
Federal consortium (minimal) = $50k/yr
Federation gateway + observation = $100k/yr
Audit + compliance = $500k/yr
Staff (10 FTEs across oversight) = $2M/yr
Total: ~$2.5M/yr
Compare to current US election spending: ~$5B / year across
all jurisdictions. The Quidnug deployment replaces
proprietary voting-machine contracts ($500M-$1B / year) and
registration-database licenses ($100M+/year). Net savings
are substantial at any scale.
9. Running drills before the real thing
Pre-real-election checklist:
T-90 days: full dry-run with 1000 fake voters across
10 test precincts. Include a suspected-fraud scenario and
a consortium-node-failure scenario.
T-60 days: security audit final report + fixes
deployed.
T-30 days: second dry-run with 10,000 fake voters;
observer teams run recounts.
T-14 days: final integration test + all poll workers
certified on the precinct device.
T-7 days: freeze code. No deploys until post-election.
T-1 day: polling-place hardware verified.
Day 0: operate the election.
10. What this doc doesn’t cover
Specific local legal requirements. These vary by state
and by country. Work with election counsel.
Voter accessibility (ADA, multilingual). The protocol
handles signing; the UX/client apps handle accessibility.
That’s a substantial separate design track.
Long-term archival policy. Events live forever on
chain; but storing + serving 30 years of election data
is an evolving operations question.
Integration with existing SoS workflows. Every state
has its own admin software. Bridges are use-case-specific.
For all of these, adapt the pattern. The protocol layer is
the same; the policy and UX layers wrap it.
Sequential T-90 through T+30 go-live steps for running a
Quidnug-based election. Work top to bottom; each item
gates the next. Designed for a county-scale election;
scale items up/down for different deployments.
Before you’re actually running against a real election,
you need the infrastructure standing.
Legal + governance foundation
Legal counsel reviews + approves the overall design.
Specifically: does running elections on Quidnug
satisfy state election law? (Varies by state; some
require specific vendor certifications, some allow
custom systems with public audit provisions.)
If required: engage an independent election-software
auditor for pre-certification.
Bipartisan oversight board formed + briefed on the
protocol architecture.
Governance structure defined + documented (see
integration.md §2.2):
- Governor quorum (who, weights, threshold)
- Consortium membership (who runs validators)
- Emergency-notice clause
- Guardian quorums per governor
Legal agreements signed with observer organizations
(LWV, R party, D party, SoS office) re: key custody,
emergency procedures, liability.
Public governance documentation published at
elections.<county>.gov/governance.
Hardware + infrastructure
Consortium node hardware procured:
- Authority-primary (in gov data center 1)
- Authority-backup (in gov data center 2)
- 3-4 observer nodes (one per observer org’s site)
Cache tier hardware procured (10+ nodes in
geographically-diverse regions).
Archive node hardware procured (2+ nodes).
Precinct device fleet ordered (iPad Pro or equivalent,
~1 per precinct + 10% spares).
Cloudflare account set up with:
- Domain registered (elections.<county>.gov)
- Tunnel account for home/remote access
- Worker deployed for api.elections.<county>.gov
- Monitoring configured
Software + keys
Quidnug node binary built from a specific tagged
release (e.g. v2.4.0). SHA-256 hashes published.
All consortium node keys generated OFFLINE on an
air-gapped machine. Paper backups printed.
Guardian quorums installed for each governor key
(following QDP-0002).
Observer keys generated + distributed to observer
organizations.
Precinct device keys generated + preloaded into
secure enclaves.
CLI tooling (quidnug-cli elections) tested on
staging.
Staging environment
Staging cluster set up mirroring production (different
domain: elections-staging.<county>.gov).
100 fake voters registered in staging.
Fake election run end-to-end in staging (registration
→ ballot-issuance → voting → tally → recount).
Staging election results match expected (seeded) data.
T-90 days: Domain + consortium setup
Publish the network descriptor
Publish https://elections.<county>.gov/.well-known/quidnug-network.json
per QDP-0014 §7. Signed by the operator key. Includes:
- Operator quid + pubkey
- API gateway URL
- Seed nodes + capabilities
- Governors + quorum
- Domain tree
Publish backup mirror of the well-known file at
https://quidnug.com/.well-known/elections/<county>.json
(federated publication for resilience).
Test voters cast ballots with each poll worker
observing.
Poll workers sign certification events (published
on-chain for audit).
Voter education
Public education campaign explaining:
- How to generate a VRQ (on phone / kiosk / paper)
- How to verify your own registration
- How the ballot is anonymous but your vote is verifiable
- How to recount on your own laptop
Election-day incident-response team on-call:
- Chief election official
- Oversight board members (rotating)
- IT team lead + two engineers
- Legal counsel
- Communications lead
T-1 day: Pre-flight
All consortium members connect + verify blockchain
head matches across all nodes.
Final status check (operations.md §5.1).
Publish ELECTION_DAY_READY event to audit domain.
Team rest; don’t schedule last-minute changes.
T-0 (Election Day)
Polls open (typically 7am local)
Each precinct chief judge signs + publishes
POLLS_OPENED event.
Precinct devices start accepting check-ins.
Incident-response team on-call.
Status dashboard publicly visible.
Throughout the day
Monitor turnout per precinct (dashboard).
Respond to any reported issues within 15 minutes.
Publish occasional STATUS_UPDATE events with
turnout summaries.
If a precinct has issues: deploy backup staff,
switch to paper-only check-in if needed.
Polls close (typically 7pm local)
Each precinct chief judge signs POLLS_CLOSED event.
Consortium waits 30 minutes for straggler events.
Tally computation runs automatically.
Preliminary results published within 60 minutes of
close.
Observer orgs run independent recounts; confirm
agreement.
T+1 day: Observer review + audit
24-hour observer-review window. Observers publish
findings on the audit domain.
Any discrepancies flagged for paper-ballot comparison.
Paper-ballot audit (statistical sample, per state law)
compared against digital tally.
Audit firm cross-checks: every winning contest’s
signature chain is valid, no suppressed or
inflated votes.
T+2 days: Canvassing + certification
County canvassing board meets.
Any challenges from candidates / observers heard.
Final adjudication on flagged ballots (typically
paper-ballot cases).
Certification event published with full governor
quorum signatures:
bash quidnug-cli elections certify \ --year 2026-nov \ --quorum-signatures "<signatures>" \ --sign-with <authority-key>
Certified results federate to state network via
TRUST_IMPORT.
T+7 days: Post-election report
Operational postmortem written and published:
- Turnout statistics
- Any incidents + resolutions
- Performance metrics (response times, uptime)
- Comparisons with prior elections
All code audit findings that were deferred get
reviewed for future fixes.
T+30 days: Archival + handoff
Full chain data archived to long-term storage
(archive nodes + offline backup).
Election authority quid retired; governor keys
transitioned or stored.
Precinct devices collected + wiped (except key
material is zeroized).
Post-election audit report published.
Legal + media archives finalized.
Begin planning for next election cycle.
Metrics to track
For every election, track these against targets from
operations.md §4:
Metric
Target
How to measure
Total registered voters
(set per election)
Count of VOTER_REGISTERED events
Total voters who voted
(set per election)
Count of unique BQs with cast-vote events
Average voter wait time
< 15 minutes
Logged per precinct
Precinct device uptime
> 99%
Device-reported health checks
Consortium uptime
> 99.9%
Node-reported health + block production rate
Response time (poll worker query)
< 500ms p99
API logs
Response time (observer query)
< 2s p99
API logs
Discrepancies flagged
< 0.01% of ballots
Audit reports
Post-election audit results match
100%
Audit summary
Observer satisfaction
> 90%
Survey post-election
What to do if…
…you find evidence of fraud during voting
Don’t stop voting. Publish a FRAUD_SUSPECTED event.
Route suspicious activity to IR team immediately.
If the fraud appears widespread + actionable, consult
legal about whether to extend hours or contest results.
Post-election audit becomes the forum for adjudication.
…the consortium becomes partitioned
Don’t panic. Partitions happen.
Consortium members on each side produce blocks
independently (tiered Tentative across the split).
When partition heals, the existing tiered-block-
acceptance machinery converges.
No lost votes (they’re in local cache on each side and
sync up on reconnection).
…a precinct device is stolen / compromised
Precinct switches to paper-only check-in immediately.
IR team revokes the stolen device’s node key.
Any votes cast through that device flagged for paper
verification.
File a police report; file an INCIDENT_REPORT event.
…the election is contested
Contesting candidate submits a CONTEST_CHALLENGE
event with their basis.
Canvassing board reviews per state law.
Cryptographic recount is always available (anyone’s
laptop can do it).
If paper-ballot audit disagrees with digital tally,
paper wins; investigation into discrepancy.