Develop a smart contract with the IBM Blockchain Platform VS Code extension

Learn how to use IBM Blockchain Platform’s Visual Studio Code 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 VS Code. This tutorial assumes some basic understanding of Hyperledger Fabric.

Learning objectives

This tutorial will show you how to:

  • Install the IBM Blockchain Platform extension for VS Code
  • Create a new smart contract project
  • Package a smart contract
  • Start and use the local, pre-configured Hyperledger Fabric runtime
  • Deploy the smart contract on local_fabric
  • Transact on your locally-deployed smart contract

Prerequisites

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

  • VS Code version 1.32 or greater
  • Node v8.x or greater and npm v5.x or greater
  • Docker version v17.06.2-ce or greater
  • Docker Compose v1.14.0 or greater

If you are using Windows, you must also ensure the following:

  • Your version of Windows supports Hyper-V and Docker:
    • Windows 10 Enterprise, Pro, or Education with 1607 Anniversary Update or later
  • Docker for Windows is configured to use Linux containers (this is the default)
  • You have installed the C++ Build Tools for Windows from windows-build-tools
  • You have installed OpenSSL v1.0.2 from Win32 OpenSSL, as follows:
    • Install the normal version, not the version marked as “light”
    • Install the Win32 version into C:\OpenSSL-Win32 on 32-bit systems
    • Install the Win64 version into C:\OpenSSL-Win64 on 64-bit systems

You can check your installed versions by running the following commands from a terminal:

  • node --version
  • npm --version
  • docker --version
  • docker-compose --version

Estimated time

After the prerequisites are installed, it should take you about 20-30 minutes to complete this tutorial.

Steps

Before you get started, you’ll need to install the IBM Blockchain Platform VS Code extension. To do this, you should install the latest version of VS Code; to see if you have the latest VS Code extension, go to Code > Check for Updates. 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. You should now be all set to use the extension!

1

Create a new smart contract project

The extension can generate a smart contract skeleton in your chosen Hyperledger Fabric-supported programming language. This means you start with a basic but useful smart contract rather than a blank sheet!

For the purposes of this tutorial, we’ll use TypeScript as the example language.

In VS Code, every command can be executed from the Command Palette (press Ctrl+Shift+P, or Cmd+Shift+P on MacOS). All of this extension’s commands start with IBM Blockchain Platform:. In these tutorial steps, we’ll show you where to click in the UI, but look out for comment boxes like this one if you want to know the Command Palette alternatives.

  1. In the left sidebar, click on the IBM Blockchain Platform icon (it looks like a square, and will probably be at the bottom of the set of icons if this was the latest extension you installed).

  2. Mouse-over the SMART CONTRACT PACKAGES panel, click the “” menu, and select Create Smart Contract Project from the dropdown.

    Command Palette alternative: Create Smart Contract Project

  3. Choose a smart contract language. JavaScript, TypeScript, Java, and Go are all available. For the purposes of this tutorial, please choose TypeScript.

  4. The extension will ask you if you want to name the asset in the generated contract. (This will default to “MyAsset,” but you’re welcome to have some fun. 😉 What do you intend to use your blockchain for? Knowing this will determine what type of asset you will create, update, and read from the ledger: “Radish?” “Pineapple?” “Penguin?” Pick whatever you like! For this tutorial, we’ll be boring and stick with “MyAsset.”

    Pro Tip: If you decide to change the name of your asset, remember to swap out “MyAsset” for whatever you named it in future steps!

  5. Choose a location to save the project. Click Browse, then click New Folder, and name the project whatever you want (for example, “demoContract”).

    Pro Tip: Avoid using spaces when naming the project!

  6. Click Create and then select the new folder you just created and click Save.

  7. Finally, select Add to workspace from the list of options.

    The extension will generate a skeleton contract based on your selected language and asset name. Once that’s done, you can navigate to the Explorer view (most likely the top icon in the left sidebar, which looks like a “document” icon) and open the src/my-asset-contract.ts file to see your smart contract code scaffold. Great work! You’ve got yourself a smart contract — now, let’s take a look at its contents…

2

Understand the smart contract

The generated smart contract code scaffold provides a good example of some common operations for interacting with data on a blockchain ledger. If you’re in a big rush, you can skip this section, but why not stay a while and learn the basic anatomy of a smart contract?

Notice the lines that start with @Transaction: These are functions that define your contract’s transactions — the things allow you to interact with the ledger.

Skipping over the first one (myAssetExists), take a look at the createMyAsset function:

    @Transaction()
    public async createMyAsset(ctx: Context, myAssetId: string, value: string): Promise<void> {
        const exists = await this.myAssetExists(ctx, myAssetId);
        if (exists) {
            throw new Error(`The my asset ${myAssetId} already exists`);
        }
        const myAsset = new MyAsset();
        myAsset.value = value;
        const buffer = Buffer.from(JSON.stringify(myAsset));
        await ctx.stub.putState(myAssetId, buffer);
    }

The empty brackets in @Transaction() tell you that this function is intended to change the contents of the ledger. Transactions like this are typically submitted (as opposed to evaluated) — more on that later in this tutorial. The function is called createMyAsset and it takes myAssetId and a value, both of which are strings. When this transaction is submitted, a new asset is then created, with the key myAssetId and the value value. For example, let’s say you were to create “001,” “A juicy delicious pineapple”; then later on, when you read the value of key 001, you’ll learn that the value of that particular state is A juicy delicious pineapple.

Now, take a look at the next transaction:

    @Transaction(false)
    @Returns('MyAsset')
    public async readMyAsset(ctx: Context, myAssetId: string): Promise<MyAsset> {
        const exists = await this.myAssetExists(ctx, myAssetId);
        if (!exists) {
            throw new Error(`The my asset ${myAssetId} does not exist`);
        }
        const buffer = await ctx.stub.getState(myAssetId);
        const myAsset = JSON.parse(buffer.toString()) as MyAsset;
        return myAsset;
    }

This one starts with @Transaction(false) — the “false” means that this function is not typically intended to change the contents of the ledger. Transactions like this are typically evaluated. You’ll often hear such transactions referred to as “queries.” As you can see, this function only takes myAssetId and returns the value of the whatever state that key points to.

Take a look at the other transactions in the contract at your leisure. Then you can move on to packaging and deploying that contract so you can start using it.

3

Package the smart contract

Now that you have created your smart contract and understand the transactions therein, it’s time to package it. Smart contract projects are packaged into .CDS files — a special type of file that can be installed on Hyperledger Fabric peers.

  1. In the left sidebar, click on the IBM Blockchain Platform icon.

  2. Mouse-over the SMART CONTRACT PACKAGES panel, click the “” menu, and select Package a Smart Contract Project from the dropdown.

    Command Palette alternative: Package a smart contract project

  3. You should see a new package on the list, demoContract@0.0.1 (or the name you gave to the packaged contract), if everything went well.

    The package you just created can be installed onto any Hyperledger Fabric peer (running at the correct version). For example, you could right-click and choose Export Package, then deploy it into a cloud environment using the IBM Blockchain Platform operational tooling console. You’ll learn how to do this later; for now, you’ll deploy the package locally on the runtime that comes pre-configured with the VS Code extension, so there’s no need to export your package just yet!

4

Local Fabric Ops

The panel titled LOCAL FABRIC OPS (in the IBM Blockchain Platform view) allows you to operate a simple Hyperledger Fabric runtime using Docker on your local machine. Initially, it will be stopped, and you should see:

Local Fabric runtime is stopped. Click to start.

Click that message and the extension will start spinning up Docker containers for you. You should then see the message “Local Fabric runtime is starting…” with a loading spinner, and when the task is complete you will see a set of expandable/collapsible sectioned labelled “Smart Contracts,” “Channels,” “Nodes,” and “Organizations.”

Command Palette alternative: Start Fabric Runtime

That’s all you need to do in this step, but whilst you’re waiting for local_fabric to start up, here’s a little more about what it comprises.

We won’t go into too much detail in this tutorial, but here are a few handy facts to know:

  • The Smart Contract section shows you the Instantiated and Installed contracts on this network. The next couple of steps in this tutorial will show you how to install then instantiate the smart contract that you’ve packaged.
  • Under Channels there is a single channel called “mychannel.” In order for a smart contract to be used, it must be instantiated on a channel. This happens in the next step of this tutorial, after you first install the contract on a peer.
  • The Nodes section contains a single peer (peer0.org1.example.com). The naming follows Hyperledger Fabric conventions, and you can see from the “org1” part that this peer is owned by Org1. (You may see a little infinity-symbol after the peer name indicating that it is currently in development mode — this can be toggled on or off via the right-click menu, but you don’t need to worry about it for now.)
  • There is also a single certificate authority (CA), ca.org1.example.com, and a single orderer node, orderer.example.com. Again, you’ll learn more about these node types when building your own network later; for now, it is enough to know that they’re essential parts of the network, so the extension has created them for you.
  • There is a single organization in this simple blockchain network called “Org1.” Recall that Org1 owns the peer you saw in the Nodes section. A network with just a single organization isn’t very realistic for real-world use, as the whole point is to share a ledger between multiple organizations, but it’s sufficient for local development purposes. Under Organizations, you will see Org1MSP: This is Org1’s MSP ID. You don’t need to worry too much about this right now: membership services providers (MSPs) will be covered in later tutorials when you start building your own network.
  • If you’re a big Docker fan, you may find it useful to know that the following containers are started on your local machine: Orderer, Certificate Authority, CouchDB, and Peer.

Now that you’ve started up the local Fabric runtime, it’s time to install and instantiate your smart contract…

5

Install the smart contract

In a real network, each of the organizations that will be endorsing transactions will install the smart contract on their peers, then the contract will be instantiated on the channel. Your basic local Fabric runtime only has a single organization (Org1) with a single peer (peer0.org1.example.com) and a single channel (mychannel).

So, you only have to install the contract on that single peer, and then you will be able to instantiate it in mychannel. Here’s how to do this:

  1. In the LOCAL FABRIC OPS panel, look for + Install (under Smart Contracts > Installed) and click it.

  2. You’ll be asked to choose a peer. Pick the only option, peer0.org1.example.com.

  3. You’ll then be asked to choose a package to install. Pick demoContract@0.0.1.

    You should see demoContract@0.0.1 appear under the Smart Contracts > Installed list.

    Command Palette alternative: Install Smart Contract

That’s it — job done! Next up, you’ll instantiate the smart contract…

6

Instantiate the smart contract

The installed smart contracts aren’t ready to be invoked by client applications yet: You need a shared instance of the contract that all organizations in the network can use. In your simplified local dev network with just one organization, this is a bit of a moot point. However, as you’ll see in later tutorials, when multiple organizations are involved they must individually install the same contract on their respective peers before the group can instantiate on their shared channel. So it’s useful to be thinking about this deployment as a two-stage process even at this early stage: This will save you some surprises later!

For now, though, you’ve got your contract installed on all (one) of the peers that participate in mychannel so you can go ahead and instantiate:

  1. In the LOCAL FABRIC OPS panel, look for + Instantiate (under Smart Contracts > Instantiated) and click it.

  2. You’ll be asked to choose a channel. Pick the only option, mychannel.

  3. You’ll then be asked to choose a smart contract to instantiate. Pick demoContract@0.0.1.

  4. You’ll then be asked what function to call. If you wanted to use a specific function as part of your instantiation, you could enter something here. You’ll see that happen in future tutorials, but for now just hit Enter to skip this step.

  5. You’ll then be asked if you want to provide a private data configuration file. For this tutorial just click No — you’ll find out more about this in future tutorials.

    Instantiation can take a while longer than installation — watch out for the success message and demoContract@0.0.1 appearing in the Smart Contracts > Instantiated list to confirm that it’s worked!

    Command Palette alternative: Instantiate Smart Contract

7

Submit and evaluate transactions

Fabric gateways are connections to peers that participate in Hyperledger Fabric networks, which can be used by client applications to submit transactions. When you started the local runtime in LOCAL FABRIC OPS, a gateway was automatically created for you as well. You’ll find it under FABRIC GATEWAYS and it’s called “local_fabric.”

To use a gateway, you also need an identity that’s valid for transacting on the network in question. Again, for the local Fabric runtime, this has already been set up for you. Observe that under FABRIC WALLETS there is a wallet called local_fabric_wallet, which contains an ID called admin. If you hover your mouse over local_fabric in the FABRIC GATEWAYS panel, you will see that it tells you “Associated wallet: local_fabric_wallet.”

So you’ve got a gateway and an associated wallet with a single identity in it — this means the gateway is ready to be used.

  1. Click on local_fabric (under FABRIC GATEWAYS) to connect via this gateway. You will now see “Connected via gateway: local_fabric, Using ID: admin” and a collapsed section labelled Channels.

  2. Expand Channels and then expand mychannel and demoContract@0.0.1. You will see a list of all the transactions that were defined in your smart contract.

  3. Now you need to create an asset. Right-click on createMyAsset and select Submit Transaction. You will be asked to provide arguments for the transaction: Try ["001", "a juicy delicious asset"] (or whatever key and value you like, but make sure you remember the key you use!).

    Pro tip: Arguments are submitted as JSON, so make sure you type the inputs exactly as shown, so that you’re submitting an array of 2 strings as required by this transaction.

    Command Palette alternative: Submit Transaction

  4. You will then be asked to set the transient data for the transaction. Don’t worry about this for now; we will cover it in a later tutorial. For now, just hit Enter.

  5. Next, submit updateMyAsset in a similar way. This time, for the arguments, provide the same key and a different value, such as ["001", "a tremendously delicious asset"]. So now the value of key 001 on your ledger should be “a tremendously delicious asset.” Let’s check that by reading the value back…

  6. readMyAsset is for reading from rather than writing to the ledger, so this time select Evaluate Transaction. Enter ["001"] (or whatever you set your key to) as the argument. You should see the following in the output console:

    [SUCCESS] Returned value from readMyAsset: {"value":" a tremendously delicious asset"}
    

    Command Palette alternative: Evaluate Transaction

You’ve now proven you can submit and evaluate transactions to update and read your ledger!

Summary

Congratulations — you now know the key steps in the workflow of local smart contract development! You’ve generated a skeleton contract, deployed it locally, and used it to submit/evaluate transactions.

If you wish to spend some more time locally developing your own smart contracts, the samples (accessed from the extension’s homepage) can help you explore development concepts. If you’re iterating a lot on your code, you should read up on Debug in the ReadMe: It’s very useful for developers!

If you want to take the next steps in your introduction to the IBM Blockchain Platform, a series of three tutorials is included in the VS Code extension, which you can access via its homepage. Great news: You’ve already completed the first one in that series! So you can skip ahead to Tutorial 2: Create a cloud blockchain deployment to continue your learning.

Horea Porutiu
Ed Moffatt