Start your own Hyperledger blockchain the Easy Way!

10 min readJun 18, 2018

It seems almost monthly there is a new blockchain that’s generating all the buzz. Right now there is a lot of hype around EOS. Before, there was Ardor and NXT, before that there was NEM, and so on. How does anyone keep up?

The key, is you don’t have to stress yourself out trying to learn all the ins and outs of every blockchain out there. What you do have to do, however, is appropriately judge the strengths of each blockchain and apply them to your specific use case.

Do you want high security and true decentralization but don’t care too much about scalability? Ethereum is right for you. Do you want high scalability but don’t need as broad decentralization? Take look at many of the proof of stake blockchains available.

A blockchain that’s not always in the headlines but is quietly gaining massive steam is Hyperledger Fabric. Hyperledger Fabric is maintained by the Linux Foundation and evangelized by IBM. You’d probably be surprised to hear that Fabric is the most widely adopted blockchain by the biggest enterprises, much more so than your “big name” blockchains. Companies like Oracle, Accenture, The National Association of Realtors, Deutsche Borse Group, and Sony Global Education have all hitched their wagons onto Fabric. Do you see a pattern with those companies? They’re all giant enterprises.

No other blockchain has this kind of heavy hitting industry support. It’s a serious project maintained by the biggest open source organization in the world and not a group of kids or a benevolent dictator. This merits our attention.

Fabric has some key properties that makes it an ideal distributed ledger for private companies wanting to enter the blockchain game. While it’s nice to think that the blockchain’s benefits are so obvious it’s going to skyrocket us to paradigm shifting consumer applications overnight, in reality, it’s these companies making incremental operational improvements that are giving the world the true transformative benefits of the blockchain.

In this series of tutorials, we’re going to learn:

What is Hyperledger Fabric? Why is it such a good fit for enterprises?
How do I bushwhack through the complicated Hyperledger documentation and simply get my own Fabric network up and running? (This article will stop at this stage).
How do I write smart contracts on Fabric? (Next article)
How do I deploy my smart contracts and make my code “live”? (Next article)

Sound fun? Let’s get started!

A Quick Note

The first thing you’ll notice when wading through Fabric’s official documentation is that it’s not beginner friendly. Even basic setup instructions appear needlessly complicated. For example:

If you want to use the docker-compose-e2e.yaml without first running the byfn.sh script, then we will need to make four slight modifications. We need to point to the private keys for our Organization’s CA’s. You can locate these values in your crypto-config folder. For example, to locate the private key for Org1 we would follow this path - crypto-config/peerOrganizations/org1.example.com/ca/. The private key is a long hash value followed by _sk. The path for Org2 would be - crypto-config/peerOrganizations/org2.example.com/ca/.

What on earth?!?! We understand that Hyperledger wants to provide comprehensive documentation but the above is just a big plate of code salad. Ironically, this is from their “Getting Started” page. We believe their ridiculously cumbersome documentation is part of the reason for slow consumer uptake.

We think Hyperledger is awesome. These tutorials are meant to simplify usage for beginners. When you get comfortable with Hyperledger, you can refer back to their documentation and learn more about the specific areas that interest you.

What is Hyperledger Fabric? Why is it a good fit for enterprises?

Fabric has some key properties that differentiate it from other blockchains. To keep it simple, this is what you need to know:

It’s a permissioned blockchain. It’s not designed to be open to the world but you can add as many entities as you want.
It supports smart contracts, the same way Ethereum does. It’s written in chaincode (Fabric’s fancy word for smart contract code). All you need to know is that Fabric’s smart contracts are written in Go.
There is a concept of “Channels” where parties that are part of a blockchain can create separate transactions privately and then pass the final state to the be recorded on the main blockchain. This is not unlike state channels in other blockchains, but there is an additional privacy layer.
All participants have known identities, maintained by what Fabric calls “Membership Service Providers” (MSP). If you’re allowing a group of 10 hospitals to participate in your blockchain, each of the 10 hospitals are known to the network. This is the key feature of Hyperledger Fabric that makes it fit well with enterprise solutions.
Consensus: Fabric doesn’t use typical Proof of Work or Proof of Stake mechanisms to achieve consensus. Because it’s highly permissioned, it uses a sequence of verified transactions (based on MSP) instead. You can use chaincode to only accept a transaction if two parties who conduct a transaction both sign it and then peers that take in the transaction validate it as well. In short, all you need to worry about for now is that multiple verified participants need to sign transactions for them to get included to the ledger. This is a good fit for enterprise based blockchains that don’t have a huge number of participants. Because the participants are known to each other, there is a natural deterrent to malicious behavior. Read more here. This is a simple transaction flow diagram. You don’t need to understand all the details for now.

From: http://hyperledger-fabric.readthedocs.io/en/release-1.1/txflow.html

These key properties of Fabric give you the background info you need to start working with it. Like anything, the best way to learn is to dive right in and roll up your sleeves. Let’s fire up our own network and start tinkering with Fabric!

Start your own Fabric network!

The following section will get a live Fabric network up and running on our local. It is based on the official Fabric tutorial but is meant to simplify it immensely. It skips a lot of the background information and simply explains what is happening.

This tutorial will end at getting your network up and testing it. The next tutorial will be on writing custom smart contracts (chaincode) for your Fabric blockchain. We assume you have some basic programming knowledge for this tutorial.

Dependencies

Install the following if you don’t have them already:

Docker
The Go programming language

Run the following script. This script will clone the pre-packaged Hyperledger Fabric samples and download the binaries you need. Then navigate to the first-network directory we’ll work out of with the cd command below.

> curl -sSL https://goo.gl/6wtTN5 | bash -s 1.1.0> cd fabric-samples/first-network

Set an environment variable with a path to your binaries so Fabric knows where to find them. Replace the < > part below with the full path of the directory where the bin folder is found. You can find that by typing pwd in your terminal.

> export PATH=<replace this with your path>/bin:$PATH

Great! We have everything we need to proceed with getting our network set up.

Create Network Entities

We need to now create the participants in our network. Since they are permissioned participants, we need to give them all unique, secure IDs. Here is how we do it.

We’ll run the commands first and explain what’s happening after.

> ../bin/cryptogen generate --config=./crypto-config.yaml

You should see:

> export FABRIC_CFG_PATH=$PWD> ../bin/configtxgen -profile TwoOrgsOrdererGenesis -outputBlock ./channel-artifacts/genesis.block

You should see:

So what happened here? Simply,

We created 2 organizations
We created 2 peers per organization
We created certificates for each of the above, so each transaction can be signed by them and we know who created and signed the transactions
We created a genesis block

Next we need to create channels where our peers can interact and create transactions. We’ll call this mychannel but feel free to change it to whatever you want.

> export CHANNEL_NAME=mychannel  && ../bin/configtxgen -profile TwoOrgsChannel -outputCreateChannelTx ./channel-artifacts/channel.tx -channelID $CHANNEL_NAME> ../bin/configtxgen -profile TwoOrgsChannel -outputAnchorPeersUpdate ./channel-artifacts/Org1MSPanchors.tx -channelID $CHANNEL_NAME -asOrg Org1MSP> ../bin/configtxgen -profile TwoOrgsChannel -outputAnchorPeersUpdate ./channel-artifacts/Org2MSPanchors.tx -channelID $CHANNEL_NAME -asOrg Org2MSP

The last two lines are important. Anchor Peers are created so that new participants who join the network can talk to it and find out who the other participants are in the channel.

Enough setup! Let’s start our network!

We’ll use Docker to bring up our network.

> docker-compose -f docker-compose-cli.yaml up -d

You’ll see this:

Let’s also set up our Docker command line interface so we can enter it and execute our transaction commands.

> docker start cli

Now let’s enter our Docker container.

> docker exec -it cli bash

Voila! We’re now in our container:

We’ll now pass in the channel configuration we created earlier so our container can start the channel.

> export CHANNEL_NAME=mychannel> peer channel create -o orderer.example.com:7050 -c $CHANNEL_NAME -f ./channel-artifacts/channel.tx --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

Let’s now add our peers to the channel. We’ll run through the commands first then explain them.

> peer channel join -b mychannel.block>CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp CORE_PEER_ADDRESS=peer0.org2.example.com:7051 CORE_PEER_LOCALMSPID="Org2MSP" CORE_PEER_TLS_ROOTCERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt peer channel join -b mychannel.block> peer channel update -o orderer.example.com:7050 -c $CHANNEL_NAME -f ./channel-artifacts/Org1MSPanchors.tx --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> CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp CORE_PEER_ADDRESS=peer0.org2.example.com:7051 CORE_PEER_LOCALMSPID="Org2MSP" CORE_PEER_TLS_ROOTCERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt peer channel update -o orderer.example.com:7050 -c $CHANNEL_NAME -f ./channel-artifacts/Org2MSPanchors.tx --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

What did we just do?

We joined the first peer of our first organization
We joined the first peer of our second organization and updated the environment variables accordingly to recognize it
We made these two peers the Anchor Peers of each organization so new peers can talk to them and learn about other peers

Install our Smart Contract

Remember, smart contracts are referred to as “chaincode” in Fabric. Here, we will pull some pre-packaged chaincode that Fabric provides and install it to our network.

> peer chaincode install -n mycc -v 1.0 -p github.com/chaincode/chaincode_example02/go/> peer chaincode instantiate -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 -v 1.0 -c '{"Args":["init","a", "100", "b","200"]}' -P "OR ('Org1MSP.peer','Org2MSP.peer')"

You’ll see:

What did we do?

We pulled the chaincode from Github
We instantiated it then set asset balances (you can think of these as token balances for simplicity). We set “a”, or the first peer we created as having 100 tokens, and “b”, the second peer as having 200 tokens.

The fun stuff!

We’ve got our Fabric network up and running with a couple peers with starting token balances! Let’s play around with it and send some tokens around.

Let’s double check and see how many tokens “a” has

> peer chaincode query -C $CHANNEL_NAME -n mycc -c '{"Args":["query","a"]}'

As expected, we see that “a” has 100 tokens. Now let’s send 10 tokens from “a” to “b”

> 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 '{"Args":["invoke","a","b","10"]}'

Now let’s try the same query from before. In theory, “a” should now have 90 tokens.

> peer chaincode query -C $CHANNEL_NAME -n mycc -c '{"Args":["query","a"]}'

Lo and behold!

Congratulations!

You’ve just got an entire Hyperledger Fabric network up and running, installed chaincode on it and created transactions between peers. This is no small feat. You’ve just run through the core steps of starting a blockchain enterprise application.

Our mission in this tutorial was to give you a simple way to run through the Fabric documentation without being encumbered by all the unnecessary minutia they give, particularly when you just want to try Hyperledger for yourself. If you want the full details of all the steps above, feel free to refer to their more detailed documentation.

Next Steps

You already have all the tools you need to run your own Fabric blockchain and add transactions. In the next tutorial, we’ll be taking a deeper dive at chaincode and showing you how to program your own smart contracts on Fabric with Go.

You’ve successfully completed your first step in becoming an enterprise blockchain developer!

Also, be sure to read our previous posts. If you were curious about the basic concepts about the blockchain that supported this tutorial, these articles are the perfect place to start:

Until next time, happy blockchain programming!

To learn more about Coral Health and how we’re using the blockchain to advance personalized medicine research, visit our website and follow us on Twitter!