Use cloud functions to send your data to your blockchain

Introduction

In this tutorial, you’ll learn how to use cloud functions to connect devices and applications to your blockchain. It provides code for two cloud functions and step-by-step instructions to deploy and test those cloud functions, allowing you to store your blockchain credentials in a Cloudant database and use those credentials to securely send transactions to your blockchain. This tutorial provides cloud functions that you can use to send transactions from any webhook-enabled application or device to your own blockchain smart contract, providing rich sources of data to enhance your business objectives.

Learning objectives

This tutorial guides you through the steps to build and test cloud functions that provide connectivity to your blockchain. When you finish this tutorial, you will have:

  • A set of IBM Cloud Functions that act as an IBM Blockchain Platform client.
  • A test environment to send transactions securely to your IBM Blockchain Platform instance.

Prerequisites

For this tutorial, you will need an IBM Cloud account, an IBM Blockchain Platform instance, Docker, and Node.js installed on your local machine, and a test utility such as curl, Postman, or Node-RED to make REST calls. This tutorial will show you how to use Postman for testing.

Before you start, you need to prepare the following products to complete this tutorial:

Note: You may opt for a free 30-day Kubernetes cluster and a free 30-day IBM Blockchain Platform instance when deploying IBM Blockchain Platform to a free Kubernetes cluster. The free Kubernetes cluster is deleted automatically after 30 days.

You will need the Docker and Node.js tools to build the cloud functions, including creating the correct node_modules directory for the cloud function runtime environment, before you upload them to your IBM Cloud account.

Estimated time

After the prerequisites are installed, this tutorial should take you about 45 minutes to complete.

Step 1. Clone the repository

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

Note: All directories mentioned in this tutorial are relative to the ibm-cloud-functions-serverless-blockchain base directory of this project.

Step 2. Install the IBM Cloud CLI

Follow the installation instructions to install the IBM Cloud Functions command-line interface (CLI). Make sure you run the test action so that your ~/.wskprops is pointing to the right account:

ibmcloud fn action invoke /whisk.system/utils/echo -p message hello --result

Step 3. Deploy the provided cloud functions

Deploy the send-to-blockchain cloud function to your IBM Cloud account

  1. Change directories to the send-to-blockchain cloud function directory:

     cd cloud-functions/send-to-blockchain
    
  2. Add your Cloudant URL to line 8 of the send-to-blockchain.js file, which displays const dbUrl = "<add-your-cloudant-url-here>", and save the file.

  3. Generate the node_modules directory with the correct operating system for the machine that the cloud function will run on by executing this command without changes:

    docker run -it -v $PWD:/nodejsAction openwhisk/action-nodejs-v8 /bin/bash
    
  4. Once inside the container, run npm i and then exit.

  5. Zip up the source code and generated node_modules directory for the action:

    zip -r action.zip *
    
  6. Create the action in your IBM Cloud account:

     ibmcloud wsk action create send-to-blockchain \--kind nodejs:8 action.zip
    

Deploy the store-credentials-cloudant cloud function to your IBM Cloud account

  1. Change directories to the store-credentials-cloudant cloud function directory:

     cd cloud-functions/store-credentials-cloudant
    
  2. Add your Cloudant URL to line 7 of the store-credentials-cloudant.js file, which displays const dbUrl = "<add-your-cloudant-url-here>", and save the file.

  3. Generate the node_modules directory with the correct operating system for the machine that the cloud function will run on by executing this command without changes:

    docker run -it -v $PWD:/nodejsAction openwhisk/action-nodejs-v8 /bin/bash
    
  4. Once inside the container, run npm i and then exit.

  5. Zip up the source code and generated node_modules directory for the action:

    zip -r action.zip *
    
  6. Create the action in your IBM Cloud account:

    ibmcloud wsk action create store-credentials-cloudant \--kind nodejs:8 action.zip
    

Step 4. Obtain the API key and URLs for your cloud functions

  1. From your browser, navigate to IBM Cloud and select Functions from the Navigation Menu located in the upper-left corner of the window.
  2. In the Functions menu, click Actions and then select the send-to-blockchain action.
  3. In the next menu, click Endpoints and then click API-KEY on the resulting panel.
  4. In the CF-based API key for this namespace section, click the eye icon to view your API key and copy it.
  5. Save this value, which you’ll need to configure your Postman REST calls to your cloud functions.
  6. In the same section, copy the URL and save this value.
  7. Back in the Functions menu, click Actions and then select the store-credentials-cloudant action.
  8. In the next menu, click Endpoints.
  9. In the CF-based API key for this namespace section, copy the URL and save this value, which you’ll need to configure your Postman REST calls to your cloud functions in an upcoming step.

Step 5. Install the provided blockchain smart contract

Follow the instructions to install and instantiate the tutorials/cf-send-to-blockchain/iot-shipping-contract.cds smart contract on your peer in your IBM Blockchain Platform instance.

Step 6. Download blockchain credentials and connection profile

  1. Follow the instructions to download the connection profile for your contract.
  2. In your IBM Blockchain Platform user interface, click Wallet, select the user you will connect to your blockchain, and then click Export. (If you created your IBM Blockchain Platform instance just for this tutorial, use your Org1 admin credentials.)

Step 7. Install and configure the provided Postman collection

Import the Postman collection

In the Postman user interface, click Import to import the tutorials/cf-send-to-blockchain/BlockchainCloudFunctions.postman_collection.json file.

Import the environment

In the Postman user interface, click the environment settings gear to Manage Environments. Then click Import to import the tutorials/cf-send-to-blockchain/cloud-functions.postman_environment.json file.

Configure the environment

  1. Select the imported cloud-functions environment to see the defined Postman environment variables.
  2. Open the blockchain connection profile that you downloaded, copy the entire contents, and paste those contents into the Postman environment connectonJson value.
  3. Open the credential file that you downloaded and copy the private_key value into the Postman environment privateKey value.
  4. From the same credential file, copy the value of cert into the Postman environment userCert value.

Note: Record the name value from the credential file, as you will need it in an upcoming step.

Step 8. Store your blockchain credentials in IBM Cloudant

Set the REST Call Authorization

  1. Select the Blockchain Cloud Functions collection you imported to Postman.
  2. Select the Create or update credentials REST call.
  3. Select the Authorization tab.
  4. Select Basic Auth and provide the API key you saved in Step 4. The API key consists of user:password. Copy the portion before the colon to the Username field and the portion after the colon to the Password field.

Set the URL to your cloud function URL

Update the URL field of the Create or update credentials REST call with the URL for the store-credentials-cloudant action obtained in Step 4.

Set your request parameters

Click on the request Body tab and edit the JSON:

{  
  "id": "admin-myFabric",  
  "contract": "iot-shipping-contract",  
  "username": "admin",  
  "cert": {{userCert}},  
  "key": {{privateKey}},  
  "connection": {{connectionJson}}
}

Note: In the code above, supply any value for id (this will be the value you send with each transaction). For username, supply the name of the user you noted from the credential file in Step 7. If your display name does not match your user’s name (for example, if your display name in your blockchain platform for your user is Org1 admin but you know you used the admin user credentials for that user), supply admin for username in the request body.

Send the request

Save your changes and click Send to store your credentials in your Cloudant database. You will use these credentials to send each transaction to your blockchain.

Step 9. Send a transaction to your blockchain

Set the REST Call Authorization

  1. In the Blockchain Cloud Functions collection you imported to Postman, select the Send transaction REST call.
  2. Select the Authorization tab.
  3. Select Basic Auth and provide the API key you saved in Step 4.

Set the URL to your cloud function URL

Update the URL field of the Send transaction REST call with the URL for the send-to-blockchain action, obtained in Step 4.

Set your request parameters

Click on the request Body tab and edit the JSON, supplying the value for id that you used in Step 8 (this specifies the credentials you will use to send transactions to your blockchain):

{  
  "id": "admin-myFabric",  
  "fcn": "createShipment",  
  "args": [ "1000", "Shipment of widgets",
    "30.2672", "97.7431", "103", ".35" ]
}

Send the request

Save your changes and click Send to send your transaction to your blockchain. The first value in args is the shipment ID. Change the shipment ID each time you submit a transaction. Other fields are (in order): description, latitude, longitude, temperature, and humidity.

Step 10. Look for a new block in your blockchain

  1. In your IBM Blockchain Platform user interface, click Channels.
  2. Click on the channel you created when setting up your blockchain network.
  3. Scroll down to Block History and click on the most recent block.
  4. In the resulting transaction list for that block, click on the most recent transaction to see the transaction you just sent.

Summary

Congratulations! You should now be able to call your cloud functions to store blockchain credentials in your Cloudant database and then use those credentials to send transactions securely to your blockchain. You can use these same cloud functions to send any data from any webhook-enabled application or device to your blockchain smart contract to help you meet your business objectives.

As a next step, you can explore receiving events from your blockchain smart contract via the listener code in the send-to-blockchain cloud function.

Carole Corley