Streamline the process of developing, testing, and deploying a smart contract

Learn the process of using IBM Blockchain Platform’s VSCode extension to streamline the process of developing, testing, and deploying a smart contract. Once you finish this tutorial, you will understand how to quickly develop, demo, and deploy your blockchain application on a local Hyperledger Fabric network using VSCode. This tutorial assumes some basic understanding of Hyperledger Fabric.

Watch the videos

Learning objectives

Install the IBM Blockchain Platform VSCode extension

Create a new JavaScript smart contract

Package a smart contract

Create, explore, and understand a Hyperledger Fabric network

Deploy the smart contract on a local Hyperledger Fabric instance

Use a Node.js SDK to interact with the deployed smart contract package

Step 1. Get started

The first thing you need to do is to install the IBM Blockchain Platform VSCode extension. To do this, you
need to install the latest version of VSCode; to see if you have the latest
VSCode extension, go to
Code > Check for Updates. If VSCode crashes at this point (which it did for me), it likely
means you don’t have the latest version. If your VSCode crashes, check the troubleshooting section below. Otherwise, update your VSCode, and once you’re done, click on extensions in the
sidebar on the left side of your screen. At the top, search the extension marketplace for
IBM Blockchain Platform. Click Install and then click reload. Now you should be all set to use the extension!

Step 2. Create a new smart contract project

To create a smart contract project:

Click on your newly downloaded IBM Blockchain Platform extension. It should be the extension
all the way at the bottom of the left sidebar.

Note: the .gifs may not exactly match the above smart contract, but this is the one
you should have in your lib/my-contract.js file now!

Let’s examine the functions you just defined. The instantiate function creates a greeting
object and then stores that on the ledger with the key GREETING.
The transaction1 function takes the Hyperledger
Fabric context and one argument, arg1, which is used to store a greeting as defined by the user.
The ctx.stub.putState method is used to record the greeting on the ledger and then you
return that object back. Save the file and proceed!

Step 4. Package the smart contract

Now that you have created your smart contract and understand which functions you’ve defined,
it’s time to package it so you can install it on a peer.

In the left sidebar, click on the IBM Blockchain Platform icon (it looks like a square).
In the top-left corner, you will see all of your smart contract packages. You should
see demoContract@0.0.1 if everything went well.

Step 5. Install the smart contract

Ok, you’re more than halfway there. Now for the fun part! Let’s install this contract on the peer!
To do this, you must first connect to a Hyperledger Fabric network. The network that comes with
the VSCode extension is perfect for development — it offers the minimal resources to develop and
test your contract.

The following Docker containers are started on your local machine, each with a different role in
the network: Orderer, Certificate Authority, CouchDB, and Peer.

To start your network, look at your IBM Blockchain Platform extension, at the bottom-right corner
where it says Blockchain Connections.

You should see local_fabric. Go ahead and click that. It should automatically run a script and you should see the following output:

Step 6. Instantiate the smart contract

From the IBM Blockchain extension, in the bottom-left corner, under Blockchain Connections,
right-click on mychannel and then on Instantiate / Upgrade Smart Contract.

The extension will then ask you which contract and version to instantiate — choose demoContract@0.0.1.

The extension will then ask you which function to call — type in instantiate.

Next, it will ask you for the arguments. There are none, so just hit enter.

The extension will do some work, and then in the bottom-right corner you should see that the contract
was successfully instantiated. Hooray!!

Step 7. Import the certificate and key

At this point, you need to start interacting a bit more closely with your
Fabric instance. You’ll need to prove to the certificate authority that you are allowed
to create a digital identity on the network, and that is by showing the certificate
authority your certificate and private key. For the sake of keeping this tutorial as short as possible,
I have a GitHub repo with all the certs, keys, and scripts you
will work with, so go ahead and git clone this repo in a directory of your choice, but outside
the demoContract directory.

In a terminal, navigate to a directory to clone the GitHub repository into.

Skim the cert and key files — they contain your certificate and private key
which will be used to request an identity from the certificate authority. There is
also an addIdentity.js script which has the following code:

This code creates an identity by passing in your certificate and private key. Notice that you are using the fabric-network NPM package to call the createIdentity method, and then using the import function to add that identity to your wallet. The most important line in this file is await wallet.import(identityLabel, X509WalletMixin.createIdentity('Org1MSP', cert, key));, which actually creates a new MSP identity using your cert and key file. This Membership Service Provider (MSP) identity will be able to connect to the
network and invoke smart contracts.

Step 8. Add an Identity

Now that you have an identity that can interact with your network, you need to
to run npm install to install all the dependencies that are needed to connect to your local Fabric network.

Run npm install in the VSCodeLocalNetwork.

Then, run node addIdentity. You should see that this command creates a new folder called _idwallet
and populates that folder with the MSP identity, which in this case goes by the name of
User1@org1.example.com. Nice job!

Step 9. Update the network ports

Next, open the network.yaml in the VSCodeLocalNetwork folder. You will use this file to connect
to your Docker containers running locally.

Next, look for fabric-peer,fabric-ca, and fabric-orderer in the docker ps logs.
It may be hard to read, so be careful here. The 5-digit number is the port
number that you need to update in the appropriate place in the network.yaml file.
Update the peer, CA, and orderer’s URL field as shown in the preceding .gif.

In the example above the ports in network.yaml would be set as follows:

orderers:
orderer.example.com:
url: grpc://localhost:32823

Then the peer:

peers:
peer0.org1.example.com:
# this URL is used to send endorsement and query requests
url: grpc://localhost:32827

Then the CA:

certificateAuthorities:
ca-org1:
url: http://localhost:32822

Great job! Save the file.

Step 10. Invoke the smart contract

Ok, so you’ve instantiated your contract and created your identity, so now what?
Well now, it’s time to actually invoke the functions in your contract! To do this,
you will need to invoke a script from your VSCodeLocalNetwork directory.

From your git clone, you should have a file called invoke.js. Let’s examine this file.

After you create an instance of the fabric-network, you connect to the network with the following code:

await gateway.connect(connectionProfile, connectionOptions);

Notice here that the connection profile is the network.yaml file that you updated in the previous step, and the connectionOptions is an object that contains the credentials from your _idwallet directory.

After you connect to the network, you need to specify the channel to connect to, which
in this case happens to be mychannel. This line connects to your channel:

const network = await gateway.getNetwork('mychannel');

Your channel may have many contracts installed, so in the next line, you need to specify which contract
to invoke. In this case, it would be demoContract.

const contract = await network.getContract('demoContract');

The final part of your script picks which function to invoke and specifies the arguments. In
this case, you are invoking transaction1 with an arg of hello, as can be seen here:

Step 11. Update the smart contract

In the previous step, you updated the ledger by using the putState API, passing in a key and a value.
The key happened to be “GREETING” and the value happened to be the object:

{
text: 'hello'
}

The last thing you should learn is how to query — how to retrieve data from the ledger. You will do this
by using the getState API, which takes in a key and returns the value associated with that key, if it finds it.

The code adds an addMember function, which takes in arguments from the user such as
email, name, address, and phone number, and saves that data on the ledger as a key-value pair.

This code also adds a query function — this function takes in one argument, which is the key to look up.
The function returns the value associated with a given key, if there is any.

Update the package.json file such that line 3, which contains the version number, now reads:

"version": "0.0.2",

Save the file.

After you have updated package.json, go back and follow steps 3 and 4 to package and install your
new smart contract.

To upgrade your existing smart contract to your new version, in the bottom left corner
of your IBM Blockchain extension, expand the Instantiated Smart Contract link, and then
right-click on demoContract and choose Upgrade Smart Contract. If all goes
well, you should get a notification in the bottom right corner saying Successfully upgraded smart contract.

The main difference is that in this file, you use the queryByChaincode API, which
reads from the ledger. This is very important. In your invoke.js file, you submit
transactions to the ledger, which will all get written to the ledger
but here, in your query.js file, you will not update the ledger.

The output should be similar to the one above, except with Arvind’s data.

Summary

Nice work! You learned how to create, package, install, instantiate,
and invoke a smart contract using Hyperledger’s newest APIs. At this point,
you can focus on developing your smart contract and updating your my-contract.js
file knowing that you have taken care of the networking aspects of blockchain.
You can also successfully invoke and update your ledger using just VSCode,
Node.js, and Docker. Please, please, please reach out to me if there are bugs —
comment on this post and I will fix them. Thanks so much for
reading this tutorial. I hope you enjoyed it! Horea Blockchain out!