Hyperledger Fabric Developer Tutorial Part 1: Make Your Own Blockchain

Recommended snack and song:

Sliced bananas and strawberries with granola all mixed in a bowl of natural yogurt while listening to Royal Blood.

When you hear about blockchain, you normally think of a publicly available ledger, on a worldwide distributed network of peers that have an agreement strategy to include new blocks (or transactions) on the blockchain. This is OK for most applications, but what happens when you’d like to take advantage of the blockchain technology, but don’t want your data to be scattered around in the world? What happens when there’s sensitive data that, if made public, could potentially hurt your business interests?

Enter Hyperledger Fabric: an open-source blockchain framework implementation hosted by The Linux Foundation, which you can use to host your very own and very private blockchain. You can read more about it on their website, and perhaps even watch this intro video, which makes it a bit easier to understand what the motivation behind the entire project is.

tl;dr: Go clone this repo and follow the README instructions to get this running.

This is what we’re gonna cover:

• Installing the prerequisites.
• Using the yeoman generator to get a basic business network definition project.
• Coding a simple solution with it.
• Deploying locally.
• Looking at some follow-up steps you might want to consider.

Just a quick note—this first part of the Hyperledger Tutorial series is all about getting started building business logic and having it deployed onto your own blockchain. Later blog posts in this series will take a deeper dive into the concepts that really make Hyperledger very powerful.

Installing the Prerequisites

First, make sure you have NodeJS installed (go with LTS, that’s the safest choice). If you already have, a good security measure is making sure you can do sudoless npm global installs (in case you’re using Linux or OSX).

Now, run these commands:

$ npm install -g composer-cli
$ npm install -g composer-rest-server
$ npm install -g composer-playground
$ npm install -g yo
$ npm install -g generator-hyperledger-composer

You’ll also need to download and install Docker, which you can do by going to the Docker install page and downloading the Docker Community Edition for your OS.

Once you have Docker running on your system, it’s time to run a few bash script commands:

$ mkdir ~/fabric-tools && cd $_
$ curl -O https://raw.githubusercontent.com/hyperledger/composer-tools/master/packages/fabric-dev-servers/fabric-dev-servers.zip
$ unzip fabric-dev-servers.zip
$ ./downloadFabric.sh

This will create a directory in ~/fabric-tools, download a few provision scripts and start downloading the Hyperledger Fabric Docker containers.

One other thing—you’d benefit a lot from using VSCode to code this project up. This can be done by installing the Hyperledger Composer extension.

Generating the Business Network Definition Project

We’re going to build some small asset management software for Dr. Who so he/she can track who owns a key and even track the creation of new keys.

First, run the yeoman generator:

$ yo hyperledger-composer:businessnetwork

…which will ask the following questions (answer them as shown below):

Welcome to the business network generator
? Business network name: tardis
? Description: Key asset management system for Dr Who
? Author name:
? Author email:
? License: Apache-2.0
? Namespace: com.gallifrey.tardis
   create index.js
   create package.json
   create README.md
   create models/com.gallifrey.tardis.cto
   create .eslintrc.yml
   create test/logic.js
   create lib/logic.js

Perfect! Now we have to create our models to represent our network, which will be super simple; we just need a Key asset and a Companion. Also, we need to create a TransferKey transaction to transfer the keys around. Open up the models/com.gallifrey.tardis.cto file and replace its contents with:

namespace com.gallifrey.tardis

participant Companion identified by companionId {
  o String companionId
  o String name
}

asset Key identified by keyId {
  o String keyId
  o String owner
}

transaction TransferKey {
  --> Companion companion
  --> Key key
}

As for the logic of the TransferKey transaction, replace the contents of lib/logic.js with:

'use strict';

var NETWORK_NAME = 'com.gallifrey.tardis';
var KEY_ASSET = 'Key';

/**
 * Transfer ownership of a TARDIS key to a fello
 * @param {com.gallifrey.tardis.TransferKey} transferKey
 * @transaction
 */
function onTransferKey(transferKey) {
    var key = transferKey.key;
    var keyFQDN = [NETWORK_NAME, KEY_ASSET].join('.');

    return getAssetRegistry(keyFQDN)
        .then(function(registry) {
            key.owner = transferKey.companion;
            return registry.update(key);
        });
}

Quick note: These JS logic files inside the lib folder are NOT NodeJS modules and currently don’t support ES6 syntax. I asked and this was their answer.

Awesome, we’ve coded our first official Business Network Definition project! It’s time to deploy it locally to our Hyperledger Fabric servers:

$ cd ~/fabric-tools/
$ ./startFabric.sh # This will kickstart the fabric servers.
$ ./createPeerAdminCard.sh # This will create a peer admin user

The peer admin user takes care of deploying the business network definitions to the peers. For the purposes of this tutorial, we’re gonna have one peer admin card to rule all the peers.

Build Code for Deployment

Once you have your business network definition done, and you’ve made sure your servers are up and operational, we can proceed with building our BNA (business network archive) file by navigating the console to your project’s folder and running:

$ composer archive create -t dir -n .

Then we need to install our business network as a runtime for the peer:

$ composer runtime install --card PeerAdmin@hlfv1 --businessNetworkName tardis

Next up, we need to create a network admin card and deploy our previously generated .bna file:

$ composer network start --card PeerAdmin@hlfv1 --networkAdmin admin
--networkAdminEnrollSecret adminpw --archiveFile tardis@0.0.1.bna --file
networkadmin.card

Make sure you change the parameters accordingly; for instance, the name of the .bna file may change depending on the version of the project in the package.json file.

Now we need to import the generated networkadmin.card card file by typing:

$ composer card import --file networkadmin.card

And just to check that everything is up and running:

$ composer network ping --card admin@tardis

For us to take a look at the final result of what we’ve accomplished, there’s a tool we’ve installed called Composer Playground, which we can launch by doing:

$ composer-playground -p 5000

In there, you can play around with your data; you can also launch a small REST server for you to play around with the data, which is built on top of Loopback:

$ composer-rest-server -c admin@tardis -n never -p 9000

Now you have a complete blockchain-based business network using Hyperledger running on your computer using Docker! How cool is that? For the next parts of this tutorial, we’re going to take a deep dive into more complex concepts that will give you a better perspective on how to apply this technology in your applications.