/simple-democracy

If only voting was as simple as this dApp...

Primary LanguageJavaScript

Simple Democracy

Truffle, Drizzle & React dApp for conducting basic elections on the Ethereum blockchain.

You can interact with the smart contract using a local network (see instructions below) or on the Rinkeby testnet (see deploying section).

Prerequisites

You will need the following properly installed on your computer:

Installation

Install yarn (or use NPM if you prefer):

brew install yarn

Install Truffle:

yarn global add truffle

Ensure you have truffle 5. Running truffle version should output look something like:

Truffle v5.0.1 (core: 5.0.1)
Solidity v0.5.0 (solc-js)
Node v10.13.0

Install Ganache-CLI:

yarn global add ganache-cli

Clone & navigate into the repository:

git clone git@github.com:sbrichards/simple-democracy.git && cd simple-democracy

Running / Development

From project root...

Download dependencies:

yarn

Fire up your local development blockchain:

ganache-cli

In addition to spinning up a test network (listening on 127.0.0.1:8545 by default), Ganache also creates 10 addresses, each with a balance of 100 ETH.

Leave this terminal window open and copy the Mnemonic output. You'll need to paste this seed phrase into MetaMask in order to import and control these accounts.

Compile & deploy the application contracts to the test network:

truffle migrate

From app/ directory...

Download dependencies:

yarn

Fire up the React application:

yarn start

The application shoud now be accessible at http://localhost:3000/.

Leave this terminal window open.

Paste the Mnemonic from Ganache into MetaMask using the "import with seed phrase" option. From the MetaMask network dropdown, select the private network (Localhost 8545). You should now have control of the generated addresses to sign transactions.

Using the dApp

This dApp has three user types:

  1. Admins
  2. Voters
  3. Unregistered users

A "user" in the dApp is an Ethereum account address. Users can interact with this dApp through MetaMask.

Only admins can:

  • Register users (i.e. Ethereum account addresses) as admins and/or as voters
  • Create elections by submitting a name for the election
  • Add candidates (i.e. Ethereum account addresses) to an election
  • Open elections, which allow voters to vote on the election
  • Close elections, which end voting and calculate a winner

All voters can:

  • Vote once for a candidate per open election
  • View their admin & registration status
  • View election stats

Unregistered users can:

  • View their Ethereum address and Ether balance
  • Not much else...

Note: the account that deploys the contract (the first account in your local test network) will be automatically registered as an admin.

Elections structs are state machines stored in contract storage - they maintain a status (either "Pending", "Active" or "Closed") representing their lifecycle stage.

  • Pending: the election has been created, admins can add candidates to this election and open the election
  • Active: the election is open, voters can vote on the election and admins can close the election
  • Closed: the election is close, the winner is calculated and no further actions can be taken on the election

Running Tests

truffle test

Deploying

If you'd like to interact with the contract on a testnet, see deployed_addresses.txt.

If you'd like to deploy the contract to a testnet, the truffle-config.js is set up to deploy to Rinkeby. You'll have place your mnemonic seed phrase into a file named .secret in this project root:

echo 'your seed phrase in a string like this' >> .secret

Ensure your account address has adequate funds to deploy the contract, e.g. by using the Rinkeby Faucet.

Then run:

truffle migrate --network rinkeby

Resources

Troubleshooting

In general, if you encounter an issue (e.g. when submitting an input), refreshing the browser should solve the problem.

If you're able to describe the steps that produced your issue and copy any errors from the console, please email me at sbrichards(at)gmail(dot)com and I'll look into it!