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.
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 and for being able to search for them. And we’ve decided to use Hyperledger Fabric platform to do the job.
At the end of the day, we want this application look like below (with terse explanation unless self explanatory).
Our first screen is the web application’s Login page with background of Hyperledger Fabric api service debugging output:
The following screen is the web application’s Login page (continued). Login uses 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 form to records house transaction onto blockchain:
The following screen enters a house transaction onto the form:
The following screen records house transaction onto blockchain and queries the chain to retrieve it (to confirm successful recording of 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 would facilitate our problem-solving in creating a blockchain application.
The following image depicts such an architecture and let 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. Using cryptographical tools to create keys, secure identities, roles etc. Using 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 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, such configuration file or files defines the overall network topology. You don’t have to gain a full ability in linear fashion in a short time, but pretty good 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 step by step, 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 chaincode that we developers/programmers create.
User chaincode has four life cycle of “Install”, “Instantiate”, “Invoke” and “Query”.
“Install” essentially maps the chaincode’s location/path, thus, when 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, write data or put data onto the blockchain.
“Query”, simply put, get data or retrieve data from the blockchain.
“Install” and “Instantiate” 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”. Knowing how to install and instantiate is critically important.
There are at least 3 methods to install and instantiate chaincode.
- (a) via the “peer” command at CLI command prompt and this is a good method.
- (b) via call to a Fabric REST api server, in my experience this method is pretty good as well
- © via Hyperledger Composer and this introduces a totally new paradigm. While I have 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 going many directions / introducing unnecessary, extra processes, so, personally I’m avoiding this option for efficiency’s sake. Contact me for details on that.
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 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 “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, once done, use “peer chaincode list -C mychannel — instantiated” 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 “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. 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, two key functionality 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, 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 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 api and Composer api. As stated above, I’m a fan of Occam’s Razor principle, solving problems efficiently (vs. any convoluted method regardless), thus, I’ve eliminated 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 chaincode, this low level api is called “shim”, 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 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 / 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… Take a look at the following screenshot, sort of a mess but 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 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 also bring us a sense of community.
Like other blockchain platforms, Hyperledger Fabric technology is still nascent, the good thing is it seems evolving steadfast.
Thank you for reading and I hope you’ve benefited from it and you can get my two sets of Hyperledger Fabric training materials (each about 40 page long) for only $6 payable via PayPal. This special offer is only valid from September 8 through September 11.
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… ).
