Hyperledger Fabric Debugger for Visual Studio Code
Hyperledger Fabric Debugger Plugin by Spydra is an Open Source Extension for Visual Studio Code that makes it easy for developers to build and debug Hyperledger Fabric Chaincode right from within the IDE. Typically, developing Chaincode for Fabric requires developers to set up a Fabric environment, deploy the developed Chaincode to it and then debug it by printing log messages to the console. In addition, installing a new version of Chaincode in a Fabric network is not as simple as uploading the new code. Developers have to execute the chaincode lifecycle commands for every modification to upgrade the Chaincode. This makes it very difficult to develop code in an iterative manner.
By using the Hyperledger Fabric Debug Plugin, a developer does not need to set up a Hyperledger Fabric network to deploy and test Chaincode. The plugin will automatically set up a local Fabric v2.5 environment and manage the process of installing the Chaincode.
You can use the Add Configuration button on the launch.json page and choose either "Go: Debug Fabric Chaincode" or "Node.js: Debug Fabric Chaincode" options to add the required launch configuration.
Additional configuration options that are supported natively by the Go and Node.js language debuggers can also be added if needed.
For a list of additional options supported by Go Debugger, please refer to Go launchjson-attributes.
For a list of additional options supported by Node.js Debugger, please refer to Node.js launchjson-attributes.
Start debugging as you would normally do by pressing F5 or select the Run and Debug button from the Run view. Typical debug functionalities provided by the Go and Node.js debugger for VS Code like setting a breakpoint, stepping in/stepping over, viewing variables, stack trace etc. are all supported.
Manage Local Fabric Network
The Hyperledger Fabric Debugger automatically creates a local Fabric v2.5 network with a single organization, one orderer, one peer with CouchDB and one ca node. The network is created in Docker as containers. When you exit VS Code, the nodes that belong to this network are automatically stopped, but the containers are not removed. Due to this, any Ledger data is persisted across VS Code or even Docker/machine restarts.
The extension provides various ways to manage the local Fabric network. For e.g if you want to remove the Docker containers or simply reset the network to remove any Ledger data. Navigate to the Hyperledger Debugger Explorer by clicking the logo on the left pane. The following actions can be performed on the local network.
Manage Wallet Identities
By default, the extension, creates two users - one user 'Org1Admin' with an Admin NodeOU role and one user 'User1' with a Client NodeOU role for testing. Navigate to the Hyperledger Debugger Explorer to create additional identities that can be used for testing.
For creating additional identities, click the + icon against the organization that you want the identity to be created for and provide a username. These identities can subsequently be used while submitting transactions.
For remove an identity, click the X icon against the corresponding identity.
Submit Transactions to Chaincode
Once the breakpoints are set up and the Debugger is launched, in order for the code to execute and hit the breakpoint, the corresponding Chaincode method has to be invoked with the right arguments. This is similar to debugging an API wherein a request to the API has to be made. The Hyperledger Fabric extension supports invoking Chaincode methods directly from VS Code.
Create a .fabric file anywhere in the project. The .fabric file is a JSON file in which you can add the details of one or more Chaincode methods that you want to invoke as well as arguments to be supplied and identity to be used. You can define multiple requests in one file as well as you can create multiple files as needed. e.g
The various keys supported for each request object are:
Click on "Send Request" link that appears at the top of each of the method. The response will be displayed in a separate window that appears.
Stream Chaincode events
Hyperledger Fabric Chaincode can raise chaincode level events during execution. The debugger automatically captures these events and displays them in the output console. To view the chaincode events:
Connect to CouchDB
The Hyperledger Fabric local network which is deployed by the debugger uses CouchDB as the state database. You can connect to CouchDB to view the documents that are stored by the chaincode. To connect to CouchDB:
Connect to the Network from your own Application
The Hyperledger Fabric debugger provides an easy way to submit "query" or "invoke" transactions to the locally deployed network as mentioned above. This enables you to easily test and debug the chaincode that you are creating. You can also use this local network from any application that you are developing using the Fabric SDK.
This is particularly useful when you want to debug the chaincode as well as a client application which will be connecting to the chaincode - for e.g. a web application connecting to the Blockchain layer and submitting transactions to chaincode. In this example, you can run and debug the web application in one Visual Studio Code window and run the Chaincode in another VS Code window and perform end to end debugging. In order to connect to the network from your own application, do the following.
Some of the settings that are required to connect to the local network are:
Using the Fabric Gateway Client API
The Fabric Gateway API is the newer SDK for Fabric versions 2.4 and 2.5 and is now the recommended way to develop Fabric applications. In order to connect to the chaincode running the Fabric debugger from this SDK, the chaincode has to be developed and run using the Chaincode as a Service model.
Using the older Fabric Network SDK
The Fabric Network SDK (which is not deprecated) can be used to connect to legacy as well as Chaincode as a Service mode chaincode running in the Fabric debugger. Follow the below steps in order to connect to the network from your own application.
Frequently Asked Questions
1. Debugging fails for Go Chaincode with the following error "Failed to launch: could not launch process: not an executable file " or with the error "Build Error: go build -o /.vscode/__debug_bin -gcflags all=-N -l . no Go files in /.vscode (exit status 1)"
For the Go Debugger to work properly, you need to select the file which contains the main() function first and then start debugging. Alternatively, in the .vscode/launch.json file, add an additional field called "program" that points to the file that contains the main() function in the Chaincode. For e.g.
2. I've installed the extension, but when I debug a Go Chaincode, I get the error "Error starting chaincode: 'CORE_CHAINCODE_ID_NAME' must be set"
This typically happens when the launch.json file is not created with the right debug settings. The launch.json file specifies that the Hyperledger Fabric debugger extension has to be used instead of the regular Go Debugger. Create the launch settings file as mentioned here.
3. I've installed the extension, but when I debug a Node.js Chaincode, nothing happens. The debugger starts and stops immediately
This typically happens when the launch.json file is not created with the right debug settings. The launch.json file specifies that the Hyperledger Fabric debugger extension has to be used instead of the regular Node.js Debugger. Create the launch settings file as mentioned here.
4. I've installed the extension and started the local fabric network also. When I submit a transaction in the .fabric file, I get an error "Start the Network or Start Debugging(F5) before submitting a transaction to Fabric"
Even though the local fabric network is started, in order for you to submit a transaction defined in the .fabric file, the Chaincode has to be started in Debug mode. Press F5 or select the Run and Debug button from the Run view to start debugging.
5. When I start debugging the Chaincode, I get the error "error starting chaincode: ccid must be specified"
This usually means that the Chaincode that you are trying to debug is developed using the Fabric External Chaincode as a Service model. Stop debugging, set the property "isCaas":true in the .vscode/launch.json file and start debugging again.
6. When I start debugging the Chaincode, I get a message "You don't have an extension for debugging 'JSON with Comments'"
This typically means that the launch.json file is not created. Create the launch settings file as mentioned here, select the code file that contains the entry point for the Chaincode and start debugging again.
6. When I start debugging the Chaincode, the network doesn't start and I get a lot of errors in the output console
If the network is not continuously starting, try resetting the network by going to the Hyperledger Fabric Debugger logo on the left, "Networks" section on the top, hover over "Local Fabric Network" and click the first icon for "Remove Network". Try debugging again which will create a fresh network from scratch.