Hyperledger Fabric for Beginners
Tags: hyperledgerfabric, blockchain, tutorial, discuss
Published: 2022-03-25 23:41:41

This blog post is intended to help people like me who are new to Hyperledger Fabric but don't have a good tutorial article to introduce them to Hyperledger Fabric. This semester I took a course that has a theme about blockchain technology, in which our team decided to use Hyperledger Fabric to build our back-end services. Since the Hyperledger Fabric community is still relatively small, I spent a lot of time reading and learning official documentation and searching for relevant useful materials. This blog will start with an introduction to Hyperledger Fabric and its crucial concepts of elements and finally describe how to write a toy application that can connect and interact with the fabric network.

## Table of Contents

- [Introduction](#introduction)
  * [Crucial Concepts](#crucial-concepts)
      * [Blockchain Network](#blockchain-network)
      * [Identity](#identity)
      * [Peer Nodes](#peer-nodes)
      * [Ledger](#ledger)
      * [Chaincode](#chaincode)
- [Install](#install)
  * [Prerequisites](#prerequisites)
  * [Download Binaries](#download-binaries)
- [Write Your First Application](#write-your-first-application)
  * [Enroll Admin](#enroll-admin)
  * [Register User](#register-user)
  * [Invoke](#invoke)
  * [Query Ledger](#query-ledger)
- [Summary](#summary)
- [References](#references)

## Introduction

Hyperledger Fabric, an open-source project from the Linux Foundation, is the modular blockchain framework and de facto standard for enterprise blockchain platforms. Intended as a foundation for developing enterprise-grade applications and industry solutions, the open, modular architecture uses plug-and-play components to accommodate a wide range of use cases. It can provide the following benefits while you are developing [1]:
  * Permissioned network: Establish decentralized trust in a network of known participants rather than an open network of anonymous participants.
  * Confidential transactions: Expose only the data you want to share to the parties you want to share it with.
  * Pluggable architecture: Tailor the blockchain to industry needs with a pluggable architecture rather than a one-size-fits-all approach.
  * Easy to get started: Program smart contracts in the languages your team works in today, instead of learning custom languages and architectures.

### Crucial Concepts

#### Blockchain Network

A blockchain network is a technology infrastructure that provides ledgers and smart contract (chaincode) services for applications. First, smart contracts are used to generate transactions that are then distributed to each peer node in the network, where they are immutably recorded on their copy of the shared ledger. The user of the application may be an end-user or blockchain network administrator using the client application.

In most cases, multiple organizations form a consortium to form a network, and their permissions are determined by a set of policies that the consortium agreed to when initially configuring the network. In addition, network policies can change over time, depending on the agreement of the organizations in the alliance [3].

#### Identity

As far as I know, every role and element in a fabric network including peer nodes, organizations, and end-user applications requires a legitimate digital identity. To help you understand and use an appropriate analogy when we go to the supermarket to buy something, the payment method usually only accepts Mastercard or Visa at the end of the checkout. And if we want to use a payment method that is not accepted then we can't complete the checkout and buy what we want. So the entire Hyperledger Fabric network is entirely based on digital identity authentication.

For a more detailed introduction and conceptual statements, please refer to the [Hyperledger Fabric official documentation](https://hyperledger-fabric.readthedocs.io/en/release-2.2/identity/identity.html). Here I am just stating my own personal understanding in the hope that it will help you grasp the core ideas behind this [3].

#### Peer Nodes

Let's take a closer look at these peer nodes and how they relate to all of the different components inside of the network. End users communicate with the network using applications that connect to the peer nodes of the same organization. In the below example, the application connects to the peer node and invokes the chaincode, that generates a proposal response which is containing a ledger update. 

When the application receives back, the proposal responds, it can then request the transaction to the orderer, the orderer then collects all of the transactions, put them into blocks, and then shifts the blocks back to the peer nodes. When the peer receives this new block, which is containing all of the transactions, it can then update the ledger using these transactions. 

When this is done and the transaction is persistent on the ledger, the peer then notifies the application with a ledger update event. Now, this is in the case of an invocation of the chaincode when we only want to query the chain code. So we want to retrieve some information from the ledger. Only the first three steps apply. So the application connects to the peer [4].

![End-users communicate with the network](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xgcb1869izr24phrgu19.png)

#### Ledger 

A ledger consists of two parts the world states and the blockchain. They both store facts about objects. First up, there's the world state, a database that holds the current value of the object. This way we can have direct access to the current value of the object. Ledger states are by default expressed as key-value pairs, the world state can change frequently because every transaction for the relative object changes to the current state.

Secondly, there's the blockchain, the blockchain records, all the transactions for the objects that together result in the current world state. Transactions are collected inside blocks that are appended to the blockchain. This way we can understand the history of changes that have resulted in the current world. The blockchain data structure is very different than the world state because one reason it cannot be modified and it is immutable [4].

![Ledger](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/v5srng3hdy3mjwduky9m.png)


#### Chaincode

Next up is chain code, a lot of times chaincode and smart contracts are used interchangeably because in most cases they mean the same. This chaincode is the software that defines the asset. Chaincode also enforces rules for interacting with the asset or any other information that is stored on the distributed ledger. Chaincode functions execute against the ledger current state database and are initiated through a so-called transaction proposal.

Chaincode execution results in a set of key-value pairs that is also called a right set. The right set can be submitted to the network and thereby appended to the ledger [4].

You can get more information about the chaincode via the [official documentation of Hyperledger Fabric](https://hyperledger-fabric.readthedocs.io/en/release-2.2/smartcontract/smartcontract.html).

## Install
### Prerequisites

To actually install, use, and develop with the Hyperledger Fabric, we have to first have all of the prerequisites [2]:
  * [Git](https://hyperledger-fabric.readthedocs.io/en/release-2.2/prereqs.html#install-git)
  * [cURL](https://hyperledger-fabric.readthedocs.io/en/release-2.2/prereqs.html#install-curl)
  * [Docker and Docker Compose](https://hyperledger-fabric.readthedocs.io/en/release-2.2/prereqs.html#docker-and-docker-compose)

You can follow the detailed steps listed on the [official documentation of the Hyperledger Fabric](https://hyperledger-fabric.readthedocs.io/en/release-2.2/prereqs.html) to have those prerequisites installed according to your operating system.

### Download Binaries

To start actually working on the Hyperledger Fabric, we need to download the following:
  * fabric-samples
  * executable binaries
  * docker images

And to download those files, you can use the following command line:
```console
curl -sSL https://bit.ly/2ysbOFE | bash -s -- <fabric_version> <fabric-ca_version>
curl -sSL https://bit.ly/2ysbOFE | bash -s -- 2.2.5 1.5.2
```

After downloading the files, then you are good to go. If you want, you can follow the [tutorials](https://hyperledger-fabric.readthedocs.io/en/release-2.2/test_network.html) on the official website to get familiar with and play around with the fabric test network. We will talk about how to write a simple toy application and connect it with the fabric network in the next section [5].

## Write Your First Application

### Enroll Admin
To write a toy application to interact with the shared ledger, we need to enroll the admin user first. To do that, there are 4 following steps [4]:
  * Load the fabric network configuration
  * Create the CA client to interact with the Certificate Authorities (CA).
  * Create a new file system based wallet for managing identities
  * Enroll the admin user, and import the new identity into the wallet for end users so that they can invoke and query the ledger.

![EnrollAdmin](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/eth784jlbtg0qqj1uusy.png)


### Register User

After we add the admin user, we need to write code to add the end-user, and there are 5 steps to follow. The first two steps are the same as the previous section [4]. 

![First two steps](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/z6gyeip6sibwt99g6qzj.png)

The rest steps are defining objects and importing those identities and involve the following:
  * Create a new wallet
  * Build the admin object for CA
  * Register, enroll and import the identity

![Rest Steps](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/csrpvqjj540wacl6gjgi.png)

### Invoke

Invoking with the Hyperledger Fabric in this example is to add a piece of new transaction information to the ledger and it has the following important steps [4]:
  * Create gateway
  * Create network object
  * Create contract object
  * Invoke (submit a transaction)
  * Disconnect from gateway

![Invoke](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vie53a734osiheu40t7x.png)

### Query Ledger

The only code difference between invoking with the ledger and querying the ledger is just two lines of code that are different. So instead of using `contract.submitTransaction()` function we use the `contract.evaluateTransaction()` function [4].

![Query Ledger](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kv3w3hsuwvaz7a6m899y.png)
 
I have squared out the different lines of code, please pay attention to it.

## Summary

In this blog, I mainly briefly introduced what is Hyperledger Fabric and some very important components and concepts. I took us through the simple walk from prerequisites, installing fabric samples and binary files to writing a toy application and connecting to the fabric network. Although connecting with the fabric network also involves using the Docker image to bring up the network, it would be better to refer to the official document for that part, which has clear steps. Here, I would like to share with you how to write a toy application so that we can start working on it.

## References

[1] What is hyperledger fabric? IBM. (n.d.). Retrieved March 25, 2022, from https://www.ibm.com/topics/hyperledger 
[2] Prerequisites¶. hyperledger. (n.d.). Retrieved March 25, 2022, from https://hyperledger-fabric.readthedocs.io/en/release-2.2/prereqs.html
[3] Key concepts¶. hyperledger. (n.d.). Retrieved March 25, 2022, from https://hyperledger-fabric.readthedocs.io/en/release-2.2/key_concepts.html
[4] Juffermans, R. (n.d.). Hyperledger fabric 2.X: Blockchain Network &amp; Smart Contracts. Udemy. Retrieved March 25, 2022, from https://www.udemy.com/course/hyperledger-fabric-2x/
[5] Install samples, binaries, and Docker images¶. hyperledger. (n.d.). Retrieved March 25, 2022, from https://hyperledger-fabric.readthedocs.io/en/release-2.2/install.html