Build a Blockchain PoC Application Using Hyperledger Fabric

This piece is about my experience in creating a blockchain PoC application for land and title recording on blockchain leveraging Hyperledger Fabric (HF) blockchain platform. It may benefit those who just got started on HF or intend to learn it, and for those who are already experienced in HF, it may offer another equally viable option. It’s pretty long, but for readers who are interested in blockchain technology, your time will be well spent.

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

Our goal is to create a web application for recording house transactions (buying and selling houses) on a small, permissioned blockchain and being able to search for them. And we’ve decided to use the Hyperledger Fabric platform to do the job.

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

Our first screen is the web application’s Login page with a background of Hyperledger Fabric API service debugging output:

The following screen is the web application’s Login page (continued). Login uses a two-factor authentication process.

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

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

The following screen enters a house transaction onto the form:

The following screen records house transactions onto a 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. 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 an architecture.

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

Breaking them into three tiers or components facilitates problem-solving and creates a blockchain application.

The following image depicts such an architecture and lets it guide us in our such blockchain application development endeavor:

Part One:  Hyperledger Fabric Network Infrastructure

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

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

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

Part Two:  Hyperledger Fabric Chaincode

The term “chaincode” is equivalent to a “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, understanding various aspects of 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. docker run …  is to kick off /run a container’s service … docker rm -f $(docker ps -qa) is used to kill all running processes/containers. Along the way, some essential Unix/Linux/Ubuntu skill is a must. For instance, ls to list files in a directory,  cp for copy, mv for move or rename, 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).

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

User chaincode has four lifecycles — Install, Instantiate, Invoke, and Query. Let's look at those in a bit more detail:

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

• “Instantiate” would create a container image to support all future invocation and query needs of the particular chaincode, 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” beyond the basics

In my opinion, in a production environment, chaincode "Install" and "Instantiate" would usually be a one-time process; once a particular chaincode is installed and instantiated, they would “always” be there for future use such as for “invoke” and/or “query.” Knowing how to install and instantiate your chaincode is critically important.

There are at least three methods to install and instantiate chaincode.

• (a) via the peer command at CLI command prompt, and this is a good method.
• (b) via a call to a Fabric REST API server. In my experience, this method is pretty good as well
• (c) via Hyperledger Composer — this introduces a totally new paradigm. While I have the highest respect for people working on Hyperledger project, I have an issue with how it fits into the overall Fabric architecture, by having Composer to re-create a Fabric network, etc., it seems to be going in many directions/introducing unnecessary, extra processes. So, personally, I’m avoiding this option. See the following note and URL for details on the future prospect 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.”

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 chaincode. Since mycc has already been installed, you may install fabcar, look for its path to install mycc from the ./byfn.sh up screen when you brought up the Fabric network.

Once installed, you can verify if it’s truly installed via the peer chaincode list — installed  command. Then, instantiate fabcar chaincode by looking at how it’s done for the mycc chaincode ( and make sure you’re ONLINE, it needs some npm reference ). It may take several minutes, but once done, use peer chaincode list -C mychannel — instantiated to verify if it’s truly instantiated.

Thus, once again, it’s important to obtain the ability to perform the chaincode lifecycle, as mentioned above — install, instantiate, invoke, and query.

Chaincode coding-wise, a great way to learn is to read and understand sample chaincode. Both the Balance-Transfer  sample app and Fabcar sample app are good examples. The important thing is a willingness to experiment with or tweak with 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, instead of: It must do this or that.

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

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

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

Part Three:  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, we look at how to connect the chaincode to the web app, so the chaincode sort of sits in the middle. An API is the way to go to make the connections for both ends. Then, API-wise, we have the Fabric API and Composer API. As stated above, I’m a fan of Occam’s Razor principle, solving problems efficiently, instead of any other convoluted method), thus, I’ve eliminated the Composer API, which means Fabric API is my choice.

In a nutshell, the Fabric API server works like this: On the chaincode side, it leverages a low-level API to communicate with the chaincode. This low-level API is called “shim,” 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, 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, we need to create an HTML FORM to accept House Transaction data input, some code to accept that transaction, and write data to the chain. Then, we will need some more code to accept a query for transactions, and some code to process such query/search, get data from the chain, and then present the user with such results, or none if not found.

By now, we have several terminals for the Fabric chaincode-type of business, such as running the Fabric API server, verifying running processes/mounted containers/programs, running a web server, and possibly another for verifying files. Now, 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. Take a look at the following screenshot, which is sort of a mess but a NICE mess, in my opinion:

Summary

Blockchain technology is complex. Our background and faculty would 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 road map, what key knowledge we need to obtain, how each component/piece connect with another and fit together, what goes first and what needs to follow, what is our priority 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 them 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 chaincode to the network; (3) Ability to write server-side script for web interface into the chaincode via Fabric API server. And as a practitioner, we need to remember Occam’s Razor principle:

Efficiency beats any convoluted design and/or architecture.

And as equally important, we need to continuously find good, competent, and experienced people along our journey; they may not only enrich our knowledge but very well may bring us a sense of community.

Like other blockchain platforms, Hyperledger Fabric technology is still nascent; but the good thing is that it seems to be remaining steadfast.

Thank you for reading, and I welcome your input and feedback in the comments below!

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 (just need to edit the docker-compose.yaml configuration file and editing some chaincode parameters, restart the network, and do some testing).