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: This is the first of a three-part tutorial series. Part 2 builds on this, adding queries to the contract to report on the full transaction history of a commercial paper stored in the ledger.

Figure 1: “Papernet” — overview of commercial paper organizations used in this tutorial series

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 Help -> 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 (“Package a Smart Contract”), 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. Using the IBM Blockchain Platform from the left sidebar, start up a local development runtime Fabric environment — the IBM Blockchain Platform VSCode extension conveniently provides these local dev operations (such as start, stop, teardown, restart, etc.) for you. If you’ve already got an IBM Blockchain Platform VSCode extension Fabric development environment running, that can be used, too (it’s one started by the extension recently). Click on the ellipsis (“…”) button in the section “Local Fabric Ops” and “Start Fabric Runtime.” Check your Output terminal pane at the bottom; you should see a message indicating that you’ve successfully submitted the proposal to join the channel. If this is the case, you can proceed.

2. Now click on the + Install item under the Smart Contracts sidebar panel, and in the popup (up top) you’ll see a message prompting you to select a peer to install the contract on. Select the peer offered.

3. Next, choose the papercontract version 0.0.1 (see popup prompt) as the contract to install. You should then get a message in “Output” indicating that it was successfully installed.

4. Under the IBM Blockchain Platform sidebar panel Fabric Local Ops, select the channel “mychannel” and then right-click and choose to “instantiate a smart contract.”

5. Select papercontract version 0.0.1 as the contract to instantiate.

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

7. When you’re prompted to enter arguments, hit ENTER to leave it blank (there are no arguments).

   After a minute or so, you should see a progress message in the bottom right indicating that it is instantiating. Check the output pane to see if it was successfully instantiated.

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. For the purposes this tutorial, you will use the default identity available in the VSCode extension to execute the transactions in turn. Figure 6 summarizes how they would interact using client applications and wallets (provided as employees of each company organization).

Figure 6. “Papernet” — overview of transaction flow

Transaction 1: Execute an issue transaction as Isabella@MagnetoCorp

1. From the IBM Blockchain Platform VSCode sidebar panel, locate the “Fabric Gateways” sub-panel and click on the “Admin” identity under “local_fabric.”

2. Expand the “mychannel” twisty and then the “papercontract” twisty, in turn. You should see a list of transaction names, one of which is “issue.”

3. Highlight the “issue” transaction and right-click “Submit Transaction.” A pop-up window should appear at the top.

4. When prompted to enter parameters, copy and paste the following parameters (note that each parameter has single quotes and they are separated by commas):

   MagnetoCorp,00001,2020-05-31,2020-11-30,5000000
   

   Show more

5. Press ENTER and you should then see a message (in the Output pane) indicating that the transaction was successfully submitted.

Transaction 2. Execute a buy transaction as Balaji@DigiBank

1. Now highlight the buy transaction from the list of transactions and right-click “Submit Transaction.” A pop-up window will appear.

2. When prompted, copy and paste the following parameter string:

   MagnetoCorp,00001,MagnetoCorp,DigiBank,4900000,2020-05-31
   

   Show more

3. Press ENTER and you should then see a message (in the Output pane) indicating that the transaction was successfully submitted.

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. Now highlight the redeem transaction from the list of transactions and right-click “Submit Transaction.” A pop-up window will appear.

2. When prompted, copy and paste the following parameter string:

   MagnetoCorp,00001,DigiBank,2020-11-30
   

   Show more

3. Press ENTER and you should then see a message (in the Output pane) indicating that the transaction was successfully submitted.

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.)

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.

To complete the next tutorials (Parts 2 and 3), you’ll need to clone some sample artifacts (code, script files, etc.) from GitHub. To do this, open up a terminal window, locate your desired directory, and paste in the following commands:

cd $HOME
git clone https://github.com/mahoney1/commpaper

The repository should now be successfully cloned, in preparation for the next stage.

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!