Base URL of the Digital Ballot Box for this election.
OptionaldbbPublicKey: stringOptional DBB public key to pin at construction time. If omitted, the key is read from the genesis config once initialize is called.
Initializes the verifier with an election configuration.
If no config is provided, fetches it from the Digital Ballot Box
(GET /configuration/latest_config) and initialises AVCrypto with the elliptic curve
specified in the genesis config. Must be the first method called on a new AVVerifier.
OptionallatestConfig: LatestConfigOptional election configuration to inject (useful for testing). If omitted, the config is fetched from the DBB.
Returns undefined on success or throws an error.
Locates a ballot on the Digital Ballot Box by its tracking code and loads the data needed to decrypt and verify it.
Decodes the Base58 tracking code to its hex short address, queries
GET /verification/vote_track, and validates that the returned short address matches the
tracking code. On success, stores the voter commitment, board commitment, ballot cryptograms,
and cryptogram address internally.
Must be called after initialize and before pollForSpoilRequest.
The 7-character Base58 tracking code shown on the voter's device.
The DBB address of the ballot cryptograms item (cryptogramAddress).
InvalidTrackingCodeError if the tracking code does not match the DBB response.
Registers this verifier device on the Digital Ballot Box so the voter's device can pair with it.
Generates a fresh EC key pair for this verifier session, constructs a VerifierItem signed
with the verifier's private key, and posts it to POST /verification/verifiers. The
spoilRequestAddress (obtained from AVClient.spoilBallot)
links the verifier to the specific spoil request.
Must be called after findBallot and before pollForCommitmentOpening.
The DBB address of the spoil request item, as returned by
AVClient.spoilBallot.
The 7-character Base58 pairing code derived from the verifier item's short address. Both the voter's app and this verifier should display this code so the voter can confirm they are paired with the correct device.
NetworkError if any request failed to get a response.
Decrypts the ballot and returns the original contest selections.
Synchronous. Uses the verifier's private key (generated in
submitVerifierKey) to decrypt both the voter and board
commitment openings retrieved in
pollForCommitmentOpening. Validates both
Pedersen commitments to confirm neither party manipulated their randomizers, then decrypts
each contest pile to recover the original ContestSelection[].
This is the core end-to-end verification step: if it succeeds, the ballot was encrypted honestly and matches what the voter submitted.
Must be called after pollForCommitmentOpening.
Array of ContestSelection objects representing the original ballot choices.
Polls the Digital Ballot Box until the voter submits a spoil (or cast) request.
Queries GET /verification/spoil_status every 1000ms for up to 600 attempts (10 minutes).
Resolves as soon as a SpoilRequestItem is detected on the DBB chain for this ballot.
Rejects immediately if a CastRequestItem is detected instead (ballot was cast, not spoiled).
The returned address is passed to submitVerifierKey to link the verifier to the spoil request.
Must be called after findBallot.
The spoilRequest.address string once the voter has initiated the spoil flow.
Transforms raw contest selections into human-readable form using localised titles.
Maps each ContestSelection (which uses internal contest and option references) to a
ReadableContestSelection with localised titles from the election config. Falls back to the
first available locale if locale is not present in the config.
Typically called after decryptBallot to present the verification result to the voter in a readable format.
Array of ContestSelection objects as returned by decryptBallot.
BCP 47 locale tag (e.g. "en", "es", "fr") for title localisation.
Array of ReadableContestSelection objects:
{
reference: string,
title: string, // localised contest title
piles: {
multiplier: number,
optionSelections: {
reference: string,
title: string, // localised option title
text?: string // write-in text, if applicable
}[]
}[]
}[]
InvalidContestError if a contest reference is not found in the election configuration.
InvalidOptionError if an option reference inside a contest is not found in the election configuration.
Polls the Digital Ballot Box until both the voter and board commitment openings are available.
Queries GET /verification/commitment_openings every 1000ms for up to 600 attempts
(10 minutes). Resolves once both voterCommitmentOpening and boardCommitmentOpening are
present in the DBB response and stores them internally for use in
decryptBallot.
Must be called after submitVerifierKey and after the
voter's device has called AVClient.challengeBallot to post the encrypted commitment opening.
Typical usage: consumers simply await this method and immediately call
decryptBallot — the return value is not usually needed.
The full commitment openings response data once both openings are available.
Validates a BallotBoxReceipt against the DBB public key and the ballot's tracking code.
encodedReceipt is a base64-encoded JSON string containing the cast request item fields
(address, parentAddress, previousAddress, registeredAt, voterSignature) and the DBB
signature (dbbSignature). This method:
Base64-encoded JSON receipt string as returned by
AVClient.castBallot (after further encoding by the consuming app).
The 7-character Base58 tracking code for the ballot.
InvalidReceiptError if the receipt string is malformed or fails the cryptographic check.
InvalidTrackingCodeError if the tracking code does not match the receipt address.
Creates a new AVVerifier instance pointed at a specific Digital Ballot Box.