Hyperledger Fabric Architecture: A Deep Dive

If you are a blockchain enthusiast, you must have heard about Hyperledger fabric architecture by the Linux Foundation. There are two major types of blockchain technology. Public and private, often referred to as permissionless or permissioned blockchain. The Hyperledger Fabric is a permissioned blockchain framework that runs on a modular architecture (plug-and-play).

Hyperledger Fabric leverages container technology to host its smart contact (Chaincode) that contains the application logic. Back in 2015, the Linux Foundation started Hyperledger as an umbrella body of open-source projects and tools. In this article, we will explore the basic components of Hyperledger Fabric architecture. 

IBM leads the Hyperledger Fabric. It is specifically designed to create blockchain applications that are scalable using the flexibility of permissions. Before we discuss the Hyperledger fabric architecture, let’s understand the concept of Hyperledger fabric.

What Is Hypeledger Fabric?

Hyperledger Fabric is a permissioned blockchain system that allows permits unknown identities to be part of the network. The unknown identities have to register through the Membership Service Provider (MSP). The design of Hyperledger Fabric was to develop solutions using a modular architecture. 

It gives users the ability to create channels; therefore, a group of participants can create a separate ledger of transactions. As a permissioned blockchain system, Hyperledger fabric has some advantages over other blockchain systems. Some of such advantages include the following:

It offers data protection and consistency

The use of permissions ensures that members are held accountable, and access rights are controlled effectively.

The transactions are confidential. 

Hyperledger fabric gives businesses the flexibility and security needed to make transactions visible to selected parties. The use of correct encryption keys makes it possible to achieve this.

Does not require cryptocurrency 

Hyperledger fabric does not require mining and other expensive computations to assure transactions. 

It is programmable

With the inbuilt logic in the smart contract you can automate business process across your network. 

The Hyperledger Fabric Model 

Before we delve fully into the Hyperledger fabric architecture, let us consider the key features that made it a customizable enterprise blockchain.  

Assets

They enable users to exchange of monetary value over the Hyperledger fabric network. 

Chaincode

It helps to limit the required levels of trust and verification across the different node types. Also, it helps to optimize Hyperledger network scalability and performance. 

Channels

The channels allow multi-lateral transactions that involve a high degree of privacy and confidentiality.

Ledger Features

It encodes the entire transaction history for each channel on the Hyperledger network. 

Security and membership services

All transactions on the Hyperledger fabric network can be detected and tracked by authorized regulators and auditors. 

Consensus

It allows network starters to select a consensus mechanism that is the best representation of the relationship existing between participants. 

The Hyperledger Fabric Architecture

In a nutshell, blockchain developer makes up the Hyperledger fabric architecture. Firstly, the developer codes the application and smart contract on the network. Then, the developer deploys the app on a server, and the smart contract on a peer using DEPLOY. Every registered user interacts with the app by sending an order (INVOKE) or retrieving information (QUERY) via the smart contract. Also, the smart contract can, in turn, emit an event that the app subcscribes.  

Now, let us go a little deeper into the Hyperledger architecture. The channel allows participating organizations to communicate with one another. You can see the channel as a tunnel that permits an organization to secretly exchange information with other participating organizations joining the same channel. In fact, if an organization is not part of the channel in question, it will not have access to information or transactions associated with that channel. An organization can be part of multiple channels all at once. 

The Hyperledger fabric architecture I made up of the following components:

The Peer 

It is a blockchain node that stores all transactions on a joining channel. A peer can be a part of one or more channels as required. However, each channel on the same peer is stored separately. Hence, an organization can ensure that the sharing of confidential information is only to permitted participants on a channel. 

The Orderer

This is one of the most important components of the Hyperledger fabric consensus mechanism. It ensures the creation of new blocks of ordered transactions, and it is responsible for ordering transactions. The orderer also distributes newly created blocks to all peers on a relevant channel. 

Certificate Authority (CA)

The CA is responsible for managing all user certificates like user enrollment, user registration, user revocation, and so on. But, as a permissioned network, only permitted users can access information (query) or create a new transaction (invoke) on a granted channel. Hyperledger Fabric uses an X.509 standard certificate to represent permissions, roles, and attributes to every use of the channel. Therefore, a user’s ability to query or invoke any transaction on any channel is dependent on the permission, role, or attribute he/she possesses.  

The Client

This is an application that interacts with the Hyerledger fabric blockchain network. Therefore, the Client can interact with the fabric network according to its permissions, roles, and attributes. Also, These attributes are as specified on the certificate derived from the associated organization’s Certificate Authority (CA) server. 

The Chaincode 

This is a concept of smart contracts in the Hyperledger fabric. It can be programmed in three languages which include Golang, Node.s, and Java. Before the deployment of chaincode, the network admin must install the chaincode onto target peers. Then, the admin invokes an orderer to instantiate the chaincode onto a specific channel. As an admin, you can define an endorsement policy while also instantiating the chaincode. An endorsement policy defines which peers need to sanction the authenticity of a transaction result before adding the transaction onto the ledgers of all peers on the channel. 

The peer that is saddled with the responsibility of the endorsement policy is called an endorsing peer. It consists of an already installed chaincode and a local ledger. 

How Hyperledger Fabric Our Works

The fabric issues a transaction with derived certificates. These certificates cannot be linked to the owning participant. Every user or participant on the fabric’s network must register proof of identity to membership services. Also, The registration gives the participant access to the system. On the learned fabric, the content of each transaction is encrypted. Therefore, It ensures that only the intended participants can see the content. 

Every transaction is secure, private, and confidential on the fabric network. Only the consensus of the peers on the network can update the Hyperledger fabric. As a matter of fact, Each transaction executes without a cryptocurrency, and the events are structured as transactions and distributed among the different participants. Every transaction relies on a smart contract system (chaincode) which every participant on the network runs in Docker containers. 

There are three distinct types of peers on the Hyperledger fabric network, and they include:

Committer Peer

This peer commits the transaction and maintains the ledger.

Endorsing Peer

It receives a transaction proposal for endorsement, and either grants or rejects endorsement.

Ordering Peer

This peer is responsible for approving the inclusion of transaction blocks into the ledger and communicates with peer and endorsing peer nodes. 

Conclusion  

The strategic goal of Hyperledger to build business solutions clearly separates it from currency based blockchain systems. With scalability as a huge advantage, Hyperledger fabric allows for the development of almost any type of business network. We hope you enjoyed your read and learnt something new. For your contribution and questions regarding this topic, kindly use the comment box below. 

Also Read, Chainlink: An In-Depth Explanation

Xord is a blockchain development company providing blockchain solutions to your business processes. Connect with us for your projects and free blockchain consultation at https://xord.solutions/contact/

How To Set Up Hyperledger Aries Cloud Agent

Before we go into discussing the hyperledger Aries client agent development, let's explain hyperledger. Hyperledger is an umbrella project of open-source blockchains and related tools hosted by The Linux Foundation. The mission is to create enterprise-based, distributed ledger frameworks that support business transactions. Upon its launch in 2016, Hyperledger already had an organizational and technical governance structure with 30 founding corporate members.

Hyperledger leverages a modular approach to develop blockchain and helps companies build what works for them. Several big companies like J.P. Morgan, IBM, Samsung, and Intel have become part of the Linux Foundation network. Hyperledger comprises several enterprise-based solutions: Fabric, Indy, Aries, etc. However, the interest here is on Hyperledger Aries and how to set up Aries client agents. Concurrently, let's go further to explore Hyperledger Aries Client Agent.

What Is Hyperledger Aries

Hyperledger Aries regards as the 13th project on the hyperledger framework. It is an infrastructure for peer-2-peer (P2P), blockchain-based interaction. Hyperledger Aries facilitates the interoperable interaction between varieties of distributed ledger technologies (DLTs).

As a reusable, shared, interoperable tool kit, Hyperledger Aries will help create, store, and transmit verifiable digital credentials. Before the development of Hyperledger Aries, Hyperledger already had the Hyperledger Indy. Hyperledger Indy is an identity project that underpins the Sovrin Network. However, Indy emphasizes the blockchain or backend side. Meanwhile, the communication between organizations and individuals and how individuals manage their wallets will be handled by Hyperledger Aries.You must understand that Aries is neither a blockchain nor an application. According to Hyperledger, it provides the infrastructure to create applications. There will be many identity networks, and these networks need to be interoperable. Aries infrastructure addresses these concerns.

Hyperledger Aries is related to both Hyperledger Ursa and Indy. While Hyperledger Ursa provides the Aries cryptographic functionality, Indy provides a revolver implementation. Aries employs the cryptographic support from Ursa to provide both hardware security modules support and secure secret management. Hyperledger Aries to change the client layers found in Indy for facilitating interoperability with other identity projects. Indy incubates protocol work between identity owners for peer to peer transactions within the system.

The Goal Of Hyperledger Aries

Aries intends to help solve two major issues which include:

The Components Of Hyperledger Aries

Aries comprises of the following:

At the onset, the generic interface of Aries supports the Hyperledger Indy resolver. Meanwhile, the interface is flexible enough that anyone can build a pluggable method with DID method resolvers like Ethereum and Hyperledger Fabric. Developers can also utilize any other DID method resolver of their choice. Resolvers allow the resolution of transactions and data on other ledgers.

The Aries Hyperledger will also provide the functionality and features not within the scope of Hyperledger Indy or Hyperledger Ursa before it can be thoroughly planned and supported. These capabilities ensure that the community can build a core message family that facilitates interoperable interactions that use a wide range of cases involving blockchain-based identity.

Hyperledger Aries Agents and Controller

First, both agents and controllers are subsets of each other. While the controller houses the business logic, the agents execute the business logic at the command of the controller. By implication, the codes are written on the controller and the agent at each stage performs the logic therein.

Setting Up Your Hyperledger Aries Cloud Agent

Aries cloud agent comprises of two main parts; the agent and controller. The Aries cloud agent is responsible for the core Aries functionalities like interacting with other agents, managing secure storage, receiving direction from the controller, and sending event notification. The controller is responsible for the provision of logic that defines the behavior of a particular agent. Its business logic determines how to respond to events in the agent and trigger the agent to initiate events.


Controllers can be in the form of a web or native user interface that individual or coded business solutions. Between the agent and the controller is a simple interface. The agent sends event notifications to the controller while the controller sends administrator messages to the agent. However, the controller registers a webhook with the agent, and the event notifications are HTTP callbacks. The agent exposes a REST API to the controller for every administrative message you have configured it to handle. Then, the controller responds to events through the administrative message set by the DIDcomm protocol in support of the agents. An Aries cloud agent has an OpenAPI user interface that developers use to explore the specific agent's API. Therefore, the agent is simply a configured dependency in an Aries cloud agent deployment.

As an Aries developer, you have to pay attention to building controllers (business logic) and some agent's custom plugins. However, some small groups of Aries cloud agent developers will focus on adding and maintaining the agent's dependency.

Aries Cloud Agents Are Configured With The Following Sub-Components

Transport plugins

These are pluggable transport-based message sender/receiver modules that interact with other agents. All messages outside the plugins are transport-agnostic JSON structures, and the current modules are HTTP and WebSockets. With time, we might include ZMQ, SMTP, etc.

Conductor

The conductor receives all inbound messages and sends corresponding outbound messages to the transport plugins. After all internal processing, this conductor will pass all inbound messages and receive all outbound messages from the Dispatcher. It is the job of the conductor to handle all generic decorators in messages. These generic decorators include but are not limited to verifying and generating signatures on message data elements, internationalization, etc.

The Dispatcher

It handles the distribution of messages to the DIDcomm protocol message handlers as well as the responses received. The Dispatcher sends the thread state to the conductor that should be persistent and the message data to be sent to the Aries cloud agent.

Ledger Interface Plugin

In the current Hyperledger Aries cloud agent implementation, the Indy SDK offers an interface an Indy-based public ledger for verifiable credential protocols. There is the possibility of moving implementations into the DIDcomm protocol modules.

Handler API

It provides an abstract interface to different handlers needed by the protocols and core Aries cloud agent components. It enables these components to access the secure storage, other storage, the ledger, etc.

Conclusion

The Hyperledger Aries cloud agent offers a scalable and searchable storage layer capable of storing data necessary for identity maintenance. Some examples include health records, tax records, pictures, etc.

Also read our article on Blockchain Scalability: Limitations and Solutions.

Xord is a Blockchain development company providing Blockchain solutions to your business processes. Connect with us for your projects and free Blockchain consultation at https://xord.solutions/contact/

Hyperledger Indy [Part I] - Layer of Trust

In this series of articles, we will be discussing what Hyperledger Indy is, what are its main components and architecture, and how to deploy your own agent. So fasten your seat belts because we are about to begin our journey. 

Introduction:

As we know that in the current era, we have two ways to prove our identity over the internet. One way is User ID/Email and password, another way is Single Sign On (SSO). Big organizations such as Facebook or Google maintain our identity and we use the provided APIs in our platform to receive the proof of the user's identity. 

This model leads to data breaches and vulnerabilities and correlations. We no longer own our data and data breaches can expose our sensitive information. Other than that, one more problem that we face is verifying the issued credentials. 

Therefore, in this article, we will discuss the Paper Credential Model and how the Verifiable Credential Model solves many problems regarding centralized identifiers and also what enables the layer of trust over the internet. 

Paper Credential Model:

Before explaining the Paper Credential Model, first, let’s understand what actually a credential is.

A credential is basically an attested qualification issued to a person or entity by an organization that is competent. Examples of credentials are your national identity card, driver’s license, degree, or any kind of certificate. 

Hyperledger Indy - Paper Credential Model

Consider a scenario in which you have to prove that you are eligible to drive. The entity (holder) holds the credential which is the driver's license. An authorized organization (issuer) issues this credential. The holder presents the proof to the organization (verifier), which then verifies it. That’s the Paper Credential Model.

Hyperledger Indy - Paper Credential Model

Ideally Paper Credential Model proves:

Disadvantages of the model:

One can easily forge or alter the documents, certificates, or any other kind of credential. In the modern world with modern technology, it's really easy for the person to even create fake credentials. And the verification process totally depends on the skills of the verifying organization. 

Verifiable Credential Model:

The Verifiable Credential Model works in the same way as the Paper Credential Model which means:

Before moving on, let’s understand one more term “Claim”. Credentials are a set of claims. Your driver's license is a credential but your name and other information are individual claims. 

Verifiable credentials are not as simple as paper credentials that anyone can use. They are cryptographically encrypted documents. Calculations and algorithms run over these documents to verify these four attributes.

Verifiable credentials are stored in verifiable data registry (Blockchain). When a verifier asks for proof from the issuer he uses the information from the registry and performs cryptographic calculations to verify the four attributes. This cryptographic calculation and storing of the document make it hard to forge.

Trust layer over the Internet:

As we have discussed Paper Credential Model and how the Verifiable Credential Model is more secure, VCM is being enabled by some key concepts which enable this trust layer over the internet. So let’s discuss them.  

Self Sovereign Identity:

The literal meaning of SSI is an identity that you control and own. There is no central organization that owns or controls your identity. In order to understand SSI more, let’s look at these principles of SSI:

Decentralized Identifiers (DIDs):

Decentralized Identifiers are the enabler and important components of verifiable credentials. The owners themselves create DIDs independent of any central authority. A DID looks like the following as per DID specification. It is similar to an HTTP address but the usage is different. 

Hyperledger Indy - DID

DID doc is the document that is linked to this specific pattern string. It contains the public key whose private key is owned by the owner, also a service endpoint through which we can communicate with the holder. A DID is like a URL, you can resolve your DID doc by using the DID resolver.

Following are some benefits of a DID:

Zero-Knowledge Proof and Selective Disclosure:

Zero-Knowledge Proof means to prove the claim without revealing the DID or any correlating information. In a ZKP claim, the DID of the holder is not revealed. Only the DID of the issuer is revealed. 

As we have mentioned above that credentials are a set of claims. It means that your driver’s license is a credential and your first name, last name, etc are individual claims. Now in today’s world when you are asked to present a claim to prove that you are above 18. Your other information is also disclosed including name and other relevant information in your credential. 

But selective disclosure enables the user to disclose only relevant information in the presentation of claims. Selective disclosure and ZKP are both used together to ensure security and also the confidentiality of the data. The reason for this is that in SSI, data is owned by the user and the user decides how much information they want to share. 

Agents and Wallets:

In the article, we have talked about terms like verifiable credentials, DIDs, public and private keys, etc. But where do they reside? How to manage them? What is the channel through which the DIDs communicate and present claims? Agents store them.

Agents and wallets are interchangeable terms. They have secure storage to manage DIDs, public and private keys, and verifiable credentials. 

There are different types of agents. The most common one is “Mobile Agent”. For simple understanding, agents are software that is used to manage DIDs, wallet keys, and verifiable credentials. But agents are used for other purposes too. We won’t be diving deep into the technical details in this article.

Conclusion:

In this article, we have talked about the building components which provide the layer of trust over the internet. We have discussed two credential models. Also, we learned about SSI, DID, verifiable credential, and many other things that help to implement the Verifiable Credential Model and other things. We haven’t taken a deep dive technically into things yet but in the next article, we will take the leap of faith. Just to give you a sneak peek, we will discuss the architecture of agents, type of agents, and how Hyperledger Indy enables all of this with other Hyperledger tools. 

Also read our series of articles on Setting up Hyperledger Fabric Network.

Xord is here to help you with your Blockchain projects. Connect with us at https://xord.solutions/contact/

Guide to setting up your first Hyperledger Fabric network (Part 2)

Overview

This part serves a next step after completing part 1 of the guide. In part 1, we discussed the different components that are needed to bootstrap a simple network. We formed one organization, created a channel, and joined that organization to that channel.

In this part, we are going to write a chaincode (smart contract), install and instantiate it, and interact with it. We are going to use the repository that we developed in the previous guide. The repository contains both the network and chaincode as well as useful scripts to automate crucial tasks.

What is chaincode?

Chaincode (smart contract) is a piece of code that is used to provide access to the state of the ledger in a channel. Chaincode is the only way to gain access to the ledger and the ledger cannot be accessed outside of that chaincode. Chaincode can also be used to implement access control permissions as well as complex business logic while updating or reading the data in the ledger.

Prerequisites to writing chaincode

We are going to use Typescript and the fabric-node-chaincode-utils to write chaincode.

npm install typescript -g
mkdir chaincode/node
cd chaincode/node
tsc --init
https://gist.github.com/sami-abdul/8aff9b5f34991860ecc1e190cd943d6e#file-package-json
https://gist.github.com/sami-abdul/429d3d459f3c9171c83406dcaa4ec8ba#file-tsconfig-json
https://gist.github.com/sami-abdul/9dd96a588150234d478ce086b34e9828#file-yarn-lock
npm install

Writing chaincode

https://gist.github.com/sami-abdul/89bcfd5eac4e40649903316268e228e6#file-chaincode-ts
https://gist.github.com/sami-abdul/89bcfd5eac4e40649903316268e228e6#file-index-ts

If you have experience writing smart contracts using Solidity in Ethereum or other public blockchain, you might notice similarities. We have a chaincode class named FirstChaincode which has two functions that are available to be executed from outside the ledger. initLedger function adds car entries into the ledger. The second function queryAllCars returns all the car objects that have been initialized.

We use the chaincode utils developed by the TheLedger. You will find the chaincode Node.js SDK to be quite different if you look at the official chaincode samples developed by Hyperledger Fabric. These utilities are intended to make writing chaincode easier.

We are going to start the network that we built in the previous article, create and join channels, install and instantiate the chaincode, and finally call functions on the chaincode.

Building the network

Go to the network directory and run the following commands.

Starting the network

This command will start all the docker containers.

docker-compose -f docker-compose.yml up -d

Creating and joining the channel

A new channel mychannel is created and Org1 is joined to that channel.

docker exec -e "CORE_PEER_LOCALMSPID=Org1MSP" -e "CORE_PEER_MSPCONFIGPATH=/etc/hyperledger/msp/users/Admin@org1.example.com/msp" peer0.org1.example.com peer channel create -o orderer.example.com:7050 -c mychannel -f /etc/hyperledger/configtx/channel.txdocker exec -e "CORE_PEER_LOCALMSPID=Org1MSP" -e "CORE_PEER_MSPCONFIGPATH=/etc/hyperledger/msp/users/Admin@org1.example.com/msp" peer0.org1.example.com peer channel join -b mychannel.block

Installing the chaincode

There are three steps to installing chaincode.

Go to the chaincode/node directory.

Building

The following commands will install all the dependencies and make a new build out of source code to be installed on peers.

yarn
yarn run clean
yarn run build

Installing

This command will install the chaincode on the peer.

docker exec -e "CORE_PEER_LOCALMSPID=Org1MSP" -e "CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp" cli peer chaincode install -n "firstchaincode" -v "1.0" -p "/opt/gopath/src/github.com/firstchaincode/node" -l "node"

Instantiating

This command will instantiate the chaincode on the peer.

docker exec -e "CORE_PEER_LOCALMSPID=Org1MSP" -e "CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp" cli peer chaincode instantiate -o orderer.example.com:7050 -C mychannel -n "firstchaincode" -l "node" -v "1.0" -c '{"function":"init","Args":["'1.0'"]}'

Now, that we have the network deployed and chaincode installed and instantiated. We will interact with the chaincode.

Executing a transaction

This command will make use of the invoke command to execute initLedgerfunction which will populate the ledger with entries.

docker exec -e "CORE_PEER_LOCALMSPID=Org1MSP" -e "CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp" cli peer chaincode invoke -o orderer.example.com:7050 -C mychannel -n "firstchaincode" -c '{"function":"initLedger","Args":[""]}'

You should see the following message.

2019-03-14 08:56:24.608 UTC [chaincodeCmd] chaincodeInvokeOrQuery -> INFO 04f Chaincode invoke successful. result: status:200

Querying the chaincode

The command below will run the queryAllCars function get all the cars that have been put onto the ledger.

docker exec -e "CORE_PEER_LOCALMSPID=Org1MSP" -e "CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp" cli peer chaincode query -o orderer.example.com:7050 -C mychannel -n "firstchaincode" -c '{"function":"queryAllCars","Args":[""]}'

If you see an output like this, your invoke function was successful.

[{"color":"black","docType":"car","id":"1","make":"Honda","model":"Civic"},{"color":"blue","docType":"car","id":"2","make":"Toyota","model":"Prius"},{"color":"red","docType":"car","id":"3","make":"Suzuki","model":"Ciaz"}]

Conclusion

We created a simple chaincode which adds entries in the ledger and queries them. We might get into exploring the Node.js SDK that enables us to build client applications for Hyperledger Fabric network.

If you want to get your hands on the code, you can get it here.

Get in touch

Interested in starting your own blockchain project, but don’t know how? Get in touch at https://xord.solutions/contact

Guide to setting up your first Hyperledger Fabric network (Part 1)

There are two ways to go about building applications on Hyperledger Fabric framework. The first method is to use Composer and the other is work directly on core Fabric and writing chaincode using Golang, Node.js, or Java.

What is Composer and why you should stay away from it?

Hyperledger Composer is a set of tools that makes the whole process of building blockchain application faster and easier. Composer speeds up the development time significantly and provides RESTful APIs for your applications to interact with.

Composer also abstracts away essential development steps that would otherwise prove crucial to understand critical parts of the Fabric framework. While the tool is helpful for rapid prototyping and can prove vital for a non-technical or a beginner to get started, however it does abstract away the most interesting parts of the technology.

Composer is helpful to get started on learning the technology but it you wish to understand the ins and outs of technology, Composer is not the way to go.

Here, we will be building a small network with one ordering service and one organization. We will be creating one channel for that organization and bootstrap one anchor peer in this part.

In the next part, we will then be using Typescript to write chaincode in Node.js environment and install it on the peer to provide access to the ledger.

If you wish to get your hands on the code, you can find the repository here.

Installing the development environment

If you haven’t already set up the development environment for Hyperledger Fabric, I urge you to head to this article I wrote a week ago.

What we will be building

We will be creating a simple network with one ordering service (orderer), one organization with one peer. We will create one channel and then install chaincode on that channel. In real life, one channel with one organization makes no sense but we are building it like this for the sake of simplicity.

If you are not familiar with the terms that I used and want to learn the basic of Fabric, there is no better place than the official documentation.

Let’s get started

We will have following directory structure.

-> first-network
   -> /network
      -- /crypto-config.yaml

Defining orderer and organizations in crypto-config.yaml

We define the orderer and different organizations that we want to be part of the network in a .yaml file. We normally call it crypto-config.yaml. Put the following in the crypto-config.yaml file.

OrdererOrgs:
  - Name: Orderer
    Domain: example.com
    Specs:
      - Hostname: orderer
PeerOrgs:
  - Name: Org1
    Domain: org1.example.com
    Template:
      Count: 1
    Users:
      Count: 1

As we can see, we have defined one orderer and one organization. The domain/ID of the orderer is orderer.example.com and the domain of the peer organization is org1.example.comThe Template Count defines the number of peers that we want to bootstrap as part of the network and Users Count defines the number of users that will belong to that organization when the network is first created.

Defining specifications of the orderer and organizations in configtx.yaml

Create a new file called configtx.yaml inside the network directory. The project structure will now look like this.

-> first-network
   -> /network
      -- /crypto-config.yaml
      -- /configtx.yaml

Paste this in configtx.yaml file.

Organizations:
    - &OrdererOrg
        Name: OrdererOrg
        ID: OrdererMSP
        MSPDir: crypto-config/ordererOrganizations/example.com/msp
    - &Org1
        Name: Org1MSP
        ID: Org1MSP
        MSPDir: crypto-config/peerOrganizations/org1.example.com/msp
        AnchorPeers:
            - Host: peer0.org1.example.com
              Port: 7051

Application: &ApplicationDefaults

    Organizations:

Capabilities:
    Global: &ChannelCapabilities
        V1_1: true

    Orderer: &OrdererCapabilities
        V1_1: true

    Application: &ApplicationCapabilities
        V1_2: true

Orderer: &OrdererDefaults

    OrdererType: solo
    Addresses:
        - orderer.example.com:7050
    BatchTimeout: 2s
    BatchSize:
        MaxMessageCount: 10
        AbsoluteMaxBytes: 99 MB
        PreferredMaxBytes: 512 KB
    Kafka:
        Brokers:
            - 127.0.0.1:9092
    Organizations:

Profiles:
    OneOrgOrdererGenesis:
        Capabilities:
            <<: *ChannelCapabilities
        Orderer:
            <<: *OrdererDefaults
            Organizations:
                - *OrdererOrg
            Capabilities:
                <<: *OrdererCapabilities
        Consortiums:
            SampleConsortium:
                Organizations:
                    - *Org1
    OneOrgChannel:
        Consortium: SampleConsortium
        Application:
            <<: *ApplicationDefaults
            Organizations:
                - *Org1
            Capabilities:
                <<: *ApplicationCapabilities

First we define the MSP IDs of our Orderer and Org1 and also define the paths to the certificates that we will generate later. The path that we define in MSPDir does not exist right now. We will generate the certificates and create the paths later. Here, we also define the domain and port of anchor peers for our organization.

The we configure the capabilities of our network as having the ability to create new channels, etc,. Then we define Orderer specifications as running on solo consensus algorithm and its port.

Finally, we define Profiles that we will be using to refer to these specifications. We define the genesis block for our Orderer as OneOrgOrdererGenesis. The thing that we need to understand here is that there is no global blockchain ledger in the Fabric framework and ledgers are only available at the channel level. And there are two types of channels in a Fabric network, a system channel that is used by different orderers in the network and application channels that are composed of different peers at the application level. OneOrgOrdererGenesis is the profile name of the genesis block of the ledger in the system channel that is used to start the Orderer.

Then we define a consortium called SampleConsortium with Org1 as part of that consortium. And then we have the profile name of our channel called OneOrgChannel with Org1 as a member of that channel.

Create cryptographic materials

Open a terminal window in the /first-network/network directory and execute these commands.

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

The Cryptogen tool that we installed in the previous article will be used to generate crypto materials to be used when signing transactions. This will create a new directory and output two more directories inside it. Our project looks like this now.

-> first-network
   -> /network
      -> /crypto-config
         -> /ordererOrganizations
         -> /peerOrganizations    
      -- /crypto-config.yaml
      -- /configtx.yaml

The new directories will have the crypto material for our orderer and peer organization.

Create genesis block and configuration transactions

Execute the following commands to generate a genesis block, a channel transaction, and an anchor peer configuration transaction. We will then use these configuration transactions to bootstrap a Fabric network.

Configtxgen tool that we installed in the previous article will be used to generate configuration transactions.

mkdir config
configtxgen -profile OneOrgOrdererGenesis -outputBlock ./config/genesis.block

configtxgen uses the profile that we defined in the configtx.yaml file. The tool will look for the profile named OneOrgOrdererGenesis in the configtx.yaml.

configtxgen -profile OneOrgChannel -outputCreateChannelTx ./config/channel.tx -channelID mychannel

The tool will look for a channel profile named OneOrgChannel and output a configuration transaction named channel.tx in the /config directory. We also provided the ID of the channel.

configtxgen -profile OneOrgChannel -outputAnchorPeersUpdate ./config/Org1MSPanchors.tx -channelID mychannel -asOrg Org1MSP

The above command will create anchor peer configuration transaction called Org1MSPanchors.tx in the /config/ directory.

The project structure now looks like this.

-> first-network
   -> /network
      -> /config
         -> /channel.tx
         -> /genesis.block
         -> /Org1MSPanchors.tx      
      -> /crypto-config
         -> /ordererOrganizations
         -> /peerOrganizations    
      -- /crypto-config.yaml
      -- /configtx.yaml

Now that we have the configuration transactions, we will now move on to using these configuration transactions to start Orderer and create a channel.

Configuring docker-compose.yml

We will be using a tool called docker-compose to start multiple docker containers that will work to simulate a Fabric network. To make things simpler, we will not be using multiple machines, we will be taking advantage of the power of docker and docker-compose to simulate multiple machines.

We will not be talking much about docker-compose here. If you want to learn more, visit docker’s documentation.

Create a new file called docker-compose.yml inside /first-network/network directory.

Paste this in docker-compose.yml.

version: '2'

networks:
  basic:

services:
  ca.example.com:
    image: hyperledger/fabric-ca
    environment:
    - FABRIC_CA_HOME=/etc/hyperledger/fabric-ca-server
    - FABRIC_CA_SERVER_CA_NAME=ca.example.com
    - FABRIC_CA_SERVER_CA_CERTFILE=/etc/hyperledger/fabric-ca-server-config/ca.org1.example.com-cert.pem
    - FABRIC_CA_SERVER_CA_KEYFILE=/etc/hyperledger/fabric-ca-server-config/c8934e1a2f95d83d34852d9615f7c92880947bc1a077a9c0ae393fa33e8e6454_sk
    ports:
    - "7054:7054"
    command: sh -c 'fabric-ca-server start -b admin:adminpw -d'
    volumes:
    - ./crypto-config/peerOrganizations/org1.example.com/ca/:/etc/hyperledger/fabric-ca-server-config
    container_name: ca.example.com
    networks:
    - basic

  orderer.example.com:
    container_name: orderer.example.com
    image: hyperledger/fabric-orderer
    environment:
    - ORDERER_GENERAL_LOGLEVEL=debug
    - ORDERER_GENERAL_LISTENADDRESS=0.0.0.0
    - ORDERER_GENERAL_GENESISMETHOD=file
    - ORDERER_GENERAL_GENESISFILE=/etc/hyperledger/configtx/genesis.block
    - ORDERER_GENERAL_LOCALMSPID=OrdererMSP
    - ORDERER_GENERAL_LOCALMSPDIR=/etc/hyperledger/msp/orderer/msp
    working_dir: /opt/gopath/src/github.com/hyperledger/fabric/orderer
    command: orderer
    ports:
    - 7050:7050
    volumes:
    - ./config/:/etc/hyperledger/configtx
    - ./crypto-config/ordererOrganizations/example.com/orderers/orderer.example.com/:/etc/hyperledger/msp/orderer
    - ./crypto-config/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/:/etc/hyperledger/msp/peerOrg1
    networks:
    - basic

  peer0.org1.example.com:
    container_name: peer0.org1.example.com
    image: hyperledger/fabric-peer
    environment:
    - CORE_VM_ENDPOINT=unix:///host/var/run/docker.sock
    - CORE_PEER_ID=peer0.org1.example.com
    - CORE_LOGGING_PEER=debug
    - CORE_CHAINCODE_LOGGING_LEVEL=DEBUG
    - CORE_PEER_LOCALMSPID=Org1MSP
    - CORE_PEER_MSPCONFIGPATH=/etc/hyperledger/msp/peer/
    - CORE_PEER_ADDRESS=peer0.org1.example.com:7051
    # # the following setting starts chaincode containers on the same
    # # bridge network as the peers
    # # https://docs.docker.com/compose/networking/
    - CORE_VM_DOCKER_HOSTCONFIG_NETWORKMODE=${COMPOSE_PROJECT_NAME}_basic
    - CORE_LEDGER_STATE_STATEDATABASE=CouchDB
    - CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=couchdb:5984
    # The CORE_LEDGER_STATE_COUCHDBCONFIG_USERNAME and CORE_LEDGER_STATE_COUCHDBCONFIG_PASSWORD
    # provide the credentials for ledger to connect to CouchDB.  The username and password must
    # match the username and password set for the associated CouchDB.
    - CORE_LEDGER_STATE_COUCHDBCONFIG_USERNAME=
    - CORE_LEDGER_STATE_COUCHDBCONFIG_PASSWORD=
    working_dir: /opt/gopath/src/github.com/hyperledger/fabric
    command: peer node start
    # command: peer node start --peer-chaincodedev=true
    ports:
    - 7051:7051
    - 7053:7053
    volumes:
    - /var/run/:/host/var/run/
    - ./crypto-config/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/msp:/etc/hyperledger/msp/peer
    - ./crypto-config/peerOrganizations/org1.example.com/users:/etc/hyperledger/msp/users
    - ./config:/etc/hyperledger/configtx
    depends_on:
    - orderer.example.com
    - couchdb
    networks:
    - basic

  couchdb:
    container_name: couchdb
    image: hyperledger/fabric-couchdb
    # Populate the COUCHDB_USER and COUCHDB_PASSWORD to set an admin user and password
    # for CouchDB.  This will prevent CouchDB from operating in an "Admin Party" mode.
    environment:
    - COUCHDB_USER=
    - COUCHDB_PASSWORD=
    ports:
    - 5984:5984
    networks:
    - basic

  cli:
    container_name: cli
    image: hyperledger/fabric-tools
    tty: true
    environment:
    - GOPATH=/opt/gopath
    - CORE_VM_ENDPOINT=unix:///host/var/run/docker.sock
    - CORE_LOGGING_LEVEL=DEBUG
    - CORE_PEER_ID=cli
    - CORE_PEER_ADDRESS=peer0.org1.example.com:7051
    - CORE_PEER_LOCALMSPID=Org1MSP
    - CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp
    - CORE_CHAINCODE_KEEPALIVE=10
    working_dir: /opt/gopath/src/github.com/hyperledger/fabric/peer
    command: /bin/bash
    volumes:
    - /var/run/:/host/var/run/
    - ./../chaincode/:/opt/gopath/src/github.com/phr
    - ./crypto-config:/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/
    networks:
    - basic

As you can probably guess, we will be using docker-compose to start five containers namely ca.example.comorderer.example.compeer0.org.example.comcouchdb, and cli.

The orderer container uses the genesis.block that we generated earlier to start the orderer.

Before we start the network, we need to do a very important change in the docker-compose.yml.

Execute this command from the network directory.

ls crypto-config/peerOrganizations/org1.example.com/ca

You will see a file with _sk appended at the end. Copy the name of the file, the secret key of our CA. Go back to docker-compose.yml file and search for the keyword “secret_key_here”. Replace the phrase “secret_key_here” with the name of the file you just copied. We are good to go now.

Starting the network

Run the command to start the network.

docker-compose -f docker-compose.yml up -d ca.example.com orderer.example.com peer0.org1.example.com couchdb

The command will start four containers that will form our network.

You can verify the containers that are running by executing the command.

docker ps

You should see an output like this.

CONTAINER ID        IMAGE                        COMMAND                  CREATED             STATUS              PORTS                                            NAMES
621bbda9f6ac        hyperledger/fabric-peer      "peer node start"        4 seconds ago       Up 3 seconds        0.0.0.0:7051->7051/tcp, 0.0.0.0:7053->7053/tcp   peer0.org1.example.com
1e3f3476f727        hyperledger/fabric-orderer   "orderer"                7 seconds ago       Up 4 seconds        0.0.0.0:7050->7050/tcp                           orderer.example.com
32fcf0d2baa9        hyperledger/fabric-ca        "sh -c 'fabric-ca-se…"   7 seconds ago       Up 4 seconds        0.0.0.0:7054->7054/tcp                           ca.example.com
de9b898e3c09        hyperledger/fabric-couchdb   "tini -- /docker-ent…"   7 seconds ago       Up 4 seconds        4369/tcp, 9100/tcp, 0.0.0.0:5984->5984/tcp       couchdb

If you see a similar output as above, you have successfully started a Hyperledger Fabric network.

Now, we will create a channel and join Org1 to that channel.

Creating and joining channel

docker exec -e "CORE_PEER_LOCALMSPID=Org1MSP" -e "CORE_PEER_MSPCONFIGPATH=/etc/hyperledger/msp/users/Admin@org1.example.com/msp" peer0.org1.example.com peer channel create -o orderer.example.com:7050 -c mychannel -f /etc/hyperledger/configtx/channel.tx

The above command will use channel.tx configuration transaction that we generated earlier to create a new channel.

docker exec -e "CORE_PEER_LOCALMSPID=Org1MSP" -e "CORE_PEER_MSPCONFIGPATH=/etc/hyperledger/msp/users/Admin@org1.example.com/msp" peer0.org1.example.com peer channel join -b mychannel.block

Now, our peer from Org1 is joined to the channel mychannel.

Conclusion

We created the simplest network with one orderer and one organization. In reality, there are multiple orderers and multiple organizations connected to multiple channels. We might get into exploring it later down the line.

If you want to get your hands on the code, you can get it here.

In the next part, we will learn to code chaincode in Node.js and install it on our peer.

UPDATE: The part 2 is available here

Get in touch

Interested in starting your own blockchain project, but don’t know how? Get in touch at https://xord.solutions/contact

The Right Way To Set-up The Hyperledger Fabric Development Environment

Hyperledger Fabric is an exciting technology and is progressing rapidly with the approach of move fast and break things so it can sometimes turn out to be a soul-destroying task to set up the Fabric development environment. Even the official documentation falls short of discussing everything there is in setting up the environment. So, I have written this guide to lay down all the steps you will need to go through to set up the development environment. I will try to keep this guide updated to reflect the latest changes in the Fabric protocol.]

Understanding the basics

I am not going to bore you with explaining what blockchain is and why it matters and explain the use cases of permissioned blockchain technology frameworks like Hyperledger Fabric. If you want to learn the basics of blockchain, Hyperledger Fabric, and its use cases. There is no better way than to study the official documentation here.

Installing the development environment

Installing one wrong package version might generate errors that can take days to debug. These steps have been tested to work well on Ubuntu 18.04 LTS.

Let us get started.

Installing cURL

cURL is a tool that is used to transfer data over the internet.

  1. Execute the command to install cURL.
sudo apt-get install curl

Installing Docker

Docker is a tool designed to make it easier to create, deploy, and run applications in virtual containers. We will use docker to set up simulate different peers in the network. We use docker CLI container to interact with the peers and ordering service, install and upgrade chaincode, and create and join channels.

Uninstall previous docker packages.

If you previously installed docker on your machine. You will need to remove all previous docker packages.

dpkg -l | grep -i docker
sudo apt-get purge -y docker-engine docker docker.io docker-ce  
sudo apt-get autoremove -y --purge docker-engine docker docker.io docker-ce
sudo rm -rf /var/lib/docker sudo rm /etc/apparmor.d/docker sudo groupdel docker sudo rm -rf /var/run/docker.sock

You have now successfully removed Docker from the system completely.

Set up the repository.

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg agent software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

Install docker.

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

Verify that Docker CE is installed correctly.

Run the command to run hello-world docker image.

sudo docker run hello-world

Post installation steps for docker.

You need to eliminate the requirement of using sudo while working with docker

sudo groupadd docker
sudo usermod -aG docker $USER
docker run hello-world

Installing docker-compose

Docker Compose is a tool for running multi-container Docker applications. You need to define all the containers that your application depends on in a .yaml file. Then, with one single command, all the service are started and your application starts running.

sudo curl -L "https://github.com/docker/compose/releases/download/1.23.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

Installing Go programming language.

Go language is used to write chaincode business logic for the channels. You can also write chaincode in Node.js and Java. Whichever language you decide to use, you need to set up the $GOPATH.

sudo apt-get install golang-go
nano ~/.profile
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
source ~/.profile

Installing Node.js package manager.

Installing NPM

curl -sL https://deb.nodesource.com/setup_8.x | sudo bash -
sudo apt install nodejs
node -vnpm -v

Post installation steps for NPM.

You need to set a new prefix for npm to eliminate the need of using sudo while installing packages.

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
nano ~/.profile
export PATH=~/.npm-global/bin:$PATH
source ~/.profile

Installing Hyperledger Fabric packages.

The documentation of Hyperledger Fabric provides a script that will download and install samples and binaries to your system. These sample applications installed are useful to learn more about the capabilities and operations of Hyperledger Fabric.

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

This will install 1.4 version of Hyperledger Fabric binaries.

The command above downloads and executes a bash script that will download and extract all of the platform-specific binaries you will need to set up your network.

It also retrieves some executable binaries that are needed in development and places them in the bin sub-directory of the current working directory.

nano ~/.profile
export PATH=~/fabric-samples/bin:$PATH
source ~/.profile

Run the sample network

cd fabric-samples/first-network
./byfn.sh up

The above command will bootstrap a sample network with fabcar chaincode installed. You can head to here to learn more about the network that we have just started.

Conclusion

After a year of development on Hyperledger Fabric framework, I have realized the importance of getting small things right when setting up the environment. Many errors that you might face during development might well be due to the mistakes in setting up the environment.

I hope this guide will help beginners starting to learn this new technology. Please feel free to point out mistakes in this guide.

Get in touch

Interested in starting your own blockchain project, but don’t know how? Get in touch at https://xord.solutions/contact