Visual Studio Code Fans Rejoice! VSCode-Corda Extension is out! 🎉

With Visual Studio Code’s soaring popularity, we’ve released an extension to make developing a CordApp in VSCode a first class experience.

The extension was officially announced at CordaCon 2019 along with the Braid/OpenAPI project. It is a set of tools and views that allow you to seamlessly build and test CorDapps right inside the IDE. It is available for download at the following link:

Click to Download

Overview

The README at the above link offers a fairly comprehensive list of features, as well as screenshots — so be sure to check it out. I’ll just describe some of the highlights.

After installing the extension, it is automatically activated and all you need to do is open a Corda project. As far as the extension is concerned, a ‘Corda Project’ is a folder that includes a valid build.gradle; one that specifies Corda 4.0+ as well as a network definition. Upon meeting this condition you will see in the bottom left status bar the text ‘Corda-Project’:

Detected as Corda-Project

If you see the above status, then the tools included with the extension can be launched via the command palette.

• Command Palette shortcut: ⇧⌘P (Windows/Linux Ctrl+Shift+P).

From here you can Clean/Build/Test/Deploy/RunNodes, all without having to manually setup a run configuration.

Where the extension really shines, however, is its interactive views which enables live in IDE testing on simulated networks.

Corda Extension Interactive Views

To put things in perspective, let’s revisit how we would traditionally interact with nodes in the pre-extension era.

The old way of node interaction

When developing CorDapps there are generally three methods for communicating with nodes and testing your apps on a mock-network.

1. Create a test class to instantiate a custom mock-network with using the net.corda.node.testing package. Then run flows and queries through code.
2. Use a gradle task to deployNodes, launch the nodes through the generated runNodes script and use the Corda CRaSH shell to run flows and queries with console command input.
3. Bring up a mock-network with either methods 1 or 2 to enable an RPC connection address, then use CordaRPCConnection and CordaRPCOps in tandem with a REST API server or Java RPCClient driver for executing flows or queries via RPC — whew!

Each of these traditional CorDapp testing methods is a little bit cumbersome.

The first method is great if you have specific unit-tests you want to run but it is slow for fiddling and testing impromptu transactions. Also, it doesn’t provide much in the way of feedback (unless you code it in), and states are not persistent (everything is in-memory only).

The second method is probably more common for new CorDapp developers. It DOES provide persistence (your node vaults will remain intact so long as you don’t deployNodes again or delete the build/nodes directories). However, typing in arguments manually to the shell can be really frustrating — and there are some arguments (such as objects) which can not be instantiated or passed through terminal input, which limits functionality.

The third method, is not common for early stage testing, but if determined, you could build a custom UI with endpoint server to test your CorDapp. The issue is that it’s a lot more setup than most developers would want to do… just to begin testing transactions!

Enter the Corda Transaction Explorer and Corda Vault Query View…

The new way of node interaction

Below is the Corda Transaction Explorer view. It allows you to explore any node defined in the project’s build.gradle, giving you a birds-eye view of the node info and all states. Additionally, it will scan all registered flows on each node and allow you to start the flow with the click of a button.

Corda Transaction Explorer — Start Flow

Starting a flow
You can see in the screenshot above a drop-down list that lets you pick any installed flow. When you choose a flow, inputs for the required arguments will automatically display — in this case owner:Party and amount:int. This is completely dynamic and derived from the actual flow’s constructor method so there is no configuration necessary. If that wasn’t easy enough, if an argument needs to pass an object derived from the ServiceHub API, such as a network Party or an on-ledger StateRef, then the input field will auto-suggest for that argument. Take that CRaSH shell!

Finally, click the “Run Flow” button and profit! ✔

Examining transactions
In the transaction explorer, you’ll be presented with a list of all transactions in the selected node’s vault. Basic information includes; timestamp, TxHash, and outputs. Clicking a transaction expands the field to show all output states and their properties.

Viewing states in a transaction

For convenience, the StateRef (TxHash and Index) of each state, has a copy-to-clipboard button.

The transaction list is auto-updating so immediately after executing a transaction flow you will see the result here. That’s cool!

The Corda Vault Query View is for filtering states in a node’s vault based on selected constraints. Running queries is something that is REALLY a lot easier through the extension UI. 😁

A basic vault query in the CRaSH shell would be executed with run vaultQuery contractStateType: <youpackage>.<yourstate> (you would have to type this every time). However, the Vault Query API is so much more powerful allowing many different filtering criteria, and the CRaSH shell isn’t designed to accept advanced queries (it is unable to construct the requisite QueryCriteria object).

Previously, utilizing the full power of vault queries involved generating unique code for each query. For Example, the code below will return a list of states where:

1. the state is UNCONSUMED
2. the state is of type myState.class or myState2.class
3. the state was signed by either MyNotary1 or MyNotary2
4. the state has a RELEVANT status.

Vault.StateStatus = Vault.StateStatus.UNCONSUMED;
Set<Class<ContractState>> contractStateTypes = 
 new HashSet<>(Arrays.asList(myState1.class, myState2.class));
Party notary1 = currentNode.getServices().getNetworkMapCache().getNotary(new CordaX500Name(“MyNotary1”,”London”,”GB”));
Party notary2 = currentNode.getServices().getNetworkMapCache().getNotary(new CordaX500Name(“MyNotary2”,”Vancouver”,”CA”));
List<AbstractParty> notaries = Arrays.asList(notary1, notary2);
Vault.RelevancyStatus rs = Vault.RelevancyStatus.RELEVANT;
QueryCriteria userCriteria = new QueryCriteria.VaultQueryCriteria()
 .withStatus(stateStatus)
 .withContractStateTypes(contractStateTypes)
 .withNotary(notaries)
 .withRelevancyStatus(rs);
Vault.Page<ContractState> result = 
 proxy.vaultQueryByWithPagingSpec(ContractState.class, userCriteria, new PageSpecification());

Vault Query Views Queries Quickly
First, looking at the above code-block, instantiating predicate types every time you want to run a particular query/filter can really become a chore. Secondly, this method also demands that you actually KNOW the details of all the filters you want to apply. Do you know the CordaX500Name of all the required notaries? Do you know all the ContractState types which are of interest to the current node?

The Corda Vault Query view automatically determines valid query predicates and allows you to filter with simple clicks.

Vault Query Builder UI

The ContractStateType, Notary, and Participants field options are automatically derived from the node vault contents and network properties. In this example, all the vault contents are of type bootcamp.TokenState but if other types are present they also appear here as options. There is one available notary and three parties on the network. Query results are displayed instantly on any selection.

All the fetching, instantiation and QueryCriteria building we saw in the verbose code-block above, is happening under the hood dynamically. We can focus on the results!

Video Demo

Conclusion

In my opinion, the VSCode-Corda extension is a must-have for those who want to do their Corda development in Visual Studio Code. It’s only been out for a few weeks so expect some bug fixes and more innovative features to be added in the near future. The project is opensource so there is opportunity to contribute new functionality or dive into the inner workings here. Now let’s go build some CorDapps! 🏆