Run a commercial paper smart contract with the IBM Blockchain VSCode extension

Using the new IBM Blockchain Platform VSCode extension and the latest Hyperledger Fabric features, developing blockchain applications and smart contracts couldn’t be simpler! The extension is an intuitive tool that enables developers to discover, code, test, debug, package, and deploy smart contracts to a blockchain network in a single tool. And what better way to illustrate than to show it in action! You can read more about it in this announcement. In addition, while you’re working with a local Fabric environment below, you’ll soon be able to deploy the example you build here to your own IBM Blockchain Platform Cloud instance.

This tutorial shows you how to deploy a sample commercial paper smart contract to the Fabric blockchain using the IBM Blockchain Platform VSCode extension, and then run it. You’ll also interact with the contract and execute transactions using a simple command-line application. The sample is available from GitHub.

Note: The next tutorial in this series will build on this, adding queries to the contract to report on the full transaction history of a commercial paper stored in the ledger. (Stay tuned for Part 2.)

Figure 1. “Papernet” — overview of commercial paper use case

Background

Commercial paper has existed since at least the 19th century. What is it? Well, there is a fantastic description of it in the latest Fabric Developing Applications docs, and the scenario depicted makes fascinating reading. In short, it’s a way for large institutions to obtain funds to meet short-term debt obligations. For example, let’s say MagnetoCorp issues a commercial paper (or “CP”) on April 1 with a face value of $1 million. It promises to pay the bearer (the “paper” is transferable, so it can be re-sold) this amount in 6 months’ time (October 1, the maturity date). However, on May 1 the CP is purchased by an investment bank (DigiBank) for a discounted price — $0.96 million (valued at $1 million in 6 months’ time). If DigiBank holds this until maturity (managing its investment risk in the meantime), then as the bearer, it can redeem it at face value ($1 million) with MagnetoCorp — a profit of $40,000. This is effectively the interest earned on an investment of $0.96m for 6 months. Most investors in the commercial paper marketplace tend to hold it until maturity, but there are varying marketplaces, options, and strategies … far beyond the scope of this little explainer.

Prerequisites

You will need to have the following installed in order to use the extension:

• Node v8.x or greater and npm v5.x or greater
• Yeoman (yo) v2.x
• Docker version v17.06.2-ce or greater
• Docker Compose v1.14.0 or greater
• VSCode 1.28.2 or higher

You can check your versions using the following commands:

• node –version
• npm –version
• yo –version
• docker –version
• docker-compose –version

Estimated time

After the prerequisites are installed, this should take approximately 45 minutes to complete.

Preparation

Before starting, you need to do a little housekeeping. Run the following command to kill any stale or active containers:

docker rm -f $(docker ps -aq)

Clear any cached networks and volumes:

docker network prune ; docker volume prune

Finally, if you’ve already run through this tutorial or tried it previously, you’ll also want to delete the underlying chaincode image for the commercial paper smart contract. If you’re going through this content for the first time, then you won’t have this chaincode image on your system (so you won’t need to perform this next step). Get the container ID using:

docker rmi $(docker images -q dev*)

It will remove any lingering container images related to previous instantiated papercontract containers (prefixed dev-peer0).

Scenario

MagnetoCorp issues a commercial paper; this is performed by Isabella, a MagnetoCorp employee. An investor, DigiBank (through its investment trader, Balaji) purchases the commercial paper. DigiBank holds it for a period of time, and then redeems it at face value with MagnetoCorp for a small profit. You can read more about this commercial paper example in this Hyperledger Fabric docs tutorial.

Steps

Step 1. Get the commercial paper sample

From a terminal window, clone the Fabric samples repo (and specifically the “master” branch) to your $HOME directory:

git clone https://github.com/hyperledger/fabric-samples

Step 2. Launch VSCode and install the IBM Blockchain Platform extension for VSCode

You can launch VSCode from the task bar, or by typing code in a terminal window.

Now you need to install the IBM Blockchain Platform VSCode extension — you’ll need to install the latest version of VSCode to do this. To see if you have the latest version, go to Code -> Check for Updates. If VSCode exits at this point, it likely means you don’t have the latest version. If so, update your VSCode (using the link provided earlier) and once you’re done, click on extensions in the sidebar on the left side of your screen. At the top, search the extensions marketplace for IBM Blockchain Platform and click on Install. You should see a status of “Installing” and eventually “Installed” — then click on reload.

Figure 2. Find and install the extension from VSCode marketplace

Step 3. Open the commercial paper contract

1. In VSCode, choose File > Open Folder, and select the contracts folder by navigating to the $HOME/fabric-samples/commercial-paper/organization/magnetocorp directory. This is your top-level project folder for this tutorial.

2. Click on the Explorer icon (top left) and open the contract folder under $HOME/fabric-samples/commercial-paper/organization/magnetocorp/.

   Figure 3. Open the commercial paper sample project in VSCode

3. Explore the papercontract.js file, which is located in the lib subfolder. It effectively orchestrates the logic for the different smart contract transaction functions (issue, buy, redeem, etc.), and is underpinned by essential core functions (in the sample contract) that interact with the ledger. The link provided in the introduction section above explains the concepts, themes, and programmatic approach to writing contracts using the commercial paper scenario. Take some time to read that explainer and then resume here.

4. Go back to the contract folder by clicking on the folder name on the left in the VSCode Explorer. It’s important to do so before the next step.

   Figure 4. Choose the contract folder

Step 4. Package the smart contract

1. Click on the package.json file in the Explorer palette and edit the “name” field; change the name to papercontract.

   Figure 5. Editing the package.json file

   

2. Edit these existing “dependencies” entries (as necessary). They should read as follows:

     "fabric-contract-api": "~1.4.0",
    "fabric-shim": "~1.4.0"
   

   Show more

   Now save (CTRL + S) the file.

3. Click on the IBM Blockchain Platform sidebar icon. When you do this the first time, you may get a message that the extension is “activating” in the output pane.

4. Click on the “+” symbol (“Add a new package”), under the ‘Smart Contract packages’ panel, to package up the commercial paper smart contract package for installing onto a peer. It will be called something like papercontract@0.0.1.

Step 5. Install the smart contract on a running Fabric

1. Let’s start up a sample Fabric runtime environment from the downloaded Hyperledger Fabric samples to run the smart contract. To that end, we’ve provided a sample connection.json to import into the IBM Blockchain VSCode environment; the beauty here is that you can connect to the local Fabric provided, or to one you’ve already got up and running. The Fabric sample uses its own “basic-network” sample. In a terminal window copy the following command sequence:

   cd $HOME/fabric-samples/basic-network

   ./start.sh

   Wait for the output message to indicate that the Fabric network has been started (message: “Successfully submitted proposal to join channel”).

2. You’ll also need to download the following commpaper sample Github repository (“repo”) as it has tutorial artifacts, including the connection profile for the VSCode extension that’s used to connect to the blockchain network. You’ll import it using the IBM Blockchain Platform VSCode extension (as well an admin certificate in the same repo that you’ll use in the demo):

   cd $HOME

   git clone https://github.com/mahoney1/commpaper

3. Back in VSCode, click on the “IBM Blockchain Platform” sidebar icon in VSCode (at the bottom left). You’ll see an “IBM Blockchain Connections” sidebar panel.

4. Next, collapse the Smart Contract Packages using the twisty and expand the Blockchain Connections panel.

5. Click the Add New Connection button or icon. Enter “myfabric” for the connection name and then browse to find and import the connection.json file from the commpaper repo that you cloned earlier.

6. Next, browse and select the AdminCert for the certificate file to import and “browse … select” the Adminkey for the key file.

7. You should now be able to click on myfabric and see the channel mychannel become active. Click mychannel to drill down and see the only peer in the basic-network network.

8. Right-click on the peer node, peer0.org1.example.com, and elect to Install Smart Contract. Then choose the papercontract@0.0.1 package from the list up top.

9. Next, highlight the channel mychannel and right-click and choose to Instantiate Smart Contract; select papercontract as the contract to instantiate.

10. Paste in the string org.papernet.commercialpaper:instantiate when prompted to enter a function name to call, and hit ENTER.

11. When you’re prompted to enter arguments, hit ENTER to leave it blank (there are no arguments in this case). After a minute or so, you should see a progress message in the output pane.

The instantiation process will take about a minute while it builds the chaincode container with the smart contract code and dependencies. The Instantiated Smart Contracts twisty will appear inside VSCode Extension panel in about 30 seconds to a minute. The smart contract container is being built.

Step 6. Execute the commercial paper smart contract transactions from client applications: MagnetoCorp and DigiBank

So far, you’ve installed and instantiated your smart contract on the blockchain. Now it’s time to try out the smart contract transactions.

The commercial paper scenario describes contract transactions that are run by employees of two different organizations, MagnetoCorp and DigiBank. The sample certificate/keys required to transact as two different blockchain identities are provided with the basic-network sample. At this point, the relevant employee identities (certificate/key combination) need to be imported into their private wallet to use with their respective client apps, which they’ll use to transact on the commercial paper papernet marketplace. Let’s start with Isabella at MagnetoCorp. The diagram below summarises how she would interact as an employee of that company.

Figure 6. “Papernet” — overview of transaction flow

Transaction 1: Execute an issue transaction as Isabella@MagnetoCorp

1. Change directory to MagnetoCorp’s application directory:

   cd commercial-paper/organization/magnetocorp/application

2. Install the NodeJS application dependencies (you may get some “WARNs” in the output — you can ignore those for now):

   npm install

3. Run the wallet import script. This will import the User1 sample cert for this Org1 user into an identity/user/isabella/wallet folder, which is located under the same sub-tree as the application folder.

   node addToWallet.js

   A simple message of “done” will show that the import task is complete.

4. Now execute the first commercial paper transaction from the application directory — the “issue” transaction:

   node issue.js

   You should get messages confirming it was successful:

   Figure 7. The “issue” transaction

Transaction 2. Execute a buy transaction as Balaji@DigiBank

1. Change the directory to DigiBank’s application directory:

   cd ../../digibank/application

2. Install the NodeJS application dependencies (you may get some “WARNs” in the output — you can ignore those for now):

   npm install

3. Run the wallet import script. This will import the sample cert for this Org2 user into an identity/user/balaji/wallet folder, which is located under the same sub-tree as the application folder.

   node addToWallet.js

   A simple message of “done” will show that the import task is completed.

4. Now execute the “buy” commercial paper transaction from the application directory:

   node buy.js

   You should get messages confirming it was successful:

   Figure 8. The “buy” transaction

Transaction 3. Execute a redeem transaction as Balaji@DigiBank — six months later

The time has come in this commercial paper’s lifecycle for the owner (DigiBank) to redeem the commercial paper at face value and recoup the investment outlay. A client application called redeem.js performs this task using Balaji’s certificate (from his wallet) to perform it.

1. From the same directory, commercial-paper/organization/digibank/application, run the redeem.js script:

   node redeem.js

   You should get messages confirming it was successful:

   Figure 9. The “redeem” transaction — the last in the lifecycle

Well done! You’ve completed this tutorial and successfully interacted with the smart contract, which demonstrates a simple lifecycle of a commercial paper instance (with 3 transactions) on the blockchain.

Summary

You’ve now learned how to deploy a simple yet substantial commercial paper smart contract sample to a Fabric blockchain network. You’ve seen how it can create, package, install, and instantiate a smart contract that’s developed using Hyperledger Fabric’s newest programming model. (Clearly, the extension provides a lot more — such as the develop/debug/test lifecycle of a developer — beyond the scope of this particular tutorial.) You’ve interacted as employees of two different organizations, using simple client applications and wallets that contain identities (provided by their respective organisations) to carry out the transactions.

My next tutorial will concentrate on another application perspective, querying the ledger — for example, getting the history of transactions for a particular asset. I’ll answer questions like:

• What was the “paper” trail? (Get it?)
• Who performed the transactions (the identities involved)?
• Exactly when did they take place?
• What exactly were the changes made (i.e. the “deltas”) for each transaction in that history?

This means adding query functionality to the smart contract, as well as some “getters” to get you the right information from the historical transactions. These results are sent back to the respective application clients.

If you haven’t done so, I recommend reading Horea Porutiu’s excellent introductory tutorial, Develop a smart contract with the IBM Blockchain Platform VSCode extension, and try creating your own small starter smart contract.

Thanks for joining me!