-
Notifications
You must be signed in to change notification settings - Fork 156
Common tasks and how to complete them
A smart contract project is a directory containing all the relevant contract and metadata files that define a smart contract. Use the Create New Project command to create a basic smart contract, available in JavaScript, TypeScript, Go or Java.
To package a project you have open in your workspace, run the Package Open Project command. Packages are listed in the Smart Contracts panel. The Blockchain output channel lists what files have been packaged during this action. Alternatively run the Import a Package command to import a pre-existing .cds package to be used within VS Code.
If you wish to control which files in the project are packaged, you can create a .fabricignore file in the top level directory of your smart contract project. The file and pattern format for a .fabricignore file is the same as a .gitignore file, for example:
/.classpath
/.git/
/.gradle/
/.project
/.settings/
/bin/
/build/
The extension is compatible with connecting to and interacting with any Fabric 2.2.x network.
The extension contains a pre-configured local instance of Hyperledger Fabric named 1 Org Local Fabric, which the extension will automatically pull and use the correct Docker images for. It is a pre-configured network with one organization, one peer and one channel. It can be enabled and operated under the Fabric Environments panel. The first time it is started, Fabric 2.2.0 images will be installed and an admin identity created in the 1 Org Local Fabric - Org1 Wallet wallet.
For 1 Org Local Fabric management tasks such as restart and teardown, right click on 1 Org Local Fabric in the Fabric Environments panel.
The 1 Org Local Fabric currently uses Fabric 2.2.0 images.
The extension allow you to connect to any Hyperledger Fabric instance and perform some operational tasks. The tasks available are: install, instantiate and registering and enrolling identities.
To connect to a Hyperledger Fabric instance on the Fabric Environments panel click the + button. This will ask you for JSON node files that describe how to connect to a Hyperledger Fabric Node i.e. peer, orderer, or certificate authority.
If you are connecting to an instance of IBM Blockchain Platform console on IBM Cloud, you can add an environment by connecting directly to the console. You will be able to login to IBM Cloud using username and password, API key or single sign-on, as well as create a new account if you don't already have one. Once the environment is created, if you prefer to work whilst logged out and do not want to be prompted to login on connect, you can disable 'Poll For Config Updates When Connected To IBM Blockchain Platform On IBM Cloud Environments' in the user settings.
If connecting to an IBM Blockchain Platform console software version, you can also add an environment by connecting directly to the console. When prompted for authentication credentials you can either provide User ID and password, or API key and API secret.
For other instances of Hyperledger Fabric you can create the JSON node files yourself.
All node files must contain a name, type, and api_url property. There are three types: fabric-peer, fabric-ca and fabric-orderer. Peer and Orderer nodes must also contain an msp_id property. While Certificate Authority nodes must contain a ca_name property. If you have TLS enabled then then the pem property must also be set.
There are also some additional optional properties. peer and orderer nodes can set the property ssl_target_name_override, this will override the hostname used to verify the servers TLS certificate. A certificate authority node can contain the properties enroll_id and enroll_secret, these properties are used for identity to connect to the certificate authority. If you have a multi-node ordering service then on each orderer node the cluster_name property can be set. If this property is set then the orderer nodes in the same cluster will be grouped together.
A JSON node file can contain more than one node definition using array syntax
Here are some examples of node files:
These some basic examples showing the required properties
{
"name": "ca.org1.example.com",
"api_url": "http://localhost:17054",
"type": "fabric-ca",
"ca_name": "ca.org1.example.com"
}
{
"name": "peer0.org1.example.com",
"api_url": "grpc://localhost:17051",
"type": "fabric-peer",
"msp_id": "Org1MSP"
}
{
"name": "orderer.example.com",
"api_url": "grpc://localhost:17050",
"type": "fabric-orderer",
"msp_id": "OrdererMSP"
}
Here is how to have multiple nodes in one JSON file
[
{
"name": "peer0.org1.example.com",
"api_url": "grpc://localhost:17051",
"type": "fabric-peer",
"msp_id": "Org1MSP"
},
{
"name": "orderer.example.com",
"api_url": "grpc://localhost:17050",
"type": "fabric-orderer",
"msp_id": "OrdererMSP"
}
]
Here is a certificate authority with enroll_id and enroll_secret set
{
"name": "ca.org1.example.com",
"api_url": "http://localhost:17054",
"type": "fabric-ca",
"ca_name": "ca.org1.example.com",
"enroll_id": "admin",
"enroll_secret": "adminpw"
}
Here is an example of a multi-node ordering service
[
{
"name": "orderer.example.com",
"api_url": "grpc://localhost:17050",
"type": "fabric-orderer",
"msp_id": "OrdererMSP",
"cluster_name": "myCluster"
},
{
"name": "orderer1.example.com",
"api_url": "grpc://localhost:17051",
"type": "fabric-orderer",
"msp_id": "OrdererMSP",
"cluster_name": "myCluster"
}
]
Here is an example of a peer with TLS enabled, please note the pem property value has been shortened. The pem property is the root TLS certificate of the peer's MSP. The property should be base64 encoded from a pem file.
{
"name": "peer0.org1.example.com",
"api_url": "grpcs://localhost:17051",
"type": "fabric-peer",
"msp_id": "Org1MSP",
"pem": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNJVENDQWNpZ0F3"
}
If you already have a wallet in the extension with the identity you want to use for a node, you can set the wallet and identity properties. Setting both the properties would skip the setup step for that node. For example if you had the wallet myWallet with identity myIdentity you could do the following:
{
"name": "peer0.org1.example.com",
"api_url": "grpc://localhost:17051",
"type": "fabric-peer",
"msp_id": "Org1MSP",
"wallet": "myWallet",
"identity": "myIdentity"
}
After creating an environment, the next step before connecting is to associate an identity with each node. To do this, click the name of the environment you have just created in the Fabric Environments panel. To complete setup, click on each node from the list to associate an identity with them. The identity must be an admin identity for the node. To change the identity associated with a node when connected the environment, right-click on the node and select Replace identity associated with a node.
You can import more nodes to an existing environment by connecting to the environment, expand nodes and then click on + Import nodes.
To connect to our own Hyperledger Fabric instance, it must be running Hyperledger Fabric v2.2.0 or later.
Add your gateway by providing a name and connection profile via the Add Gateway command; it will be listed in the Fabric Gateways panel. Add a file system wallet to connect to your gateway with via the Add Wallet command.
You can also create a gateway from a fabric environment. When you run the Add Gateway command there will be an option to create a gateway from a fabric environment, select this then choose the environment you want to create the gateway from.
Connect by clicking on a gateway in the Fabric Gateways panel, and expand the navigation tree to explore its resources. Instantiated Smart Contracts are listed under the channel and from here you can generate functional-level test files on single or multiple smart contracts. Submit or evaluate individual transactions listed under the instantiated smart contracts, with the result displayed in the Blockchain output channel.
fabric-contract-api & fabric-shim should be changed in the package.json to use 2.x.x or greater.
Example:
"dependencies": {
"fabric-contract-api": "^2.2.1",
"fabric-shim": "^2.2.1"
},
For more information check the Node.js chaincode docs
fabric-chaincode-shim or fabric-chaincode-java should be changed in the build.gradle or pom.xml to use 2.x.x or greater.
Example:
dependencies {
implementation 'org.hyperledger.fabric-chaincode-java:fabric-chaincode-shim:2.0.0'
implementation 'com.owlike:genson:1.6'
testImplementation 'org.junit.jupiter:junit-jupiter:5.4.2'
testImplementation 'org.assertj:assertj-core:3.11.1'
testImplementation 'org.mockito:mockito-core:2.+'
}
For more information check the Java chaincode docs
fabric-contract-api-go or fabric-chaincode-go should be set in the go.mod file.
Example:
github.com/hyperledger/fabric-chaincode-go v0.0.0-20210319203922-6b661064d4d9
github.com/hyperledger/fabric-contract-api-go v1.1.1
For more information check the Go chaincode docs
To test Java smart contracts, please install the Java Test Runner extension.
When creating Java functional tests new dependencies must be added to the build file.
If you select 'Yes' when prompted with The last step might overwrite build.gradle/pom.xml. Do you wish to continue?, these modifications will be done automatically. You can alternatively choose to skip this step and manually add the code listed below.
Add the following dependencies:
testImplementation 'org.hyperledger.fabric:fabric-gateway-java:2.2.0'
testImplementation 'org.assertj:assertj-core:3.14.0'
testImplementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.10.0'
testImplementation 'com.fasterxml.jackson.core:jackson-databind:2.10.0'
Add the following dependencies:
<dependency>
<groupId>org.hyperledger.fabric</groupId>
<artifactId>fabric-gateway-java</artifactId>
<version>2.2.0</version>
</dependency>
<dependency>
<groupId>org.assertj</groupId>
<artifactId>assertj-core</artifactId>
<version>3.14.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.dataformat</groupId>
<artifactId>jackson-dataformat-yaml</artifactId>
<version>2.10.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.10.0</version>
</dependency>
All functional tests will be created in <yourProject>/src/test/java/org/example.
Instead of manually typing in your arguments when you want to submit or evaluate a transaction, you can instead associate a directory of transaction data with your smart contract, and use the data files in that directory to submit your transaction instead. These associations are stored on the gateway that you are connected to when you associate - if you connect to a different gateway that has the same smart contract installed and instantiated, you will have to associate your transaction data directory again.
To associate a directory of transaction data with your smart contract, run the Associate Directory for Transaction Data command, and choose the directory that you want to associate. When you submit or evaluate a transaction when you have associated a transaction data directory, you will be able to submit any transaction data in that directory instead of inputting the informattion manually.
Transaction data files are in JSON format, but must end with the file extension .txdata. Each file contains an array of objects that are parsed by the extension and used to submit transactions. Below is an example of what your transaction data file might look like:
[
{
"transactionName": "myTransaction",
"transactionLabel": "This is my transaction",
"arguments": [
"001",
"myValue"
],
"transientData": {
"key": "value"
}
}
]
Note that the transactionName is the name of the transaction as defined in your smart contract, whereas transactionLabel is a custom label that is used to differentiate between transaction data objects.
As a developer, it might be nice to prevent your VS Code version and extensions from automatically updating - especially if doing a demonstration or lab.
To stop VS Code extensions from updating:
- Run
>Open User Settingscommand - Find
Extensions: Auto Updatesetting and uncheck it.
To stop the VS Code version from updating:
- Run
>Open User Settingscommand - Find
Update: Modesetting and set tonone.