AWS Database Blog

Building a serverless blockchain application with Amazon Managed Blockchain

Amazon Managed Blockchain makes it easy to create and manage scalable blockchain networks.  In Part 1 of this multi-part post, you learned how to deploy a Hyperledger Fabric blockchain using Amazon Managed Blockchain.  You also learned how to deploy a REST API to provide a simple interface to read and write to the network. To enable this, you deployed an Amazon EC2 instance running a REST API server, using the Hyperledger Fabric SDK to communicate with Managed Blockchain.

This post demonstrates an alternate way of building REST APIs with a serverless architecture using AWS Lambda and Amazon API Gateway.  Lambda has built-in fault tolerance and provides high availability for the service itself and the functions it operates, which allows developers to focus on developing the business logic.  Deploying the APIs with Lambda and API Gateway allows your application to scale automatically, while you only pay for the resources consumed.

In this step-by-step walkthrough, you deploy a Lambda function that uses the Node.js Fabric SDK to read and write to Managed Blockchain.  You also deploy an API Gateway that invokes the Lambda function for each of the API routes that are deployed.  API Gateway allows you to handle request authorization and authentication, before passing the request on to Lambda.

Solution

Managed Blockchain runs all the Fabric components (ordering service, certificate authorities, and per nodes) within an AWS managed VPC. You can only access the Fabric components via a VPC endpoint, so this post deploys the Lambda function within a VPC that you have already created and is set up to communicate with the VPC endpoint.

Because the Lambda function runs within your VPC, by default it cannot access any managed AWS services, such as AWS Secrets Manager. Your function must be able to download user enrollment credentials from Secrets Manager, so you must create another VPC endpoint to provide access to it.­

The following architecture diagram illustrates the high-level end-to-end solution.

 

API Gateway provides API routes to a web application, and invokes a Lambda function for each route.  The Lambda function obtains users’ blockchain credentials from Secrets Manager and uses those to sign blockchain transactions.  Next, the Lambda function sends the signed blockchain transactions for endorsement via VPC Endpoint to the peer node running within an Amazon Managed Blockchain network.  Lastly, the Lambda function sends the endorsed transaction proposal to the ordering service where it will get committed to the blockchain.

Solution walkthrough

For more information about the following steps, see Part 6: Read and write to the blockchain with Amazon API Gateway and AWS Lambda in the GitHub repo.

An end-to-end web request coming through the REST API runs through several AWS services.  To help explain how each service is involved, we will follow the steps taken to fulfill a request made to our non-profit blockchain network, which provides transparency into NGO donations and the spending of those donations.  In this example, we will follow a request to query all donors on our non-profit blockchain network.

To begin, the API Gateway receives the web request and invokes a Lambda function.

The Lambda function you deploy is not specific to the non-profit blockchain, and is designed to work with any chaincode.  Its runtime is controlled by the environment variables you define when you create the function.  The Lambda function uses the Node.js Fabric SDK to construct a blockchain request object that queries all donors.

When API Gateway invokes the Lambda function, it specifies a username identifying the Fabric user the Lambda function should use to sign and execute the transaction.  Every Fabric user is identified by a public certificate and a corresponding private key, which is used to sign the transaction that will be sent to the blockchain network.

The public certificate and private key are stored in Secrets Manager.  Secrets Manager provides secure, encrypted storage of credentials, and a centralized view of the credential access patterns. The Lambda function downloads the Fabric user’s blockchain credentials from Secrets Manager.

The Lambda function sends the signed transaction to a Managed Blockchain peer node and returns the query response from the blockchain network to API Gateway.

Download the Lambda function source code from GitHub.

API Gateway and Lambda Integration

In this post, API Gateway deploys with three REST API routes, which allow you to do the following:

  • Create a new donor
  • Query a donor by user name
  • Query for all donors

The API Gateway invokes the Lambda function for each route, and uses API Gateway Mapping Templates to convert the HTTP request into the parameters the Lambda function requires.  These are:

  • chaincodeFunction – The name of the chaincode function to be executed
  • chaincodeFunctionArgs – An object of arguments to pass into the chaincode function
  • functionType – One of the following: invoke, queryObject, queryString, or queryArray
  • fabricUsername – The user context in which to execute this transaction

For more information, see Build an API Gateway API with Lambda Integration.

Prerequisites

Prior to completing the step-by-step walkthrough, you must complete Part 1 and Part 2 of the GitHub repo.

Step-by-step walkthrough

For more information about each step in this process, see the GitHub repo. Each step listed here has a matching step in the repo. You can follow along with the steps and the code base in the repo to gain a more in-depth understanding.

Step 1: Creating the Fabric user

Lambda needs to execute transactions on the blockchain for a user context. Every user who interacts with the blockchain must first register and enroll with their certificate authority.

The process of registering creates an entry for the user within their organization’s certificate authority. Enrolling the user generates signing credentials that identify them. These credentials are used to sign transactions that are sent to the peer nodes when reading or writing to the blockchain.

The enrollment process generates the following two artifacts:

  • A private key
  • A signing certificate (public key)

You can enroll a user any number of times, and each time the enrollment process creates a new private key and signing certificate.

Within this step, the enrolled user’s private key and signing certificate are persisted on Secrets Manager, where the Lambda function downloads them during its execution.

For more information, see Register and Enroll a User as an Administrator.

Step 2: Deploying the Lambda function and API Gateway

The Lambda function and API Gateway are defined using AWS SAM within an AWS CloudFormation template. The API routes are defined with a Swagger document. The template also defines the creation of a VPC endpoint to Secrets Manager, along with the necessary IAM roles and policies for the Lambda function and API Gateway.

The Lambda function deploys within the VPC you created in the previous post of this series. The API Gateway deploys into a stage named dev. For more information, see Build and deploy an application for Hyperledger Fabric on Amazon Managed Blockchain.

Step 3: Testing the Lambda function

You are now ready to test your Lambda function. The function exposes a single handler function that you can use for read or write transactions.

First, test that you can write to the blockchain by creating a new donor. You can also test that you can read from the blockchain by querying the new donor you just created and querying for all donors on the network.

You can test your Lambda function via the command line interface or via the Lambda console. For more information about testing via the CLI, see Step 3 – Test the Lambda function in GitHub.

Step 4: Testing the API Gateway

The API Gateway deploys into a stage named dev. The URL to this stage displays at the end of Step 2 in this post, and you can also retrieve it from the API Gateway console.

You can test that you can use the three API routes to execute the same steps you did when testing the Lambda function.

Summary

This post walked you through a step-by-step process to easily and securely execute transactions on your Managed Blockchain network by using a Lambda function and Amazon API Gateway, and persisting user credentials on Secrets Manager.

To extend this API, you can define additional API routes either via the API Gateway console or in a Swagger document. For each route, you create a mapping template to define the arguments to pass into the Lambda function.

 

About the Author

 

Emile is a Senior Blockchain Architect at AWS. In his free time, he enjoys trail running in the hills north of San Francisco, and trying to keep up with his 18 month old daughter.