Sample Solution: Hyperledger Fabric

Introduction

This Sample Solution demonstrates how to use a Hyperledger Fabric platform to solve a data sharing problem on a distributed and decentralized blockchain network in a secure and trustworthy way.

Problem Statement

Blockchain Distributed Ledger Technology (DLT) is a complex technology, both in how it works and how to build applications on it, so having the tools to quickly jump-start a working environment can be a big advantage.

Blockchain DLT is relatively new but holds potential for solving multiple business problems that have no current, viable solution.

Conceivably, every new project that uses DLT could easily spend an outsized portion of its budget on DevOps, including but not limited to:

  • installing the DLT software,
  • creating the network and adding network nodes,
  • opening communication channels, and
  • deploying applications, etc.

This BoosterPack will spare you from all this effort.

Hyperledger Fabric (HLF) is an open source, multi-purpose, enterprise-grade DLT implementation that can serve the needs of any business. It allows users to build a service or product that uses one form of blockchain-based DLT. HLF allows for private, permissioned networks, where new participants of the network are approved and allowed only when existing network participants agree. The data is not shared publicly and is visible only to network participants.

By using the Hyperledger Fabric BoosterPack, a business can quickly leverage Hyperledger Fabric (HLF) and focus on building the chaincode (distributed application logic, also known as smart contracts) and web application on day one. The BoosterPack includes a sample chaincode, web application, and instructions on how to deploy and use them, helping reduce the time to market. The source code of the Sample Solution is open-source and may be modified and used to quickly develop a proof of concept or minimum viable product (MVP) of your own.

The BoosterPack provides the following benefits:

  • seamless HLF installation to CANARIE’s DAIR Cloud
  • simplified installation – all underlying software that’s needed is installed on the target DAIR Cloud server
  • centralized configuration (HLF network configuration files like Docker files, peer configurations)

Next, we will showcase best practices on how to build distributed application logic (chaincode) and how to securely integrate a web application with the HLF network.

Sample Solution Overview Diagram

The diagram below illustrates the structure of the Sample Solution.

The Sample Solution showcases how a private and permissioned DLT can solve issues with performing transactions and sharing real-time data securely among partners on a business network (Clinical Trials), powered by HLF.

The Clinical Trials sample chaincode and web application logic will simulate a consortium of three organizations (a hospital, a pharmaceutical company, and a regulator). The consortium’s main goal is to share live, real-time data on the process of a clinical trial, allowing the participants to see the recorded transactions on the platform.

Solution Overview

The solution allows you to perform the basic functions of working with Hyperledger Fabric (HLF). As a DAIR tenant, you will receive a running HLF network with a sample application you can explore and customize.

The bootstrapped HLF network will have the following topology:

  • Membership Service Provider (MSP) – every organization will be represented by a membership service provider. An MSP allows a business organization to be modelled as a single entity in the Hyperledger Fabric network.
  • Ordering Service – one ordering service for the network, allowing the transactions to be ordered based on the RAFT consensus protocol.
  • Peers – three peers, where each MSPs will operate its own peer. Peers are the core of an HLF network, allowing for transactions to be processed and the data to be written and read by the clients of that network.
  • Chaincode – sample chaincode that will hold the business logic for Clinical Trials.

The Ansible scripts install Docker as a prerequisite, along with some of the tools required to run the Hyperledger Fabric stack. The following applications are installed on the DAIR Cloud instance:

  • Hyperledger Fabric Network Nodes
  • Hyperledger Fabric Certificate Authority
  • Hyperledger Fabric Explorer – allows the users to see the blocks and transactions recorded on the Blockchain DLT
  • Hyperledger Fabric Command Line Interface (CLI) tools – a set of tools necessary to administer the network, once the network has been provisioned
  • Clinical Trials Chaincode deployed to all the Hyperledger Fabric peers
  • Clinical Trials Web Application

Clinical Trials Network Topology

The Sample Solution HLF network is based on three participants (MSPs): “nova”, “genh” and “regulator.” Each of those participants has a dedicated peer on the network and a dedicated web application. The ordering service provider is represented by a separate entity named “orderer.” The network participants also own their own CA server to manage the certificates of the network identities (peers, orderer, administrators and users).

The Sample Solution showcases how a private and permissioned DLT can solve issues with performing transactions and sharing real-time data securely among partners on a business network (Clinical Trials), powered by HLF.

The Clinical Trials sample chaincode and web application logic will simulate a consortium of three organizations (a hospital, a pharmaceutical company, and a regulator). The consortium’s main goal is to share live, real-time data on the process of a clinical trial, allowing the participants to see the recorded transactions on the platform.

Solution Overview

The solution allows you to perform the basic functions of working with Hyperledger Fabric (HLF). As a DAIR tenant, you will receive a running HLF network with a sample application you can explore and customize.

The bootstrapped HLF network will have the following topology:

  • Membership Service Provider (MSP) – every organization will be represented by a membership service provider. An MSP allows a business organization to be modelled as a single entity in the Hyperledger Fabric network.
  • Ordering Service – one ordering service for the network, allowing the transactions to be ordered based on the RAFT consensus protocol.
  • Peers – three peers, where each MSPs will operate its own peer. Peers are the core of an HLF network, allowing for transactions to be processed and the data to be written and read by the clients of that network.
  • Chaincode – sample chaincode that will hold the business logic for Clinical Trials.

The Ansible scripts install Docker as a prerequisite, along with some of the tools required to run the Hyperledger Fabric stack. The following applications are installed on the DAIR Cloud instance:

  • Hyperledger Fabric Network Nodes
  • Hyperledger Fabric Certificate Authority
  • Hyperledger Fabric Explorer – allows the users to see the blocks and transactions recorded on the Blockchain DLT
  • Hyperledger Fabric Command Line Interface (CLI) tools – a set of tools necessary to administer the network, once the network has been provisioned
  • Clinical Trials Chaincode deployed to all the Hyperledger Fabric peers
  • Clinical Trials Web Application

Clinical Trials Network Topology

The Sample Solution HLF network is based on three participants (MSPs): “nova”, “genh” and “regulator.” Each of those participants has a dedicated peer on the network and a dedicated web application. The ordering service provider is represented by a separate entity named “orderer.” The network participants also own their own CA server to manage the certificates of the network identities (peers, orderer, administrators and users).

Clinical Trials Web Application

The Clinical Trials Web Application is based on Vue.js and enables network participants to file a trial case and view its development in the process. The transactional data is recorded on the HLF blockchain and accessed through HLF clinical trial chaincode. The web application uses the Java HLF SDK library to initiate transactions and read the transactional data.

Clinical Trials Chaincode

The chaincode is the operating application logic running on the Hyperledger Fabric peer nodes and controls when transactions get recorded in the blockchain.

The Clinical Trials Chaincode has the following functionality:

  • Record a Trial Case
  • Update a Trial Case status
  • Close a Trial Case by setting the status to ‘closed’

Component Descriptions

The significant components used in the Sample Solution are summarized in the table below:

ComponentSummary
DAIR Cloud PlatformThe DAIR Cloud Platform provides a web-based user interface for participants to access DAIR resources.
Hyperledger Fabric Network  Based on the open-source DLT project Hyperledger Fabric, the network is formed by running the required nodes for the DLT to function.

The network consists of the following nodes:
1. Orderer(s)
2. Peer(s)
Hyperledger Fabric Certificate AuthorityProvides functions such as:
1. registration of identities, or connects to LDAP as the user registry
2. issuance of Enrollment Certificates (ECerts)
3. certificate renewal and revocation
Hyperledger Fabric CA consists of both a server and a client component.
Hyperledger Fabric Command Line Interface ToolsA set of command line commands that allow for management of the Hyperledger Fabric components through a Linux Shell environment.
Automation ScriptsProvides the ability to automate common tasks when dealing with Hyperledger Fabric:
1. create a new Hyperledger Fabric network with Certificate Authority, Ordering Service, Orderers, and Peers
2. deploy chaincode
3. deploy web application
Sample Chaincode / Distributed Application (Clinical Trials)Hold the distributed application logic of the sample application, allowing the system to store and record transactions in Hyperledger Fabric based on the user input as communicated by the Sample Web Application.
Sample Web Application (Clinical Trials Web UI)The sample web application will provide the bridge between the user interface and the Hyperledger Fabric network. It allows end users to record and read transactional data that is stored in the distributed ledger.
GitHub RepositoryGit repository that holds the source code for the shell scripts used in DAIR Cloud, the sample web application, and sample chaincode

How to Deploy and Configure

Browse to cloud.canarie.ca and log in to the Morpheus dashboard with the credentials provided to you by the DAIR team.

Navigate to the top-right corner of your screen where you have your account name, click on the drop-down arrow and select the SERVICE CATALOG option under PERSONA.

Once the new Service Catalog dashboard appears, look for the SENOFI-HYPERLEDGER-FABRIC-STARTER-AWS application tile and click ORDER. If you prefer to have the sample application hosted on Microsoft Azure, click ORDER from the SENOFI-HYPERLEDGER-FABRIC-STARTER-AZURE tile instead.

You will be presented with a configuration form to fill. In the first field, type in a unique instance name for your application and then complete the rest of the form using the drop-down option, to select your appropriate configuration settings. Once you are done, click ORDER NOW to deploy the application.

 

The application deployment will start with creating a new instance and the deployment automation will follow. To access (and view the progress of) your application, you will need to switch back to the STANDARD persona. This time, navigate to the top-right corner of your screen where you have your account name, click on the drop-down arrow and select the STANDARD option under PERSONA.

Once back to the STANDARD dashboard, Navigate to Provisioning > Apps and click on the recently deployed application.

This screen should appear:

The average time to complete the deployment process is around 7-10 minutes. While you wait, navigate to the security group configuration under Infrastructure > Network > Security Groups.

Select the security group you chose for the application deployment and open it. You should see the rules of the security group.

We want to allow connections on HTTP port 80, where the Sample Solution web applications will be accessed. If you do not have that rule in your rules list, add it – the configuration should look like this:

Make sure that the SOURCE field contains IP range 0.0.0.0/0.

Now, let’s go back to the application and wait for the deployment to complete. Navigate to Provisioning > Apps and wait for the status to change to a green arrow  .

Select the name of your application to open its contents in Morpheus and look for the IP address of the instance.

You will find the IP address under the LOCATION column, under the VMS section. Copy the IP address and paste it into your browser. If the deployment is successfully completed, you will see the landing page of the Sample Solution, which gives you all the entry points to the web applications and the Hyperledger Explorer.

You can now view the existing blocks and transactions in the network by clicking the Open button under Hyperledger Explorer. A new window/tab will open. Your login username/password are admin/adminpw.

Note: If you plan to re-use or leave this Sample Solution running in DAIR for more that a week, we urge you to strengthen the password

Once you click the SIGN IN button, you should see the dashboard.

Feel free to explore and look around the explorer. Visit the NETWORK tab to see the nodes on the blockchain network, the BLOCKS and TRANSACTIONS tabs to see what has been recorded already, and the CHAINCODES and CHANNELS tabs to get to know the smart contract name and the channels existing on the network.

Technology Demonstration

This section guides you through a demonstration of a Sample Solution built on Hyperledger Fabric. We will illustrate how to use a decentralized system based on Hyperledger Fabric to build a decentralized application.

To create a new transaction on the network, you can now open the landing page (find the IP address as described above and paste it into your browser’s address bar), and open the General Hospital web application. Use login username/password: user/pass.

Once you have logged in, select RECORD NEW CASE on the top right.

Fill in the details and click RECORD.

Now the trial case record is visible in Hyperledger Explorer as a transaction.

Now, log into the Nova Pharma web application to investigate the trial case. Username and password are user/pass.

Now you can see the trial case in the role of Nova Pharma.

You can launch an investigation and eventually close the trial case.

The Government Regulator can see the trial case record as soon as it is logged by General Hospital. If you sign into the web application of Government Regulator with the “user/pass” credentials, you will be able to see the trial case and its status. Once the trial case has been closed by Nova Pharma, Government Regulator will be able to ACCEPT that trial case, acknowledging it as resolved and closed and setting the trial case status to Regulator Accepted.

Termination

To terminate and remove the application from your DAIR account, go to Provisioning > Apps > <Select your application>. Once the application view is displayed, click the DELETE button in the top right corner and accept the options to remove instances and release EIP.

Note: If you choose to stop and then restart the application instance, you will need to Run Workflow again from the Instances > Actions drop-down menu to restart the web application and services. This is the same workflow automation that was run during original deployment of the application.

Factors to Consider

Alternate Deployment Options

The Sample Solution is designed to deploy and run on a single VM. There are a few important things to consider in respect to the application performance, scalability, and availability.

Performance

Transactions performed on the Sample Solution network are regular HLF transactions that go through a flow of operations performed by the different nodes on the network (client, peer, and orderer). It is important to know that there are computational tasks (e.g., calculating hashcodes) that bring load to the CPU. Adding more CPU power may positively impact the computational tasks and increase the transaction throughput in case of heavy loads.

Scalability

The network can be scaled horizontally by adding additional peers that can process the requests of additional clients (e.g., reading transactional data). Multi-core CPUs can be used to increase the transaction throughput. Detailed sizing of the network is usually an ongoing process as DLT networks are expected to grow/shrink with the time (e.g., as new participants join the network or existing participants leave). For production grade networks, use multiple VMs to bring the network to a proper state to handle increasing transactional volumes. The Sample Solution doesn’t include a scalability concept outside of a single VM.

Availability

The availability of the network depends on the number of nodes and their distribution across different infrastructures (e. g., cloud providers and data centers). Usually, a product-grade HLF network may run on different data centers and cloud providers across the globe in case the participants are international. Regular backups of the peers/orderers and their CouchDB stores (in cases where CouchDB is used), can be performed to restore the peers in case of hardware failures. The Sample Solution doesn’t cover or automate any backup strategy.

Technology Alternatives

HLF is one of several blockchain-based DLT technologies available to build a private and permissioned network. There are also public blockchain networks that focus on tokenization and are entirely public, open, and un-permissioned. However, those public networks are slow to process transactions, provide no real privacy, and lack support of permissioned network models. The latter capabilities are essential for many enterprise-grade applications where privacy and permissioned control of data and transactions is a must.

Public blockchain networks are usually powered by many distributed and decentralized peers. Those peers can be run by anyone and are often commercially hosted in pools (farms) operated worldwide. Some of those networks are dedicated to the sole purpose of recording all transactions that move tokens between accounts/addresses (e.g., the Bitcoin network) on the ledger. Some support more complex transactions powered by smart contracts that allow the developers to record data on the public ledger. Those public networks are suitable for many use cases like asset modeling and trading through non-fungible tokens (NFTs). One of the most used and proven public networks that supports smart contracts is Ethereum.

Most permissioned and private DLT networks are built on several established blockchain technology implementations, like Corda, HLF, Quorum, Hyperledger Sawtooth, etc. They each have their own strengths and weaknesses and have specific use cases. There are also open-source projects supported by communities of individual developers and companies. HLF is one of the most used and popular implementations, as it is open and generic enough to handle and solve problems across industries like supply chain, healthcare, financing, etc.

Security

The provisioned HLF network is accessible through its nodes on different ports that may be exposed outside the VM using a proper security group. Peers and orderers are connected to each other through their internal Docker ports, where the communication channels are TLS encrypted. The network nodes’ PKI artifacts are stored on the local file system of the VM. For storing those artifacts outside the file system, you may wish to use an HSM or any other PKI management system (e.g., Vault).

The provided web applications use a sample user identity management system restricted to a single pre-defined user. The purpose of the solution is to focus on Hyperledger Fabric capabilities consumed by a client, where user management is usually integrated with an identity management system based on specific project needs.

Note: The integration with a PKI management system or web application identity management system is outside the scope of this BoosterPack Sample Solution.

Scaling

HLF networks are powered by ordering service nodes and peer nodes. The network allows the participants to add any number of peers to the network so that high availability and horizontal scalability can be achieved. Peers can be hosted on different cloud providers or regions, so that hybrid cloud deployment and a high level of distribution can be achieved. The ordering service of HLF can also distribute the nodes (orderers) across different infrastructures, where every channel must maintain a manageable number of orderers to maintain a stable RAFT cluster (the RAFT consensus protocol is used in many other projects like Kubernetes). The network nodes are hosted and managed by the participants so that every one of them is responsible to host their peers on an infrastructure that allows a high level of horizontal or vertical scalability.

Availability

HLF nodes can be hosted on different cloud providers or regions. Higher node distribution usually means higher overall network availability. Therefore, each network participant may operate multiple nodes to reduce the risk of downtime for a particular class of transactions. For example, some transactions may require endorsements from a subset of the participants, so that faulty or inaccessible peers do not affect them.

This BoosterPack provides a solution to host the network nodes on a single VM. This is a good option for developing and building proof-of-concept applications. For production-grade networks and applications, it is expected and highly recommended to host the nodes on a variety of infrastructures in different regions, on the same or on multiple cloud providers.

API

Hyperledger Fabric nodes (orderers and peers) and Hyperledger Certificate Authorities provide APIs for management and operations (e.g., health checks, log level management, chaincode deployment/invocation, node-to-node communication, identity registration, and enrolment, etc.). The APIs are Web APIs based on gRPC. In most cases, it is highly recommended to secure the APIs using TLS. The following links provide technical instructions for enabling TLS on different nodes:

Note: In a highly secured and permissioned environment, a mutual TLS protocol can be used to further strengthen the security of communication protocols level by level, enabling only clients with trusted certificates to pass the mutual TLS server check.

Cost

The cost of operating an HLF network depends on the infrastructure chosen to accommodate various non-functional requirements on the network, like availability, performance, security, etc.

Production-grade networks may require several nodes in different geographical locations (or datacenters) to achieve high availability. Hardware Security Modules (HSM) may be used to store Private Key Infrastructure (PKI) artifacts like certificates and private keys.

For the Senofi Hyperledger Fabric network, we are using a single VM with few peers and orderers. The network artifacts are stored on the VM local file system. For reference, AWS and Azure charge $45/month for the 2 core 4GB instance which is the minimum resource required to run this Sample Solution.

A specific calculation of the required services and infrastructure will define the exact cost.

The following calculators may be used:

Any production network may change in the future due to added/removed nodes and participants. Ongoing network operational costs may increase or decrease accordingly.

License

All components of the Senofi Hyperledger Fabric Solution are subject to open-source licensing. You may consult the solution’s source code repositories to learn more about licensing terms.

Launch Codes

The source code repository for this Sample Solution is in a public GitHub repository.

Glossary

The following terminology, as defined below, is used throughout this document.

TermDescriptionLink
APIApplication Programming InterfaceWikipedia
EIPThis term is used in the Morpheus UI meaning “External IP” or public IP address of your cloud instance.Morpheus
HyperledgerHyperledger is an open-source community focused on developing a suite of stable frameworks, tools, and libraries for enterprise-grade blockchain deployments.Hyperledger
Hyperledger FabricHyperledger Fabric is an open-source enterprise-grade permissioned distributed ledger technology (DLT) platform, designed for use in enterprise contexts.Hyperledger Fabric
Hyperledger Certificate AuthorityThe Hyperledger Fabric CA is a Certificate Authority (CA) for Hyperledger Fabric.Hyperledger CA
Hyperledger ExplorerHyperledger Explorer is a user-friendly Web application tool used to view, invoke, deploy, or query blocks, transactions and associated data and network information.Hyperledger Explorer
Vue.jsVue.js is a Java script framework for building user interfaces.Vue.js
CouchDBApache CouchDB is an open-source document-oriented NoSQL database.CouchDB Documentation
HLF PeerA network entity that maintains a ledger and runs chaincode containers.HLF Glossary
HLF OrdererA network entity that orders transactions into a block and then distributes blocks to connected peers for validation and commit.HLF Glossary
HLF Membership Service ProviderThe Membership Service Provider (MSP) refers to an abstract component of the system that provides credentials to clients and peers, so that they can participate in a Hyperledger Fabric network.HLF Glossary
Hardware Security ModulesA hardware security module (HSM) is a physical computing device that safeguards and manages digital keys and performs encryption and decryption functions.Wikipedia
VaultVault is a tool for securely accessing secrets.Vault

GitHub

Transport Layer Security (TLS)Transport Layer Security (TLS) is a cryptographic protocol designed to provide communications security over a computer network.Wikipedia
Distributed Ledger Technology (DLT)A distributed ledger (DLT) is a consensus of replicated, shared, and synchronized digital data geographically spread across multiple sites, countries, or institutions.Wikipedia
BlockchainA blockchain is a growing list of records, called blocks, that are linked together using cryptography.Wikipedia
gRPCgRPC is a modern, open source remote procedure call (RPC) framework. It enables client and server applications to communicate transparently, and makes it easier to build connected systems.gRPC
Web APIA web API is an application programming interface for either a web server or a web browser.Wikipedia