Blockchain and web3 have changed our understanding of transparency, trust and decentralization. One of the most incredible use-case for this technology is the development of web3 dapps (decentralized applications) that offers solutions that are secure, verifiable and tamper-proof solutions to our everyday challenges. Among all the use-cases, decentralized voting stands out. Decentralized technologies remove middlemen and ensure transparent vote counts, this voting dapp has the potential to change governance system while enhancing the democratic process.

In this tutorial, we will build a simple voting dapp on linea, a zkEVM layer 2 blockchain solution. You will learn how to write, deploy and interact with a smart contract which is designed for decentralized voting process. By the end of this tutorial, you’ll have a solid understanding of the tools and features provided by linea for decentralized applications.

Understanding the Voting Dapp Architecture

The voting dapp has three main components: smart contracts, smart contracts integration and the frontend interface.

The smart contract is one of the main components of the application. This can handle critical functionalities such as registering candidates, allowing users to give their votes based on candidates index numbers, enforcing a one vote per wallet address policy and managing voting period by automatically closing the voting period after a specified duration. The smart contract makes sure that the voting process is secure, transparent and tamper-proof by recording all votes on the blockchain.

The frontend interface is the user-facing part of the application where users will be able to interact and cast their votes by inputting the candidate index number. It also can show the information about remaining time period. By offering a clear and responsive design, it encourages user participation and trust in the voting process.

To ensure smooth interaction with the Linea blockchain, we'll utilize the MetaMask SDK along with libraries like Wagmi and connect through Infura RPC providers. These tools allow the frontend to communicate with the blockchain, enabling users to sign transactions and interact with the smart contracts directly from their web browsers. This integration is crucial for maintaining the decentralized nature of the application while providing a user-friendly experience.

Setting Up the Environment

Before we start building our decentralized voting dapp, we'll set up the development environment using Consensys's Create Web3 Template CLI. This tool streamlines the process by generating a monorepo structure that includes both the frontend and backend components needed for our application.

Prerequisites

• Node.js and pnpm/any other package manager installed on your system.

• Basic familiarity with the command line.

Initializing the Project

Let's create a new project using the Create Web3 Template CLI by Consensys.

This command-line tool simplifies the setup process by providing all the necessary tools and integrations out of the box, including MetaMask SDK, Linea support, Infura integration, and a selection of templates to choose from.

1. Open your terminal and run the following command:

2. You'll be prompted to specify a name for your project. We'll name it simple-voting-dapp:

3. Next, select the framework for your frontend. We'll choose Next.js:

Selected framework: Next.js

4. Choose the smart contract development environment. We'll go with HardHat:

Selected tooling: HardHat

5. Select your preferred package manager. We'll use pnpm:

6. The CLI will generate the project based on your selections.

Project Structure

After the setup is complete, your project directory simple-voting-dapp will have the following structure:

• packages/site: Contains the frontend code of the dApp, built with Next.js.

• packages/blockchain: Contains the smart contracts and related scripts using HardHat.

• pnpm-workspace.yaml: Defines the workspace configuration for the monorepo.

Installing Dependencies

Navigate into your project directory:

Install all the necessary dependencies:

This command will install all packages for both the frontend and backend components.

Understanding the Monorepo

A monorepo (monolithic repository) is a single repository that stores code for multiple projects or packages. In our case, it allows us to manage both the frontend and backend in a unified codebase, making development and maintenance more efficient.

Verifying the Setup

To ensure everything is set up correctly, let's run the development servers.

For the Frontend:

1. Navigate to the site directory:

2. Start the Next.js development server:

3. Open your browser and go to http://localhost:3000 to see the frontend running.

For the Backend:

1. Open a new terminal window.

2. Navigate to the blockchain directory:

3.Compile the default smart contracts:

This will compile the sample contracts included in the HardHat setup.

Write the Smart Contract

Let’s create a Voting.sol file and add the following code:

This contract provides a basic framework for a decentralized voting system where users can cast votes for candidates securely and transparently. It ensures that each user can vote only once by tracking voter addresses, and it maintains a record of all votes on the blockchain. The contract manages the voting period by specifying start and end times, enforces voting rules, and provides functions to retrieve voting results and status. Let’s explore the concept of the smart contract a bit more:

1. Contract Initialization and Candidate Setup

• The Voting contract initializes with an array of candidate names provided during deployment.

• Each candidate is represented by a Candidate struct containing a name and a voteCount.

• The constructor sets the votingStart time to the current block timestamp.

• It calculates the votingEnd time by adding the specified duration in minutes to the start time.

2. Access Control and Owner Functions

• The contract stores the deployer's address as owner.

• An onlyOwner modifier restricts certain functions to the contract owner.

• The addCandidate function allows the owner to add new candidates after hardhat deployment.This ensures only authorized users can modify the list of candidates.

3. Voting Mechanism

• The vote function lets users cast a vote by specifying a candidate's index.

• A voters mapping tracks whether an address has already voted.

• The function checks if the voter hasn't voted before and if the candidate index is valid.

• Upon a valid vote, it increments the candidate's voteCount and marks the voter as having voted.

4. Utility Functions and Voting Status

• getAllVotesOfCandidates returns all candidates and their current vote counts.

• getVotingStatus returns true if voting is active based on the current time.

• getRemainingTime calculates and returns how much time is left in the voting period.

• These functions provide users with real-time information about the election.

This smart contract facilitates a decentralized voting system where users can vote for candidates securely, with all votes and results recorded on the blockchain.

Deploying the Smart Contract with Hardhat Ignition

In the ignition folder, let's create a file named Voting.ts to deploy our contract. Add the following code:

In this deployment script, we utilize Hardhat Ignition to manage the deployment of our Voting contract. We set default candidates and a default voting duration but also allow these values to be customized through parameters if needed.

Compiling the Contract

Before deploying, compile the contract by running the following command in the blockchain directory:

This will compile your Solidity code and prepare it for deployment.

Setting Up Environment Variables

Before deploying the smart contract, ensure that your .env file in the packages/blockchain directory is updated with the necessary environment variables:

• Replace your_infura_api_key_here with your actual Infura API key.

• Replace your_account_private_key_here with the private key of the Ethereum account you will use for deploying the contract.

Deploying the Smart Contract

To deploy the smart contract to the Linea testnet, run the following command from the blockchain directory:

This command tells Hardhat to use Ignition to deploy the Voting module to the linea-testnet network.

Alternatively, you can add a deployment script to your package.json to simplify the process. Add the following line under the "scripts" section:

Now you can deploy the contract by simply running:

After deployment, you'll receive the contract address. Keep this address safe, as we'll need it when integrating with the frontend.

Frontend Integration with Next.js and Shadcn UI

Setting Up the Frontend Project

Navigate to the site directory in your monorepo:

Since we've already set up the frontend using the Create Web3 Template CLI, we can proceed to integrate our smart contract.

Configuring Wagmi and MetaMask SDK

Create a wagmi.config.ts file in the src directory with the following content:

This configuration sets up the connection to the Linea testnet and enables wallet integration using MetaMask.

Adding Contract Constants

In the src directory, create a file named constants.ts and add the following:

• Replace 'your_deployed_contract_address_here' with the actual contract address you obtained after deployment.

• For the ABI, you can find it in the artifacts folder generated by Hardhat after compilation.

React and Hooks Usage

is Next.js client-side component uses React's useState for state management, Wagmi hooks (useAccount, useWalletClient, useReadContract, useWriteContract) for wallet and contract interactions, imports UI elements (Button, Input, Card, CardContent) from Shadcn UI, includes a ConnectButton for MetaMask connection, and brings in contractAddress and contractAbi from constants for contract use.

Interface Definition

• Defines a TypeScript interface named Candidate.

• Specifies the structure for candidate objects:

  • index : The candidate's index number.
  • name : The candidate's name.
  • voteCount : The number of votes the candidate has received.

Component Initialization

• Function Component: Defines the Home component as the default export.

• Wallet Information:

  • address : The user's wallet address obtained from useAccount.
  • walletClient : The wallet client used for signing transactions.

• State Management:

  • number : A state variable to store the candidate index input by the user for voting.
  • setNumber : Function to update the number state.

Smart Contract Interaction - Reading Data

• Writing to Contract:

  1. writeContract is prepared for sending transactions to the smart contract.

• Reading Contract Data:

  • votingStatus : Retrieves whether the voting is currently active.
  • canVote : Checks if the current user has already voted.
  • remainingTime : Gets the time remaining before the voting period ends.
  • candidates : Fetches the list of all candidates and their vote counts.

• Type Assertions:

  1. Uses TypeScript as syntax to specify the expected data type for better type safety.

Early Return for Missing Data

• Checks if the candidates data is available.

• If candidates is undefined or null, the component returns early to prevent rendering errors.

Voting Functionality

• Input Validation:

  • Checks if the wallet client, user address, and candidate number are available.
  • Validates that the candidate index is a valid number within the range of available candidates.
  • Ensures that voting is currently active.

• Voting Process:

  • Uses writeContract to call the vote function on the smart contract.
  • Passes the candidate index as a BigInt .
  • Uses the user's wallet address as the account.

• Error Handling:

  • Wraps the contract interaction in a try-catch block to handle any errors that occur during the voting process.
  • Logs detailed error information to the console.

UI Rendering

The component features a styled main container with a header and a ConnectButton for MetaMask integration. It conditionally renders content based on votingStatus and user connection: if voting is active and the user is connected, it displays their address, remaining time, and voting options; if they've already voted, it notifies them and lists all candidates. If the user isn't connected, it prompts them to connect their wallet. When voting has ended, it shows "Voting has finished".

Error Handling and Validation

• Input Validation:

  1. Ensures the candidate index entered is a valid number within the acceptable range.

• Error Messages:

  1. Uses console.error to log meaningful error messages for debugging purposes.

• User Feedback:

  1. Provides real-time feedback to the user based on their actions and the application's state.

View full code here: https://github.com/meowyx/simple-voting-dapp

Run the Development Server

Your Next.js application with Shadcn UI should now be running at http://localhost:3000.

Now, you have a decentralized voting DAPP where users can vote for the candidates by using their index number. These votes are secure, transparent and recorded on Linea blockchain.

In this tutorial, we built a simple decentralized voting application on Linea, while leveraging zkEVM technology for scalability, security, and cost efficiency. We covered everything from setting up the environment by using the CLI to writing and deploying smart contracts, and integrating the frontend with Next.js and Shadcn UI.

As you continue to explore and expand upon this foundational knowledge, consider potential enhancements such as adding voter registration, implementing vote delegation, enhancing security measures, or improving the user interface for better accessibility. The possibilities for decentralized applications (dApps) are endless, and voting systems are just one of the many impactful use cases.

Happy coding!