Understanding First Network Example in Hyperledger Fabric (Part 1)

This is a practical guide for Hyperledger Fabric, currently the most popular permissioned blockchain framework in business world.

Hyperledger Fabric comes with a lot of examples, and among them, the First Network is always the one we begin with (Building Your First Network). The official documentation is very detailed in explaining the First Network. However it presents me certain challenges when I follow the steps.

Therefore I am writing this article as a companion guide to the official documentation. I think it will be helpful if we have first got an overall picture on how the First Network looks like, and then explore step-by-step how things work and what happens behind once we have done something.

The article is divided into two parts. In this part, we first take a look on how First Network looks like, the preparation and go through the byfn.sh script. In the second part, we will repeat what happens in byfn.sh by doing it step-by-step with command line. I have put quite a lot screen shot to show some steps that help us understand what’s happening behind.

Hope you find this very useful. Let’s begin our journey to First Network.

(You can find the illustration of First Network example here.)

First Network

First Network Setup

We first take a look on how the First Network looks like.

First Network Setup (showing organizations)

The namespace in the First Network is example.com. From which there are three organizations and their namespace.

• (Organization) Orderer, example.com
• Organization 1 (Org1), org1.example.com
• Organization 2 (Org2), org2.example.com

At the node level, there is one node in Orderer. In Org1 and Org2, there are two peers in each organization. The two peers are labeled as peer0 and peer1. Therefore in the First Network there are totally five nodes.

• order.example.com
• peer0.org1.example.com
• peer1.org1.example.com
• peer0.org2.example.com
• peer1.org2.example.com

Peer0 in Org1 and Org2 are designated as the Anchor Peer.

First Network Deployed in Local Host

These components inside First Network, when deployed in a local host, are implemented as containers. The docker images are pre-built by Hyperledger Fabric. Each node mentioned above is a running container. Here we first have five containers running in the local host. Usually the setup is built through docker compose with a proper docker-compose YAML file. There are more containers running when we start working on the chain code.

We will keep tracking the container using docker commands and we see more containers running later.

Preparation of First Network Setup

Docker Runtime and Docker Composer

First Network is the network of nodes running as containers in Docker runtime environment. Docker Compose to bring up containers.

Use instruction here for installing Docker in your local host, and here for Docker Compose.

Here I have both ready in my localhost.

Go Language

Hyperledger Fabric uses Go programming language, and proper environment variable GOPATH is needed. Here is the rc file and command to include the variable.

Fabric Samples, Tools and Docker Images

We can first get the repo on both the fabric samples and the binary of Hyperledger Fabric. We can access this through short url and execute this shell script.

$ curl -sSL http://bit.ly/2ysbOFE | bash -s 1.2.0

After this command completes there are several things done.

• clone the fabric samples (kept in fabric-samples)
• download the binary tools in Hyperledger Fabric (stored inside fabric-sample/bin)
• download the docker images of Hyperledger Fabric

here are the directory structure and tools

and the docker images (it may take quite a while for the first time download)

Begin with Predefined Script: ./byfn.sh

Hyperledger Fabric comes with a script byfn.sh (build your first network).

We will use three options available in byfn.sh in this demo. They are

• generate: generate the required certificates and genesis block (channel artifacts)
• up: bring up First Network, and execute the First Network chain code
• down: tear down First Network

Here is the original directory structure when we first clone the repository. Note that there is nothing in channel-artifacts directory.

./byfn.sh generate

Run ./byfn.sh generate to create the required components

$ ./byfn.sh generate

Accept all default answers in any questions.

From the response we see several things generated after generate command.

1. Generating certificates using cryptogen tool
2. Generating Orderer Genesis block
3. Generating channel configuration transaction 'channel.tx'
4. Generating anchor peer update for Org1MSP and Org2MSP

A new directory crypto-config is created. Inside this folder, certificates of all organizations are generated and stored. You can browse the directory and get some ideas what are created about certificates.

And inside channel-artifacts directory, we see items 2–4 generated: the genesis block, the channel configuration and anchor peer for each organization.

./byfn.sh up

Before bringing up the network, let’s first take a look on containers running in the local host. We should see nothing here. No containers are running yet.

$ docker ps

Run ./byfn.sh up to create the required components

$ ./byfn.sh up

Accept all default answers in any questions.

From the log we roughly group what’s happening into two stages.

Infrastructure Setup

1. Bring up all containers, the five nodes plus a CLI container. Total six containers.
2. Create channel mychannel based on the channel.tx artifact.
3. Join all the peers (total four in two organizations) to mychannel.
4. Update the anchor peer on peer0 in both organizations.

After this, the containers are up and running with proper setup on First Network. Currently we have total six containers running in local host.

Interaction with chaincode on First Network

1. Install chaincode to anchor peer of both organizations (peer0.org1, peer0.org2)
2. Instantiate chaincode with initial values (a: 100, b: 200, endorsement policy requires both org1 and org2 approval) from peer0.org2.
3. Query the value a from peer0.org1. We will get initial value set when chaincode is instantiated (result: 100)
4. Invoke a transaction (move 10 from a to b).
5. Install the chain code on peer1.org2, which does not have the chaincode yet.
6. Query the value a again from peer1.org2, and now the result reflects the invocation of transaction in step 8 (result: 90).

Get confused with the peer node? Don’t worry, as we will do it through command line the exact steps in second part of article and make observation what’s happening behind. Here, we just take a look on the containers running in local host.

The five containers (one orderer and four peers) are the First Network setup. The container CLI is the tool to interact with the First Network, and we will work on this CLI quite a lot in the next section. These six containers are created in step 1 above.

There are also three containers running chain code. This reflects the steps of instantiation and query in step 2, 3 and 6 above.

So there are three more containers, which somehow link to the peer nodes.

./byfn.sh down

Run ./byfn.sh down to tear down the First Network.

$ ./byfn.sh down

Accept all default answers in any questions.

Note that all the running containers are stopped and then removed. This script includes Org3 which we do not build it when we bring up the network. Simply ignore them.

Checking the running containers and we see nothing there. All the docker images are still there, and image download is not needed provided that we are using the same version.

This is what the script byfn.sh provides us. In second part of this article we are doing the same steps using command line.