Create a fair evoting application to ensure correct election results with Hyperledger Fabric and IBM Blockchain Platform
Have you ever wondered how exactly the votes in a presidential election counted? What if instead of having volunteers that are spending hours a day counting votes manually, we have an app that was backed by blockchain, recording each vote made by a voter, ensuring double-voting is not possible? That's what this code pattern explains how to do. We aim to build a web-app in which the voter can register with their drivers license, get a unique voterId which is used to login to the app, and cast the vote. The vote is tallied on the blockchain, and the web-app shows the current standings of the polls.
At the start of the application, the user registers to vote by providing their drivers license number, registrar district, and first and last name. In this step, we can check to see if the drivers license is valid, and has not been registered previously. If all goes well, we create a private and public key for the voter with our certificate authority that is running on the cloud, and add those keys to the wallet. To read more about public key infrastructure, and how Hyperledger Fabric implements identity using this technology, go here.
After that, we use our drivers license number to submit our vote, during which the application checks if this drivers license number has voted before and tells the user they have already submitted a vote if so. If all goes well, the political party which the voter has chosen is given a vote, and the world state is updated. The application then updates our current standings of the election to show how many votes each political party currently has.
Since each transaction that is submitted to the ordering service must have a signature from a valid public-private key pair, we can trace back each transaction to a registered voter of the application, in the case of an audit.
In conclusion, although this is a simple application, the developer can see how they can implement a Hyperledger Fabric web-app to decrease the chance of election-meddling, and enhance a voting application by using blockchain technology.
When the reader has completed this code pattern, they will understand how to:
- Create, build, and use the IBM Blockchain Platform service.
- Build a blockchain back-end using Hyperledger Fabric API's
- Create and use a (free) Kubernetes Cluster to deploy and monitor our Hyperledger Fabric nodes.
- Deploy a Node.js app that will interact with our deployed smart contract.
- The blockchain operator sets up the IBM Blockchain Platform 2.0 service.
- The IBM Blockchain Platform 2.0 creates a Hyperledger Fabric network on an IBM Kubernetes Service, and the operator installs and instantiates the smart contract on the network.
- The Node.js application server uses the Fabric SDK to interact with the deployed network on IBM Blockchain Platform 2.0 and creates APIs for a web client.
- The Vue.js client uses the Node.js application API to interact with the network.
- The user interacts with the Vue.js web interface to cast their ballot and and query the world state to see current poll standings.
- IBM Blockchain Platform gives you total control of your blockchain network with a user interface that can simplify and accelerate your journey to deploy and manage blockchain components on the IBM Cloud Kubernetes Service.
- IBM Cloud Kubernetes Service creates a cluster of compute hosts and deploys highly available containers. A Kubernetes cluster lets you securely manage the resources that you need to quickly deploy, update, and scale applications.
- IBM Blockchain Platform Extension for VS Code is designed to assist users in developing, testing, and deploying smart contracts -- including connecting to Hyperledger Fabric environments.
- Hyperledger Fabric v1.4 is a platform for distributed ledger solutions, underpinned by a modular architecture that delivers high degrees of confidentiality, resiliency, flexibility, and scalability.
- Node.js is an open source, cross-platform JavaScript run-time environment that executes server-side JavaScript code.
- Vue.js 2.6.10 Vue.js is an open-source JavaScript framework for building user interfaces and single-page applications.
π§π§Note: you will need Node 8.x to run this pattern!π§π§
For example, to install and run Node 8.9.0:
brew install nvm
nvm install 8.9.0
nvm use 8.9.0
This Cloud pattern assumes you have an IBM Cloud account.
You do not technically need VSCode or the IBM Blockchain Platform extension for VSCode if you are running the Cloud pattern, but if you want to make any changes to the smart contract, you will need the extension to package your smart contract project.
If you want to run this pattern locally, without any Cloud services, then all you need is VSCode and the IBM Blockchain Platform extension.
- Install VSCode version 1.38.0 or greater
- Install IBM Blockchain Platform Extension for VSCode
- Node v8.x or greater and npm v5.x or greater
To run a local network, you can find steps here.
- Clone the Repo
- Create IBM Cloud services
- Build a network
- Deploy voterContract Smart Contract on the network
- Connect application to the network
- Run the application
Git clone this repo onto your computer in the destination of your choice, then go into the web-app folder:
HoreaPorutiu$ git clone https://github.com/IBM/evote
- Create the IBM Cloud Kubernetes Service. You can find the service in the
Catalog
. For this code pattern, we can use theFree
cluster, and give it a name. Note, that the IBM Cloud allows one instance of a free cluster and expires after 30 days. The cluster takes around 20 minutes to provision, so please be patient!
-
Create the IBM Blockchain Platform service on the IBM Cloud. You can find the service in the
Catalog
, and give a name. -
After your Kubernetes cluster is up and running, you can deploy your IBM Blockchain Platform service on the cluster. The service walks through few steps and finds your cluster on the IBM Cloud to deploy the service on.
-
In the gif below, you can see me choosing my free cluster to deploy my IBM Blockchain Platform.
-
Once the Blockchain Platform is deployed on the Kubernetes cluster (which can take a couple of minutes, you can launch the console to start operating on your blockchain network by clicking on Launch the IBM Blockchain Platform.
We will build a network as provided by the IBM Blockchain Platform documentation. This will include creating a channel with a single peer organization with its own MSP and CA (Certificate Authority), and an orderer organization with its own MSP and CA. We will create the respective identities to deploy peers and operate nodes.
-
- Navigate to the Nodes tab in the left navigation and click Add Certificate Authority.
- Click Create an IBM Cloud Certificate Authority and Next.
- Give it a Display name of
Voter CA
. Note that the gif names the certificate a more generic name. - Specify an Admin ID of
admin
and Admin Secret ofadminpw
, then click Next. - Review the summary and click Add Certificate Authority
- In the Nodes tab, select the Voter CA once it is running (indicated by the green box in the tile).
- Click Associate identity on the CA overview panel.
- On the side panel, select Enroll ID.
- Provide an Enroll ID of
admin
and an Enroll secret ofadminpw
. Use the default value ofVoter CA Admin
for the Identity display name. - Click Associate identity to add the identity into your wallet and associate the admin identity with the Voter CA.
-
- We will register an admin for our voter organization. Click on the Register User button. Give an Enroll ID of
voterAdmin
, and Enroll Secret ofvoterAdminpw
. Set the Type for this identity asclient
. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments field blank. Click Next. click Register User. - We will not be adding any attributes to this user. Click Register user.
- We will repeat the process to create an identity of the peer. Click on the Register User button. Give an Enroll ID of
peer1
, and Enroll Secret ofpeer1pw
. Set the Type for this identity aspeer
. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments field blank. Click Next. Click Next. Then on the next page, click Register User.
- We will register an admin for our voter organization. Click on the Register User button. Give an Enroll ID of
-
- Navigate to the Organizations tab in the left navigation and click Create MSP definition.
- Enter the MSP Display name as
Voter MSP
and an MSP ID ofvotermsp
. - Under Root Certificate Authority details, specify the peer CA that we created
Voter CA
as the root CA for the organization. - Give the Enroll ID and Enroll secret for your organization admin,
voterAdmin
andvoterAdminpw
. Then, give the Identity name,Voter Admin
. - Click the Generate button to enroll this identity as the admin of your organization and export the identity to the wallet. Click Export to export the admin certificates to your file system. Finally click Create MSP definition.
- Create a peer
- On the Nodes page, click Add peer.
- Click Create an IBM Cloud peer and then click Next.
- Give your peer a Display name of
Voter Peer
and then click Next. - On the next screen, select
Voter CA
as your Certificate Authority. Then, give the Enroll ID and Enroll secret for the peer identity that you created for your peer,peer1
, andpeer1pw
. Then, select the Organization MSP as ,Voter MSP
, from the drop-down list. Leave the TLS CSR hostname blank and click Next. - The next step is to Associate an identity with this peer to make it the admin of your peer. Select your peer admin identity Org1 Admin and click Next.
- Review the summary and click Add peer.
-
- Navigate to the Nodes tab in the left navigation and click Add Certificate Authority.
- Click Create an IBM Cloud Certificate Authority and click Next.
- Give it a unique Display name of
Orderer CA
. - Specify an Admin ID of
admin
and Admin Secret ofadminpw
and click Next Review the summary and click Add Certificate Authority.
- In the Nodes tab, select the Orderer CA once it is running (indicated by the green box in the tile).
- Click Associate identity on the CA overview panel.
- On the side panel, select Enroll ID.
- Provide an Enroll ID of
admin
and an Enroll secret ofadminpw
. Use the default value ofOrderer CA Admin
for the Identity display name. - Click Associate identity to add the identity into your wallet and associate the admin identity with the Orderer CA.
-
- In the Nodes tab, select the Orderer CA Certificate Authority that we created and ensure the admin identity that was created for the CA is visible in the table.
- We will register an admin for our organization. Click on the Register User button. Give an Enroll ID of
ordererAdmin
, and Enroll Secret ofordererAdminpw
. Set the Type for this identity asclient
. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments field blank. Click Next. - We will not be adding any attributes to this user. Click Register user.
- We will repeat the process to create an identity of the orderer. Click on the Register User button. Give an Enroll ID of
orderer1
, and Enroll Secret oforderer1pw
. Set the Type for this identity asorderer
. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. Click Next. - We will not be adding any attributes to this user. Click Register user.
-
- Navigate to the Organizations tab in the left navigation and click Create MSP definition.
- Enter the MSP Display name as
Orderer MSP
and an MSP ID oforderermsp
. - Under Root Certificate Authority details, specify the peer CA that we created
Orderer CA
as the root CA for the organization. - Give the Enroll ID and Enroll secret for your organization admin,
ordererAdmin
andordererAdminpw
. Then, give the Identity name,Orderer Admin
. - Click the Generate button to enroll this identity as the admin of your organization and export the identity to the wallet. Click Export to export the admin certificates to your file system. Finally click Create MSP definition.
-
- On the Nodes page, click Add orderer.
- Click IBM Cloud Orderering Service and proceed with Next.
- Give Ordering service Display name of
Orderer
and click Next - On the next screen, select Orderer CA as the Certificate Authority. Then, give the Ordering service enroll ID and Ordering service enroll secret for the peer identity that you created for your orderer, that is,
orderer1
, andorderer1pw
. Select the Organization MSP asOrdererMSP
, from the drop-down list. Leave the TLS CSR hostname blank. Click Next. - Give the TLS Enroll ID,
admin
, and TLS Enroll secret,adminpw
, the same values are the Enroll ID and Enroll secret that you gave when creating the CA. Leave the TLS CSR hostname blank. - The next step is to Associate an identity with this orderer to make it the admin of your orderer. Select your peer admin identity
Orderer Admin
and click Next. - Review the summary and click Add ordering service.
-
- Navigate to the Nodes tab, and click on the Orderer that we created. Ensure it is green first.
- Under Consortium Members, click Add organization.
- From the drop-down list, select
Voter MSP
, as this is the MSP that represents the peer's Voter organization. - Click Add Organization.
-
- Navigate to the Channels tab in the left navigation.
- Click Create channel.
- Give the channel a name,
mychannel
. - Select the orderer you created,
Orderer
from the orderers drop-down list. - Under Organizations, select Voter MSP and then click Add. This adds the organization Voter as a membe of this channel. Next make your organization an Operator.
- Scroll down to the Creator organization. Select the MSP identifying the organization from the drop-down list. This should be
Voter MSP (votermsp)
. - Associate available identity as
Voter Admin
. - Click Create channel.
-
- Click Join channel to launch the side panels.
- Select your
Orderer
and click Next. - Enter the name of the channel you just created.
mychannel
and click Next. - Select which peers you want to join the channel, click
Voter Peer
. - Click Join Channel.
-
- Navigate to the Smart contracts tab in the left navigation and click the Smart contracts tab to install the smart contract.
- Click Install smart contract to upload the voterContract smart contract package file, which is in the root of the repo we cloned - the file
is called
voterContract.cds
. - Click on Add file and find your packaged smart contract.
- Once the contract is uploaded, click Install smart contract.
-
-
On the smart contracts tab, find the smart contract from the list installed on your peers and click Instantiate from the overflow menu on the right side of the row.
-
On the side panel that opens, select the channel,
mychannel
to instantiate the smart contract on. Click Next -
Select the organization members to be included in the endorsement policy,
votermsp
. Click Next. -
We can skip the Setup private data collection step and simply click Next.
-
Give Function name of
init
and leave Arguments blank. Note: init is the method in the voteerContract.js file that initiates the smart contracts on the peer. -
Click Instantiate Smart Contact.
-
-
- Scroll down to the Instantiated smart contracts section and find "VoterContract". Click on
Connect with SDK
from the overflow menu on the right side of the row. - Choose from the dropdown for MSP for connection,
votermsp
. - Choose from Certificate Authority dropdown,
Voter CA
. - Download the connection profile by scrolling down and clicking Download Connection Profile. This will download the connection json which we will use soon to establish connection.
- You can click Close once the download completes.
- Scroll down to the Instantiated smart contracts section and find "VoterContract". Click on
-
- Go to the Nodes tab on the left bar, and under Certificate Authorities, choose your organization CA, Voter CA.
- Click on Register user.
- Give an Enroll ID and Enroll Secret to administer your application users,
app-admin
andapp-adminpw
. - Choose
client
as Type. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments field blank. Click Next. - Under Attributes, click on Add attribute. Give attribute as
hf.Registrar.Roles
=*
. This will allow this identity to act as registrar and issues identities for our app. Click Add-attribute. - Click Register user.
-
- Copy the connection profile you downloaded into server folder
- Rename the connection profile you downloaded ibpConnection.json
- Update the config.json file with:
ibpConnection.json
.- The enroll id and enroll secret for your app admin, which we earlier provided as
app-admin
andapp-adminpw
. - The orgMSP ID, which we provided as
votermsp
. - The caName, which can be found in your connection json file under "organization" -> "votermsp" -> certificateAuthorities". This would be like an IP address and a port. You should also use the
https
version of the certificateAuthorities line. - The peerName, which can be found in your connection json file under "organization" -> "votermsp" -> peers". This would be like an IP address and a port.
- The username you would like to register.
- Update gateway discovery to
{ enabled: true, asLocalhost: false }
to connect to IBP.
- Once you are done, the final version of the config.json should look something like this:
{
"connection_file": "ibpConnection.json",
"appAdmin": "app-admin",
"appAdminSecret": "app-adminpw",
"orgMSPID": "votermsp",
"caName": "https://173.193.106.28:32634",
"userName": "V1",
"gatewayDiscovery": { "enabled": true, "asLocalhost": false }
}
-
-
First, navigate to the
web-app/server
directory, and install the node dependencies.cd web-app/server npm install
-
Run the
enrollAdmin.js
scriptnode enrollAdmin.js
-
You should see the following in the terminal:
msg: Successfully enrolled admin user app-admin and imported it into the wallet
-
Start the server:
npm start
-
-
-
In a new terminal, open the
web-app/client
folder from the root directory. Install the required dependencies withnpm install
.cd web-app/client npm install
-
Start the client:
npm run serve
-
In a browser of your choice, go to http://localhost:8080/#/. If all goes well, you should see something like the gif below:
-
You can find the app running at http://localhost:8080/ If all goes well, you should be greeted with the homepage that says 2020 Presidential Election
Now, we can start interacting with the app.
First, we need to register as a voter, and create our digital identity with
which we will submit our vote with. To do this, we will need to enter
a uniqueId (drivers license) with a registrarId, and our first and last names.
After we do that, and click register
the world state will be updated with
our voterId and our name and registrarId.
If all goes well, you should see voter with voterId {} is updated in the world state. Use voterId to login above.
Note: on the first try, the app can take a second to start up. If you click on register
and nothing
happens, try to fill in the form and click register again!
Next, we can login to the app with our voterId.
Once we login, we can cast our vote. We will use our voterId again to cast our
vote. Since we are voting for the presidential
election for 2020, we can choose the party of our liking. Once we are done, we
can choose submit, and then our vote is cast. As long as this voterId hasn't
voted before, all is well. Next, we can view the poll standings by clicking
Get Poll Standings
and clicking Check Poll
. This will query the world
state and get the current number of votes for each political party.
If we want to query for a particular voterId, we can do so in the Query by Key
tab.
If we want to query by object, we can do so by clicking on the Query by Type
tab, and entering a type, such as voter
. This will return all voter objects
that are currently in the state. QueryAll
will return all objects in the state.
Pull requests and contribution are always welcome. Remember that a code pattern is a path to a solution, and not a complete solution on its own. To make this a more complete solution, this application can be expanded in a couple of ways:
- Use an API to verify the drivers license to make sure it is valid, and registered with the DMV.
- Use a more complex consensus mechanism where multiple organizations (DMV, US Federal Government, US State Government) have to approve a vote before it is successfully recorded onto the blockchain.
- Use ordering service which uses Raft consensus mechanism.
This code pattern is licensed under the Apache Software License, Version 2. Separate third-party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to the Developer Certificate of Origin, Version 1.1 (DCO) and the Apache Software License, Version 2.