How to build a Hello World CorDapp? (Part 1)

6 min readNov 19, 2020

In this tutorial we will see how to build and run a simple Hello World CorDapp. We will be writing a simple IOUState and IOUFlow. Part2 will cover the contract constraints.

So let’s get started.

What is a CorDapp?

CorDapps (Corda Distributed Applications) are distributed applications that run on the Corda platform. The goal of a CorDapp is to allow nodes to reach agreement on updates to the ledger.

CorDapp Components:

CorDapp is basically a set of jar files containing class definitions written in Java and/or Kotlin. These class definitions will commonly include the following elements:

Flows: Set of functions for the node to run, usually to update the ledger
States: Define the facts over which agreement is reached
Contracts: Defining what constitutes a valid ledger update
Services: Providing long — lived utilities within the node.
Serialization Whitelists, restricting what types your node will receive off the wire. You can read more info here.
API’s and static web content
Utility classes

Create CorDapp:

Let’s create a Hello World CorDapp. Writing a CorDapp involves the following steps:

Setting up the CorDapp template (Java/Kotlin)
Writing the state
Writing the flow
Running your CorDapp

Prerequisites:

You should set up the dev environment (https://docs.corda.net/docs/corda-os/4.6/getting-set-up.html).
You should know the Corda core concepts (https://docs.corda.net/docs/corda-os/4.6/key-concepts.html).

Use-case

We will write a CorDapp to model IOU’s on the blockchain. Each IOU — short for “I O(we) (yo)U” — will record the fact that one node
owes another node a certain amount.

This use-case will showcase several key benefits of Corda as a blockchain platform:

Privacy: IOU’s represent sensitive information, we will be taking advantage of Corda’s ability to only share ledger updates with other nodes on a need to know basis.
Well known identities: Each Corda node has a well-known identity on the network. This will allow us to write code in terms of real identities.
Re-use of existing, proven technologies: We will be writing our CorDapp using standard Java. It will run on a Corda Node, which is simply a java process and runs on a regular java machine. The nodes will store
their data in a standard SQL database.

CorDapps usually define at least three things:

States — the (possibly shared) facts that are written to the ledger.
Flows — the procedures for carrying out specific ledger updates.
Contracts — The constraints governing how states of a given type can evolve over time.

Downloading the template:

We will be using java template. Clone the CorDapp java template.


$ git clone https://github.com/corda/cordapp-template-java.git ; cd cordapp-template-java

Once the template is downloaded. Open it in intellij IDE and import the template as gradle project.

Defining the state:

Let’s create a java class called IOUState in the package com.template.states. Here is the IOUState code:

Writing flow:

Now we will have to write a flow that will allow a node to orchestrate the creation of a new IOUState on the blockchain, while only sharing information on a need-to-know basis.

The goal of your flow will be to orchestrate an IOU issuance transaction. Transactions in Corda are the atomic units of change that update the ledger. Each transaction is a proposal to mark zero or more existing states as historic (the inputs), while creating zero or more new states (the outputs).

The process of creating and applying this transaction to a ledger will be conducted by the IOU’s lender, and will require the following steps:

Building the transaction proposal for the issuance of a new IOU onto a ledger.
Signing the transaction proposal.
Recording the transaction and sending it to the IOU’s borrower so that they can record it too.

Enough theory let’s write the flow :)

Writing Initiating flow:

Let’s create a java class called IOUFlow in the package com.template.flows.

Writing Responder Flow:

The borrower has to use ReceiveFinalityFlow in order to receive and record the transaction; it needs to respond to the lender’s flow.

Let create another class file called IOUFlowResponder.java and add the following code in the package com.template.flows :

Start nodes and run the flow:

Your flow, and your CorDapp, are now ready!

We have now defined a flow that we can start on our node to completely automate the process of issuing an IOU onto the ledger. All that’s left is to spin up some nodes and test our CorDapp.

Open terminal or console. Run this command in your project folder.

Windows:

gradlew clean deployNodes

Mac / Linux:

./gradlew clean deployNodesC:\Users\karthik\Documents\GitHub\cordapp-template-java>gradlew clean deployNodes
Starting a Gradle Daemon, 1 incompatible Daemon could not be reused, use --status for details> Task :jar
Cordapp metadata not defined for this gradle build file. See https://docs.corda.net/head/cordapp-build-systems.html#separation-of-cordapp-contracts-flows-and-services> Task :deployNodes
Running Cordform task
Deleting C:\Users\karthik\Documents\GitHub\cordapp-template-java\build\nodes
Bootstrapping local test network in C:\Users\karthik\Documents\GitHub\cordapp-template-java\build\nodes
Generating node directory for Notary
Generating node directory for PartyA
Generating node directory for PartyB
Waiting for all nodes to generate their node-info files...... still waiting. If this is taking longer than usual, check the node logs.> Task :deployNodes
Distributing all node-info files to all nodes
Loading existing network parameters... none found
Gathering notary identities
Generating contract implementations whitelist
New NetworkParameters {
      minimumPlatformVersion=8
      notaries=[NotaryInfo(identity=O=Notary, L=London, C=GB, validating=false)]
      maxMessageSize=10485760
      maxTransactionSize=524288000
      whitelistedContractImplementations {}
      eventHorizon=PT720H
      packageOwnership {}
      modifiedTime=2020-11-19T07:56:20.774Z
      epoch=1
  }
Bootstrapping complete!
Run database schema migration scripts
Run database schema migration scripts
Run database schema migration scripts

Starting the nodes:

Start the nodes by running the following command

Mac / Linux:

build/nodes/runnodes

Windows:

build/nodes/runnodes.bat

This will start a new terminal window for each node. Give some time to each terminal to start. You will get a welcome message on the terminal once the node is ready.

Interacting with the nodes:

You want to create an IOU of 100 with PartyB. To start the IOUFlow, type the following command:

start IOUFlow iouValue: 100, otherParty: "O=PartyB,L=New York,C=US"

You can check the contents of each node’s vault by running:

run vaultQuery contractStateType: com.template.states.IOUState

Here is the sample vault query output:

- state:
    data: !<com.template.states.IOUState>
      value: 100
      lender: "O=PartyA, L=London, C=GB"
      borrower: "O=PartyB, L=New York, C=US"
    contract: "com.template.contracts.TemplateContract"
    notary: "O=Notary, L=London, C=GB"
    encumbrance: null
    constraint: !<net.corda.core.contracts.SignatureAttachmentConstraint>
      key: "aSq9DsNNvGhYxYyqA9wd2eduEAZ5AXWgJTbTEw3G5d2maAq8vtLE4kZHgCs5jcB1N31cx1hpsLeqG2ngSysVHqcXhbNts6SkRWDaV7xNcr6MtcbufGUchxredBb6"
  ref:
    txhash: "854486E98104F5C5751A47DF54E528FF379AA9C8D88A8F0B82AFBEF02C3F5B38"
    index: 0
statesMetadata:
- ref:
    txhash: "854486E98104F5C5751A47DF54E528FF379AA9C8D88A8F0B82AFBEF02C3F5B38"
    index: 0
  contractStateClassName: "com.template.states.IOUState"
  recordedTime: "2020-11-19T10:02:38.006Z"
  consumedTime: null
  status: "UNCONSUMED"
  notary: "O=Notary, L=London, C=GB"
  lockId: null
  lockUpdateTime: null
  relevancyStatus: "RELEVANT"
  constraintInfo:
    constraint:
      key: "aSq9DsNNvGhYxYyqA9wd2eduEAZ5AXWgJTbTEw3G5d2maAq8vtLE4kZHgCs5jcB1N31cx1hpsLeqG2ngSysVHqcXhbNts6SkRWDaV7xNcr6MtcbufGUchxredBb6"
totalStatesAvailable: -1
stateTypes: "UNCONSUMED"
otherResults: []

Conclusion:

You have written a simple CorDapp that allows IOU’s to be issued onto the ledger.

This CorDapp is made up of two key parts:

The IOUState, which represents IOU’s on the blockchain.
The IOUFlow, which orchestrates the process of agreeing the creation of an IOU on-ledger.

In the next tutorial we will see how to add contract constraints to the Hello World CorDapp.