Building with HashGraph Part 2: Technical Workthrough

A diagram illustrating a gossip based protocol. Each node represents a gossip event being sent/received.

In the previous section I described the underlying technology of the HashGraph. In this section I’m going to walk through the HashGraph Software Development Kit (SDK). Understanding and developing with this SDK provides a great way of getting your head around the underlying technology. The HashGraph SDK is free for anyone to download and allows you to play with some simple demo apps. However the technology is patented and currently the license doesn’t allow you to deploy any applications that you write.

Before we start this workthrough you will need to download the SDK and make sure you have installed Java and Maven.

Look at index.html of docs

The first step to understanding any SDK is becoming familiar with the documentation. In the SDK folder you should have downloaded, navigate to /sdk/docs/javadocs/index.html. This has all the information you will need to develop with this SDK. This can be quite daunting at first but don't worry - after this tutorial you should be able to browse this documentation with a vague idea of how everything fits togther. In particular later we'll be having a look at the Platform, SwirldMain and SwirldState classes.

Config.txt

The next step for exploring this SDK is to run the demos that are provided in the /sdk/source folder. We will be seeing how to do this by setting the correct configuration in /sdk/config.txt and by then running /sdk/swirlds.jar.

In the config.txt file you should see some lines like this:

swirld, 123
# app,		HashgraphDemo.jar,	   1,0,0,0,0,0,0,0,0,0, all
# app,		GameDemo.jar,		   9000, 9000
 app,		HelloSwirldDemo.jar
# app,		CryptocurrencyDemo.jar
# app,		StatsDemo.jar,		   0, 3000, 0, 100, 1024, -1
# app,		FilesystemDemo.jar

The line containing swirld, 123 is simply naming the world or swirld that will be instantiated. Additionally, there are a number of lines with examples of invoking each demo application. I have uncommented the line containing app HelloSwirldDemo.jar which indicates to the swirlds.jar executable that it needs to look for a jar file called ‘HelloSwirldDemo’. Some of the other demos have extra information after their names which are the parameters which are passed to the application. The comments in the latter part of this file explain what each of these programs do and what their parameters are.

Next, you should see some lines resembling the following:

address,  A, Alice,    1, 127.0.0.1, 50204, 127.0.0.1, 50204
address,  B, Bob,      1, 127.0.0.1, 50205, 127.0.0.1, 50205
address,  C, Carol,    1, 127.0.0.1, 50206, 127.0.0.1, 50206
address,  D, Dave,     1, 127.0.0.1, 50207, 127.0.0.1, 50207

These lines are specifying what participants we want to run or interact with. Again, these fields are explained fully later in the file but the takeaway is that we specify names as well as internal/external IP addresses and port numbers for any participant in our network. The address 127.0.0.1 means that swirlds.jar will not just interact with a participant, but will spin up that participant on the local machine.

Running a Demo

If you are familiar with Maven and Java then this section should be straightforward. However if you are not, then I’m going to step through all the steps you need to run the HelloSwirld Demo.

We can use /sdk/swirlds.jar to run the swirld that we specified above:

cd sdk
java -jar swirlds.jar

Now you should see some windows pop up that look like the following:

You’ll also get another window in the background:

The first set of windows are the application windows and the last window allows you to look into some statistics about the HashGraph backend. I will not be describing the last window but feel free to browse this in your own time.

In the first set of windows, each one represents a participant that sends out a transaction representing a “hello” message from themselves and then listens to all of the messages it has received from other participants.

Each line represents all the messages that have been received at a moment in time. Some of these messages are in the order agreed upon by consensus, and others are messages that are ordered in a best guess of consensus order. This is why the ordering of messages changes in the last line of each window, but more on that later!

Now, we are going to make a change to our source code, recompile it and run it to see how to make changes to the demo applications. Firstly, navigate to /sdk/source/HelloSwirldDemo/src/HelloSwirldDemoMain.java. You should see a run() method in the class that looks like the following:

Now you can try making a simple change such as changing the string on line 6 from "Hello Swirld from " to "This is a modified program. Hello Swirld from ". Now we can rebuild the project, and run it again to check that the change has come into effect:

mvn deploy 
cd ../../
java -jar swirlds.jar

You should see a different text output in the top line of each application window. If you don’t, take another careful look at all the steps we’ve just taken and make sure you’ve followed them all correctly.

So now you know how the config.txt file works, and you know how to make changes to the demo applications, we can start looking at how the HelloSwirld demo actually works!

HelloSwirld Demo

There are a number of demo applications included in the /sdk/source directory, and we will be looking at the HelloSwirld demo which is intended to be the simplest working example of a HashGraph application. As explained earlier, the application consists of a number of participants sending just one message each and then listening for any received messages.

Each HashGraph application requires two classes to be implemented: a main class implementing com.swirlds.platform.SwirldMain and a state class implementing com.swirlds.platform.SwirldState. These classes will also make use of a com.swirlds.platform.Platform object which can be used to get state and create transactions.

SwirldMain is the interface for the class in charge of the application. It must implement an init() and run() method that contain all the logic for e.g. updating user interface, interacting with non-hashgraph state etc. In the HelloSwirld demo, you will find a main class which sends a hello message and then polls for any updates from the state class:

SwirldState is the interface for classes that handle state stored within the HashGraph. Transactions are passed to the Platform object as byte arrays and are received by the State object as byte arrays but can be serialised, deserialised and stored in memory however the developer specifies. The most important method here is handleTransaction() which updates the state object whenever a new transaction (in the form of a byte array) is received.

The consensus parameter to handleTransaction() indicates whether or not a transaction is agreed upon by consensus yet. You may wonder what happens if the consensus order is different to the order in which the state object receives transactions. You do not need to worry about implementing any rollback mechanism because the order of transactions seen by a particular instantiation of the state class will always be the same — if the consensus ordering changes, the SDK will spin up a new state class and will pass it the new transactions in the correct order. This is handy because it allows us to perform preemptive actions even before a transaction is agreed upon by consensus.

There will be some extra boilerplate code and some code that allows fast copying of the state objects, but HelloSwirldDemoState should look something like the following:

In particular, notice how the handleTransactions() method ignores the consensus parameter such that at any moment, using the getReceived() method will give all transactions, consensus or not. If you wanted to make sure that transactions were only seen if they are agreed upon by consensus, then you may choose to only add them if the consensus parameter is true. You might do this by changing line 18 to:

if (consensus) {
  strings.add(new String(transaction, StandardCharsets.UTF_8));
}

Now if you recompile and run the application, you should see an output like the following:

If you don’t understand why we get this output, take some time to try and understand what is happening here.

Summary

So now you should be able to understand how the HashGraph works, and how you can go about building and running apps using the SDK. Again, make sure that you are only playing around with this for fun and if you want to deploy applications, you get in touch with Swirlds. If you are interested in learning more about HashGraph then I can recomend the following links:

• Hedera HashGraph Website
• Hedera HashGraph YouTube
• Swirlds HashGraph Website

I hope you’ve found this helpful and if you have any thoughts or questions, please comment and I’ll try to help the best I can.