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.

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.

1. The blockchain operator sets up the IBM Blockchain Platform 2.0 service.
2. 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.
3. 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.
4. The Vue.js client uses the Node.js application API to interact with the network.
5. 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 V2 Beta 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 Vue.js is an open-source JavaScript framework for building user interfaces and single-page applications.

This pattern assumes you have an IBM Cloud account, VSCode and IBM Blockchain Platform Extension for VSCode installed

• IBM Cloud account
• Install VSCode
• 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.

1. Clone the Repo
2. Create IBM Cloud services
3. Build a network
4. Deploy voterContract Smart Contract on the network
5. Connect application to the network
6. 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 the Free 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 10-15 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.

• Create your Voter Organization CA

  • Click Add Certificate Authority.
  • Click IBM Cloud under Create 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 of adminpw.

• Use your CA to register identities

  • Select the Voter CA Certificate Authority that we created.
  • First, we will register an admin for our voter organization. Click on the Register User button. Give an Enroll ID of voterAdmin, and Enroll Secret of voterAdminpw. Click Next. Set the Type for this identity as client and select org1 from the affiliated organizations drop-down list. We will leave the Maximum enrollments and Add Attributes fields blank.
  • 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 of peer1pw. Click Next. Set the Type for this identity as peer and select org1 from the affiliated organizations drop-down list. We will leave the Maximum enrollments and Add Attributes fields blank.

• Create the peer organization MSP definition

  • 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 of votermsp.
  • 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 and voterAdminpw. 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 IBM Cloud under Create a new peer and Next.
  • Give your peer a Display name of Voter Peer.
  • 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, and peer1pw. Then, select the Administrator Certificate (from MSP), Voter MSP, from the drop-down list and 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 last side panel will ask you to Associate an identity and make it the admin of your peer. Select your peer admin identity Voter Admin.
  • Review the summary and click Submit.

• Create your orderer organization CA

  • Click Add Certificate Authority.
  • Click IBM Cloud under Create Certificate Authority and Next.
  • Give it a unique Display name of Orderer CA.
  • Specify an Admin ID of admin and Admin Secret of adminpw.

• Use your CA to register orderer and orderer admin identities

  • In the Nodes tab, select the Orderer CA Certificate Authority that we created.
  • First, we will register an admin for our organization. Click on the Register User button. Give an Enroll ID of ordererAdmin, and Enroll Secret of ordererAdminpw. Click Next. Set the Type for this identity as client and select org1 from the affiliated organizations drop-down list. We will leave the Maximum enrollments and Add Attributes fields blank.
  • 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 of orderer1pw. Click Next. Set the Type for this identity as peer and select org1 from the affiliated organizations drop-down list. We will leave the Maximum enrollments and Add Attributes fields blank.

• Create the orderer organization MSP definition

  • 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 of orderermsp.
  • 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 and ordererAdminpw. 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.

• Create an orderer

  • On the Nodes page, click Add orderer.
  • Click IBM Cloud and proceed with Next.
  • Give your peer a Display name of Orderer.
  • On the next screen, select Orderer CA as your Certificate Authority. Then, give the Enroll ID and Enroll secret for the peer identity that you created for your orderer, orderer1, and orderer1pw. Then, select the Administrator Certificate (from MSP), Orderer MSP, from the drop-down list and 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 last side panel will ask to Associate an identity and make it the admin of your peer. Select your peer admin identity Orderer Admin.
  • Review the summary and click Submit.

• Add organization as Consortium Member on the orderer to transact

  • Navigate to the Nodes tab, and click on the Orderer that we created.
  • 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 Submit.

• Create the channel

  • 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.
  • Select the MSP identifying the organization of the channel creator from the drop-down list. This should be Voter MSP (votermsp).
  • Associate available identity as Voter Admin.
  • Click Add next to your organization. Make your organization an Operator.
  • Click Create.

• Join your peer to the 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 Submit.

• Install a smart contract

  • 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.

• Instantiate 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 policy, votermsp. Click Next.
  • Give Function name of init and leave Arguments blank.
  • Click Instantiate.

• Connect with sdk through connection profile

  • Under the Instantiated Smart Contract, 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.

• Create an application admin

  • Go to the Nodes tab on the left bar, and under Certificate Authorities, choose your organization CA, Org1 CA.
  • Click on Register user.
  • Give an Enroll ID and Enroll Secret to administer your application users, app-admin and app-adminpw.
  • Choose client as Type and any organization for affiliation. We can pick org1 to be consistent.
  • You can leave the Maximum enrollments blank.
  • 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.

• Update application connection

  • Copy the connection profile you downloaded into server folder
  • Rename the connection profile you downloaded ibpConnection.json
  • Update the config.json file with:
    • The connection json file name you downloaded.
    • The enroll id and enroll secret for your app admin, which we earlier provided as app-admin and app-adminpw.
    • The orgMSP ID, which we provided as votermsp.
    • The caName, which can be found in your connection json file under "organization" -> "org1msp" -> certificateAuthorities". This would be like an IP address and a port. This is circled in red above.
    • The username you would like to register.
    • Update gateway discovery to { enabled: true, asLocalhost: false } to connect to IBP.

the current default setup is to connect to a local fabric instance from VS Code

• Once you are done, the final version of the config.json should look something like this (note that I took the caName from the above pic):

{
    "connection_file": "ibpConnection.json",
    "appAdmin": "app-admin",
    "appAdminSecret": "app-adminpw",
    "orgMSPID": "votermsp",
    "caName": "173.193.106.28:32634",
    "userName": "V1",
    "gatewayDiscovery": { "enabled": true, "asLocalhost": false }
}

• Enroll admin

  • First, navigate to the web-app/server directory, and install the node dependencies.

    cd web-app/server
    npm install

  • Run the enrollAdmin.js script

    node 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

• Start the web client

  • In a new terminal, open the web-app/client folder from the root directory. Install the required dependencies with npm install.

    cd web-app/client
    npm install

  • Start the client:

    npm run serve

  • In a broswer 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 see something like the picture below:

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. Next, we can login to the app with our voterId.

Once we login, we can 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.

That's it for the app. It can be improved in a myriad of ways, but hopefully this gives you inspiration to create apps that improve our current proccesses. Thank you SO MUCH for taking the time to go through this pattern, and hopefully you learned something.

If you want to keep your application running all the time, you'll want to deploy it to the cloud. The goal is to deploy something like this: http://blockchainbeans2.mybluemix.net/

To do this, please follow the guide here:

• Hyperledger Fabric Docs
• IBM Code Patterns for Blockchain

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.

Apache Software License (ASL) FAQ