Skip to content

AuditRecord.md

Latest commit

 

History

History
118 lines (83 loc) · 5.97 KB

AuditRecord.md

File metadata and controls

118 lines (83 loc) · 5.97 KB

The AuditRecord

last changed 04/11/2026

An Audit Record may have the following files in it:

$auditdir/
    // election record - output of createElectionRecord (prover)
    cardManifest.csv      // AuditableCardCsv, may be zipped
    cardPools.csv         // CardPoolCsv:    CardPoolIF -> CardPool (optional)
    cardStyles.json       // CardStylesJson: CardStyleIF -> CardStyle (optional)  
    contests.json         // ContestsUnderAuditJson
    electionInfo.json     // ElectionInfoJson 

    // auditRecord - output of createAuditRecord, after the seed has been chosen
    auditCreationConfig.json  // AuditCreationConfigJson 
    auditRoundPrototype.json  // auditRoundConfigJson ; prototype for auditRoundConfigX
    sortedCards.csv       // AuditableCardCsv, sorted by prn, may be zipped

    roundX/
        auditEstX.json       // AuditRoundJson,  an audit state with estimation, ready for auditing
        auditRoundConfigX.json  // auditRoundConfigJson, configuration for this round
        auditStateX.json     // AuditRoundJson,  the results of the audit for this round
        sampleCardsX.csv     // AuditableCardCsv, complete sorted cards used for this round; matches samplePrnsX.csv
        sampleMvrsX.csv      // AuditableCardCsv, complete sorted mvrs used for this round; matches samplePrnsX.csv
        samplePrnsX.json     // SamplePrnsJson, complete sorted sample prns for this round

    private/                  (test only - not part of the public record)
        sortedMvrs.csv       // AuditableCardCsv, sorted by prn, matches sortedCards.csv, may be zipped
        unsortedMvrs.csv     // AuditableCardCsv (optional)

Also see core/src/main/kotlin/org/cryptobiotic/rlauxe/persist/Publisher.kt.

Commitment Sequence

  1. createElectionRecord

The election information is contained in the following files. The EA can modify these until satisfied that they are correct. Before the seed is chosen in step 2, they are digitally signed and published publically (aka committed to the Audit Record), and then may not be changed.

    cardManifest.csv      // AuditableCardCsv, may be zipped
    cardPools.csv         // CardPoolCsv:    CardPoolIF -> CardPool (optional)
    cardStyles.json       // CardStylesJson: CardStyleIF -> CardStyle (optional) 
    contests.json         // ContestsUnderAuditJson
    electionInfo.json     // ElectionInfoJson
  1. createAuditRecord : PRNG seed chosen, cards assigned PRNs

The PRNG seed is chosen, and all the cards in the card manifest are assigned a PRN in sequence by the PRNG. The cards are then sorted by PRN and written to sortedCards.csv. These are commited to the Audit Record. The PRNG seed can only be chosen once and the cards immediately committed.

    auditCreationConfig.json  // AuditCreationConfigJson (contains the seed)
    auditRoundPrototype.json  // auditRoundConfigJson ; prototype for auditRoundConfigX
    sortedCards.csv           // AuditableCardCsv, sorted by prn, may be zipped
  1. Audit Round X Sample Estimation

The EA decides which contests are in (or will continue to be in) the audit, and what the configuration parameters are for the round. The EA can calculate estimated sample sizes, and modify contest sample sizes and AuditRoundConfig parameters as often as they want. The EA cannot hand pick which ballots to sample, only modify how many samples for each contest are used in the round. This preserves the canonical ordering of each contest, see Deterministic sampling order for each Contest for more explanation.

Once the EA is satisfied with sample sizes and auditing parameters, the following files are committed to the Audit Record:

    roundX/
        auditRoundConfigX.json  // the configuration parameters for round X
        auditEstX.json          // the estimation of sample sizes of the contests in this round
        samplePrnsX.json        // the chosen sample cards' prns for this round
  1. Audit Round X gather MVRs

The physical ballots/cards are found that match samplePrnsX.json. These are hand-audited and their MVRs are written to sampleMvrsX.csv. The matching cards from the CardManifest are written to sampleCardsX.csv, for completeness and security. Before the audit is run, these are committed to the Audit Record:

    roundX/
        sampleMvrsX.csv      // complete mvrs used for this round; matches samplePrnsX.csv
        sampleCardsX.csv     // complete cards used for this round; matches samplePrnsX.csv
  1. Run Audit Round X

The audit is run for round X, and the following file is committed to the Audit Record:

    roundX/
        auditStateX.json     // the results of the audit for this round

If not all contests are complete at the end of each round, then a new round begins and steps 3,4,5 are repeated.

Composite AuditRecord

This is an experimental feature for Belgium elections. Each componment is a single contest.

$compositedir/
    $component1/
       audit/
    $component2/
       audit/      
    ...

Use AuditRecord.readFrom($compositedir). Each $component/audit is an AuditRecord. The contests from all components are put into the CompositeRecord. You can view and read, but not run audits on the CompositeRecord. Run audits independently on the individual components.

SingleRoundAudit vs Auditing with rounds

For simulation and testing, its convenient to do the audit in a single round, with all MVRs available, skipping the estimation steps, and keeping everything in memory (no persistence).

AuditWorkflow and its subclasses (esp PersistedWorkflow) implement auditing with rounds.

For real-world workflow examples, see createSfElection(), createBoulderElection(), createBelgiumClca(), and createColoradoElection() in the cases module.

Auditing with rounds workflow

Running an audir round is done through the RunRlaRoundCli, or from the viewer.