A Quick Overview of Hyperledger Fabric

Introduction

Not long ago I prepared a one-hour crash course for my team about Hyperledger Fabric. Here I am sharing what I have covered in this course. I hope this provides the first glance about Fabric before you further explore how interesting and complex this enterprise blockchain framework is.

The topic and flow of my exploration will be

1. Fabric network: the infrastructure
2. Chaincode
3. Deployment of chaincode on a Fabric network
4. Client application
5. Overall flow: from invoking a chaincode function to ledger being updated

Fabric Network

Unlike any public permissionless blockchains, in which a Mainnet is always up and running, Fabric as permissioned blockchain framework requires the buildup of a network where the business logic (smart contract) can be deployed. Here in this part we break a network down into components and some important concepts of Fabric.

Organizations

Fabric is always positioned in use cases for a consortium, that is, a group of business entities. In Fabric, organizations are referring to the consortium members. In many cases we can roughly consider organizations as companies. They can be partners, or even competitors to one another. As seen later, every network component and each user must belong to one organization in a fabric network. This is implemented through digital certificates. In general, each organization is managing its own certificate authority (CA), and responsible for certificate issuance and revocation within the organization.

Network Components

To make a fabric network running, we can easily identify two types of network components: orderer and peer. Among many functions, orderers are responsible for block creation. Peers, each of which keeps a ledger, commit the block received from orderers and update its own ledger. We will immediately cover the ledger in details, while the block creation will be shown in the final session.

Certificate authority (CA) is another component in an organization, and its role is to issue certificates to network components and users for its own organization. It does not participate in the majority of fabric activities (querying or invoking chaincode functions). It is needed when a new component or user is added (new certificate) and when a certificate is revoked. We do not cover CA in this article.

Some Samples of Fabric Network Setup

Fabric supports a variety of network setup in order to meet the business needs.

We first see a typical network setup, in which one orderer organization keeps some orderers, and two peer organizations keep some peers. This setup is good for consortium when a governing organization is needed.

This setup can be expanded with more organizations when needed. The addition of an organization into an existing network is no easy task though.

In case if no such governing organization exists, or the consortium prefers a more decentralized approach, orderers can also be provided and owned by each organization. Here is an example of such a setup.

Note: Orderers runs as a raft-based cluster, no matter whether they are in one organization or decentralized in several organizations.

Finally, fabric can also be used and deployed in one organization rather than a consortium. However it is always being questioned whether a blockchain is needed in this case.

The key point is that the same fabric behaviour and operation applies no matter how a fabric network setup is . Building channels and managing chaincode in these setups are largely the same.

Ledger

Each peer keeps and manages its own ledger. Inside the ledger there are two parts: blockchain and worldstate. The blockchain is a chain of blocks. Each block is a collection of transactions, and is created by an orderer. The worldstate is to keep the latest state of everything being stored in the ledger, stored as key/value pair. The state is updated once a block is committed to the ledger.

Inside a peer, both blockchain and worldstate are implemented in a database. By default it is a LevelDB running in a peer. Optionally, we can use CouchDB for the worldstate.

Committing a Block into the Ledger

With this, we can take a look at what happens when the peer commits a block to the ledger.

Assuming that our application is to keep balance of an asset for different participants. At this moment, the worldstate has this recorded: {Alice: 15, Bob: 8}.

A block is generated by an orderer, and received by a peer. Inside the block there is a transaction to update the state such that {Alice: 13, Bob: 10}. Here we first omit why this happened, and will cover this when we see the full picture at the end of this article.

When committing a block, this peer examines the block and its transactions. If everything looks good, the block is appended to the blockchain, and the worldstate is updated according to the transactions. As a result, after the block is committed to the ledger, the state is changed to {Alice: 13, Bob: 10}.

This happens in each peer in all organizations, and is performed by each peer independently.

Channel

Channel is another important concept in Fabric. It provides a mechanism to group relevant organizations in a consortium based on business purposes. A channel can contain one organization, all organizations, and some of them. In general, we use a different channel for a different application.

Ledger is channel specific. Those organizations belonging to a channel will have the ledger for that channel. For example, in this diagram, two channels are built for this fabric network. The blue channel is joined by all the three organizations, while the red channel is only joined by the first two organizations. The ledger for blue channel (blue ledger) can be seen in all the three organizations, while the ledger for red channel (red ledger) only appears in the first two organizations. The last organization sees nothing about the red channel.

We will see very soon that when a chaincode is deployed, we need to specify which channel the chaincode is deployed.

User: Administrators and Clients

Like network components, any users interacting with the fabric network also belong to an organization and identified with certificates. Among them, administrators are responsible for handling fabric network administration and operation, such as joining channels and handling lifecycle chaincode, etc. Other users act as clients, invoking and querying chaincode functions after the chaincode is ready for use.

Flow of Bringing Up a Fabric Network

We finish the network part with a typical flow about building a fabric network.

1. Bring up identity material for each organization, which includes CA, issuance of certificates to each network component and user.
2. When needed, prepare crypto material for TLS communications, for both network components and users.
3. Prepare channel artifacts, including genesis block and configuration update transactions. (Note that there is a major change in V2.3, where the system channel is not needed any more.)
4. Bring up network components (orderers and peers).
5. Use material created in step 3 to create channel genesis block, and join peers of organization to that channel.

With this, we have a fabric network running, and we can work on the chaincode portion.

Chaincode

Overview

One of the important features on blockchain frameworks is the programmability, always known as the smart contract capability. In Fabric, it is called chaincode. In general chaincode contains the business logic to achieve our business purposes.

Business logic contains data manipulation (computation). Data always comes from the external world (as input arguments) or from the current state kept in the ledger. Certain access control and restriction can be applied upon the data. The result is either returned to the chaincode requestor or stored in the ledger. As we can see immediately, this can be done by coding appropriate functions in a chaincode.

Structure and Language

Like other smart contracts, in chaincode we mainly define two parts. Data structures are the schema or structure of data (state) stored in the ledger, and functions are the actions which can be invoked after a chaincode is deployed.

Majority of coding effort is spent on designing the appropriate and yet a minimal set of functions to achieve the business purposes. The business logic mentioned above is coded in the functions.

As the implementation of chaincode is largely tied into the way the fabric software is being developed, the chaincode has a fixed template or boilerplate. Without writing from scratch, we always begin with the template and then insert our business logic. Recently contract API (link) was introduced to provide a high level coding API, making coding chaincode much easier.

In terms of the coding language, Fabric first supports Golang as the chaincode language, and later NodeJS and Java are added.

Pseudo Code of a Sample Chaincode

To show how a chaincode works, here we use some pseudo codes. This example is to implement an application keeping account balance of an asset (a token, or a deposit). As mentioned above, business logic is largely implemented in the functions. Here I just show two functions: query and transfer.

The function query is used to check the balance of a given account. The logic is quite simple: it obtains the account as an input argument, retrieves state in the ledger, and the result is returned. No state is updated.

The function transfer of assets between accounts. The logic is more complex now. First we obtain from input arguments the sender, the recipient and the amount of assets to be transferred. Some restriction applies such as the amount cannot be negative. Then the balances (current state) of both sender and recipient are retrieved from the ledger. After an accurate computation, the result is then written back in the ledger.

Note that there is no fabric network specific information inside the chaincode. In theory this chaincode can be deployed in any types of the fabric networks mentioned in previous sessions.

Now we have the chaincode developed. It is ready for deployment to a fabric network. The chaincode is not usable or accessible until it is deployed in a channel. Once deployed, clients can use the chaincode by invoking and querying the chaincode functions. We see both the chaincode deployment and client application in the next two sessions.

Chaincode Deployment

Chaincode is not usable unless it is deployed in the channel. In Fabric, it is the lifecycle chaincode responsible for chaincode deployment. Introduced since v2.0, lifecycle chaincode involves several steps when deploying a chaincode in the channel.

1. package chaincode
2. install chaincode to peers
3. approve chaincode definition (chaincode and its deployment policy) by participating organizations
4. commit chaincode definition to channel

Lifecycle chaincode requires explicit approval by organizations (step 3). Step 4 can be performed only when lifecycle endorsement policy is met. For example, chaincode cannot be committed until the majority of organizations have approved the chaincode.

Note: Prior to v2.0, chaincode is “instantiated” in the channel by any organization. Lifecycle chaincode in v2.0 grants approval rights to participating organizations. For more information about lifecycle chaincode and how it differs from v1.4, you can refer to this article (link).

Client Application

Once the chaincode is deployed in a channel, clients can use the chaincode, by means of querying or invoking chaincode functions. This is usually implemented as client applications.

In order to let client application use the chaincode functions, certain information is needed

• the access point to this fabric network
• the name of channel
• the name of chaincode
• the chaincode function name and the arguments required in this function

In Fabric, only authorized clients who can use chaincode functions. Credentials are included in client applications. A client signs and submits proposals and transactions to the network with its own credential, and the signatures are well recorded in the blockchain. This is for traceability, which means we can always know who has done what, and for non-repudiation, which means the client cannot deny its activities.

Client applications interact with the fabric network (and the chaincode) through Fabric SDK. As of today in V2.3, Fabric officially releases NodeJS, Java and Go, where Python is available for downloading and testing (link).

In a more typical implementation, and for integration into existing systems, the client application is always implemented as an API server, exposing standard API to the external world for using the chaincode. Fabric sees this API server as a client application.

Note: You can find a sample setup of API server on top of a fabric deployment here.

A Complete Flow: from invoking chaincode function to committing block in ledger

With all the parts above, we can now paint the final picture. Here we use a sample application to illustrate the whole flow, from a client invoking a chaincode function to the ledger being updated in the network.

Here we have a fabric network: one orderer organization of three orderers, running a raft-based cluster, and two peer organizations, each of which has two peers. A channel is created and joined by both organizations (and all their peers). The chaincode is designed in order to keep a balance of an asset for different owners.

We will use the same transfer function in our pseudo code above. Assuming the current state we only have two entries, say {Alice: 15, Bob: 8}. And a client invokes transfer(Alice, Bob, 2), simulating a case that Alice has given 2 of this asset to Bob.

Here is how things work.

1. Client Application sends proposal to selected peer(s) for this function, requesting answers upon invoking a chaincode function transfer(alice, bob, 2).

The selection of peers depends on endorsement policy. In this case, the client application selects a peer from each organization.

2. Upon requests, those selected peers execute the chaincode function by themselves, and return proposal responses. Inside the proposal response, it contains the simulated result after the function is executed. In this example, it contains (alice: 13, bob: 10).

Note that in this stage, there is NO change in the ledger yet.

3. Upon receiving proposal responses, Client Application ensures that the results received from different peers are identical, and from organizations satisfies the endorsement policy. If anything does not meet the requirement, Client Application would not proceed.

4. Assuming everything is correct, Client Application then constructs a transaction, including the proposal and simulated result (received from proposal responses) and the signatures who made this simulation (endorsement). This transaction is sent to one of the orderers.

Each of these orderers can process this, as they are running as a raft-based cluster.

5. The Orderer checks again if transaction is valid (with proper signatures) and endorsement policy is satisfied. Then the Orderer places this transaction (alongside with other transactions for this channel) in a newly generated block.

6. The Orderer then sends this block to ALL peers participating in this channel (not just those performing simulation).

7. Upon receiving a new block, each peer commits the block individually. That is, each peer validates the block and transactions and updates the ledger.

Note: during the flow we see a term endorsement. A client application selects peers from one or several organizations to compute the result. Endorsement policy governs how many results to be received before the client application proceeds. In our example, the default endorsement policy is majority, which means 2 out of 2 organizations are needed (equivalent to all in two-org situation). According to the business needs, we can define endorsement from one, majority or even all organizations.

Why do we need computation from other organizations? This is a means of guarantee that states kept in different organizations are identical. It is also a proof that a peer of an organization has participated in this computation. The endorsing peers return the result with their own signatures.

Summary

This article provided a full picture of Hyperledger Fabric, an enterprise blockchain framework that we can build a variety of blockchain applications. There are still certain parts and details not covered in this article, but I hope this serves as a source that you can set sail on this platform.