Build and deploy an application for Hyperledger Fabric on Amazon Managed Blockchain

At re:Invent 2018, AWS announced Amazon Managed Blockchain, a fully managed service that makes it easy to create and manage scalable blockchain networks using the popular open source frameworks Hyperledger Fabric and Ethereum. General availability of Hyperledger Fabric was announced in April 2019, with support for Ethereum coming soon. For additional details about Managed Blockchain, see What Is Amazon Managed Blockchain?

In this post, you will learn how to build a Hyperledger Fabric blockchain network using Managed Blockchain. After creating the Fabric network, you deploy a three-tier application that uses the network to track donations to a nonprofit organization. Nonprofits want to provide visibility to their supporters and transparency into how they are spending donations. For each donation made by a donor, Hyperledger Fabric tracks the specifics of how the donation is spent. Donors can use this information to decide whether the nonprofit is spending their donations as they had anticipated.

An online recording that shows the steps covered in this post is available on YouTube.

Blockchain is suitable for this scenario because it promotes trust between all members in the network, including donor organizations, investors, philanthropic institutions, suppliers, and the nonprofit itself. All members in the network have their own immutable, cryptographically secure copy of the donation and spending records. They can then independently review how effectively donations are spent. This transparency could lead to increased efficiency and insight into lowering costs for nonprofits.

Architecture overview

The application consists of the following tiers:

Hyperledger Fabric chaincode that executes on the Fabric peer node. Chaincode is the smart contract that queries data and invokes transactions on the Fabric network.
A RESTful API that uses the Hyperledger Fabric Client SDK to interact with the Fabric network and expose the functions provided by the chaincode. The Hyperledger Fabric Client SDK provides APIs to create and join channels, install and instantiate chaincode, and query data or invoke transactions.
A user interface application that calls the API provided by the RESTful API.

This architecture provides loose coupling and abstraction in such a way that the end user of the application is not exposed to the inner workings of a Hyperledger Fabric network. In fact, besides a slider component on the user interface showing the blocks received from the Fabric network, there is no indication to the end users that the underlying technology is blockchain.

This loose coupling extends to the user interface developers, who simply use the functionality provided by the RESTful API and don’t need to know anything about Hyperledger Fabric or chaincode. Loose coupling therefore allows development of applications with a familiar look and feel, whether they be web, mobile, or other types of applications.

The rest of this article is divided into four sections, each discussing the different layers of the architecture, as follows:

Part 1 builds a Hyperledger Fabric network using Amazon Managed Blockchain.
Part 2 deploys business logic in the form of chaincode to the Fabric network.
Part 3 deploys a RESTful API that uses the Hyperledger Fabric Client SDK to interact with the chaincode.
Part 4 deploys an application that uses the functionality exposed by the RESTful API.

A request by an end user would flow through the layers as shown in Figure 1. Activity by a user on the user interface would result in a REST API call to the RESTful API server. In turn, this would use the Fabric SDK to interact with the Hyperledger Fabric components in Managed Blockchain to invoke a transaction or query data.

Figure 1 – Users interacting with a Hyperledger Fabric application

The accompanying repository

The Git repository that accompanies this post contains the artifacts that are required to finish parts 1–4 to create the end application:

https://github.com/aws-samples/non-profit-blockchain

Each part in this post is associated with a matching part in the Git repo. As we progress through each part, the post elaborates on the steps in the README files in the accompanying repo.

Note that executing the steps in this post consumes AWS resources that will be billed at the applicable rates.

Let’s get started with Part 1.

Part 1: Build a Hyperledger Fabric network using Amazon Managed Blockchain

Using the AWS Management Console, you can create a Hyperledger Fabric network using Managed Blockchain with just a few clicks. Open the Managed Blockchain console, and choose Create a network. Choose the Hyperledger Fabric framework, and provide a name for your network. Then choose Next.

Enter a name for the initial member that you want to add to your network. A member is the equivalent of a Hyperledger Fabric organization and often maps to a real-world organization. If you consider a Fabric network to be made up of a consortium of organizations that want to transact with each other, a member would be one of the organizations in the consortium.

Finally, enter an administrator user name and password for the member. Each member in an Amazon Managed Blockchain network has its own certificate authority (CA) that is responsible for registering and enrolling the users for this member. Entering this information here defines an identity that has the administrator role for this Hyperledger Fabric member.

After reviewing the details that you entered, create the network and member.

For additional details about these steps, see Part 1, Step 1: Create the Hyperledger Fabric blockchain network in the accompanying repository.

Managed Blockchain is a fully managed service. It creates and manages shared components such as the Hyperledger Fabric ordering service and the Fabric CA for each member, and it exposes them with endpoints. In a future step, you use virtual private cloud (VPC) endpoints to make the endpoints of these components available to a VPC in your account.

Creating a Hyperledger Fabric peer node

After your Hyperledger Fabric network and member have an ACTIVE status, it’s time to create a Fabric peer node. Peer nodes are where Fabric smart contracts execute (for example, chaincode). Peer nodes also contain the Fabric ledger, which consists of two parts: a journal that holds a cryptographically immutable transaction log (or “blockchain”) and a key-value store known as the world state that stores the current state of the ledger.

Part 1, Step 2 contains the steps to create a peer node. Each member on a network creates their own peer nodes, so select the member that you created previously and choose the link to create a peer node. Choose an instance type and the amount of storage for that node, and then create the peer node.

Like the ordering service and CA, each member’s peer nodes are managed by Amazon Managed Blockchain and can be accessed from your VPC via a VPC endpoint.

At this stage, you have a Hyperledger Fabric network with a highly available ordering service and CA, and a single peer. For the remainder of this post, we remain with this single-member network to reduce the scope. However, in a more robust test or production scenario that would simulate a multimember decentralized network, you could use the Amazon Managed Blockchain console or API to invite other members to join the network. In a follow-up blog post, we will walk through these steps.

Now, you need a way to interact with the Fabric network so that you can create channels, install chaincode, and invoke transactions.

Creating a Hyperledger Fabric client node in your VPC

To interact with the Fabric components provisioned by Amazon Managed Blockchain, you can download and use the open source Hyperledger Fabric CLI or SDK. You configure these clients to interact with the endpoints exposed by Managed Blockchain. The CLI is a peer binary that enables you to install, query, and invoke chaincode and create and join channels.

As shown in Figure 2, the Hyperledger Fabric components managed by Amazon Managed Blockchain are accessed via a Fabric client node (for example, Client A), which you provision in a VPC in your account. The Fabric client node hosts the open source Hyperledger Fabric CLI and allows you to interact with your Fabric network via the VPC endpoint. All network traffic between your VPC and your managed Fabric network occurs over the AWS backbone and is not exposed to the public internet.

Figure 2 – The layout of an Amazon Managed Blockchain network with two members

You use AWS CloudFormation to provision a new VPC in your AWS account, an Amazon EC2 instance configured as your Fabric client node, and the VPC endpoint to communicate with your Fabric network.

Part 1, Steps 3 and 4 in the GitHub repo explain how to provision and prepare your Fabric client node. Don’t forget to follow the prerequisites in Part 1 to create your AWS Cloud9 environment. AWS Cloud9 is a cloud-based integrated development environment (IDE) that lets you write, run, and debug your code with just a browser. However, you won’t be using the IDE functions. You’ll use the Linux command line provided by AWS Cloud9 because it comes pre-installed with some of the packages we need, such as the AWS CLI.

Creating a Hyperledger Fabric channel and installing chaincode

From the Fabric client node, you now create a channel on the Fabric network. Channels in Hyperledger Fabric are the means by which applications and peer nodes interact and transact privately with each other. A Fabric network can support many channels where each channel has a different combination of members.

The process for creating a channel includes creating a channel config file (configtx.yaml), which contains channel definitions in the form of profiles. You use the Hyperledger Fabric channel configuration (configtxgen) tool to generate a binary channel creation transaction file based on one of the profiles from configtx.yaml. Then you submit the channel creation transaction file to the Fabric ordering service where the channel is created. Block 0, the channel genesis block, is created at this point. It is added to the channel and returned to the peer node where it can be used to join the peer to the channel.

After creating the channel, install sample chaincode on the peer node and instantiate the chaincode on the channel. The sample chaincode comes from the Hyperledger Fabric samples repo and has already been cloned to the Fabric client node. Whereas installing chaincode simply packages the chaincode and copies it to the peer, instantiating chaincode is a binding process that binds the chaincode to the channel.

Instantiating chaincode performs a number of tasks:

It sets the endorsement policy for the chaincode. For more information, see Endorsement policies on the Hyperledger Fabric site.
It builds a Docker image where the chaincode is launched on the peer node that instantiated the chaincode.
It invokes the init method on the chaincode to initialize the ledger.

To create the channel and install and instantiate the chaincode, follow Steps 5–9 in Part 1 in the GitHub repo.

Querying the chaincode and invoking transactions

In Steps 10–12, you query the chaincode, invoke a chaincode transaction, and then query the chaincode again to check the effect of the transaction. As shown in Figure 3, querying chaincode takes place on the peer node. It involves the chaincode querying the world state, which is a key-value store storing the current state of the ledger. An identical copy of the world state is stored on each peer node that is joined to a channel.

Figure 3 – Chaincode interacting with the Hyperledger Fabric Ledger via the peer

This is the transaction flow that is kicked off when invoking a transaction: A Fabric client application sends a transaction proposal to the endorsing peers in the network for endorsement. The endorsing peers simulate the transaction and return the results to the client application. The client application packages all the endorsed transaction responses and submits the package to the ordering service. Transactions are ordered and cut into blocks before being sent back to all the peer nodes joined to the channel. Here the transactions are validated, their read/write set is checked, and each transaction updates the world state. The block is finally appended to the ledger.

At the end of Part 1, you’ve done the following:

Created a Hyperledger Fabric network using Amazon Managed Blockchain and provisioned a peer node
Created a new VPC with a Fabric client node connecting to the Fabric network via a VPC endpoint
Created a new channel
Installed chaincode on the peer and instantiated the chaincode on the channel
Queried the chaincode and invoked a transaction that updates the world state and results in a new block being added to the blockchain

Part 2: Deploy and test the chaincode for nonprofit transactions

Deploying chaincode is a process that you became familiar with in Part 1. The only difference in Part 2 is that you take the chaincode for the nonprofit application from the repo and deploy that, rather than deploying the sample chaincode that is already present on the Hyperledger Fabric client node.

Some background on the Fabric client node might help make this process clearer. The Fabric client node is an EC2 instance that runs a Docker container with the name of cli. To see this, enter docker ps after you connect using SSH to the Hyperledger Fabric client node. Entering docker inspect cli shows you detailed information about the cli container, including the directories on the host EC2 instance that are mounted into the Docker container. For example, the directory /home/ec2-user/fabric-samples/chaincode is mounted. This means that you can simply copy chaincode (or any file) to this directory on your EC2 Fabric client node, and it will be available within the cli container. After it is available to the cli container, you can use the peer chaincode install command to install the chaincode on the peer node.

To copy, install, and instantiate the nonprofit chaincode on the channel, follow the steps in Part 2: Non-profit (NGO) Chaincode in the GitHub repo.

Part 3: Deploy the RESTful API server

The RESTful API server is a Node.js Express application that uses the Hyperledger Fabric Client SDK to interact with the Fabric network. As mentioned previously, the Hyperledger Fabric Client SDK provides a wealth of functionality. It includes APIs to create and join channels, install and instantiate chaincode, and query blockchain metadata such as block heights and channel configuration information. In this post, we use a subset of SDK functionality that allows us to query chaincode and invoke transactions.

How does the RESTful API Node.js application connect to the Fabric network? There are two options:

Use the API provided by the Hyperledger Fabric Client SDK to connect to the ordering service, the CA, and the peer nodes in your network.
Create a connection profile, which is a YAML file describing the structure of your Fabric network. Pass this file to the Fabric Client SDK. The SDK uses it to connect to and interact with your Fabric network.

We use the second approach by creating a connection profile. You can see this in Step 3 of Part 3, where I use a script to generate a simple connection profile for your network.

Follow the steps in Part 3: RESTful API to expose the Chaincode to deploy the Node.js RESTful API server.

Part 4: Run the Node.js/Angular user interface application

The user interface application is a Node.js/Angular application that calls the API provided by the RESTful API server. It does not use the Hyperledger Fabric Client SDK nor does it have any connectivity to the Fabric network. Instead, each action in the application invokes a corresponding REST API function.

It’s also worth noting that all application data is owned by the Fabric network. Besides the images displayed in the gallery, all data is retrieved from the Fabric world state database via the RESTful API and the Fabric chaincode. The application provides functionality that allows donors to track how their donations are spent and includes the following functions:

Donors can review each nonprofit organization, donate funds to them, and rate them.
Donors can view the items that each nonprofit has spent funds on and can see how much of each donation was used to fund each spend item.
Donors can track the donations that they have personally made.

The steps to deploy the application are the same as for any Node.js application. One small edit is required to provide the endpoint for the RESTful API to the Node.js application, which is explained in Step 3.

Follow the steps in Part 4: The User Interface to deploy the Node.js user interface application.

Conclusion

Well done on completing the steps in this post. You built a Hyperledger Fabric network using Amazon Managed Blockchain and deployed a multi-tier application consisting of chaincode, a RESTful API, and a user interface application. You also deployed a working application that uses blockchain as its underlying data source.

Besides the slider component on the user interface showing the blocks received from the Hyperledger Fabric network, there is no indication to the end users that the underlying technology is blockchain. We have abstracted the application from the blockchain using a REST API that could support multiple channels such as web and mobile, and we provided block notifications via a standard WebSocket protocol.

For a test network to simulate this application on a decentralized architecture, the next step would be to add more members to the Fabric network and have those members provision peers that join the same channel. This will be the topic of a future blog post.

Thanks to the following people:

Siva Puppala, Khan Iftikhar, Rangavajhala Srikanth, and Pentakota Deekshitulu for building a great UI application
Michael Braendle, who reviewed and tested the accompanying repo

Next Steps

After creating your Fabric network you might want to create a multi-member decentralized network by adding new members to the network. The steps to do this can be found in the next blog post: Add new members to a Hyperledger Fabric channel on Amazon Managed Blockchain.

About the Author

Michael Edge is a senior blockchain architect with AWS Professional Services.