Building a blockchain application in Java using Amazon Managed Blockchain

Amazon Managed Blockchain allows you to easily set up and scale blockchain networks. You interact with the chaincode using the Hyperledger Fabric Command Line Interface (CLI). Your blockchain application interacts programmatically with your network using the Hyperledger Fabric SDK. For more information about creating a Hyperledger Fabric network, setting up members, creating channels, and deploying chaincode on your network, see Get Started Creating a Hyperledger Fabric Blockchain Network Using Amazon Managed Blockchain.

This post demonstrates how to set up a blockchain application written in Java to read and write data to Managed Blockchain using the Fabric Java SDK. The Java SDK allows customers with applications written in Java to integrate blockchain support with their existing codebase. This makes it easier to handle rich data structures and complex business logic before writing records to the blockchain. You can also integrate Managed Blockchain using the Fabric Node.js SDK. For more information, see Building serverless blockchain application with Fabric Node.js SDK.

In this post, you create a sample Java application that consists of a REST API server communicating with the blockchain network. You can run a REST API server on AWS either via an Amazon Elastic Compute Cloud (Amazon EC2) instance or using Amazon API Gateway and AWS Lambda.

Our application uses Lambda instead of an EC2 instance to avoid the operational overhead of provisioning and managing a server. Two benefits of the Lambda architecture are built-in scaling and fault-tolerance. Moreover, Lambda functions only incur costs when running, thus enabling high cost-optimization.

Solution overview

This post walks you through creating a blockchain application in Java running on Lambda that interacts with your blockchain network using the Fabric Java SDK. API requests are first sent to API Gateway, which dispatches the requests to Lambda. API Gateway allows you to securely authenticate and authorize incoming requests before forwarding them to Lambda. The solution also uses AWS Secrets Manager to securely store and retrieve the credentials required to transact on the blockchain network.

The following diagram illustrates the architecture of the solution.

The architecture consists of the following components:

  • API Gateway configured with Lambda proxy integration
  • A Java Lambda function integrating with the Fabric Java SDK and running in a custom VPC within a private subnet
  • VPC endpoints to access to Secrets Manager and Managed Blockchain
  • Secrets Manager to store Fabric users’ credentials
  • Managed Blockchain, which includes all the Hyperledger Fabric components (peer node, certificate authority (CA), and ordering service)

The incoming request originates from a web or a mobile application and goes to API Gateway. The request is forwarded from API Gateway to the Lambda function that runs the blockchain application written in Java using Spring Boot 2.

The application uses the Hyperledger Fabric SDK to interact with Managed Blockchain. Because the Lambda function doesn’t need to communicate with the outside world, it sits in a custom VPC within a private subnet. It communicates with Managed Blockchain and Secrets Manager using VPC endpoints. Using VPC endpoints allows private connection between your VPC and AWS services and the encrypted traffic stays within the AWS network without traversing the public internet.

Hyperledger Fabric networks require Fabric user credentials to read and write data to the blockchain. To achieve this, the Lambda function first reads the connection information (such as orderer endpoint, CA endpoint, and peer endpoint) from Lambda environment variables. It retrieves the Fabric user credentials from Secrets Manager, creates a Fabric user context, and uses it to build a request to query the chaincode. The request is sent to one of the peer nodes in Managed Blockchain. A peer node fulfills the query request and sends back the response to the Lambda function. The response is sent to the API Gateway, which transfers it to the requesting client.

The API Gateway in this solution is configured in Lambda proxy integration. For more information, see Set up Lambda proxy integrations in API Gateway.

The complete end-to-end architecture presented here is provided in the GitHub repo. Download it to follow the step-by-step guide.

Walkthrough

Each step of the walkthrough has a matching step in the repo, with additional info provided in the README file. You can follow along with the steps and the code base in the repo to gain a more in-depth understanding.

To implement the solution, you complete the following steps:

  1. Configure the project.
  2. Build and deploy the serverless stack using the AWS Serverless Application Model (AWS SAM) CLI.
  3. Register and enroll lambdaUser with the Fabric CA using the SDK.
  4. Test the application and interact with Managed Blockchain.

Prerequisites

You must have a Managed Blockchain network up and running with at least one chaincode installed and instantiated before proceeding further.

If you don’t have a blockchain network in your AWS account, follow the steps in Get Started Creating a Hyperledger Fabric Blockchain Network Using Amazon Managed Blockchain and complete it up to step 7 before continuing this post. After completing the guide, you will have the chaincode mycc instantiated in your network. You interact with this chaincode later in this post.

The example project uses AWS SAM to ease the deployment process. For installation instructions, see Installing the AWS SAM CLI. In the installation guide, you can skip the Docker installation step; it’s not required in this post.

Configuring the project

In this step, you set up and configure a Java application in Spring Boot 2 to run on Lambda and integrate it with the Fabric SDK. The configuration discussed in this step is done for you on the sample project on GitHub; you don’t need to configure anything. This step helps you better understand the configuration required and makes it easier to adopt to your own application.

The sample project is built using Spring Boot 2 framework, which allows you to easily set up a REST API Server in Java. However, Spring Boot by default isn’t optimized to run on Lambda. Therefore, the project integrates the AWS Serverless Java container library, which makes it easy to run Spring Boot on Lambda. This library acts as a Servlet container; it receives events object from Lambda and translates them to a request object for the Spring Boot framework. Similarly, it translates responses from the framework into valid return values for API Gateway. Finally, it natively supports API Gateway proxy integration models for requests and responses. For more information, see Running APIs written in Java on AWS Lambda.

To set up AWS Serverless Java container with Spring Boot 2, the sample application provides an implementation of the interface RequestStreamHandler in the class StreamLambdaHandler, as shown in the following code. This class serves as the main entry point to the Lambda function.

public class StreamLambdaHandler implements RequestStreamHandler {
 private static SpringBootLambdaContainerHandler<AwsProxyRequest, AwsProxyResponse> handler;

 static {
 try {
 handler = SpringBootLambdaContainerHandler.getAwsProxyHandler(Application.class);
 } catch (ContainerInitializationException e) {
 // if we fail here. We re-throw the exception to force another cold start
 e.printStackTrace();
 throw new RuntimeException("Could not initialize Spring Boot application", e);
 }
 }

 @Override
 public void handleRequest(InputStream inputStream, OutputStream outputStream, Context context) throws IOException {
 handler.proxyStream(inputStream, outputStream, context);
 }
}

Next, you need to integrate Hyperledger Fabric Java SDK library in your application to interact with the Fabric network. The sample project achieves this by adding the following dependency in the dependencies section of pom.xml:

<dependency>
 <groupId>org.hyperledger.fabric-sdk-java</groupId>
 <artifactId>fabric-sdk-java</artifactId>
 <version>1.2.0</version>
</dependency>

Building and deploying the serverless stack using AWS SAM CLI

The Fabric SDK needs the Managed Blockchain TLS certificate chain to connect to your blockchain components. Copy the TLS certificate chain from Amazon Simple Storage Service (Amazon S3) to the project’s resources folder.

Next, build the project using the AWS SAM CLI sam build command. The build process is configured to exclude the Apache Tomcat server dependencies that comes by default with Spring Boot. Tomcat isn’t required because the Java application uses AWS Serverless Java container to run on Lambda with API Gateway.

You need to set a few environment variables for the Lambda function to register and enroll the new Fabric user lambdaUser. This user is dedicated for the Lambda function and is created in the next step. You need to provide the Fabric CA admin’s credentials for the registration process. Set the Fabric CA admin user name and password you used to create the Managed Blockchain network, and a choose a new password for lambdaUser (see the following code). In your own environment, choose a strong and unique password and consider using Secrets Manager or AWS Systems Manager Parameter Store to store these settings securely.

export ADMINUSER='YOUR_CA_ADMIN_USER'
export ADMINPWD='YOUR_CA_ADMIN_PASSWORD'
export LAMBDAUSERPWD='LamdaUserPwd1'

You’re now ready to deploy the AWS SAM template, which creates the following AWS resources:

  • Java Lambda function
  • API Gateway with endpoints to:
    • Register and enroll user
    • Query chaincode
    • Invoke chaincode
  • Custom VPC for Lambda with a private subnet without internet access
  • Two VPC endpoints for private communication between:
    • Lambda VPC and Managed Blockchain
    • Lambda VPC and Secrets Manager

To start the deployment, set the name of your blockchain network created in the prerequisites section:

export NETWORKNAME='YOUR_NETWORK_NAME'

Run the provided script deployLambda.sh to deploy the stack. The script exports all the required settings for Managed Blockchain (such as NETWORKID, MEMBERID, PEERID, and PEERENDPOINT). To ease the deployment process, the script retrieves your blockchain network settings using the AWS Command Line Interface (AWS CLI) commands. For more information, see Managed Blockchain Available Commands.

The script then creates an S3 bucket to host the Lambda source code and runs sam deploy to deploy the stack.

When the deployment is successful, you see an output similar to the following code:

$ ./deployLambda.sh
...
CloudFormation outputs from deployed stack
-----------------------------------------------------------
Outputs
-----------------------------------------------------------
Key BlockchainLambdaApi
Description URL for Managed Blockchain Lambda Function
Value https://XXXXXX.execute-api.us-east-1.amazonaws.com/
-----------------------------------------------------------
Successfully created/updated stack - lambda-java-blockchain in us-east-1
Lambda source code is stored in the S3 bucket - lambda-java-blockchain-sam-bucket-xxxxxxxxxx

Record the URL of the API that has been deployed; you use it in the following steps to interact with the Lambda function. You can also retrieve the URL on the AWS CloudFormation console: find the stack named lambda-java-blockchain and choose the Outputs tab.

On the sample project, the URL of the API is publicly accessible for testing purposes. In your own application, you should protect your API; for example, by integrating with Amazon Cognito user pools. For more information about API access, see Controlling and managing access to APIs in API Gateway.

For step-by-step instructions, see Step 2 – Build and deploy the serverless stack on the GitHub repo.

Registering and enrolling lambdaUser with the Fabric CA using the SDK

To interact with Hyperledger Fabric you need Fabric user credentials that are known by your organization’s Fabric CA.

To create a new user from the SDK, you enroll the admin user with the Fabric CA, which returns the credentials for the admin. You use the admin’s credentials to register and enroll a new Fabric user named lambdaUser dedicated for the Lambda function. The API Gateway provisioned in the previous step provides an endpoint /enroll-lambda-user to do this. In your own application, you may consider generalizing this endpoint so it can operate with additional parameters (such as user name and password) and handle registration and enrollment for many users. Use the API URL of your API Gateway and send the request to the /enroll-lambda-user endpoint to register and enroll the new user. See the following code:

$ export API_URL=API_URL_FROM_STEP_2
$ curl -s -X POST "${API_URL}/enroll-lambda-user"
lambdaUser registered and enrolled successfully

When the user is successfully registered with the Fabric CA, the enrollment process issues an enrollment certificate, which consists of a private key and a signing certificate. Secrets Manager stores these files, and the Lambda function can use them to sign transactions submitted to Managed Blockchain.

By default, the Lambda function is configured to query and invoke transactions in the blockchain on behalf of lambdaUser.

For more information about Fabric User enrollment using the AWS CLI, see Register and Enroll an Admin.

Testing the application by interacting with Managed Blockchain

You’re now ready to interact with the chaincode deployed in your blockchain network. You start with the sample chaincode mycc that you created in Step 7 of Get Started Creating a Hyperledger Fabric Blockchain Network Using Amazon Managed Blockchain.

Use the API URL of your API Gateway from Step 2 and use the endpoints /invoke and /query to send requests to the chaincode. For instructions, see Step 4 – Test the application and interact with Managed Blockchain on the GitHub repo.

The /query and /invoke endpoints are generic and work with any other chaincode. You can change the value of the following query parameters to interact with any other chaincode:

  • chaincodeName – The name of the chaincode
  • functionName – The name of the function to query or invoke
  • args/argList – The arguments to pass to the query or invoke functions

Conclusion

In this post, you learned how to build a serverless blockchain application in Java that communicates with your Managed Blockchain network using the Fabric Java SDK. You deployed an API Gateway with Lambda proxy integration that forwards incoming requests to a Java Lambda function, which communicates with the blockchain.

As a next step, you could enrich the application by creating new API endpoints to interact with other chaincodes. You could also explore other features of the Fabric SDK such as creating channels, installing, and upgrading chaincode.


About the author

Bishesh Adhikari is a Blockchain Prototyping Architect at AWS Prototyping team. He works with AWS customers to build prototypes on Blockchain and Machine Learning, which accelerates their journey to production. In his free time, he enjoys hiking, travelling, and spending time with family and friends.

Related:

  • No Related Posts

New Expanded HCI Options Deliver Flexibility and Choice

Dell EMC Solutions for Microsoft Azure Stack family Microsoft’s partner conference – Microsoft Inspire – is taking place this week. While it will look a little different this year, we are looking forward to virtually networking and discussing what’s coming in the year ahead. This year, Dell Technologies is announcing several new expanded platform options for the Microsoft Azure Stack portfolio that further simplify and automate management as well as provide flexibility and choice. For those of you not familiar, Dell Technologies offers two comprehensive Azure Stack solutions: Dell EMC Solutions for Azure Stack HCI and … READ MORE

Related:

3 Data Center Best Practices Every Mid-Market Organization Should Follow

In today’s digital world, businesses are built on data. That data has value not only to the organizations that house it, but also to external and internal threats. In order to ensure that your business has the digital services it needs, you need trusted infrastructure. Research by ESG and Dell shows the return on investment, as well as risk reduction, that is obtained from running a trusted data center is significant. On the spectrum of Leader and Laggard IT organizations, 92 percent of leaders surveyed reported that investments in infrastructure technologies to maximize uptime and availability … READ MORE

Related:

ShareFile notify users of their own activity

Notify users of their own activity

By default, ShareFile account settings prevent email notifications from being sent to any user regarding their own activity, even if they have Upload Alerts or Download Alerts enabled on a folder.

This setting can be changed so that users can receive notifications of their own uploads and downloads. Some accounts choose to make this change so that users can keep notifications as receipts of their own activity. This setting can be changed in the Advanced Preferences menu.

When you set upload or download notifications for particular users on folders, by default, the users will receive notifications about these uploads/downloads in real-time. Users can change this default behavior by clicking the Personal Settings link in their account. However, if you want to set a default value for this setting for all users on your account, you may do so using this setting.

Note:

Changing this setting does not affect existing users in the system (it is only applied to newly-created users). You can update this setting for individual users in the at their individual profile page found under People. In Real-Time is the default value.

Users can receive email notifications in the following languages: English, German, Spanish, French, Dutch, Chinese, Russian, Japanese, Korean, Portuguese.

Related:

ShareFile distribution group

Use Distribution Groups to consolidate users into functional groups for more efficient account management. This feature is useful for managing large groups of users with similar folder access needs.

Requirements

Managing Distribution Groups requires the create shared distribution groups and edit shared distribution groups permissions

Distribution Groups and User Permissions

  • Members added to the Distribution Group will inherit the folder access permissions of the group.
  • Members removed from the Distribution Group will lose the folder access permissions given to that group.
  • Permissions given on a folder to a distribution group will apply to every member. This includes notifications about downloads and uploads.


Create a Distribution Group

  1. People > Manage Users or Distribution Group
  2. On the Distribution page click on the Create Group button.
  3. The next page will allow you to name the group and give you the option to share the group with employees in your account.
  4. Click the Create Group button.
  5. Check the box beside Share this distribution group with all employees if you want users with the edit shared distribution group permission to be able to edit your group.
  6. On the Managing group page, you can add users with one of the following options:
  • Click Add Member to enter a user’s email, name and company manually. Click the checkbox when done entering a single user’s information.
  • Access the Add From drop down menu and choose Add from Personal Address Book or Add from Shared Address Book
  • Access the Add From drop down menu and choose Add from Employee List
  • Access the Add From drop down menu and choose Add from Excel. A template spreadsheet will be provided to you. Please fill in this spreadsheet and follow the instructions provided in the web app.
  • Access the Add From drop down menu and choose Classic Bulk Add. You may enter users via email. Each entry should be on its own line. Entries should NOT be separated by commas. Entering first and last names for each entry is not required. To associate a first and last name with an entry, place the name in parentheses after the email address.

Once you have saved our Distribution Group, you can return to the Distribution Groups menu to modify your group as needed.


Sending or Receiving Files from a Distribution Group

You can select a Distribution Group as the recipient of your message when sharing or requesting files. Distribution Groups can be accessed via the Address Book icon. When receiving an email sent to an entire Distribution Group, your recipient will only see his or her own email address in the recipient field. For security purposes, recipients cannot view other email addresses that may have been sent the file.

User-added image

Adding a Distribution Group to a Folder

A distribution group may be added to a folder in much the same way an individual user would be. Folder permissions can be customized across the distribution group. When receiving notifications sent to an entire Distribution Group, your recipient will only see his or her own email address in the recipient field. For security purposes, recipients cannot view other email addresses that may have received the notification.

User-added image


Distribution Group FAQ

How many users can I add to a Distribution Group?

A distribution group can have a maximum of 2000 users.

I added a user to a folder when they already had access through a Distribution Group. What permissions apply?

The individual user’s access will override that of his/her group. Example: John Doe has Download permissions on a folder due to his membership in the Doe Distribution Group. You add John Doe to the folder manually, and grant him Upload permissions. He will have both Download and Upload permissions, even though his Distribution Group membership does not include Upload.

Generate a Group Membership List

To generate a membership list for your review, access People > Manage Users or Distribution Groups. Click on the group name to access it. Access the Generate Report drop-down menu and choose Export Group List. Once the list is generated, a spreadsheet will be downloaded to your local computer.

Generate a Folder Access report

A Folder Access report shows which folders and permissions the Distribution Group has access to. To generate a folder access report for your review, access People > Manage Users or Distribution Groups. Click on the group name to access it. Access the Generate Report drop-down menu and choose Folder Access. You may print this list for your records.

Related:

  • No Related Posts

ShareFile folder permission descriptions

The folder permissions detailed below allow for user-specific folder functionality. Each user on the folder can have their own permission set. To change folder permissions for an individual folder, navigate to that folder and access the People on this Folder menu. Use the check boxes to change permissions as needed. To manage folder permissions without navigating to them individually, click here.

Download permission

With download permission, a user has the ability to download any document in the folder to their computer or mobile device.

Download alerts

With download alerts, users will be notified via email that files have been downloaded from the folder. A user must be granted admin permission on the folder to be granted download alerts, as it will allow them to identify other users on the folder when they download documents.

Upload permission

Granting a user upload permission gives the user the ability to upload files or folders to the folder. With this permission, the user is also able to create subfolders within this folder. Any subfolders created will automatically inherit the parent folder’s permissions. The user creating the subfolder will not be able to manage users on the newly created subfolder unless they were also granted admin permission on the parent folder.

Upload alerts

With upload alerts, users will be notified via email that files have been uploaded to the folder. In order to be granted this permission, the user does have to also be granted the download permission. Users with download permission will also be able to grant themselves this permission through a checkbox on the folder.

Delete permission

The delete permission grants a user the ability to delete files within the folder that they did not upload. Note that by default, all users are able to delete files that they uploaded to the folder. This can be turned off for an account by an administrator’s request to ShareFile customer support .

Admin permission

A user granted admin permission has the ability to manage folder access on this folder and can add or remove users. They will also be able to edit some folder options. Note that the user listed as Owner (usually the creator of the folder) may not be removed by any user.

View permission

Granting a user view permission allows them to view a document without downloading it. A user must be granted just view permission if you desire them to view the document with a watermark. If you grant a user download permissions on the folder, they will automatically be granted view permissions as well. Only VDR accounts and storage zones accounts with View-Only Sharing have the ability to grant View permissions.

Related:

  • No Related Posts

Data Protection Evolution in the Coming Decade – Part 4

In part 3 of this blog series we discussed our vision for future data protection. It will be a multi-year effort to fully realize, but our early efforts in this journey are already starting to bear fruit. Recently we released support for the protection of Kubernetes containers on VMware – a first-to-market data protection solution that will enable our customers to accelerate innovation and increase their agility across multi-cloud environments by leveraging containers for application deployments while ensuring the protection of critical data wherever containers are deployed. Going forward, our customers can expect to see a … READ MORE

Related:

How to resolve file reputation alerts

I need a solution

Hello ,

We get file reputation alert from couple of servers with the following information “Reputation check for unproven files failed because of network errors for the last 3 days” .Please note that those servers are hosted on Amazon Cloud and we didn’t get any such alert from the servers hosted in office network .Could you please share your thoughts .

Thanks

Sujith

0

Related:

  • No Related Posts