A Complete Tutorial to Build a working DAPP using Hyperledger Composer
Hyperledger is an open source collaborative effort created to advance cross-industry blockchain technologies. It is a global collaboration, hosted by The Linux Foundation, including leaders in finance, banking, Internet of Things, supply chains, manufacturing and Technology. A user (or peer) can create a Decentralized Application (DAPP) and this DAPP can be deployed onto the blockchain. While one can write a DAPP from scratch and deploy it onto the fabric, the easiest way by far is to use the Composer Playground. It has a (relatively) easy UI and can still directly communicate with the fabric. One can install and interact with the hyperledger fabric with a UNIX based OS, primarily MacOS and Ubuntu. Instructions to install are here:
In this tutorial we will be creating a modification to the child’s game of “telephone”, where you can give a message to another person, tell a person to stop giving a message, and make a person pass along a message to another person. I will explain the rules of the game in more detail later in this article. I will be using a Mac OS Sierra (10.12.5), but you can still follow along with Ubuntu. I am also assuming that you have everything needed installed and have created your PeerAdmin business card. So let’s begin!
Part 1: Exploring the Playground and Building a DAPP
Make sure that you have docker running. In Mac, check in the top menu bar (around where the time is displayed) and click on an icon that looks like a whale with some boxes on top of it. Once docker is running, open terminal and go to the directory where the docker.yaml file is located. On my computer, I used this command:
Once you are at this directory, run this command to start the fabric:
You should see a screen that looks like this after running the command above:
This means that you are now connected to the hyperledger fabric. Now you can open up the composer playground by typing this command into terminal:
Now, a new window should pop up in your default web browser and the address bar should show localhost:8080. The window should look like this:
Note 1: I blurred out some of my other business cards since those are some private projects I am working on
Note 2: You may get an introductory screen with a button at the bottom saying “Let’s Blockchain!”. Click that button and you should be led to this page
Click on “Deploy a new business network” and you should be on a page like this:
For the First Part (Basic Information), I named my Business Network demo2 (I originally used the name demo for another project). For part 2, choose “empty-business-network”
For part 3, choose the “ID and Secret” option. Check the picture down below to see how this part looks. You will be presented with enrollment ID and enrollment secret text boxes. Make sure the the enrollment id is ‘admin’ and the enrollment secret is ‘adminpw’ (don’t include the single quotes).
Now, towards the upper half of the page on the right side, you can click the “Deploy” button. You should now be directed back to the front page, which should now have a slot that looks like this:
Click on it and you should be led to here:
This is where the programming for the DAPP will take place. Before we continue, we should introduce and define what assets and transactions are, as they will be the fundamental base of programming. An asset is a type of object that will be stored in the DAPP. For example, in a board game, a game piece, a card, and a dice could be considered assets. A transaction is an action that will affect an asset. So rolling a dice or drawing a card would be transactions as they affect the movement and position of the game piece.
For this example, I have created a variation of the game telephone, where one is given a message and has to pass that message to his/her other friends playing the game. Here are the rules:
- A Person can carry one message at a time. If it is passed along to a friend, then the person will no longer carry that message anymore, as the message is now being carried by his friend
- You can give a message to a person who is not carrying a message at the moment, but not to one who is currently carrying one
- You can tell a person to “drop” a message, and that person will no longer be carrying any messages
Based off this, there will be one person asset and three transactions for giving, passing on, and dropping a message. So let’s first define the asset. On the current screen, click on the Model File (models/model.cto). First, we should rename this file. You can do that by clicking on the pencil icon next to the name. We will rename this file to ‘person.cto’ (just type in “person” into the text box, as the system already knows that this is a cto file). In there, you can copy and paste this code:
Here, we have three parts. First we have defined the namespace as models.person, so if we want to access this file from any other file in the project, we will have to include this statement. The part is an enum, which is a type that can only have a specific programmer defined values. In this case, the values are “TRUE” and “FALSE”. And then there is the actual person asset, which has a name, a state, and a message. With the “identified by name” part, I have made it so that if I want to access a Person, I only need to enter in the name and not all of the proceeding information.
Now let us define our transactions. For this, we will need a new model file. Near the bottom left part of the screen, there should be an option called “Add a File”. Click on that, and you be led to a screen that looks like this:
Make sure to select the ‘Model File’ option. Then, scroll down and click the “Add” button. Here, we will be defining the what is needed in each transaction. Make sure to rename this file to ‘transactions.cto’ . This is the code for the transactions model file:
First, we must import the data about the assets into this file with models.person.*. Then we must define what is needed for a transaction. For the first transaction, giveMessage, we have to give a message to someone, so it makes sense to define a message and a person to give a message to. In the next transaction, passMessage, we will have one person giving a message to another person, so it makes sense to define two people here, the message giver and the message receiver. In the last transaction, clearMessage, we tell a person to “drop” their message, so we just need to define the person who currently has the message you want to drop.
We now have everything needed to test out our DAPP! To start testing, click on the “Test” tab on the top. You should then be in a new page with transactions and asset tabs on the left. Click the asset tab. Then, near the top right, click the “Create New Asset” button.
You will then be directed to a screen that looks like this:
Fill out some random info and the asset will be added to the server. You should then create more assets like this. These are my current assets right now:
Now we can start to test the transactions. Let us first give a message, so click the “Submit Transaction” button, and you will be led to a screen looking like the one below. Make sure to select ‘giveMessage’ from the dropdown menu.
Fill in the data (in this case, my “txt” was “First Hyperledger Message” and my “receive” was “resource:models.person.Person#Jay”), then scroll to the bottom, and then click “Submit”. Here is the result after:
Voila! We have successfully passed on a message/changed an asset with our transaction! Here are some of my results with the other transactions.
We now have a working DAPP from Parts 1 and 2, but let’s say that we want to see specific data. For example, how can we see who has a specific message? For this, we will need to create a query. A query is a set of commands that will search and call upon specific data in the database (if you see in one of the earlier pictures, the fabric uses CouchDB). The Composer Playground uses the .qry language to query, and it is pretty similar to SQL. This is how a query structure will look:
-statement (where query logic begins)
-object (generally asset) you want to query on
-other query commands (optional)
To read more in depth about queries in playground, you can go here: https://hyperledger.github.io/composer/latest/tutorials/queries
Now, we will start to write our own queries. Click “Add a File” and select the ‘query file’ option. In this case, we cannot rename our query files. Below, I have made two queries – one which searches a person by name and the other which searches what person carries a specific message. Here is the code:
In the two queries above, you may notice that some of the variables have a _$ symbol preceding it. This means that they are input variables.
Now let us test out the queries. However, even if you go to the ‘test’ tab, there does not seem to be anything there to test out queries. So in order to test queries, we will have to create a REST server. To do that, first you will have to type this command into terminal:
It may take a little while for terminal to load, but you should be presented with a series of questions. You can look at the picture below to see how to answer these questions-. Once you are done answering these questions, the computer will take some time to load your REST server, and it should be running on localhost:3000.
Note: For the first question, your business network card should be admin@[your project name]. My project name, as mentioned earlier, was ‘demo2’
If we go to our web browser and go to localhost:3000, we should see this:
Now click on the “Query: Named queries” section and you should see this:
Note: The first query should say /queries/findUser. I only edited my query name after writing the first version of this article, as the original name of the query didn’t make any sense.
Let us click on the first query (either right on the name or on the “GET” button). We should see something like this:
As seen in the picture above, there is a name parameter. I typed in “Jay” there and then clicked the “Try it out!” button, which returns a JSON body. You may notice that this JSON object is the same as one of the assets we created earlier in this tutorial. This is because both the Playground and the REST server are connected to the same DAPP and the same block in the blockchain, so all data created in the Playground will show up in the REST server and vice versa. Now let us close this query window by re-clicking on the name or the “GET” button and test out the second query. It should look like this:
Here there is a message input field. I type “Hello” and I get an empty response body, meaning that no person is currently carrying this message. But let’s say we want to give the “Hello” message to somebody. So let us close this window, close the “Query: Named queries” subsection, and look for the “models_transactions_giveMessage” subsection. Open up that subsection and it should look like this:
Click on the “POST” subsection, and you should be led to a screen like this:
This “POST” method will cause a transaction to commence. If the JSON value field is empty, you can click the yellow “Example Value” box to the right to fill it up. Make sure to delete the transactionID and timestamp lines from the box (as those will be automatically generated) and the comma after the “receive” line (as otherwise the extra comma would be a JSON syntax error). Now, after the colon in the “receive” line, delete the curly brackets and enter in “resource:models.person.Person#[your person name]” (include the quotation marks). The person I gave the message to was Maya, so I entered in “resource:models.person.Person#Maya”. Now click the “Try it out!” button and your transaction should be posted. If your transaction is successfully posted, you should get a response body looking like this (Response Code should be 200):
Now let us go back to our second query (findUserWithMessage) and check again. This time, I typed “Maya” as the input instead of “Jay”. Here is the result:
As seen above, we surely now get a result back, as a person now carries the “Hello” message.
Now you should know the basics of using the Composer Playground for Hyperledger and using a REST server. Here are the big takeaways you should have learned:
- Creating a new business network
- Understanding what a DAPP is
- Understanding what assets and transactions are
- Testing a DAPP with both Playground and on the REST server
- The “GET” and “POST” functionalities of a REST server
I hope you have learned a lot and enjoyed this tutorial!
“Installing Pre-Requisites.” Hyperledger Composer, The Linux Foundation, 2017, hyperledger.github.io/composer/latest/installing/installing-prereqs.html.
“Installing the Development Environment.” Hyperledger Composer, The Linux Foundation, 2017, hyperledger.github.io/composer/latest/installing/development-tools.html.
“Queries Tutorial Using the Composer Query Language and REST APIs.” Hyperledger Composer, The Linux Foundation, 2017, hyperledger.github.io/composer/latest/tutorials/queries.
Singh, Nikhira. “How to Create an Application on Blockchain Using Hyperledger.” FreeCodeCamp, Medium, 25 Feb. 2018, medium.freecodecamp.org/ultimate-end-to-end-tutorial-to-create-an-application-on-blockchain-using-hyperledger-3a83a80cbc71.