Two authorization modes are supported, depending on the election configuration:
+proof-of-identity: the voter receives a one-time password by email (OTP flow).proof-of-election-codes: the voter derives a cryptographic proof from printed election codes.| requestAccessCode | -Initiates the authorization process, in case voter has not authorized yet. Requests access code to be sent to voter email | +Requests a one-time password sent to the voter's email | |
| validateAccessCode | -Gets voter authorized to vote. | +Validates the OTP code and obtains the identity token | |
| registerVoter | Registers the voter on the bulletin board | ||
| AVClient.constructBallotCryptograms | -constructBallotCryptograms | +constructBallot | +Encrypts the ballot selections and submits cryptograms | +
| spoilBallot | +Optional. Initiates ballot encryption testing (challenge flow). | +||
| castBallot | +Finalizes the voting process | +
| Method | +Description | +|
|---|---|---|
| initialize | +Initializes the library by fetching election configuration | +|
| generateProofOfElectionCodes | +Derives a cryptographic proof from the voter's election codes | +|
| createVoterRegistration | +Registers the voter on the bulletin board | +|
| constructBallot | +Encrypts the ballot selections and submits cryptograms | |
| spoilBallot | -Optional. Initiates process of testing the ballot encryption. | +Optional. Initiates ballot encryption testing (challenge flow). |
| castBallot | -Finalizes the voting process. | +Finalizes the voting process |
OptionaldbbPublicKey: stringInitializes the client with an election config. -If no config is provided, it fetches one from the backend.
-OptionallatestConfig: LatestConfigAllows injection of an election configuration for testing purposes
-OptionalkeyPair: KeyPairAllows injection of a keypair to support automatic testing
-Returns undefined if succeeded or throws an error
-NetworkError if any request failed to get a response
-Should be called when a voter chooses digital vote submission (instead of mail-in).
-Will attempt to get backend services to send an access code (one time password, OTP) to voter's email address.
-Should be followed by validateAccessCode to submit access code for validation.
+Creates a new AVClient instance pointed at a specific Digital Ballot Box.
+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.
+Loads the election configuration and generates a fresh EC key pair for the voter.
+If latestConfig is provided it is validated and used directly; otherwise the config is
+fetched from the DBB (GET /configuration/latest_config). After loading the config,
+AVCrypto is initialised with the elliptic curve from genesisConfig.eaCurveName and a
+fresh EC key pair is generated. Must be the first method called on a new AVClient.
OptionallatestConfig: LatestConfigOptional election configuration to inject. If provided it is validated +before use; if omitted the config is fetched from the DBB.
+OptionalkeyPair: KeyPairOptional key pair to inject instead of generating a fresh one. For testing only.
+Returns undefined on success or throws an error.
+InvalidConfigError if the injected latestConfig fails validation.
Starts the OTP (one-time password) authorization flow by requesting an access code sent to +the voter's email address.
+Calls the Voter Authorizer coordinator to create a session and trigger an OTP email. Stores
+the returned sessionId as authorizationSessionId and the email address internally.
Only used when authorizationMode === 'proof-of-identity'. For the election-codes flow,
+use generateProofOfElectionCodes instead.
Should be followed by validateAccessCode.
Voter ID that preserves voter anonymity.
-where the voter expects to receive otp code.
-OptionalballotReference: stringThe ballot which which voter voter intends to vote on
-Returns undefined or throws an error.
-NetworkError if any request failed to get a response
+The voter's email address where the OTP will be sent.
+OptionalballotReference: stringOptional ballot reference identifying which ballot the voter intends to vote on.
+Returns undefined on success or throws an error.
+VoterRecordNotFoundError if no voter record matches the given ID.
+EmailDoesNotMatchVoterRecordError if the email address does not match the voter's record.
+BallotReferenceNotOnVoterRecord if the provided ballotReference is not on the voter's record.
NetworkError if any request failed to get a response.
Should be called after requestAccessCode.
-Takes an access code (OTP) that voter received, uses it to authorize to submit votes.
-Internally, generates a private/public key pair, then attempts to authorize the public -key with each OTP provider.
-Should be followed by AVClient.constructBallotCryptograms | constructBallotCryptograms.
-An access code string.
-Returns undefined if authorization succeeded or throws an error
-InvalidStateError if called before required data is available
-AccessCodeExpired if an OTP code has expired
-AccessCodeInvalid if an OTP code is invalid
-NetworkError if any request failed to get a response
-Registers a voter based on the authorization mode of the Voter Authorizer -Authorization is done by 'proof-of-identity' or 'proof-of-election-codes'
-Registers a voter based on the authorization mode of the Voter Authorizer
-undefined or throws an error
-Should be called after validateAccessCode.
-Encrypts a ballot-selection (CVR) and generates vote cryptograms.
+Validates the one-time password (OTP) the voter received by email. On success, +stores the identity confirmation token internally so that +registerVoter can authorize the voter with the DBB.
+Should be followed by registerVoter.
+The one-time password string received by the voter via email.
+Returns undefined if authorization succeeded or throws an error.
+InvalidStateError if called before requestAccessCode.
+AccessCodeExpired if the OTP code has expired.
+AccessCodeInvalid if the OTP code is invalid.
+NetworkError if any request failed to get a response.
+Derives a cryptographic proof from the voter's printed election codes.
+Required when the election uses authorizationMode === 'proof-of-election-codes' as an
+alternative to the OTP email flow. The derived proof is stored internally and consumed by
+createVoterRegistration.
Must be called after initialize and before +createVoterRegistration.
+Array of election code strings provided to the voter (e.g. on a printed card).
+Directly sets the identity confirmation token without going through the standard OTP flow.
+Use this when the consuming application obtains an identity token through an external +authentication mechanism and needs to inject it before calling +registerVoter. This is an alternative to calling +requestAccessCode → +validateAccessCode.
+The identity confirmation token string obtained from the external identity provider.
+Sets the registration channel before calling createVoterRegistration.
+When the election configuration includes segmentsConfig.content.channels, the consuming
+application should call this method with a channel private key (typically stored in
+localStorage by a channel-provisioning flow) before registering the voter. Internally,
+the key is used to sign a JWT ({ sub: "channel" }) that is sent alongside the voter
+registration request, allowing the DBB to associate the vote with a specific channel.
Passing undefined clears any previously set channel, which means no channel JWT is
+included in the registration request.
Must be called after initialize and before +createVoterRegistration.
+Hex-encoded P-256 private key for the channel, or undefined to clear.
Retrieves voter information from the Voter Authorizer coordinator.
+Requires that the voter has already been identified — either via the OTP flow +(validateAccessCode) or via election codes +(generateProofOfElectionCodes).
+The returned AxiosResponse.data contains voter metadata as returned by the Voter Authorizer.
+Commonly accessed fields include:
ballotReference — identifies which ballot config applies to this voter.demo — whether this voter is a demo voter (used to filter voting rounds).Typical usage: call this method after identification and use data.ballotReference to look up
+the voter's ballot config from getLatestConfig().items.ballotConfigs, then determine which
+voting rounds are active and applicable before calling
+createVoterRegistration.
The raw AxiosResponse from the Voter Authorizer. Relevant shape:
{ data: { ballotReference: string, demo: boolean, ...voterMetadata } }
+InvalidStateError if neither an identity token nor an election code proof is available.
+NetworkError if any request failed to get a response.
+Registers the voter on the Digital Ballot Box, branching on the election's authorizationMode.
proof-of-identity: uses the identity confirmation token obtained via
+validateAccessCode (or
+setIdentityToken) to request a JWT from the Voter
+Authorizer, then posts a voter session to the DBB.proof-of-election-codes: uses the proof generated by
+generateProofOfElectionCodes to request a
+JWT from the Voter Authorizer, then posts a voter session to the DBB.Note: if an identity confirmation token is present (set via
+setIdentityToken), the identity path is used regardless
+of authorizationMode. This allows SSO-integrated consumers to inject a token even in
+elections configured as proof-of-election-codes.
The DBB response is validated against the DBB public key. On success, the voter session is +stored internally and used in all subsequent calls.
+Prefer registerVoter for the standard single-round case.
+Use this method when you need to specify a non-default votingRoundReference.
Identifies which voting round to register for. Defaults to "voting-round-1".
Returns undefined on success or throws an error.
+InvalidStateError if the required token or proof is missing.
+InvalidTokenError if the JWT from the Voter Authorizer cannot be decoded.
+InvalidConfigError if the election has an unknown authorizationMode.
BulletinBoardError if the DBB rejects the registration.
+NetworkError if any request failed to get a response.
+Registers the voter on the Digital Ballot Box for voting round 1.
+Convenience wrapper around createVoterRegistration
+using the default votingRoundReference = "voting-round-1". This is the method defined in
+the IAVClient interface and is sufficient for most single-round elections.
Must be preceded by voter identification:
+Returns undefined on success or throws an error.
+InvalidStateError if the required token or proof is missing.
+InvalidTokenError if the JWT from the Voter Authorizer cannot be decoded.
+BulletinBoardError if the DBB rejects the registration.
+NetworkError if any request failed to get a response.
+Expires all active voter sessions for the given voting round on the Digital Ballot Box.
+Only supported when authorizationMode === 'proof-of-election-codes'. Uses the stored
+election code proof (set by generateProofOfElectionCodes)
+to obtain an expiration JWT from the Voter Authorizer (action "expire"), then posts to
+POST /voting/expirations on the DBB.
Primarily used by IVR telephony consumers to end a voting session programmatically.
+Identifies which voting round's sessions to expire.
+The raw AxiosResponse from the DBB expiration endpoint.
InvalidStateError if called when authorizationMode === 'proof-of-identity' (not supported).
InvalidStateError if called before generateProofOfElectionCodes.
+InvalidTokenError if the expiration JWT from the Voter Authorizer cannot be decoded.
+InvalidConfigError if the election has an unknown authorizationMode.
NetworkError if any request failed to get a response.
+Extends the active voter session on the Digital Ballot Box.
+Signs a SessionExtensionItem containing { extendedBy } with the voter's private key and
+posts it to POST /voting/extensions. Requires that voter registration has completed (so that
+voterSession is set). No-ops silently if the voter session has an empty address.
Used by consuming applications to refresh the session timeout when the voter is still active
+(e.g. after a "Extend session" prompt in the UI, or while the voter is on the phone in an
+IVR flow). The number of seconds to extend by is typically read from
+electionStatus.sessionCountdown.extendSeconds.
Number of seconds to extend the session by.
+Returns undefined on success or throws an error.
+TypeError if called before voter registration (this.voterSession is undefined — the guard on line 628 dereferences it directly).
NetworkError if any request failed to get a response.
+Encrypts the voter's ballot selections and submits them to the Digital Ballot Box.
+Must be called after registerVoter (or +createVoterRegistration).
+Internally performs the following steps:
+ballotSelection against the voter's contest configs and marking rules.POST /voting/commitments — submits the voter commitment to the DBB. Receives the
+board commitment (server's Pedersen commitment) and server envelopes.POST /voting/votes — submits ballot cryptograms and ZK proofs to the DBB.Should be followed by either spoilBallot +or castBallot.
Example:
-const client = new AVClient(url);
const cvr = { '1': 'option1', '2': 'optiona' };
const trackingCode = await client.constructBallotCryptograms(cvr);
+const client = new AVClient(url);
const trackingCode = await client.constructBallot(ballotSelection);
Example of handling errors:
-try {
await client.constructBallotCryptograms({});
} catch(error) {
if(error instanceof AvClientError) {
switch(error.name) {
case 'InvalidStateError':
console.log("State is not valid for this call");
break;
case 'NetworkError':
console.log("It's a network error");
break;
default:
console.log('Something else was wrong');
}
}
}
-
+try {
await client.constructBallot(ballotSelection);
} catch(error) {
if(error instanceof AvClientError) {
switch(error.name) {
case 'InvalidStateError':
console.log("State is not valid for this call");
break;
case 'NetworkError':
console.log("It's a network error");
break;
default:
console.log('Something else was wrong');
}
}
}
+
-Where '1' and '2' are contest ids, and 'option1' and 'optiona' are
-values internal to the AV election config.
-Should be followed by either spoilBallot
-or castBallot.
-BallotSelection containing the selections for each contest.
-Returns the ballot tracking code. Example:
-'5e4d8fe41fa3819cc064e2ace0eda8a847fe322594a6fd5a9a51c699e63804b7'
+BallotSelection containing the voter's selections for each contest.
+The 7-character Base58 ballot tracking code (e.g. 'A3K9mNP').
InvalidStateError if called before registerVoter.
+CorruptCvrError if the ballot selection is structurally invalid.
+NetworkError if any request failed to get a response.
+Finalises the voting process by casting the previously constructed ballot.
+Must be called after constructBallot. Signs a
+CastRequestItem with the voter's private key and posts it to POST /voting/cast on the
+DBB. The DBB response payload and receipt are validated against the DBB public key.
If sendTrackingCodeByEmail is enabled in the election configuration, an attempt is made to
+send the receipt to the voter by email via the Voter Authorizer. Email delivery failures are
+logged but not propagated as errors.
BCP 47 locale tag for the receipt email (e.g. "en", "es", "fr"). Defaults to "en".
The BallotBoxReceipt confirming the ballot was recorded. Shape:
{
previousBoardHash: string,
boardHash: string,
registeredAt: string, // ISO 8601
serverSignature: string, // EC signature from the DBB
voteSubmissionId: number
}
InvalidStateError if called before required data is available
-CorruptCvrError if the cast vote record is invalid
-NetworkError if any request failed to get a response
-Should be the last call in the entire voting process.
-Requests that the previously constructed ballot is cast.
-The locale which the email with the vote receipt should be sent in
-Returns the vote receipt. Example of a receipt:
-{
previousBoardHash: 'd8d9742271592d1b212bbd4cbvobbe357aef8e00cdbdf312df95e9cf9a1a921465',
boardHash: '5a9175c2b3617298d78be7d0244a68f34bc8b2a37061bb4d3fdf97edc1424098',
registeredAt: '2020-03-01T10:00:00.000+01:00',
serverSignature: 'dbcce518142b8740a5c911f727f3c02829211a8ddfccabeb89297877e4198bc1,46826ddfccaac9ca105e39c8a2d015098479624c411b4783ca1a3600daf4e8fa',
voteSubmissionId: 6
}
+Throws
InvalidStateError if called before constructBallot.
+Throws
NetworkError if any request failed to get a response.
+Initiates the ballot challenge (spoil) flow to test the ballot encryption.
+Must be called after constructBallot, as an alternative to
+castBallot. Signs a SpoilRequestItem and posts it to
+POST /voting/spoil. Retrieves the server commitment opening and validates it against the
+previously stored board commitment and server envelopes.
The returned address is passed to +AVVerifier.submitVerifierKey on the second (verifier) +device to link the two devices.
+Should be followed by waitForVerifierRegistration.
+The spoilRequest.address string — the DBB chain address of the spoil request item.
InvalidStateError if called before constructBallot.
+NetworkError if any request failed to get a response.
+Sends the voter's commitment opening (ballot randomizers) to the verifier device via the DBB.
+Must be called after constructBallot (which generates the
+commitment opening) and after
+waitForVerifierRegistration (which provides the
+verifier's public key). Encrypts the voter's CommitmentOpening (ballot randomizers and
+commitment randomness) under the verifier's public key and fires a
+POST /verification/commitment_openings request to the DBB.
Note: The HTTP request is fire-and-forget — it is not awaited. The method returns +immediately regardless of network success.
+Returns undefined immediately (HTTP request is not awaited).
+InvalidStateError if called before voter registration (this.voterSession not set).
TypeError if called before waitForVerifierRegistration — this.verifierItem and this.voterCommitmentOpening are not explicitly guarded and will be undefined.
Returns the full election configuration loaded during initialize.
+The LatestConfig object containing genesis config, election config, contest configs,
+ballot configs, voting round configs, and threshold key.
InvalidStateError if called before initialize.
+Returns the voter session item received from the DBB after registration.
+The voter session item contains the voter's identifier, public key, weight, voter group, and +voting round reference as stored on the DBB chain.
+The VoterSessionItem from the DBB.
InvalidStateError if called before registerVoter.
+Returns the Voter Authorizer session ID for the current authorization session.
+Set during requestAccessCode (OTP flow) or during +createVoterRegistration (election codes flow).
+Common uses by consumers:
+The authorization session ID string.
+Returns the ballot configuration for the voter's voter group.
+The ballot config defines which contests appear on the voter's ballot (i.e. the set of contest +references for this voter group). Use getVoterContestConfigs +to get the full contest configs filtered to the active voting round.
+The BallotConfig for the voter's group.
InvalidStateError if called before registerVoter.
+Returns the contest configurations accessible to this voter in the current voting round.
+Computes the intersection of contests on the voter's ballot (from their voter group) and
+contests active in the current voting round. Each ContestConfig includes the contest title,
+marking rules (min/max selections, weights), available options, and encoding parameters.
Array of ContestConfig objects for the contests this voter can vote on.
InvalidStateError if called before registerVoter.
+Returns the DBB public key used to verify DBB-signed payloads and receipts.
+Returns the key pinned at construction time (if provided), otherwise falls back to the key +from the genesis config loaded during initialize.
+The hex-encoded DBB public key string.
+InvalidStateError if no DBB public key is available (neither pinned nor loaded).
+Signs an arbitrary string payload with the voter's EC private key.
+Useful when the consuming application needs to produce a signature on behalf of the voter +(e.g. for authenticating requests to external services). Requires +initialize to have been called so the key pair is available.
+The string to sign.
+The EC signature as a hex string.
+Polls the Digital Ballot Box until the verifier device registers its public key.
+Must be called after spoilBallot. Queries
+GET /verification/verifiers/{address} every 1000ms for up to 600 attempts (10 minutes). Resolves
+once a VerifierItem is detected on the DBB chain for this spoil request, stores the verifier
+item internally (used by challengeBallot), and returns the
+7-character Base58 pairing code derived from the verifier item's short address.
Both the voter's app and the verifier device should display the pairing code so the voter can +confirm they are connected to the correct second device.
+Should be followed by challengeBallot.
+The 7-character Base58 pairing code derived from the verifier item's DBB address.
+InvalidStateError if called before voter registration or before spoilBallot.
+TimeoutError if the verifier does not register within 600 poll attempts.
+Retrieves the current status and audit log for a ballot identified by its tracking code.
+Decodes the Base58 tracking code to its hex short address and queries
+GET /ballot_status on the DBB. This method does not require an active voter session and
+can be called unauthenticated — useful for voters checking their ballot after the fact or
+for external verification tools.
The 7-character Base58 tracking code returned by constructBallot.
+A BallotStatus object:
{
status: string, // e.g. "cast", "spoiled", "pending"
activities: Activity[] // audit log entries for this ballot
}
+Disables the voter in the Voter Authorizer so they can no longer sign in or vote.
+Signs the current authorizationSessionId with the voter's private key and calls the VA
+disable endpoint. Used in two contexts:
Requires that voter registration has been completed
+(registerVoter or
+createVoterRegistration) so that both
+authorizationSessionId and voterSession.content.votingRoundReference are available.
The raw AxiosResponse from the Voter Authorizer disable endpoint.
NetworkError if any request failed to get a response.
+Retrieves the voting round items for the voter's current voting round from the Voter Authorizer.
+Signs the authorizationSessionId with the voter's private key to authenticate the request.
+The returned AxiosResponse.data.items is an array of voting round items (e.g. information
+pages to display before the ballot). Consumers should handle the case where data.items is
+missing or not an array, as the shape depends on the Voter Authorizer configuration.
Requires that voter registration has been completed so that authorizationSessionId and the
+voter session's votingRoundReference are available.
The raw AxiosResponse from the Voter Authorizer. Relevant shape:
{ data: { items: RawVotingRoundItem[] } }
NetworkError if any request failed to get a response
-Should be called when voter chooses to test the encryption of their ballot. -Gets commitment opening of the digital ballot box and validates it.
-Returns undefined if the validation succeeds or throws an error
-InvalidStateError if called before required data is available
-NetworkError if any request failed to get a response
-Should be called when the voter has 'paired' the verifier and the voting app. -Computes and encrypts the clientEncryptionCommitment and posts it to the DBB
-Returns void if the computation was succesful
-InvalidStateError if called before required data is available
-NetworkError if any request failed to get a response
-Should be called after spoilBallot. -Gets the verifier public key from the DBB
-Returns the pairing code based on the address of the verifier item in the DBB
-InvalidStateError if called before required data is available
-TimeoutError if the verifier doesn't register itself to the DBB in time
-NetworkError if any request failed to get a response
-Finds the ballot status corresponding to the given trackingcode. -Also returns the activities associated with the ballot
-base58-encoded trackingcode
-Disables the voter in the VA, so that they can no longer vote or sign in.
-
URL to the Assembly Voting backend server, specific for election.
-