2. Functional analysis
[DRAFT VERSION]
The main objective of this project is to implement a digital governance system which includes features of anonymity and confidentiality. In order to achieve this goal, the proposed solution includes the usage of:
- a Tor network for the user-blockchain interactions, to prevent network analysis and the revelation of IP addresses of origin (layer 0 solution);
- an implementation of a ZkSNARKS protocol for the Ethereum smart contracts, with the help of ZoKrates (layer 2 solution);
Agora is a dApp composed by a web front end and a backed composed by an application server and a database. The backend interacts with the underlying public Ethereum network. On the front end side we can distinguish two applications, one that interacts with the back end, the other one directly with the blockchain network: in this way the backend it has no knowledge of the data that the user certifies on the blockchain.
The application provides two types of users:
- Admin users: access the admin area and they can create a manage elections;
- Voter users: they can register to the platform as voters, they can vote, and check if the vote is correctly registered on the blockchain network; The homepage is accessible to everyone, in the home page is possible to consult the results of the elections.
Following an high level rapresentation of the main flow of the entire voting process:
| point | explanation |
|---|---|
| 1 | A public authority deploys a Register of DECs (Digital Electoral Cards) smart contract, and for each voter emits an EOA and registers the DEC on the registry(encrypting the data). The DECs Registry contains the list of DECs of the voters and for each DEC a list of "election stamps" that certify the vote in a certain election. Since there is a third party authority in the process, Agora is not considered to be a DAO. |
| 2 | The public authority comunicates the EOA credentials (public address and private key) to the Voter. |
| 3 | The Admin (part of the public authority) deploys an Election smart contract. The smart contract contains the data of election that need to be certified on the blockchain, the registration period for parties to register their candidates and the voting period. |
| 4 | The Voter registers to the Voter panel in order to check the right to vote and downloads the client to be used for voting. |
| 5 | The Voter votes, using the ZKSNARKS cryptographic protocol and generating a pi-vote proof. The Voter uses a digital signature to sign the proof and the TOR network to send the data to the blockachain. |
| 6 | The Election smart contract verifies the Voter's right to vote and verifies that the Voter's "stamps" list registered in the DECs registry does not contain alredy the election stamp. |
| 7 | The Election smart contract verifies the proof, if it is accepted, the vote is registered on the smart contract. |
| 8 | The election smart contract put the election stamp on the Voter's DEC. |
| 9 | When the election closes, a ZKSNARKS pi-result is calculated and the proof is verified by the Election smart contract. The results of the election are published. |
| 10 | Voters and anonymous users can consult the results of the election. The Voter can also checks on the blockchain that his/her vote has been regularly registered. |
The voting protocol of Agora consists of 5 phases:
-
Phase 0, release of the DEC and EOA: An authority generates and releases a Digital Electoral Card (DEC) and an EOA for the Voter. The DEC is registered on the DEC's Registry smart contract. The pair of public address and private key of the EOA is communicated to the Voter:
-
Phase 1, setup: An Admin initializes and opens an election, prepares the lists and candidates, prepares the list of voters and all the information of the election (region, province, municipality, etc.) which will be cross-referenced with the data of the voter's DEC to verify the right to vote:
-
Phase 2, initialization: to initialize phase 2, the Admin must determine the time period for the elections. The server generates the Election smart contract and releases it onto the blockchain. The recording time is saved and the election status updated to “initialized”:
-
Phase 3, voting: the Admin canm modify the time interval for voting if needed. When the voting period begins, the voting status is updated to "open" and Voters can access the list of candidates from the server, the server verifies the election and DEC data to authorize voting, checking that the DEC has not been already "stamped". The voter carries out the vote and generates the related proof π-vote. The Voter sends the transaction to the Election smart contract. The computations are done locally in the Voter's machine and the transaction is sent directly to the smart contract. the client server does not acquire any information from the Voter. The Election smart contract double check the voting rights and "prints" the election metadata on the voter's DEC and if everything is ok acquires the π-vote proof:
-
Phase 4, calculation of the result: when the voting period ends, the server automatically closes the voting and updates the status of the election to "closed". The server takes all the ballots from the Election smart contract and calculates the result. The server generates a proof π-result of the election results and sends the proof to the Election smart contract for verification. When the election results are published, a check can be carried out by interacting directly with the blockchain to extract the result and the validity of the proof. the result is considered valid only when the corresponding proof π-result is valid. The Voter can also check whether his/her vote was correctly counted in the calculation of the results:
In cryptography, a zero-knowledge proof or zero-knowledge protocol is a method by which one party (the prover) can prove to another party (the verifier) that a given statement is true, while avoiding conveying to the verifier any information beyond the mere fact of the statement's truth.
The zero-knowledge proof voting protocol to be implemented represents the core module of the project. Such protocol is used to check a Digital Electoral Card to assert that the Voter has the right to vote, without revealing the identity of the Voter. . Such protocol is implemented using the ZoKrates library, a ZK-SNARKS protocol implementation library for Ethereum.
The smart contracts libraries are based on the following high level requirements:
- An authority releases an EOA smart contract for the Voter, deploy a DECs Registry smart contract and register the Voter's DEC into the Registry;
- The administrator creates an election with all the required information;
- The administrator creates and adds candidates to the election, adding candidates information;
- The administrator sets a time interval where it is possible for the voters to register to the election;
- The administrator sets a time interval where it is possible for the voters to vote;
- The system checks if the Voter has the right to vote, by cross-referencing the election and electoral card data;
- The voter cast the vote: 20 voting points are available for voting and can be distributed across the candidates;
- The system checks the validity of the vote;
- The vote event is registered on the Voter's DEC;
- The voter can no more vote again;
- When the election is closed, the results of the elections are published;
- The voter can check if the vote has been regularly registered;
The backend module consists of a classic application server. The server exposes a set of RESTful APIs over HTTP that invokes the smart contracts methods. Also, it serves the front end module. The APIs are designed to be consumed only after an authentication.
To summarize, the backend module’s requirements are:
- Expose the API for the authentications:
- Admin/authority users authentication;
- Voters users authentication;
- Manage the session for Admin users;
- Manage the session for Voters users;
- Manage the permissions for admin and voters users;
- All the APIs are exposed under authentication;
- The APIs deploy smart contracts and invoke their methods;
- The APIs expose the logic required by the front end module;
- The back end serves the front end application;
- The back end manage the logic that prevent ad admin to access the user front end and vice versa;
- The back end implement solutions to improve the performances (e.g. cache);
The front end module consists in a Single Page Application that has 2 submodules: The Admin Module and the Voter Module.
The dApp front end allow to login the Voter module using an EOA: it is important to highlight here that the EOA is a wallet in all respects, being able to manage fungible and non-fungible tokens. As a wallet, the EOA can be stored in a third-party browser extension (e.g. metamask) that is then used to login the frontend dApp.
It is out of scope of this project to go in depth with the gas fees payments, but we can mention here that Voting Coins (in ether, the coin of Ethereum network) can be accredited on the DEC, and then used by the Voter to pay the gas fees for the registration and the vote transactions. It is possible to implement and Escrow contract in order to allow only payments for the voting process.
The Admin instead, login the Admin Module using a classic oauth-2 authentication protocol.
Main general requirements for the Front end module are:
- the front end checks the user permissions;
- the front end forbid the access to pages if the user does not have the required permissions;
- the front end manage the routing;
- the front end displays fallback pages in case of server errors;
- the front end manage the errors by displaying appropriate warning and error messages;
- The Admin and the Voter can log in using their credentials or the EOA respectively;
- A notification system provide feedbacks for the user;
- The results of the elections are automatically displayed on an anonymous web page;
- the front end respect the W3C accessibility guidelines;
The Admin sub-module of the Front end is used by the user for creating and managing elections. It provides the following functionalities:
- create and manage elections;
- add and manage candidates;
- manage elections and candidates information;
The voter sub-module is used by the user to:
- view info about the election;
- view info about the candidates;
- view personal information related to the DEC;
- cast the vote;
- check if the vote was regularly counted;
Based on the protocol described in the Solution Proposed paragraph, the following use cases are defined:
- An authority entity create a DEC and a EOA for a Voter;
- An Admin access the application and opens and save an election;
- An Admin set the registration interval for the election;
- An Admin set the voting time interval for the election;
- A Voter votes;
- An user checks the results of an election;
The authority invokes a backend APIs for:
- Deploy the DECs Registry (only one time);
- Register a DEC for each Voter;
- Generates an EOA for each Voter;
. The data given to the API for the creation of the digital document are:
- Id
- Country
- Region
- Province
- Municipality
- Tax code
The Api answers with the address and the private key generated with the generation of the EOA contract. This couple of credentials are communicated to the Voter. The DEC is associated to the EOA public address.
The admin user log in into the application as admin, push the button "create election" and compile the form:
- Election title: a descriptive name that identifies the purpose of the election.
-
Election category: The election category data is a type of a list, that specify the kind of the election:
- National
- Regional
- Municipal Each election type defines the voting rules and mechanis.
We don't want to replicate real electoral rules since they are different from country to country and also such rules change over time, anyway we want to give to the system the necessary elasticity to define a ballot type based on the election category chosen (e.g. in Italy, municipalities election the ballot contains candidate names and each candidate is supported by a list of parties, while in a national election the ballot consist in groups of parties coalitions and no candidate names are reported).
The election category (together with the date of birth) is used to check which Voter has the right to vote for the election. This data is contained in the Voter DEC. Example, if the Vote is Regional for Region Lombardia, only Voters that have a digital electoral card signed with “Region: Lombardia” have the right to vote.
- Election category type: For “Regional” type, the value is the region, for “Provincial” the province, for “Municipal” the municipality.
- Parties-Candidates: a 1:1 data that specifies the party name and the candidate.
- Voting points: the total amount of points to be distributed across the candidates.
- Start date: the date from which it is possible to vote.
- End date: the date indicating the end of voting.
The Admin save the election into the database. The election status is "open".
The Admin user log in into the application as Admin, from the list of elections, click on the election with status "open". The Admin set the interval time for the registration and save the data. The election has now the status "initialization".
the Admin login the application. From the list of created elections, he/she can click the elections with status "registration" that passed the date and time of registration end. The Admin set the time interval for voting and save. The election has now status: "seats open".
The Voter login the application. From the list of elections, he/She click the election with status "seats open". In the voting page the Voter has an amount of points to share across the candidates. The voter distributes the points across the candidates, then push "vote". The client application generates the vote proof and sends the ballot to the Voting smart contract directly. The Voting Smart contract checks the stamps on the Voter's DEC, if not already present put the "stamp" of the Election on the DEC and acquires the ballot. If the "stamp" is already present, the Voting smart contract rejects the ballot.
Every anonymous user can see in the home page of the application the list of the Elections with status "closed", they can click the election and check the results.