Deploy Oracle Blockchain SDK on Oracle Cloud Infrastructure

[EDITED JUNE-18-2020, UPDATE TO INSTALL DOCKER, WITH SPECIAL THANKS TO MATHIJS KEMP]

In my previous post I described how to write a chaincode for Oracle Blockchain Cloud Service. Sometimes you don't have access to the blockchain cloud service, or you want to test your blockchain locally without deploying it to your production instance.

For that use case, there is good news: you can deploy it on Oracle Cloud Infrastructure.

To make this work you need to do the following:

1. Create a compartment for your blockchain (for example SDKBLOCKCHAIN)
2. Create a public/private key pair
3. Create a VCN 
4. Create a compute instance
5. Install docker
6. Build the SDK
7. Create blockchain instance (founder)

Create the VCN

see https://docs.cloud.oracle.com/iaas/Content/Network/Tasks/managingVCNs.htm for a detailed explanation of this service in Oracle Cloud Infrastructure.

For this purpose, we create a VCN and related resources. 

create VCN dialog in Oracle Cloud Infrastructure

Next we open up the ports for this VCN so the blockchain console ports are accessible from the internet

• Click on security lists
• Click on the default security list
• Make sure the provisioning page is accessible from the internet by opening port 3000
• Make sure that 500 ports are accessible from the internet (the blockchain SDK will take up to 500 ports)

Ingress rule for ports of Blockchain Console

The list of rules should look like this:

List of Ingress rules for SDK VCN

Create the Compute instance

Create a compute instance that complies with the following values:

Attribute	Value	Remark
Linux Version	7.3	or higher
Linux kernel	3.10	or higher
RAM	4GB	or higher
Storage	30GB	build.sh -d <> >=12GB Ensure there's enough space to unpack the package.Workspace build.sh -w [] >=5GB Workspace is relating to the transaction volume. For a clean installation, at least 5G of free space is recommended./var/lib >=10GB For a clean installation, Oracle Blockchain Platform SDK Docker images consume approximately 8GB /var/lib space.
CPU	2	or higher
hostname	[compute instance].[subnet].[dns vcn]	internal FDQN
IP	xxx.xx.xx.xxx	public IP of your instance

Set the timezone TZ variable

Make sure that you set the TZ variable in your profile, otherwise you will get an error when provisioning the blockchain instance.

• vi .bash_profile file
•  Add  TZ='Europe/Amsterdam'; export TZ to the file
• Save and quit (wq)
•  Log out
• Log in

Disable the firewall

Check if the firewall is running: sudo firewall-cmd --state

running
If it is running, stop it:
sudo systemctl disable firewalld
run the command again: sudo firewall-cmd --state
not running

You can of course update the firewall instead of disabling it, I was too lazy to type that up today 😁

Install Docker

1. Execute the following commands to install some required packages:

   sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
   sudo yum install -y yum-utils device-mapper-persistent-data lvm2

2. Add the repository

   sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

3. Install the docker community edition

   sudo yum install docker-ce docker-ce-cli containerd.io

4. Start docker and enable the start of docker on boot

   sudo systemctl enable --now docker.service

5. Check the version of docker

   sudo docker version

   Run hello world to see if docker is installed correctly

   docker run hello-world

Build the Instance

Now we are ready to install the SDK

• Download it from the Oracle website 
• Unzip to /usr/local/bcssdk
• Run sudo ./build.sh  This will run it with all the default:

Option	Attribute	Value
-d	package directory	/usr/local/bcssdk
-w	provision workspace directory	~/obcs_worksapce
-p	provision console port	3000

Create Instance

• Open the console: http://[IP ADDRESS]:3000
• Chose a username and password for your provisioning application and click ok
• This opens the console and you can create a founder with the following attributes:

Attribute	Value
Instance name	name you picked
host name	internal FQND
start port	port you opened in ingress
founder	yes
authorization	yes

The username password will be set to admin/Welcome1 when you check the "Authorization" box. The result can be seen below

Provision instance after building the SDK

Finally

Click on the name. This will open a browser, but it will say "not found". Replace the FQDN with the IP address, and leave the port.

When you do that, it warns about the certificate. Accept that and it prompts for username password.
Login using admin/Welcome1 and you will see your blockchain console!

http://[IP ADDRESS]:21003

Blockchain console after creating the instance

Happy coding 😀

Oracle BlockChain Service: creating a smart contract aka how to write a chaincode

In the first blog about blockchain, I used Oracle Compute Cloud Classic and installed MultiChain on it. Since then, Oracle has released a Blockchain Cloud Service with a lot of out of the box functionality, based on Hyperledger.

In this blog post I will describe how to create a smart contract for a webshop use case: getting offers from different suppliers for a specific order. I already know node.js so I will write the ChainCode in node. Note that go is also supported.

Prerequisites

• A running instance of Oracle Blockchain Service
• Node.js installed on your laptop

There are a number of steps involved in writing a smart contract (or chaincode).

1. Design the chaincode
2. Write a chaincode (in Node)
3. Deploy a ChainCode to a Peer 
4. Test the chaincode with Postman

Design 

Before you write a chaincode, you need to know what transactions need to be supported. In our example we have a webshop, that issues requests for shipping after ordering an item. Shippers can create an offer. If they are selected by the customer, they pickup the shipment. The customer receives the goods at the end of the cycle. For more information about designing the chaincode, see the hyperledger documentation

Write a ChainCode

The easiest way to write the chaincode is to download an example from the Oracle BlockChain Service and modify it.

1. Navigate to the Blockchain console and click on Developers tools.
2. Click on Download oracle samples
3. Download the Cardealer sample and unzip it
4. Navigate to [yourpath]\CarDealer\artifacts\src\github.com\node and copy cardealer_cc
5. Paste the cardealer_cc in a new folder where you want to store your code and rename it to shipment_cc
6. Leave the methods Init and Invoke as is and create methods to issue, offer, select, pickup and receive a shipment. 

        ---------------code snippet--------------------------------

        shipment.orderId = args[0];

        shipment.product = args[1].toLowerCase();

        shipment.customer = args[2].toLowerCase();

        shipment.shippingAddress = args[3];

        shipment.orderDate = parseInt(args[4]);

        if (typeof shipment.orderDate !== 'number') {

            throw new Error('5th argument must be a numeric string');

        }

        shipment.custodian = args[5].toLowerCase();

        shipment.currentState = shState.ISSUED;

        shipment.offers = [];

        // ==== Check if shipment already exists ====

        let shipmentAsBytes = await stub.getState(shipment.orderId);

        if (shipmentAsBytes.toString()) {

            console.info('This shipment already exists: ' + shipment.orderId);

            jsonResp.Error = 'This shipment already exists: ' + shipment.orderId;

            throw new Error(JSON.stringify(jsonResp));

        }

        // ==== Create shipment object and marshal to JSON ====

        let shipmentJSONasBytes = Buffer.from(JSON.stringify(shipment));

        // === Save shipment to state ===

        await stub.putState(shipment.orderId, shipmentJSONasBytes);

        -------------end code snippet --------------------------

Deploy the chaincode

After writing the chaincode, it needs to be deployed to the blockchain. In this example we will deploy it to the shipment channel using the quick start. This will instantiate it and use the default endorsement policy. Please note that channels and chaincodes can't be deleted after creating and deploying them.

1. Zip the code and the package.json in a zip
2. Click on "Deploy a new Chaincode" in the chaincode menu in the blockchain console.
3. Click on Quick Deployment
4. Fill out the right details






Upload the zipfile and wait until the dialog shows that the chaincode is instantiated and deployed succesfully. 
Enable the rest proxy by going to the chaincode and clicking on the hamburger menu. Click on "Enable on REST Proxy". 
Fill out the fields as shown in the figure below

Test the chaincode

Now that we have deployed the chaincode, we can test it using the REST proxy. Before you do this, make sure you have the right role associated with your user (RESTPROXY4_USER)

1. Open postman
2. Create a new "Post request" to issue a shipment
3. Go to the blockchain console and find the URL that is listed for the RESTProxy that you enabled for your chaincode
4. Create a request that looks as follows: 

curl -X POST \

  https://restserver:port/restproxy4/bcsgw/rest/v1/transaction/asyncInvocation \

  -H 'Authorization: Basic xxx' \

  -H 'Content-Type: application/json' \

  -H 'cache-control: no-cache' \

  -d '{

"args":[1,"iron","John Doe","Rembrandtlaan 22c Bilthoven","0330","webshop"],

"channel": "testshipping",

"chaincode": "shipment",

"chaincodeVer":"1.0",

"method": "issueShipment"

}'

The result should like this:

{

    "returnCode": "Success",

    "txid": "a4f5e851734f7e3ebdfa0761bfd54bab090cdaf08266363fe2451eacc3a14826"

}

Next steps

You can now query the result of this transaction, read the shipment etc.

Happy coding! 😃