Corda 5 Developer Preview – Running Your First CorDapp

September 28, 2021
CordaSandbox Flow Diagram
Figure 1: Sandboxing done in Corda5

It is Corda Con 2021 time and we are looking forward to sharing all the latest news about Corda 5 with you soon! To take us one step closer, today we’re sharing the Corda 5 Developer Preview 1, the next milestone release for Corda, for your testing and feedback.

Before writing a Corda 5 sample, let us get a gist of what has been cooking in Corda 5.

Problems we are trying to address in Corda 5

Sandboxing is at the heart of Corda 5 architecture. This is a marked change to Corda 4, where a CorDapp is packaged as a single big fat jar. With Corda 4, it was not possible to load multiple related CorDapps where each referred to different versions of the same library. Much of the node configuration to get an app up and operational was performed by config files. These were some of the areas which we focused on addressing for the Dev Preview release.

Questions we asked ourselves

Partner feedback has enabled us to ask these kinds of questions – how can we make network configuration and network management more industry standard? Can we isolate the CorDapps in such a way that users are free to choose which version of the library they want to use and not worry about version clashing exceptions? How can the CorDapps be packaged for a cloud compatible deployment? How can developers focus on writing the business logic first instead of worrying about network setup? These questions led us to re-architect the Corda Platform. Corda 5 Dev Preview has set the stage to address these concerns.

New ideas introduced with Corda 5

To address dependency clashing issues and to provide complete dependency isolation, we have used the OSGI framework for containerizing your contract and workflow modules. So essentially the contract and flow jars are wrapped in an OSGI bundle with a custom CPK extension. These are called CPK files in the Corda 5 world. Each bundle is a collection of dependent jars, lib folders containing external dependencies, and certain OSGI meta information.

These multiple CPKs can be bundled together to form a CPB, again a custom Corda extension. This CPB can be thought of as an actual deployable piece of software. Because of the way we structure our application using CPKs and CPB with the OSGi bundle, we automatically achieve sandboxing at a CPK level. Hence you can have multiple CPKs within a CPB file each referring to different versions of the same file.

As you can see in Figure 1, packaging/bundling our application into CPK and thus CPB sandboxes the entire application into an individual isolated sandbox. Using this design, we can now load multiple CPBs into the same JVM, each sandboxed at a CPK and hence a CPB level as well, providing complete isolation between the sandboxes. Thus this can be thought of as a virtual node, where multiple CorDapps can be run in parallel without interfering with each other.

CordaSandbox Flow Diagram
Figure 2: Deploy CPB to a virtual node, to a Corda hosting environment

If you look at the above diagram, with Corda 5 there isn’t a “node” as before , but rather a “CorDapp Hosting Environment”. Instead of packaging a CorDapp in one big fat jar, we isolate individual modules (contract and workflows) into individual CPK files, combine these into a CPB file and deploy this CPB file. This is shown in Figure 2 above.

Apart from this new packaging, there are also new tools released with the developer preview, such as the Corda CLI and the CorDapp Builder. Also released in this preview is the Corda CLI tool, which can be used for network configuration, node deployment, CorDapp  deployment, and CPK and CPB inspection. The CPB Builder tool used to create a CPB file given multiple CPK files is also shipped in this release. Additionally, at the interface level, where the clients interact with the nodes, new HTTP/RPC APIs have been introduced.

Having set out the context, let us now deploy a Corda 5 Hello Solar System Cordapp using the above concepts to guide us.

About this sample

This is a simple Corda 5 CorDapp that allows you to launch probes between planets with little messages. So come say “Hello” to Mars or Pluto. For this sample, planets will be represented by individual nodes.

How to write states, contracts and flows in Corda5?

Take a look at this blog which talks about how writing states, contracts, and flows in Corda 5 is different to Corda 4.

Prerequisites for the sample

Step 1 – Setup

Before writing our sample application, you need to download the Corda 5 jars, docker and Corda CLI jars. Take a look at this initial setup to find these.

Step 2 – Docker Configuration

In Corda 5, we will start individual nodes as individual Docker containers. Specify the nodes which you wish to create in a YAML file.

nodes:
alice:
bob:
notary:
true

Above is a sample of the minimum config that needs to be specified in the YAML file. For our current application, we will add a few more details as shown below:

nodes:
earth:
debug: true
x500: "C=IE, L=THIRD, O=EARTH, OU=PLANET"
users:
earthling:
password: password
permissions: [ "ALL" ]
mars:
x500: "C=GB, L=FOURTH, O=MARS, OU=PLANET"
users:
martian:
password: password
permissions: [ "ALL" ]
pluto:
x500: "C=US, L=NINTH, O=PLUTO, OU=DWARF_PLANET"
users:
plutonian:
password: password
permissions: [ "ALL" ]
notary:
notary: true

Step 3 – Configure the network 

Configure the docker network using the CLI tool using the below command. Take a look at the Corda CLI blog for more information.

corda-cli network config docker-compose solar-system

Generate the docker-compose script based on our solar-system.yaml file using the below command:

corda-cli network deploy -n solar-system -f solar-system.yaml > docker-compose.yaml

Start the docker Corda nodes:

docker-compose -f docker-compose.yaml up -d

Step 4 – Build the project

Since our network is ready, let’s build the project. This generates the contract and workflow CPKs

./gradlew clean build

Step 5 – Create the CPB file

Now that we have the contract and workflow CPKs, let’s package these into a CPB (collection of multiple cpk’s) files using CPB builder.

Step 5 – Create the CPB file

Now that we have the contract and workflow CPKs, let’s package these into a CPB (collection of multiple cpk’s) files using CPB builder. [Either write a blog or give docs link]

cordapp-builder create --cpk workflows/build/libs/workflows-1.0-SNAPSHOT-cordapp.cpk --cpk contracts/build/libs/contracts-1.0-SNAPSHOT-cordapp.cpk -o result.cpb

Step 6 – Install the CPB onto the docker nodes

Now let’s install the CPB onto the deployed Corda nodes.

corda-cli package install -n solar-system result.cpb

Step 7 – Check the network status

corda-cli network status -n solar-system

How do I run this sample?

Open the browser and hit the node URL:

https://localhost:<port>/api/v1/swagger

Use the below ports to run the swagger API for Earth and Mars Nodes:

  • Earth node: 12113. Login: earthling, password: password
  • Mars node: 12118. Login: martian, password: password

Corda5 provides you with many inbuilt RPC Api’s. Let us try the registered flow API and see if our flow is registered.

https://localhost:12113/api/v1/flowstarter/registeredflows

You should expect a 200 success callback code, and a response body of such:

[“net.corda.solarsystem.flows.LaunchProbeFlow”

]

Since LaunchProbeFlow is registered, let’s start the flow by calling the startflow API. Put the below parameters to form the request:

{

“rpcStartFlowRequest”: {

“clientId”: “launchpad-2”,

flowName”: “net.corda.solarsystem.flows.LaunchProbeFlow”,

“parameters”: {

“parametersInJson”: “{\”message\”: \”Hello Mars\”, \”target\”: \”C=GB, L=FIFTH, O=MARS, OU=PLANET\”, \”planetaryOnly\”:\”true\”}”

}

}

}

This starts the flow and gives you back a client-id and flow-id. Use this client-id from the response and check the flow outcome by calling the flowoutcome API:

https://localhost:12112/api/v1/flowstarter/flowoutcome/{flow-id}

You should see a successful result.

Next Steps

For complete information, visit the Corda 5 developer site. I would urge you to try writing your own CorDapp using this template.

And as Bill Gates says, “We all need people who will give us feedback. That’s how we improve.”, I would urge you all to play around with Corda 5 and give us feedback.


— Sneha Damle is a Developer Evangelist at R3, an enterprise blockchain software firm working with a global ecosystem of more than 350 participants across multiple industries from both the private and public sectors to develop on Corda, its open-source blockchain platform, Corda Enterprise, a commercial version of Corda for enterprise usage, and Conclave, a confidential computing platform.

Follow Sneha on LinkedIn here.

Share: