In part 1 of our series, we discussed a few applications of Blockchain beyond cryptocurrency. In particular we took a look at supply chain. Most large supply chains have already made requisite investments in inventory tracking through RFID based systems. Hyperledger Fabric permits supply chains to easily upgrade these tracking with more accurate auditing and transparency. In this article, we will continue with our case study of Main Street Hospital and their implementation of Blockchain to more accurately track drug shipments from manufacturers.

Creating the Fabric | Options

There are four options for creating a Fabric blockchain network. The first option to do so is to pull down the Hyperledger codebase from GitHub to an on premise server. The second option is to make use of IBM-certified Hyperledger fabric images on DockerHub(for which support is available to purchase) on an on premise server. The third and fourth options are both based on the IBM Cloud. You can choose either the IBM Bluemix container service or the more specialized IBM Blockchain Platform to be used as your PaaS substrate.

If you are time or server constrained, option #3 is the fastest way to setup a Blockchain network. If you navigate to (https://composer-playground.mybluemix.net/) you’ll be be able to interact with a hosted instance of Hyperledger Fabric through the Hyperledger Composer web interface. Composer is an application development framework intended to simplify and expedite the development of Fabric blockchain applications. By simply defining a model file, javascript transaction/function file, access control list, and a query definition file, Composer will then synthesize a business network archive that can be deployed directly upon Fabric distributed ledger. Composer is a very cool tool, but it’s out of scope for this article.

Setting up the Fabric

For our case study, we are going to use the first option and use the official Hyperledger codebase from GitHub.

Before we begin setting up an actual Fabric instance, here is a pointer to the project source code: (https://github.com/hyperledger/fabric) which is a read-only mirror of active upstream gerritt development repository at: (https://gerrit.hyperledger.org/r/#/admin/projects/fabric).

These steps will assume basic CLI familiarity with a Linux/UNIX system. Choose the Linux distro of your choice. You will need to ensure the following packages are installed on your test system:

cURL
docker (version 17.06.2-ce or greater is required), docker compose (version 1.14.0 or greater)
go language runtime (version 1.9.x or greater)
Optionally, if you intend to experiment with writing chaincode in node.js, you will additionally need to make sure that you have the node.js runtime (version 6.9.x < 7.x) and a version of Python 2.7.

Let’s begin by retrieving the hyperledger fabric samples. Navigate to whatever directory you intend to work from and execute the following commands:

> git clone -b master https://github.com/hyperledger/fabric-samples.git

> cd fabric-samples

2. Now to download the platform-specific binaries. The next command downloads and executes a bash script that puts all of the required platform-specific binaries in the right place within the repo we just cloned. This essentially bypasses the typical build process for the sake of expediency. The script also downloads the Hyperledger fabric docker images and places them into your local Docker registry. Do note that this script will take some time to complete since quite a few Docker images are going to be downloaded. You’ll need to make sure you have about 10GB free on the disk where your Docker image store resides.

> curl -sSL https://goo.gl/6wtTN5| bash -s 1.1.0-alpha

> export PATH=<path to download location>/bin:$PATH

> cd first-network

As always, please inspect any script you get from the internet before running it. Additionally, all further commands should be executed from the first-network subdirectory of the fabric-samples cloned repo.

3. So as you may have suspected, bringing up a Fabric network is not a trivial undertaking. Fortunately, there is a fantastically commented bootstrap script included with the repo. We’ll be using this script rather than reinventing the wheel. The following two commands are all that’s necessary to bring up the network:

> ./byfn.sh -m generate

> ./byfn.sh -m up

And to bring the network back down again, execute the following:

> ./byfn.sh -m down

And that’s all there is to it! There are, of course, many options available in between these steps. We heartily recommend reading through the entirety of the byfn.sh script. But if you don’t have the time to do so right now, here is a brief overview of what just happened when you ran those commands.

The Fabric Breakdown

Running the byfn.sh script created a Fabric network consisting of two organizations (Org1 and Org2), each maintaining two peer nodes, and a solo ordering service. Each organization was provisioned a unique root certificate that binds specific logical nodes (clients, peers and orderers) to that organization. The following short definitions for each type of logical node come directly from the official docs:

Client: Submits an actual transaction-invocation to the endorsers, and broadcasts transaction-proposals to the ordering service.

Peer: A node that commits transactions and maintains the state and a copy of the ledger. Peers can also have a special endorser role.

Orderer: A node running the communication service that implements a delivery guarantee, such as atomic or total order broadcast.

The network topology specified by the script has the two peer orgs, Org1 and Org2, grouped together within a consortium alongside the Orderer organization (OrdererOrg). A consortium is a logical container within which confidential channels between different orgs can be created. As part of creating the ledger’s genesis block during channel creation, two lead-up actions were performed. First, an anchor peer for each peer org was defined, and second, the location of the membership service provider for each org was pointed to by each member. Those two steps allow for storing the root certificates belonging to each org in the orderer genesis block, thus permitting verification of any entity that communicates with the ordering service thereafter.

After all the configuration artifacts have been created, the channel has been established, and all the peers have joined said channel, all that remains is to kick off the chaincode. Chaincode is the backbone upon which all transactions are executed, thus it is the mechanism through which applications interact with the actual blockchain ledger. Remember, a ledger is an ordering of transactions, so interacting with a ledger requires posting a transaction be appended to the head of the ledger. Chaincode needs to be installed on every peer that will execute and endorse transactions, and then the chaincode must also be instantiated on the channel.

Earlier when the channel was created, a copy of the genesis block was stored on each of the peers’ file systems along with the channel configuration. All of the peers were then able to join the channel using that configuration. The bootstrap script you ran installed a chaincode example “chaincode_example02” on peer0.org1.example.com and peer0.org2.example.com. It then instantiated the chaincode on the channel, starting a docker container for the target peer and initializing the key-value pairs associated with the chaincode. A required endorsement policy was also passed in so as to restrict transaction origins to only those endorsed by peers belonging to Org1 or Org2.

The chaincode running on your demo fabric network defines two keys, “a” and “b”, and initializes them with the integer values “100” and “200”. While those keys and values are completely arbitrary, there is nothing preventing you from trivially extending the chaincode example to support any number of keys (even recursively nested keys) necessary for your use case.

Moving Drugs Through the Chain

For example in our Main Street Hospital use case, each one of the keys could represent a particular shipment of pharmaceuticals from the manufacturer. In this case, Acme Meds has key “a” and Main Street Hospital has key “b”. The following Blockchain transaction with add a shipment of 10 units of a medication from Acme Meds to Main Street Hospital to the Blockchain.

The example Blockchain query and invoke commands against the chaincode look like this:

> peer chaincode query -C $CHANNEL_NAME -n mycc -c ‘’

> peer chaincode invoke -o orderer.example.com:7050 — tls — cafile /opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem -C $CHANNEL_NAME -n mycc -c ‘’

The above commands will first ask for the initialized value of key “a”, and then will transfer 10 units from Acme Meds key “a” to Main Street Hospital’s key “b”.

If you want a little more visibility into what is happening with these chaincode operations, you can inspect the logs by peeking at the logs for each of the docker containers spun up on the peers to run the chaincode:

> docker logs dev-peer0.org1.example.com-mycc-1.0

> docker logs dev-peer1.org2.example.com-mycc-1.0

So we have covered a lot of ground, and you are likely wondering how all of these technical details map back to our case study.

Adding to the Blockchain Party

In this example, Acme Meds transferred 10 units to Main Street Hospital directly. This assumes the medications are shipped directly from the manufacturer to the hospital. What if there are additional transport intermediaries? The answer to that question is to create a new organization for each distinct company involved in the transport of shipments (Org3, Org4, Org5,for example) each with their own keys. These organizations will be joined to the same channel that was created between the Main Street Hospital and Acme Meds, but they will need to be setup with different permissions.

We want the organizations representing transport intermediaries to have reduced visibility and transaction permissions. For example, there is no reason for the intermediaries to be able to see the cost details of the initial purchase order. These transport intermediaries should only be able to issue inventory transfer transactions which could be constructed from a combination of an inventory receipt and inventory issue transactions. Main Street Hospital would need the added capability of issuing order receipt transactions, and Acme Meds would similarly need the permission to execute order issue transactions.

It would also make sense to create a private channel for each leg of the shipment since the pairwise contracts between the transport intermediaries may differ. And what about the IoT sensors that are supposed to attest to the integrity of the shipping conditions? That’s accomplished by associating a new peer node within the hospital’s organization for each sensor. The peer nodes for these sensors will then have chaincode installed on them that executes a smart contract triggered by an inventory change transaction. That smart contract triggers a round of PBFT voting that will then issue an attestation transaction referencing the organization that last handled the shipment.

Conclusion

That concludes this two part series. As you can see by our case study, the scale of creating a Blockchain based supply chain can be overwhelming. It’s important to keep in mind that all the transactions mentioned above can be modeled as atomic insertions, deletions and edits to a key-value store, namely, the distributed ledger. So with that in mind, modeling each one of the semantic transactions listed above is left as an exercise for the reader. To truly become comfortable working with a system as complex as Hyperledger Fabric, the more self-guided experimentation the better. So using the discussion above, try to implement the rest of the case study atop of Fabric network. Here are a few hints to get you started.

Add another organization
Manually generate all of the required certificate validation and signature verification artifacts
Modify the Membership Service Provider schema
Generate two new channels (manufacturer<->intermediary and intermediary<->hospital)
Model the transaction types above by filling in the key-value store
Add more peers to the hospital organization to represent the IoT sensors
Study more chaincode examples to understand how to write trigger activated smart contracts

Blockchain beyond cryptocurrency is still in its infancy. As with all technology disruptions, the industry finds the value and the value finds the industry. For Blockchain, stay tuned…

ABOUT THE AUTHOR

Harrison Perl is a Stone Door Group consultant with expertise in Ansible automation and cloud native solutions. He specializes in working with growth organizations, open source initiatives, and implementing Agile and DevOps methodologies. To speak with more consultants like Harrison, drop us a line at letsdothis@stonedoogroup.com