Process blockchain events using serverless functions on the cloud

This tutorial shows you how to process blockchain events using serverless functions on IBM Cloud. Events generated by the IBM Blockchain Platform (Hyperledger Fabric) are retrieved from a Node.js function running on IBM Cloud Functions (Apache OpenWhisk). The function is then connected to a cron event timer, which automatically invokes the function periodically to process all-new chain events.

Processing events from the blockchain is a perfect use case for serverless cloud platforms. Rather than having a stateful application sit idle waiting for events to occur, serverless functions are only executed when events are available for processing. This leads to better utilisation, reduced operational burden, and (ultimately) lower application costs compared to traditional infrastructure.

Learning objectives

In this tutorial, you will learn how to:

• Set up a serverless function to process blockchain events
• Provision service credentials for IBM Cloud Blockchain Platform and Databases for Redis
• Connect a serverless function to the alarm event source

Prerequisites

Before you begin, you’ll need the following:

• An IBM Cloud account
• IBM Cloud CLI installed
• IBM Cloud Functions CLI plugin installed
• Instance of the IBM Blockchain Platform with an installed and instantiated smart contract
• IBM Cloud Redis instance provisioned
• Git CLI client installed
• Docker installed

Estimated time

It should take you about 15 minutes to complete this tutorial.

Steps

Here are the steps you’ll need to complete:

1. Retrieve the demo repository with the example serverless project
2. Create service credentials for the IBM Blockchain Platform and the Redis instance
3. Create the deployment package for the IBM Cloud Functions
4. Create an IBM Cloud Functions action to process blockchain events
5. Manually test the blockchain event processing action
6. Connect action to the alarm trigger event feed

Use the Git CLI (or the GitHub web UI) to download the example serverless project source files:

git clone https://github.com/IBM/blockchain-events-cloud-functions

Enter the project folder:

cd openwhisk-eventhub

This demonstration project contains a single TypeScript source file (src/index.ts) that processes new blockchain events from an instance of the IBM Blockchain Platform. Credentials for the service that are required to interact with the platform are stored in the credentials folder as JSON files. There is also an automated deployment script in the scripts/deploy.sh that can be used to deploy the project.

The serverless function needs authentication credentials to an instance of the IBM Blockchain Platform and Redis. The Blockchain Platform instance is used to retrieve blockchain events using the client library. Redis is used to store the processed block IDs between the serverless function invocations. Follow the instructions for steps on how to retrieve the credentials from instances of those services.

Create service credentials for the IBM Blockchain Platform

1. Navigate to the blockchain instance you want to use from the IBM Cloud Resource list.
2. Obtain your ConnectionProfile.json. This should be downloaded from the Smart contracts tab in the IBM Blockchain Platform 2.0 UI for an instantiated smart contract.
3. Obtain your OrgUser.json. This can be generated/downloaded from the IBM Blockchain Platform 2.0 UI for a given enrolled identity.

Create service credentials for the IBM Cloud Redis instance

1. Navigate to the Redis instance you want to use from the IBM Cloud Resource list.
2. Open the “Service Credentials” page from the instance dashboard.
3. Click the New credential button.
4. Click the Add button on the modal dialog to create the new credentials.
5. Click the View Credentials drop-down icon in the service credentials table to reveal the credential details.

Figure 1. Creating service credentials

The JSON object shown in the table contains all the connection details that the serverless function requires. You need to extract both the connection URL string and the TLS certificate to be stored in the credentials folder.

1. Copy the Redis connection string (starting with the rediss:// prefix) from the connection.rediss.composed value in the service credentials JSON object.
2. Save this string as the url value in the credentials/redis.json file.
3. Copy the Redis connection certificate string (starting with the rediss:// prefix) from the connection.rediss.certificate.certificate_base64 value in the service credentials JSON object.
4. Save this string as the cert value in the credentials/redis.json file.

The IBM Cloud Functions action uses external libraries to interact with the Blockchain Platform. Additional libraries need to be compiled for the runtime platform and included in the deployment package archive. The TypeScript source files for the action also need to be compiled into a JavaScript file before deployment.

1. Install the development dependencies and run the build script to generate JavaScript from TypeScript source files:

   npm install && npm run build

2. Remove the development dependencies:

   rm node_modules

3. Install the production dependencies using IBM Cloud Function runtime Docker images:

   docker run -it -v $PWD:/nodejsAction openwhisk/action-nodejs-v10 npm install --production

   Note: Installing NPM libraries in the Docker runtime image is necessary because the fabric-network NPM library has native dependencies. These external dependencies need to be compiled for the correct platform architecture — not the development environment. Native dependencies are built during the npm install process.

4. Create the action deployment package from the action source and external dependencies:

   zip -r action.zip dist/ node_modules/ package.json

5. Create the IBM Cloud Functions action from the deployment package with credential parameters:

   ibmcloud wsk action update blockchain -p credentials "$(< ./credentials/OrgUser.json)" \
    -p connectionProfile "$(< ./credentials/ConnectionProfile.json)" \
    -p redis "$(< ./credentials/redis.json)" --kind nodejs:10 action.zip
   

   Show more

Note: These steps can be executed automatically using the deployment script (scripts/deploy.sh) through the NPM command, npm deploy.

Create the IBM Cloud Functions action from the deployment package with credential parameters:

ibmcloud wsk action update blockchain -p credentials "$(< ./credentials/OrgUser.json)" \
  -p connectionProfile "$(< ./credentials/ConnectionProfile.json)" \
  -p redis "$(< ./credentials/redis.json)" --kind nodejs:10 action.zip

List the IBM Cloud Functions actions to verify the action has been deployed correctly:

ibmcloud wsk action list

This should return the following list showing the blockchain action:

actions
/<USER_NAMESPACE>/blockchain                       private nodejs:10

Invoke the action to process all previous events. The action has two (optional) parameters: startBlock and endBlock. If these aren’t specified, they default to 0 and the highest current block on the chain.

ibmcloud wsk action invoke blockchain -r

{
    "blockEventsProcessed": [1, 2, 3...],
    "startBlock": 1
    "endBlock": 100,
}

Block numbers for processed events are then returned in the action response. The highest block number processed is stored in Redis (using the connectionProfile.name property as the key). This is then used as the startBlock value on the next action invocation to ensure that events are only processed once.

Invoking the action again should return no new processed events:

ibmcloud wsk action invoke blockchain -r

Create a new trigger using the alarm feed to be called once a minute:

ibmcloud wsk trigger create once-a-min --feed /whisk.system/alarms/interval -p minutes 1

Create a new rule binding the action to the trigger:

ibmcloud wsk rule create process-blockchain-events once-a-min blockchain

Monitor the activation logs for IBM Cloud Functions to see the action being invoked:

ibmcloud wsk activation poll

The action continues to be fired indefinitely until the rule and/or trigger is removed. It processes all new blockchain events without further manual steps needed. You can check the status of the processing by looking at the action logs or checking the Redis key (used to store the last processed block number).

Summary

This tutorial showed you how to process blockchain events using serverless functions on IBM Cloud.

You created a Node.js serverless function, which processed all new events on the blockchain (when invoked). This was deployed to IBM Cloud Functions, along with all necessary external libraries and dependencies. This function used Redis to persist processed block numbers between invocations.

This function was then connected to the alarm trigger feed. The trigger feed was configured to automatically invoke the function once a minute. This allowed the function to process all new events without further manual steps or needing to have idle infrastructure waiting for events to occur.

Want to learn more about blockchain and serverless on the cloud? Check out the Blockchain and Serverless technology hubs on IBM Developer.