Build A PoC Blockchain Application Using Hyperledger Fabric

This piece is about my experience in creating a PoC blockchain application for land and title recording on a blockchain, leveraging the Hyperledger Fabric blockchain platform. It may benefit both Hyperledger Fabric novices and experienced Hyperledger Fabric professionals.

Goal

Let us first set up our goal and then see how we can achieve it.

Here our goal is to create a web application for recording house transactions (buying and selling houses) on a small permissioned blockchain built on the Hyperledger Fabric platform.

Expected Outcome with Screenshots

At the end of the day, we want this application to look like below.

Our first two screens are the web application’s login pages with a background of the Hyperledger Fabric API service's debugging output.

The following screen is the application’s main screen, which lists two core functions “add transaction” and “search for house transaction”

The following screen provides a form to record house transactions onto the blockchain.

The following screen enters a house transaction into the form.

The following screen shows the result of the house transaction recording onto the blockchain and queries the chain to retrieve it (to confirm the successful recording of the transaction)

The following screen captures the state when the Download (contract) link is clicked.

The following screen enters a house transaction search query (query house by apn)

The following screen returns transaction query results.

As we can see, the above is a fully functional PoC blockchain application. I'm calling it PoC because we have not replaced the domain name of “example.com” and related subdomains with a production one and a few other things.

Now, let’s discuss how we did it.

To start, we need conceptual clarity and architecture.

Hyperledger Fabric has a 3 tiered architecture. Specifically, its blockchain network for infrastructure, its chain code for business rules and logic, and web and/or mobile applications for end users to perform business functions.

Breaking them into three tiers or components will facilitate our problem-solving in creating a blockchain application.

The following image depicts such an architecture and guides us in our blockchain application development endeavor.

High-Level Description of How We Achieve It via the Following Three Parts.

Part 1. Hyperledger Fabric Network Infrastructure

This part involves working with stakeholders as the network participants or distributed nodes/peers, and along the way, creating and/or setting up rules and policies. We use cryptographical tools to create keys, secure identities, roles, etc. We use a special service called orderer to facilitate communication among peers and data transaction processing. And much more…

For this tier, an extensive computing background including skills in Unix/Linux/Ubuntu, Docker (containerization), etc. is needed. It’s complex and yet not much programming is needed.

An ability to set up a blockchain network with Fabric counts for this tier. A vital part is yaml file(s) such as docker-compose.yaml file, as such configuration files define the overall network topology. You don’t have to gain a full ability in a linear fashion in a short time, but a pretty good idea would be a good start.

Because it’s an important and yet complex process I’ve created a 45-page long separate document specifically on how to learn the very fundamentals of Hyperledger Fabric Network Infrastructure, which also discusses chaincode and briefly touches on web application development, so, please refer to this document for Part One if you are not familiar with it already (contact me for more details on it).

Part 2. Hyperledger Fabric Chaincode

The term, “chaincode” is equivalent to “Smart Contract” for Ethereum. Chaincode may be written in one of three languages, namely, Node.js, Go (Golang) and Java (personally, I’m in the Node.js camp). Proficiency in one of them is expected.

For this part, obtaining the Ability to know ways around Fabric such as effective use of CLI and docker commands would be quite important.

Some critical docker commands include “docker ps” to display running processes (programs and/or containers). “docker exec -it cli bash” would bring up the CLI command prompt.

# Command to kick off/run a container's service
docker run ...

docker rm -f $(docker ps -qa)

Along the way, some essential unix/linux/ubuntu skill is a must, for instance.

# Command to list files in a directory
ls

# "cp" for copy

# "mv" command for move or rename
mv

then some advanced knowledge could be handy as well, for instance.

“chmod a+r myfile” would enable “myfile” to be r (readable) by all three roles of user/group/everyone (global).

chmod a+r myfile

Chaincode management -wise, chaincode has two main categories, one is called “system chaincode” which interacts with the given blockchain and the other category, the other category is called “user chaincode” which are the chaincodes that we developers/programmers create.

User chain code has four life cycles “Install”, “Instantiate”, “Invoke” and “Query”.

“Install” essentially maps the chaincode’s location/path, thus, when the need arises it can be found and utilized.

“Instantiate” creates a container image to support all future invocation and query needs of the particular chain code, and that’s why “instantiate” takes longer to complete.

“Invoke”, plainly put, writes data or puts data onto the blockchain.

“Query”, simply put, gets data or retrieves data from the blockchain.

“Install” and “Instantiate” are beyond basics.

In my opinion, in a production environment, chain code installs and instantiation would usually be a one-time process, once a particular chain code is installed and instantiated it would “always” be there for future use such as for “invoke” and/or “query” (and yes, the chain code can be updated as well when the need arises). Knowing how to install and instantiate is critically important.

There are at least 3 methods to install and instantiate chain code.

1. Via the “peer” command at the CLI command prompt, and this is a good method.
2. Via call to a Fabric REST API server, in my experience, this method is pretty good as well
3. Via Hyperledger Composer this introduces a totally new paradigm. While I have the highest respect for people working on Hyperledger projects, I have an issue with how it fits into the overall Fabric architecture, by having Composer re-create a Fabric network, etc. it seems it's going many directions/introducing unnecessary, extra processes, so, personally I’m avoiding this option. See the following note and URL for details on the future prospects of this option, “Speaking on behalf of my team in XYZ, we’re all incredibly proud of what we’ve contributed to Composer over the last couple of years, and we are grateful to the community for all your feedback and contributions. However — we at XYZ believe that there are some fundamental problems with the architecture and design of Composer, as it is today, that has made us reconsider our future direction and plans.”. Ask me if you need its URL.

Regarding method (a), to try it, you could first bring up the “first-network”, then go to the CLI command prompt ( docker exec -it cli bash ), now you can install and instantiate chain code, since “mycc” has already been installed, you may install “fabcar”. Look for its path for installing “mycc” from the “./byfn.sh up” screen when you bring up the Fabric network.

Once installed, you can verify if it’s truly installed via the “peer chain code list — installed” (two - - dashes before install) command, then, instantiate the “fab car” chain code by looking at how it’s done for the “mycc” chain code and make sure you’re ONLINE since it needs some npm reference. It may take several minutes, once done, use “peer chain code list -C channel — instantiated” (two - - dashes before instantiate) to verify if it’s truly instantiated.

Thus, once again it’s important to obtain the Ability to perform the chaincode life cycle, as mentioned above, install, instantiate, invoke, and query.

Chaincode coding-wise, a great way to learn is to read and understand sample chain code. Both the “Balance-Transfer” sample app and the “Fabcar” sample app are good examples. The important thing is a willingness to experiment with or tweak them, thus, we would gain new understanding or even some sort of discovery. For instance, for the “First-Network” sample app, the “Instantiate” actually writes data to the chain while the “Instantiate” for the “Fabcar” sample app does not. Thus, we know that “Instantiate” can be written in a way that fits our needs better vs. the rigid thinking of “must this” or “must that”.

Now, let’s map all the above generic learning about chain code into the House Transaction blockchain application, in this case, two key functionalities are “addTransaction” and “queryTransaction” and since I’m using Node.js for chain code, one node.js source code file can address them both and once done, we make the package.json configuration file to reflect this node.js source code file. And then, we are ready to go for the chain code life cycle as described above.

So, now, we have built a blockchain network using the Hyperledger Fabric platform and have created chain code for this House Transaction blockchain application, but our end users would need to access it via the web or their mobile phone, so what’s next?

Naturally, developing a web and/or mobile interface into the chain, and since this application is for business I’ll start with the web application first. So, now it brings us to the next part.

Part 3. Web and/or Mobile Application on Top of the Blockchain

The very first question now is how to connect the chaincode with the chain’s State database and ledger and then how to connect the chaincode to the web app, so, the chaincode sort of sits in the middle. An API is a way to go to make the connections for both ends. Then API-wise, we have Fabric and Composer. As stated above, I’m a fan of Occam’s Razor principle, solving problems efficiently (vs. any convoluted method), thus, I’ve eliminated Composer, which means Fabric is my choice.

In a nutshell, the Fabric API server works like this: On the chain code side, it leverages a low-level API to communicate with chain code, this is called “shim”, it's also called “fabric-shim”, then, on the website, some server-side script calls the Fabric API for chain data action.

Now, let’s expand on the above, we first run the Fabric API server, then, we set up a web server, and create some server-side code to call the API server for different types of chain transaction needs such as “install”, “instantiate”, “invoke” and “query”.

And now, let’s turn the conceptual highlight of the above paragraph into this House Transaction application. For server-side code, we would need some code for the login page ( the FORM ) and some code to embed security/authentication logic, and then create an HTML FORM to accept house transaction data input, some code to accept that transaction, and write data to the chain, and then some more code to accept queries for transactions, and some code to process such queries/searches, get data from the chain and then present the user with such results or none if not found.

By now we have several terminals/windows for Fabric chain code type of business such as running a Fabric API server, for verifying running processes / mounted containers/programs, running a web server, and possibly another for verifying files; then, we have a Firefox web browser opened for the web app side of the business; and a text editor for file/code creation and editing. It may look like a mess but it's a NICE mess in my opinion.

Summary

Blockchain technology is complex. Our background and aptitude affect the way we learn and how fast we learn. In the meantime, we shall strive to seek clarity before we even start, technical clarity of the road map, what key knowledge we need to obtain, how each component/piece connects with another and fits together, what goes first, and what needs to follow, and our priorities are all important. And we should never underestimate the value of willingness to experiment with reason.

To put the above into perspective, we can sum it up as three core skill sets for a competent Hyperledger Fabric professional.

1. Knowledge and skill in the Fabric blockchain network or the network infrastructure
2. Ability to write and deploy chain code to the network
3. Ability to write a server-side script for web interface into the chain code via an API server. As a practitioner, we need to remember Occam’s Razor principle, that efficiency beats any convoluted design and/or architecture.

Equally important, we need to continuously find good, competent, and experienced people along our journey. They may not only enrich our knowledge but may very well also bring us a sense of community.

Like other blockchain platforms, Hyperledger Fabric technology is still nascent, the good thing is, that it seems to be evolving consistently.

Thank you for reading and I welcome input and feedback.

P.S. Currently this PoC app is for one organization with two nodes and I intend to add a few more nodes/peers from another organization to the network as well ( I just need to edit the docker-compose.yaml configuration file and edit some chain code parameters, restart the network and do some testing ).