3. Technical analysis
[DRAFT VERSION]
This document describes the Agora project from a technical point of view. Agora is a software platform for a digital voting system implemented on top of the Ethereum blockchain network. The platform allows Admin users to create and manage elections and polls, and Voter users to cast votes, check that the vote has been correctly counted and check the elections results. Agora should be considered as a Proof Of Concept, it does not resolve some key problems connected with digital voting such as:
- impersonations during the authentication process;
- scalability;
- security;
The purpose of Agora is to implement a voting system that:
- ensure the secrecy and confidentiality of the vote;
- introduces new voting mechanisms, such as points voting;
The point one goal is achieved by:
using the platform under a TOR network, so that it is not possible to analyze the blockchain voting transactions in order to obtain the IP addresses of the entity who made the transactions; Using a Zero-Knowledge proof protocol in order to ensure the confidentiality of the vote stored in a blockchain;
The point two goal is implemented at smart contracts level, the Voter user has an amount of points available for the election, and during the vote distributes the points among the candidates. This mechanism should only be considered as a demonstration of the possibilities that electronic voting opens up.
the architecture can be divided into 3 layers, from the lowest to the highest level:
- The Ethereum Blockchain Network;
- The Alchemy platform that provides APIs and SDK to interact with the blockchain;
- The Agora dApp, composed by a back end and a front end;
The Agora dApp interacts with the Alchemy platform in order to store and execute the smart contracts deployed on the network. This architecture delegates most of the low level logic from the dApp to the Alchemy layer which acts as an intermediate layer between the Agora dApp and the Ethereum blockchain.
The Agora platform serves a Single Page Application that is used by the user behind a TOR network in order to not to reveal sensitive data relating to users who vote on the platform, such as the IP address.
The Single Page application is served by a back end, composed by:
- a Node.js server that exposes REST APIs;
- a database-as-a-service external to the Agora dApp;
- the ether.js library that interacts with the smart contracts ABIs;
- a set of utilities composed by javascript scripts for operations such as smart contracts deploy;
The blockchain network selected for Agora is Ethereum. The main reasons are:
- Ethereum supports smart contracts;
- Ethereum is widely supported by the community;
- Ethereum is heavily under development and new features are constantly added;
- Ethereum is a network mature enough;
There are different Ethereum networks available, for our purposes it is enough to consider the main two networks:
- Mainnet: is the production network, gas fees and token transactions are paid in real ethers (the ethereum coin);
- Sepolia: is the test network;
Testing smart contracts is a critical part of the dapp development process. However, testing on the Ethereum mainnet is unnecessarily and prohibitively costly. Testnets like Sepolia exist to offer a cost-effective and smooth development experience.
Sepolia functions similar to Ethereum, allowing web3 developers to test their projects without spending real ETH tokens. With Sepolia, developers can confidently design, create, test, and monitor their project's performance before deploying it on the Ethereum mainnet.
Since Agora is to be considered a POC (proof of concept), there is no need to use the production network, the Ethereum Sepolia network is therefore selected for the deployment of the smart contracts.
Alchemy is a third party service that offers several features connected to Web3:
SDK APIs tools
There are several plans available, free and for subscription. For the purpose of this project, the free plan offers what is needed: the Alchemy SDK layer interacts with the underlying blockchain network abstracting the logic through a Provider and a library that offers a set of APIs that make it simple for the Agora dApp to interact with the blockchain.
In order to use the Alchemy SDK and APIs, there is need to:
- create an account on the Alchemy platform;
- create an application and select a network;
Persistent data is required to be stored in a database. The data stored regards the account registered on the platform, no information about the preferences of voting are registered. The database chosen is MongoDB for the following reasons:
- a non relational database is preferred because the nature of the data does not require complex relations and data can be stored normalized;
- MongoDB is easy to integrate with the application server (Node.js) because it stores the documents as BSON objects and uses the JSON format to communicate with the server;
- The developers that implements Agora are experienced with MongoDB;
The MongoDB database can be used on premise or to use a database-as-service. The database-as-service is considered the only practicable solution since there is no hardware infrastructure available for the deployment of the application (see. infrastructure paragraph). There are several alternatives available for the MongoDB database service:
The service chosen for Agora is MongoDB offered by MongoDB Inc. The main reason is that they offer a free plan for sandbox applications, also, the company is the same company that releases the MongoDB database.
At the moment of writing, there are two main alternatives available on the market regarding the framework to use to develop smart contracts and a back end in the context of Ethereum blockchain development, both open source:
Compared to Foundry, HardHat is easier to learn and to use, it makes the ideal choice for developers that are learning how to develop dApps. Foundry is written in Rust, it is more performant than HardHat and for this reason is the best solution for production applications and for dApps that requires a large amount of work with smart contracts. Is less easy to learn and to use compared to HardHat, but it offers a test environment in the same language used for the smart contracts, Solidity (HardHat uses JavaScript).
For the needs of Agora it is chosen to use HardHat, since the project is a POC, it uses free services and a sandbox database. Also, the development process does not require an intensive implementation of smart contracts so the smart contract compile time is not a priority feature when choosing the framework.
The application server is a classic Node.js Express server, whose job is to expose the REST APIs described in a later paragraph. The language chosen for the backend development is Typescript because it offers better control over types.
The front end application is composed by 3 submodules:
- Home page with access to Digital Electoral Card (DEC) and Admin logins;
- Admin Panel;
- Voter Panel;
The frontend is composed of a classic SPA (Single Page Application). There are several frameworks and libraries available, the 3 most important choices are:
Vue is discarded since there are no skilled developers to work with this technology for the project. Angular is an opinionated framework that offers many features but it requires to follow its own patterns. React is a light unopinionated library, it offers flexibility in the choice of development patterns. Both choices are open source and widely supported by their respective communities. For the purposes of this project the front end module is built in React, for the following reasons:
- React is a light library;
- React offers better performances than Angular;
- React is more flexible in the development of the front end patterns;
- React offers a set libraries that can be installed based on the needs;
- The development team is more familiar with React;
The smart contracts represent the core module of the entire project. Because of the nature of the blockchain, that makes smart contracts logic immutable after the deploy on the network, it is critical to develop smart contracts that are:
- Well designed;
- Written in robust and efficient way;
- Well tested;
Introducing a bug in a smart contract is expensive because the entire contract needs to be re-deployed, and bugs can introduce security issues with unpredictable consequences.
Another key requirement for the smart contracts, which constitutes one of the main purposes of the entire project, is to implement them so that the vote mechanism respects the privacy, anonymity and confidentiality of the vote.
Such problems are addressed by implementing a zk-SNARKS protocol. This represents an element of novelty in the context of blockchain. One useful library that implements this protocol in Ethereum blockchains is ZoKrates. ZoKrates is the only possible choice for the Zero-Knowledge proof protocol implementation in Agora at the moment.
Another key tool is an audit tool of the smart contracts with which is possible to perform various types of analysis before deploying them into the blockchain.
In order to make it simpler to design the smart contracts, it is possible to think of them as classes of an object-oriented language, with properties, methods and appropriate scopes and inheritance. This will allow them to better represent their relationship.
Digital Electoral Card: the DEC is a smart contract with a public address.The card contains the data about the Voter needed to verify if he/she has vote rights, all the personal data are registered encrypted on the blockchain and only the Voter knows the private key (is the EOA private key). Following a diagram of the DEC smart contract:
Digital Electoral Card Registry: The Registry smart contract contains the the mapping of the Voters public addresses with the encrypted DECs, along with the list of election stamps.
When the vote is open, the Voter sign his vote with the DEC private key, then generates the π-vote proof and cast the vote. The Election smart contracts verifies the Voter right to vote. Then, After the vote proof validation, a “stamp” of the election is imprinted on the DEC. Following a diagram for this smart contract:
Election: The elections smart contract contains the elections data, such as elections start and end timestamp, and expose all the methods related to the elections process. Every election smart contract contains all the data that needs to be certified on the blockchain, such as the list of candidates and the parties, the list of votes and the methods to validate the π-vote proof and the π-result proof. Each Election Smart contract implements a particular category of election with its own voting rules (e.g. country, regional, municipal etc.) and inherits the common properties and methods from an Election smart contract. Following the diagram of the Elections smart contract:
A smart contract audit involves a detailed analysis of a protocol’s smart contract code to identify security vulnerabilities, poor coding practices, and inefficient code before identifying solutions that resolve these issues. Audits help ensure the security, reliability, and performance of decentralized applications across Web3. A smart contract audit should be performed before deploying the contracts on the blockchain network.
Smart contract audits leverage a variety of techniques and tools to mitigate weak points and make protocols more robust. The steps needed to execute an internal audit can be summarized as follow:
Check the documentation; Implement automated tests; Manual review of the contracts logic; Identify and fix the contracts errors; Repeat the process from point 2: write a test for each bug found;
When no more errors are found the audit flow can be stopped.
According to this article, the most common smart contracts errors are:
- Reentrance Issues: A reentrance attack can occur when a smart contract function calls an untrusted external contract, enabling that external contract to drain user funds or conduct other malicious actions by recursively calling the original contract.
- Integer Overflow and Underflow: An integer overflow or underflow can occur when a smart contract performs an arithmetic operation that outputs a number that exceeds the current storage capacity, leading to incorrect calculations.
- Frontrunning Opportunities: Poorly structured code can reveal information about future purchases by the dApp, which other users can frontrun in order to lock in a guaranteed profit at the expense of the protocol.
- Replay Attack: Replay attacks occur when data is maliciously delayed or repeated in order to subvert the receiver, especially during a hard fork event where messages on the updated system are used to extract funds from the legacy system.
- Random Number Vulnerability: If a dApp seeds a random number with a publicly known number, such as a block hash, it’s vulnerable to exploitation.
- Function Visibility Errors: Functions intended to be private must be defined as private, as the default visibility property in Solidity is public. If public, anyone can call the function.
- Centralization Risks: Centralization introduces single points of failure that can undermine the security of a protocol if a single private key or similar is compromised. Timelocks and granting privileges to DAOs are common techniques that deal with centralization risks. Unlocked Compiler Version: There are a number of compiler versions for Solidity. dApps should lock the version of the compiler they use so that users cannot compile it with a different version, which could lead to different bytecode and unintended complications.
Popular open source smart contracts audit tools include:
[TO DO]
The data structure schema and the associated REST APIs exposed by the application server follow the openAPI specifications. See the specifications file attached to this document.
- The Admin authentication is implemented using the OAuth2.0 authentication protocol with the use of JWT (Json Web Token). The admin JWT allows to login to admin panel.
- The Voter authentication is performed using the EOA. A third party browser extension (e.g. metamask) manages the wallet and allows to login the Voter Panel.
Agora is deployed on the IPFS. The Moralis toolkit is selected for this task.
For the CI/CD, the tool chosen is GitHub Actions.
- development: The developer local environment is considered to be the development environment, where is present the IDE, a local blockchain network and a database server;
- staging: in the first phase of development, a test environment is not foreseen;
- pre-production: IPFS+MongoDb-as-service+sepolia;
- production: until the release of a stable version, no production environments are forseen;
The code coverage threshold for unit test is 80%.
Integration and end to end tests are implemented in order to ensure:
- Accuracy: the system registers and counts votes with accuracy;
- Security: the system is secure and free from vulnerabilities;
- Usability: the system is user friendly;
- Scalability: the system manage big quantity of users and votes;
- Transparency: the vote process of the system is clear;
- Integrity: the system maintains the integrity of the voting process;
- Reliability: the system is reliable and available;
- Accessibility: the system is accessible;
- Verifiability: the system provides guidance on all voting activities;
- Compatibility: the system is compatible with the actual voting infrastructure;
- Performance: the system performs well under high loads;
- Cost effectiveness: the system is cost-effective compared to traditional voting systems;