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 Hyperledger Fabric blockchain platform. It may benefit both Hyperledger Fabric novices and experienced Hyperledger Fabric professionals.


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 log in pages with a background of the Hyperledger Fabric API service's debugging output:

Build A PoC Blockchain Application Using Hyperledger Fabric 

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

Build A PoC Blockchain Application Using Hyperledger Fabric 

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

Build A PoC Blockchain Application Using Hyperledger Fabric 

The following screen enters a house transaction into the form:

Build A PoC Blockchain Application Using Hyperledger Fabric 

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

Build A PoC Blockchain Application Using Hyperledger Fabric 

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

Build A PoC Blockchain Application Using Hyperledger Fabric 

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

Build A PoC Blockchain Application Using Hyperledger Fabric 

The following screen returns transaction query results:

Build A PoC Blockchain Application Using Hyperledger Fabric

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 “” 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 application 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:

Build A PoC Blockchain Application Using Hyperledger Fabric 

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

Part One - 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. are 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 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 Two - 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.

docker run …” is to kick off / run a container’s service …

docker rm -f $(docker ps -qa)” 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 -wise, 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 are the chaincodes that we developers/programmers create.

User chaincode has four life cycles of “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 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” are beyond 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” (and yes, the chaincode 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 chaincode:

  1. Via the “peer” command at 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, and 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 have 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 chaincode, since “mycc” has already been installed, you may install “fabcar”. Look for its path for installing “mycc” from the “./ up” screen when you brought up the Fabric network.

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

Thus, once again it’s important to obtain an Ability to perform 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 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 vs. the rigid thinking of “must this” or “must that”.

Now, let’s map all the above generic learning about chaincode into the House Transaction blockchain application, in this case, 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 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 chaincode life cycle as described above.

So, now, we have built a blockchain network using 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 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 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 how to connect the chaincode to 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 the 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 chaincode side, it leverages a low level API to communicate with chaincode, this is called “shim”, it's also called “fabric-shim”, then, on the web site, 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 create 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 chaincode type of business such as running Fabric API server, for verifying running processes / mounted containers / programs, for running a web server and possibly another for verifying files; then, we have a Firefox web browser opened for the web app side of 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.


Blockchain technology is complex. Our background and aptitude affects 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 chaincode to the network; 
  3. Ability to write server side script for web interface into the chaincode via an API server. And as a practitioner, we need to remember the Occam’s Razor principle, that efficiency beats any convoluted design and/or architecture.

And 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, 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 chaincode parameters, restart the network and do some testing ).