Steps to Run Corda – Cordapp Sample on Ubuntu 18.04.01
What is Corda?
Let me start with brief & precise explanation of Corda.
Corda is an open source Blockchain platform. Corda is a Distributed Ledger Technology designed for businesses from the start, such as banks/financial institutions, to keep a shared ledger of transactions and thus removing the need for the involved parties to constantly check that each of their books are in line after interacting with each other.
What are Cordapps?
The core model of Corda consists of state objects(data), transactions, and transaction protocols, which when combined with contract code(allowable operations), APIs, wallet plugins, and user interface components results in constructing a Corda distributed application (CorDapp).
What does Corda Ecosystem consist of?
A Corda network consists of the following components:
- Nodes, where each node represents a JVM run-time environment hosting Corda services and executing applications (“CorDapps”). Nodes communicate using AMQP/1.0 over TLS.
- A permissioning service that automates the process of provisioning TLS certificates.
- A network map service that publishes information about nodes on the network.
- One or more pluggable notary service types (which may be distributed over multiple nodes). A notary guarantees uniqueness and validity of transactions.
- Zero or more oracle services. An oracle is a well known service that signs transactions if they state a fact and that fact is considered to be true.
- CorDapps which represent participant applications that execute contract code and communicate using the flow framework to achieve consensus over some business activity.
- Standalone Corda applications that provide manageability and tooling support to a Corda network.
Software requirements to Setup Corda Platform
Corda uses industry-standard tools:
- Oracle JDK 8 JVM – minimum supported version 8u171
- IntelliJ IDEA – supported versions 2017.x and 2018.x (with Kotlin plugin version 1.2.51)
- Applications on Corda (CorDapps) can be written in any language targeting the JVM. However, Corda itself and most of the samples are written in Kotlin.
Setup Environment :
- Open a new terminal and add the Oracle PPA to your repositories by typing “sudo add-apt-repository ppa:webupd8team/java”. Press ENTER when prompted.
- Update your packages list with the command “sudo apt update”
- Install the Oracle JDK 8 by typing “sudo apt install oracle-java8-installer”. Press Y when prompted and agree to the licence terms.
- To setup Git, from the terminal type command “sudo apt install git”
- Jetbrains offers a pre-built snap package that allows for easy, one-step installation of IntelliJ onto Ubuntu. Click Install, then View in Desktop Store. Choose Ubuntu Software in the Launch Application window. Ensure the Kotlin plugin in Intellij is updated to version 1.2.51
Install IntelliJ from Launch Application window in Ubuntu
Now that our environment is set up, we can start working with Corda!!!
Downloading & Installing the example Cordapp
In this step we will be installing an example Cordapp written by the Corda Team. It will demonstrate sending IOU contracts across a network of three nodes.
- Start by downloading the example Cordapp from GitHub. Type following command on terminal git clone https://github.com/corda/samples
- Change directories to the cordapp-example folder: cd samples/cordapp-example
Opening the example CorDapp in IntelliJ IDEA
Load IntelliJ. A dialogue will appear as below.
Click on Open, then navigate to the folder where you cloned the cordapp-tutorial and click OK.
IntelliJ will show a bunch of pop-up windows. One of which requires our attention
Click the ‘import gradle project’ link. A dialogue will pop-up. Press OK. Gradle will now obtain all the project dependencies and perform some indexing. It usually takes a minute or so. If you miss the ‘import gradle project’ dialogue, simply close and re-open IntelliJ again to see it again.
Once the project is open
- Click File, then Project Structure.
- Under Project SDK:, set the project SDK by clicking New…, clicking JDK, and navigating to C:\Program Files\Java\jdk1.8.0_XXX (where XXX is the latest minor version number).
- Click OK
Select File then Project Structure. Select Modules. Click on ‘+’, click on Import Module, then select the cordapp-example folder and click Open.
Choose to Import module from external model, select Gradle, click Next then Finish (leaving the defaults) and OK
Choose Gradle JVM as same version when you set Project SDK
Gradle will now download all the project dependencies and perform some indexing. This usually takes a minute or so.
The example CorDapp has the following structure
There are two ways to run the example CorDapp: Via the terminal and IntelliJ
- Open a terminal window in the cordapp-example directory (change to cordapp-example directory)
- Build the test nodes with our CorDapp using the following command : ./gradlew deployNodes
- The deployNodes Gradle task allows you easily create a formation of Corda nodes. This will automatically build four nodes with our CorDapp already installed.
- After the build finishes, you will see the generated nodes in the kotlin-source/build/nodes folder
- There will be a folder for each generated node, plus a runnodes shell script to run all the nodes simultaneously
- Each node in the nodes folder has the following structure:
├── corda.jar // The Corda node runtime.
├── corda-webserver.jar // The node development webserver.
├── node.conf // The node configuration file.
└── cordapps // The node’s CorDapps.
Running the example CorDapp from IntelliJ
- Start the nodes by running the following command from the root of the cordapp-example folder: kotlin-source/build/nodes/runnodes
- You may have to install xterm. Linux it will open up a new XTerm for each node.
(Commad to install Xterm from the terminal – sudo apt-get update, sudo apt-get install xterm)
- For each node, the runnodes script creates a node tab/window as below image.
It usually takes around 60 seconds for the nodes to finish starting up. To ensure that all the nodes are running, you can query the ‘status’ end-point located at http://localhost:[port]/api/status (e.g. http://localhost:10009/api/status for PartyA).
Running the example CorDapp from IntelliJ
- Select the Run Example CorDapp – Kotlin run configuration from the drop-down menu at the top right-hand side of the IDE
- Click the green arrow to start the nodes
- To stop the nodes, press the red square button at the top right-hand side of the IDE, next to the run configurations
Interacting with the example CorDapp - Via HTTP
The nodes’ webservers run locally on the following ports:
These ports are defined in each node’s node.conf file under
Each node webserver exposes the following endpoints:
/api/example/create-iou with parameters iouValue and partyName which is CN name of a node
Below is the image for Node A
Submitting an IOU via the web front-end
To create an IOU between PartyA and PartyB, navigate to /web/example (e.g http://localhost:10009/web/example), click the “create IOU” button at the top-left of the page, and enter the IOU details into the web-form.
The IOU must have a positive value. For example:
Counterparty: Select from list
Value (Int): 10
Click on Create IOU. The modal dialogue will close, and the nodes will agree the IOU. This may take some time.
Assuming all went well, you can view the newly-created IOU by accessing the vault of PartyA or PartyB
Interacting with the example CorDapp - Via HTTP API
PartyA’s vault: Navigate to http://localhost:10009/api/example/ious
PartyB’s vault: Navigate to http://localhost:10012/api/example/ious
PartyA: Navigate to http://localhost:10009/web/example and hit the “refresh” button
PartyB: Navigate to http://localhost:10012/web/example and hit the “refresh” button
The vault and web front-end of PartyC (at localhost:10015) will not display any IOUs. This is because PartyC was not involved in this transaction.
You are now able to run CorDapps from both the terminal and from an IDE.