Developing smart contracts with IBM Blockchain Platform Developer Tools

Do I need to update my smart contract for Fabric v2.x?

Although support for Fabric 2.0 networks was added to the platform, you can still run your existing smart contracts on your peers that run a v1.4 image on a channel with an application capability level of 1.4 or lower. Should you later decide to upgrade your peer to a v2.x image and update your channel application capability level to 2.0, you may need to update your existing smart contract. However, after you upgrade your peer image to v2.x and channel application capability v2.x, there is no longer a way to update the original smart contract. Instead, when an update is required, you need to repackage the smart contract in the new .tar.gz or .tgz format using v2 of the VS Code extension and then propose the definition to the channel using the new smart contract lifecycle process.

Review the following considerations:

Node

If your smart contract was written in Node, then you might need to update it. By default, a Fabric v1.4 peer will create a Node v8 runtime, and a Fabric v2.x peer creates a Node v12 runtime. In order for a smart contract to work with Node v12 runtime, the fabric-contract-api and fabric-shim node modules must be at v1.4.5 or greater. If you are using a smart contract that was originally written to work with Fabric 1.4, update the Node modules by running the following command before deploying the smart contract on a Fabric v2.x peer. See Support and compatibility for fabric-chaincode-node for more information.

npm install --save fabric-contract-api@latest-1.4 fabric-shim@latest-1.4

Go

Because Fabric v2.x peers do not have a "shim" (the external dependencies that allowed smart contracts to run on earlier versions of Fabric), you need to vendor the shim and then repackage any smart contracts written in Golang (Go) that use the Go SDK. "Vendoring the shim" effectively means that you are copying the dependencies into your project. Without this vendoring and repackaging, the Go smart contract cannot run on a peer using a Fabric 2.x image. If you are using the IBM Developer Tools to develop and package your smart contract, the tooling performs the vendoring for you. This process is not required for smart contracts that are written in Java or Node.js, nor for Go smart contracts that use the Go contract-api.

Java
The build.gradle file for the smart contract must be updated:

1. If the smart contract uses the shadowjar 2.x plugin, then it should be updated to version 5 by using the following code:

    plugins {
        id 'com.github.johnrengelman.shadow' version '5.1.0'
        id 'java'
    }
   

2. The repositories section of the file must contain the maven URL for jitpack, for example:

        repositories {
        ...
        maven {
            url 'https://jitpack.io'
        }
    }
   

Init functions

If the smart contract was written using the low-level APIs provided by the Fabric Chaincode Shim API, your smart contract needs to contain an Init function that is used to initialize the chaincode. This function is required by the smart contract interface, but does not necessarily need to be invoked by your applications. Because you cannot use the console to deploy a smart contract that contains an Init function, you need to move that initialization logic into the smart contract itself and call it separately. For example, the smart contract can use a reserved key to check whether the smart contract has already been initialized or not. If not, then call the initialization logic, otherwise proceed as usual. If your smart contract needs to include the Init function, the only way to deploy it is by using the Fabric peer lifecycle chaincode install command or the IBM Blockchain Platform collection for Ansible. You can also refer to the Fabric documentation for more details on how to use an Init function with the Fabric chaincode lifecycle.

Repackage smart contract

Attention! The IBM Blockchain Platform Extension for VS Code (VS Code extension) referenced throughout the documentation is an open-source project which is no longer active, and therefore not officially supported by IBM. Refer to the alternatives to the VS Code extension.

After you have updated your smart contract, use v2 of the VS Code extension to repackage your smart contract.

Exporting, importing, and deleting a smart contract package

After you package a smart contract project, you can export it from VS Code:

1. In the IBM Blockchain Platform extension panel, right-click the smart contract package and select Export Package.
2. Choose the directory to save your smart contract package file and click Export.

You can also import an existing smart contract package into the IBM Blockchain Platform pane:

1. In the Smart Contracts pane, click the overflow menu and select Import a Package.
2. Browse to the smart contract package that you want to import, and click Import.

You can also click Delete Package to remove the smart contract package from the list of packages.

Deploying a preconfigured Hyperledger Fabric network

Before you can deploy a smart contract, use the following steps to deploy the preconfigured network:

1. Ensure that Docker is running on your machine.
2. Open the IBM Blockchain Platform tab in VS Code.
3. In the Fabric Environments pane, click 1 Org Local Fabric. If Docker is running, the local instance should be started once the Hyperledger Fabric images are downloaded.
4. Click 1 Org Local Fabric - Org1 Gateway in the Fabric Gateways pane to connect to the local network.

The VS Code extension creates a basic Fabric network that includes one orderer, one peer, and one certificate authority. The peer is joined to a channel named mychannel. You can find the list of nodes, organizations, and channels that belong to the network in the Fabric Environments pane. Above these nodes, you can find the list of smart contracts that are deployed on your channels.

Use the following steps to create a new one organization or two organization network:

1. Ensure that Docker is running on your machine.
2. Hover your mouse over the Fabric Environments pane and click +, Add Environment.
3. Select Create new from template.
4. Select 1 Org template (1 CA, 1 peer, 1 channel). Alternatively, if you want a larger network or have generated a Private Data Contract then select 2 Org template (2 CAs, 2 peers, 1 channel).
5. Select V2_0 when asked to choose the channel capability version to use for the network. Alternatively, if you wish to have v1 channel capabilities select the other option.

This will then take a few minutes to create a local Fabric network including the environment, gateways, and wallets.

Deploying your smart contract (channel application capability V2)

Smart contracts can be deployed by using the deploy view. This view handles all the deployment steps (install, approve, commit) which are required by the smart contract lifecycle on channels that are enabled with application capability v2.0 or higher.

Follow these steps if you have your channel is configured with application capability V2 or higher and a .tar.gz smart contract package.

To launch the deploy view:

1. Check that you are connected to the network in the Fabric Environments pane.
2. Expand the channel that you want to deploy your smart contract to.
3. Click + Deploy smart contract.

There are three steps to deploying a smart contract by using the deploy view.

Deploying your smart contract (channel application capability V1)

Follow these steps if you have a channel that is configured with the application capability v1.x and a smart contract package that is in .cds format.

To launch the deploy view:

1. Check that you are connected to the network in the Fabric Environments pane.
2. Expand the channel that you want to deploy your smart contract to.
3. Click + Deploy smart contract.

There are three steps to deploying a smart contract using the deploy view.

Interacting with your smart contract

After a smart contract is deployed to a channel, you can submit transactions to the functions inside your smart contract by using the Fabric Gateways pane:

1. Ensure that your smart contract is deployed to a channel, and that you are connected to the network.
2. In the Fabric Gateways pane, expand the Channels dropdown. Click the channel that the smart contract is instantiated or committed on.
3. Expand the smart contract that you want to interact with. You can find the list of transactions that are listed beneath your smart contract.
4. Right-click the transaction to submit, and select Submit Transaction. For example, if you created and packaged the example bonds smart contract, click createBond.
5. Enter any arguments that the transaction requires, and press Enter. For example, enter ["bond01","100"] to create your first bond.
6. (Optional) Enter any arguments that will be submitted as transient data. Transient data is not stored on the channel ledger in order to keep the data private.

Connecting your applications to the preconfigured network

You can test your client applications by connecting them to the preconfigured network and submitting transactions to your smart contract.

First, you need to export your connection profile:

1. Ensure that the network is running in the Fabric Environments pane.
2. Right-click on the gateway in the Fabric Gateways panel and select Export Connection Profile.

You can then use the Fabric SDKs and the connection profile to enroll your admin identity by using the username admin and the password adminpw. You can then use this identity to invoke your smart contract or register and enroll additional users.

Invoke a smart contract that has been instantiated or committed on your channels

You can download your connection profile from the IBM Blockchain Platform console to build a gateway in the Fabric Gateways pane. You can then use the gateway to invoke the smart contracts that were deployed on your channel.

Open the IBM Blockchain Platform console that is associated with your instance of the IBM Blockchain Platform. Navigate to the Organizations tab and click the Organization MSP tile for the organization that your client application will interact with. Click Create connection profile to open a side panel that allows you to build and download your connection profile to your local file system. Then, create an application identity by using your CA and save the enrollID and secret. Use the following steps to connect to the IBM Blockchain Platform from VS Code.

1. Open the IBM Blockchain Platform tab.
2. Hover your mouse over the Fabric Gateways pane and click +.
3. Choose Create a gateway from a connection profile.
4. Enter a name for the connection.
5. Enter the fully qualified file path of your connection profile. Your connection should now appear in the connections list underneath 1 Org Local Fabric.
6. Hover your mouse over the Fabric Wallets pane and click +.
7. Choose Create a new wallet and add an identity from the options. Provide a name for your wallet and your identity.
8. Enter the MSP ID of your organization.
9. Click Select a gateway and provide an enrollment ID and secret option and choose the gateway that you created above.
10. Enter the enrollID and secret of the application identity that you created with the console. A new identity is created in the Fabric Wallets pane.
11. You can now connect to your instance of your IBM Blockchain Platform network. Click the connection name and select the name of the wallet that you created. You can also associate the wallet that you created with the gateway by right-clicking the gateway and selecting Associate A Wallet. This allows the connection to use the same wallet each time when it connects.

After you connect to the IBM Blockchain Platform from VS Code, you can see the list of channels joined by your organization peers under the gateway. Under each channel, you can see the list of smart contracts that are instantiated or committed on each channel and the transactions within each smart contract. You can submit transactions to your network by right-clicking a function and selecting Submit Transaction and passing the required arguments. You can also generate a test file for the smart contracts that are instantiated on your channels.

Deploy a smart contract from VS Code

Attention! The IBM Blockchain Platform Extension for VS Code (VS Code extension) referenced throughout the documentation is an open-source project which is no longer active, and therefore not officially supported by IBM. Refer to the alternatives to the VS Code extension.

You can also import the IBM Blockchain Platform network into the Fabric Environments pane of the extension. You can then use the extension to deploy smart contracts on your network.

You can export nodes from your console and then import them from another console. You can use the same process to export nodes from your console and then import them into the Fabric Environments pane. The easiest way is to use the extension to automatically discover the console and import the nodes.

1. Navigate to the Settings tab in the left navigation. You can see a section that is called Bulk data management that contains two buttons. The Export button opens a panel on the right.
2. Check the box to export your identities. You can deselect the other options.
3. Click Export to download the identities to your local file system in .zip file. Extract the file when the download is complete.

You can then import the nodes of your network into the extension.

Adding wallets and users

Use the following steps to create a new wallet by using a certificate and private key:

1. Hover your mouse over the Fabric Wallets pane and click +.
2. Choose to Create a new wallet and add an identity from the options. Provide a name for your wallet and your identity.
3. Enter the MSP ID of your organization.
4. Choose to add a certificate and private key.
5. If you use a certificate and private key, browse to the certificate and private key.

You can also add new users to the wallets that have already been created:

1. In the Fabric Wallets pane, right-click a wallet and select Add Identity.
2. Provide a name for the identity and an MSP ID.
3. You can upload a JSON file, provide a certificate and private key, or provide an enrollment ID and secret.
   • If you are connecting to a network on the IBM Blockchain Platform, you can download an identity from your IBM Blockchain console, either by exporting an identity from your wallet or by enrolling and then exporting an identity using your Certificate Authority. You can then upload the JSON file directly to VS Code.
   • If you use a certificate and private key, browse to the certificate and private key.
   • If you use an enrollment ID and secret, choose the gateway to enroll with and enter the enrollment ID and secret.