Introducing The Echo CorDapp

A Corda node is a single running instance of Corda with CorDapps deployed into it. Each instance is owned by, associated with or represents a party. A party is an independent actor and is typically a legal entity or organization, like Acme Corp. or XYZ Mortgage Company. A collection of these parties and their respective nodes form a permissioned Corda network where each node has access to their own copy of a private perspective to a shared ledger. A party’s node represents its participation on a permissioned Corda shared ledger and typically there is a 1:1 correlation between a party and a node. For now, we’ll avoid the scenario where a single entity has multiple nodes.

What will our first ever CorDapp do? Our Echo CorDapp will allow an arbitrary message to be sent from one node to any other node which will reverse the message and then send it back to the originating node, performing an echo. We won’t write anything to the shared ledger in this chapter so that we can focus on how code and wire up a CorDapp, learning how they are built and deployed and how a Corda node can be launched and managed.

We’ll launch two fictitious nodes and a notary (more on notaries in the next chapter) and watch them execute and communicate with each other by echoing messages between each other.

The below items are our learning objectives for our first CorDapp experience. In building this CorDapp, we will want to come away with the understanding of:

The basics of what is and how to write and run Corda flows

How to build, package and deploy the Echo CorDapp into Corda nodes

Spin up and manage a Corda network consisting of Corda nodes

Use a node’s embedded CLI to invoke our flow and observe the nodes interact with each other

What we won’t cover in this chapter is transactions, contracts, commands and storing immutable data in the ledger. Because covering these concepts involve many additional concepts and coding some additional classes, we’ll defer it to Chapter 5.

High-level overview of the Echo CorDapp

Let’s dig a little deeper to see how the Echo CorDapp will work with flows between two nodes. In Figure 3-1, we see two different flows living inside two different Corda nodes. The nodes each are owned by a party, in our case by the fictitious parties Party A and Party B. For this example, both nodes will run locally on our computer but in a real-world scenario, each node would be managed independently by Party A and Party B in their own respective data centers or clouds, connecting to each other via the Internet.

Notice that Party A’s node contains the initiating flow, the flow that will kick off or start this entire Echo process by sending a message to Party B. Party B’s node contains a responder flow which sits and waits for an inbound message to respond to.

Figure 1-1. High level overview of the process flow for sending an Echo message from Party A’s node to Party B’s node

Figure 1-2. How to invoke the initiator flow and start its execution using a shell. This shows one leg of the message going from PartyA to ParyB

The initiator flow won’t start on its own, we have to ask it to start. To do so we’ll use a command-line interface that is embedded inside the node, a shell window that opens up and becomes available to us whenever we launch a node. Starting from the left in Figure 3-2, we can observe that from a command issued inside this shell, a message is generated from Party A and sent to Party B. The shell communicates with Party A’s node and passes it an arbitrary message and asks it to relay the message to Party B. When Party A’s node receives the message from the shell, the message is processed by a flow running inside of Party A’s node.

Party A’s flow is an initiating flow because it is kicking off a process for the first time and is the entry and origin point of that process. A flow executes arbitrary logic that we code and define, and this logic can potentially invoke other responding flows residing in other nodes, although invoking other flows in other nodes is not a requirement. The initiating flow takes the message given to it from the shell and the specified recipient of the message, in the case of Figure 3-2, Party B, and then dispatches the message to Party B, which in turn has a corresponding responderflow that receives and reverses the string message and prints it to the console and then sends the reversed string back to Party A.

Every running Corda node runs a shell, an instance of the popular JVM-based CRaSH shell (https://www.crashub.org/). The CRaSH shell is an embedded shell that runs inside the same JVM process the node is running in. It is our command line window into the world of a particular node. This means every node has its own shell and this allows the shell to have direct command line access to all initiator flows deployed in that node, as well as a limited set of node services. The shell provides us quick, economical and powerful means to manage the node and issue commands to the node. Given that we get the shell for free when we start a node, having it also saves us the need to develop a separate user interface, like a web front-end app to the node. Underneath it all, and covered later in Chapter XXX, the CRaSH shell communicates with the Corda container via Corda RPC layer, which bridges the shell and the Corda services that exist within the same JVM.

In the case of our Echo CorDapp, the command that is actually issued through Party A’s shell specifies and invokes a particular flow, a flow that we will create and code . We’ll name that flow EchoInitiatorFlow and it will need to inherit from FlowLogic, a Corda framework abstract class, to be considered a Corda flow. EchoInitiatorFlow’s purpose is to take on a message and a target recipient, open a session connection to the intended recipient node and dispatch that message to that recipient. It’ll then wait for the reversed echo message to come back.

We’ll also code a second flow called EchoResponderFlow, which is the corresponding responder flow to the initiator EchoInitiatorFlow. EchoInitiatorFlow doesn’t need to specify which flow in the counterparty node should handle the message dispatch to it, instead that will be specified by EchoResponderFlow . In any given node, a plethora of unrelated flows can be written and deployed. So how does Corda know which flow is the corresponding flow to EchoInitiatorFlow? By using an annotation in the EchoResponderFlow and specifying that its counterpart is EchoInitiatorFlow, Corda has all that it needs to tie the two together.

The EchoResponderFlow will respond to any message sent by Party A from the initiator flow and process the message. In this CorDapp’s case, the processing required will simply be to reverse the message, display it and send back the reversed message. When we look at the interplay and execution of these two flows from a more detailed view it will look something like what we see below in Figure 3-3:

Figure 1-3. Detail view of the Echo interaction between two nodes and the different components in the node

After both flows are written, they are packaged and deployed in a single JAR file. In the current example, we will deploy the same codebase, or CorDapp, consisting of both flows, to all of our nodes. In this way, any one node can be instructed to dispatch a message to any other node and we’ll have some rudimentary peer-to-peer messaging working. Remember that we are not going to deploy different CorDapps to each of the two nodes, but the same one single Echo CorDapp binary. Each node gets a copy of the CorDapp binary. For example, if our CorDapp is packaged in echo.jar, PartyA and PartyB nodes both are deployed with a copy of echo.jar. This is because just like PartyA can send a message to PartyB, so to can PartyB initiate a message to PartyA and expect an echo. We’ll see in Chapter XXX that real-world deployments can involve multiple JAR files some that are shared with other nodes and some that are kept proprietary and not shared with other nodes.

As we’ll see in the next section, a node’s footprint and configuration information is simply a set of files sitting under a folder dedicated to that node. The node is not up, alive or available when it is just bits on a disk and startup scripts do the job of launching a node based on the contents of the node folder, picking up configuration information specific to that node, deployed CorDapps and cryptographic keys and then launching a JVM processes.

When we start a node, it automatically finds all the FlowLogic subclasses and registers them. Once the node has started up we can only then invoke and start the EchoInitiatorFlow and execute the flow depicted in Figure 3-3.

Creating a new CorDapp project

To get us started on building our first CorDapp, we can leverage template and scaffolding code from the Corda GitHub repository (http://github.com/corda) by cloning it to our local development environment. The template provides us with starter code, Gradle scripts and a folder structure, allowing us to simply inject our Echo business logic and get us going quickly.

On the Corda Github repository we can find two CorDapp starter templates, one for Java and one for Kotlin. In this exercise we’ll begin by using the Java template.. Although I prefer using Kotlin, starting with Java helps reduce the number of new variables you may have to contend with when learning Corda, given that there is a significantly higher probability you know Java than Kotlin. I’ll also provide the Kotlin version of the Echo CorDapp to help illustrate how much more concise Kotlin is for those who’d like to work with Kotlin immediately. Remember, all source code is available at CordaBook.com.

The starter templates can be found at the following locations:

Figure 1-4. The Corda GitHub has templates and other goodies on the main GitHub page

To stay organized for the multiple of CorDapps we’ll build, I’ve created a local folder on my computer called cordabook and will use it as my root folder for all source code in this book. If you decide to do the same, or use another folder name, after creating the folder make sure to execute the below git command inside of the root folder git clone https://github.com/corda/cordapp-template-java echo-java

This command will create a local git repository and pull down a copy of the template code for us to use. Successful execution the git command should look something like this:

PS D:cordabook3_chapter> git clone https://github.com/corda/cordapp-templat e-java echo-java

Cloning into ’03_chapter’...

remote: Enumerating objects: 60, done.

remote: Counting objects: 100% (60/60), done.

remote: Compressing objects: 100% (34/34), done.

remote: Total 3062 (delta 13), reused 52 (delta 8), pack-reused 3002

Receiving objects: 100% (3062/3062), 2.69 MiB | 13.39 MiB/s, done.

Resolving deltas: 100% (1146/1146), done.

Jumping into echo-java folder created by git and displaying the contents should show us something like this.

PS D:cordabook3_chapterecho-java> dir

Directory: D:cordabook3_chapterecho-java

Mode LastWriteTime Length Name

---- ------------- ------ ----

d----- 10/11/2019 6:21 PM .idea

d----- 10/11/2019 6:21 PM clients

d----- 10/11/2019 6:21 PM config

d----- 10/11/2019 6:21 PM contracts

d----- 10/11/2019 6:21 PM gradle

d----- 10/11/2019 6:21 PM workflows

-a---- 10/11/2019 6:21 PM 1291 .gitignore

-a---- 10/11/2019 6:21 PM 3888 build.gradle

-a---- 10/11/2019 6:21 PM 42 gradle.properties

-a---- 10/11/2019 6:21 PM 5468 gradlew

-a---- 10/11/2019 6:21 PM 2260 gradlew.bat

-a---- 10/11/2019 6:21 PM 591 LICENCE

-a---- 10/11/2019 6:21 PM 4931 README.md

-a---- 10/11/2019 6:21 PM 59 settings.gradle

-a---- 10/11/2019 6:21 PM 234 TRADEMARK

We’ll look at what some of these files are in the next section after loading this project into IntelliJ.

Loading the template code into IntelliJ

Our next step is to load the cloned template sitting in the echo-java folder into our IntelliJ editor and to allow the editor to pull down any required binaries specified in the Gradle build script. Once all that is done, we can explore some of the scaffolding code provided to us and start cranking out some Corda code.

To load this project into IntelliJ, perform the following steps after making sure you’ve installed IntelliJ. For instructions on installing IntelliJ, please see the appendix.

Step 1: Open the Project

When you fire up IntelliJ, you’ll get a screen similar to Figure 3-4:

Figure 1-5. Initial screen when opening IntelliJ. If you already have a project open, select File | Open from the menu.

From here, we will open the scaffolding project we just created. To do so, select the Open option. That’ll bring up the file dialog depicted in Figure 3-6. Navigate to and select the echo-java folder and click OK.

Figure 1-6. Use the Open File or Project dialog box to locate the scaffolding code in the echo-java folder we just generated and select the root project folder for the Java Echo codebase.

Step 2: Import and link Gradle project

As soon as you’ve clicked OK, you’ll see a notification pop-up on the bottom right asking if you’d like to import the gradle project. The Import Gradle project link in blue is what you’ll want to click on.

Figure 1-7. Click on the blue link to import the Gradle project

Step 3: Configure Gradle Wrapper

Once the Gradle project is link is clicked, IntelliJ will need to know a few configuration parameters in the subsequent screen depicted in Figure 3-7. In most cases, the defaults will be fine except that we need to select the Use Gradle ‘wrapper’ task configuration radio button to enable this option.

Figure 1-8. Select the Gradle wrapper task radio button and click OK

Clicking OK on the Import Module from Gradle dialog box depicted in Figure 3-8 will start the process of downloading all of the dependencies, including the Corda binaries and dependent libraries. Depending on your machine and Internet connection speed, this can take anywhere between a few minutes up to around 10 minutes. When it’s done, you’ll have something like Figure 3-9 at the bottom of your IntelliJ editor. Be careful to let the downloads complete before building any of the code.

Figure 1-9. Successful download of Corda binaries and dependencies

Step 4: Opening the project

All that remains to be done is to click on the Project icon in the left pane which will display a project explorer

Figure 1-10. Click on the vertical 1:Project icon to expand the project explorer window

Overview of scaffolding code

With the project loaded into IntelliJ, we can start to explore what the template provides us with and where our entry points for our custom Echo CorDapp code are. As depicted in Figure 3-11, we’re, at this stage, concerned with three sets of files, namely, the two flows sitting in the workflows subfolder, the build.gradle Gradle build script and Gradle wrappers gradlew / gradlew.bat. Let’s investigate what these five files provide us.

Figure 1-11. The three sets of files we’ll explore

The Responder

Similar to the Initiator class, the Responder class also extends from FlowLogic and overrides the call method. The key difference, however, is that the Responder class is annotated with @InitiatedBy which helps Corda wire, attach and associate this flow with the Initiator flow, making it only invocable from a call made inside the Initiator flow. By passing the Initiator’s type information to the @InitiatedBy annotation, we’re saying that this Responder flow cannot be started on its own but only in response to a call made by an instance of an Initiator flow.

package com.template.flows;

import co.paralleluniverse.fibers.Suspendable;

import net.corda.core.flows.FlowException;

import net.corda.core.flows.FlowLogic;

import net.corda.core.flows.FlowSession;

import net.corda.core.flows.InitiatedBy;

// ******************

// * Responder flow *

// ******************

@InitiatedBy(Initiator.class)

public class Responder extends FlowLogic<Void> {

private FlowSession counterpartySession;

public Responder(FlowSession counterpartySession) {

this.counterpartySession = counterpartySession;

}

@Suspendable

@Override

public Void call() throws FlowException {

// Responder flow logic goes here.

return null;

}

}

Using IntelliJ’s refactoring capabilities, let’s rename Intitiator.java and Responder.java to EchoInitiatorFlow.java and EchoResponderFlow.java respectively and change the @InitiatedBy(Initiator.java) to @InitiatedBy(EchoInitiatorFlow.java)

Figure 1-12. Renaming the Initiator and Responder flows

The underlying mechanics of the Echo CorDapp

Let’s conceptually walkthrough how our Echo CorDapp will work and attempt to visualize the interplay of the different components and classes.

As stated earlier, our Echo smart contract will be divided into two flow classes, one an initiator and the other a responder. The initiator is the flow that is first invoked. It needs to receive two arguments - who the recipient of a message should be and the message that should be transmitted to that recipient. To accomplish this, we’ll add two private member variables and arguments to the initiator’s constructor for these variables. Now, when a flow is invoked with the message and recipient parameters, Corda will instantiate the flow and pass the parameters to the constructor so that the call method has access to it.

Modifying our initiator and giving

public class EchoInitiatorFlow extends FlowLogic<Void> {

private final ProgressTracker progressTracker = new ProgressTracker();

private String message;

private String recipient;

public EchoInitiatorFlow(String message, String recipient) {

this.message = message;

this.recipient = recipient;

}

Notice that the recipient is an arbitrary String, representing the name of a possible party (or node) on the network. It must be any one of the names (i.e. PartyA) defined in the deployNodes task in the gradle.build file. The recipient string does not contain nor require any information regarding where physically this other node on the network exists. Information like PartyA’s node’s IP address is pulled from the gradle.build file and stored in each of the node folders and Corda automatically retrieves the IP address of the recipient. Therefore, we will need to use the name to allow Corda to retrieve location information in order to communicate with the node.

Once EchoInitiatorFlow is instantiated, the Corda container invokes EchoInitiatorFlow’s call method. During its execution, the call method will have access to the object attributes message and recipient. The call method’s job is then to find and dispatch the message it received to the intended recipient node. To do so, the initiator will ask Corda to locate the recipient node and pass the message on. More specifically, the initiator flow’s call method needs to perform the following operations:

Obtain a reference to the ServiceHub object, which provides contextual access to the Corda container and its services.

Using the reference to the ServiceHub, obtain a reference to the node’s Identity service, which helps find identities and other nodes that are on the same Corda network. In this case, we want to find the location of the intended recipient of the message. Since the intended recipient is passed into the flow by name as a string we are at this stage not fully sure that a node for that party exists or where it is located.

The Identity service helps lookup and locate the node corresponding to the recipient name passed in and, assuming a valid identity, returns a Party object that represents the recipient’s node.

Once we’ve identified the recipient node or Party, EchoInitiatorFlow will establish a connection session to the recipient node and pass it the message, placing it on a queue for the recipient to process.

The EchoInitiatorFlow then proceeds to wait for an echo response.

Once EchoInitiatorFlow receives the echo, it displays to the console.

Once EchoInitiatorFlow has passed a message to the responder, its dispatching job is done. The execution of the initiator now waits for a response for the echo and the responder now needs to do its job. The responder is invoked by Corda because its corresponding EchoInitiatorFlow dispatched a message by placing it on the recipients message queue. The recipient’s responder flow’s call method needs to perform the following operations:

The recipient node receives the message, including class type information of the initiating flow, and finds the appropriate responder that is annotated to respond to the class type of the initiating flow.

The recipient’s responder flow’s call method is invoked and the responder flow starts execution.

The recipient’s responder retrieves the message from the queue, stores the message in a string, reverses the text in that string and then prints it out to the CRaSH shell console.

Finally, it sends the reversed text back to the initiator’s node sending back an echo.

Let’s look to code these steps for each of the two flows.

Coding the Echo CorDapp

Let’s begin by coding the EchoInitiatorFlow.call method.

The first thing we need to do inside the call method is to find a way to access services made available to us by the container that is executing the initiator flow. We do this by simply calling the getServiceHub() method, which is a method we inherited from FlowLogic. The method returns a reference to the ServiceHub, which is our gateway into the container (much like ServletContext is for servlet containers).

ServiceHub serviceHub = getServiceHub();

ServiceHub is our gateway to internal services of the node executing the above code. The service hub will practically be required in any and every flow and so is usually the first line in the call method. Once we have a reference to the service hub, we are able to then get access to the node’s Identity service (We’ll cover this service in greater detail in Chapter XXX). We do so by calling getIdentityService() on ServiceHub.

IdentityService identityService = serviceHub.getIdentityService();

This gives us access to the service that can help us locate the intended recipient of the message. Recall that the recipient passed into the Initiator flow is only a string. The string has no real information about which node to dispatch to, where that node is located or how to contact that node. The Identity service provides us an interface to the network map cache or, DNS if you will, we can retrieve an identity by looking up the name of the recipient, similar to how a domain name is mapped to an IP address.

To find which node has the recipient name, we invoke the identity service’s partiesFromName method and pass in the recipient name. The second parameter is a boolean flag indicating we’d like an exact match on the recipient name we are searching for. Since it is entirely possible we may have zero or more matching nodes, we get back a set of Party.

Set<Party> partyRecipients = identityService.partiesFromName(recipient,true);

Given that in this example we know that the set will return containing only one matching Party, we can safely pull that element out and get back a single Party object that represents the recipient’s node.

Party partyRecipient = partyRecipients.iterator().next();

The initiator now needs to communicate with partyRecipient and its node and hand to it the message. How would it do that? Does it need to open up an HTTP or sockets connection? Fortunately, Corda provides the plumbing for connection and dispatching to other nodes. All we need to provide is what we want to send and who we want to send it to. Using FlowLogic’s initiateFlow() method, we can ask a flow in another node to execute. We can connect to the recipient node by passing the partyRecipient to initiateFlow method. This returns a FlowSession object which represents a connection to the recipient node. Using the FlowSession, we can call the send method to send the message over, like so:

FlowSession session = initiateFlow(partyRecipient);

session.send(message);

And we’re done. The Corda platform takes of the rest, the initiators job is complete for now. The message is now sent off to the partyRecipient node to deal with. The initiateFlow method establishes a session with the recipient and then sends a message via that session. All initiatiateFlow needs is a Party object to be passed in as argument and it takes care of the underlying plumbing. At this point the EchoInitiatorFlow will wait for the echo from the responder flow and we’ll add the code that waits for the echo after we code the responder flow in the next session.

Our EchoInitiatorFlow should like this thus far:

package com.template;

import co.paralleluniverse.fibers.Suspendable;

import net.corda.core.flows.FlowException;

import net.corda.core.flows.FlowLogic;

import net.corda.core.flows.InitiatingFlow;

import net.corda.core.flows.StartableByRPC;

import net.corda.core.identity.Party;

import net.corda.core.node.ServiceHub;

import net.corda.core.node.services.IdentityService;

import net.corda.core.utilities.ProgressTracker;

import java.util.Set;

// ******************

// * Initiator flow *

// ******************

@InitiatingFlow

@StartableByRPC

public class EchoInitiatorFlow extends FlowLogic<Void> {

private final ProgressTracker progressTracker = new ProgressTracker();

private String message;

private String recipient;

public EchoInitiatorFlow(String message, String recipient) {

this.message = message;

this.recipient = recipient;

}

@Override

public ProgressTracker getProgressTracker() {

return progressTracker;

}

@Suspendable

@Override

public Void call() throws FlowException {

ServiceHub serviceHub = getServiceHub();

IdentityService identityService = serviceHub.getIdentityService();

Set<Party> partyRecipients = identityService.partiesFromName(this.recipient,true);

Party partyRecipient = partyRecipients.iterator().next();

FlowSession session = initiateFlow(partyRecipient);

session.send(message);

}

}

Deploying the Echo CorDapp

To deploy our CorDapp we’ll use the Gradle custom task deployNodes we became familiar with earlier in this chapter. When we run the deployNodes task, Gradle will create a build folder in the project root, and underneath the build folder and for each node, create a subfolder. It will also create a batch file that will start up all three nodes in one shot.

We can launch the deployNodes Gradle task like so with the following command:

PS D:cordabook3_chapterecho-java> .gradlew deployNodes

Doing so will result in the following output:

> Task :deployNodes

Running Cordform task

Deleting D:cordabook3_chapterecho-javauild odes

Bootstrapping local test network in D:cordabook3_chapteruild odes

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...

Distributing all node-info files to all nodes

Loading existing network parameters... none found

Gathering notary identities

Generating contract implementations whitelist

QUASAR WARNING: Quasar Java Agent isn’t running. If you’re using another instrumentation method you can ignore this message; otherwise, please refer to the Getting Started section in the Quasar documentation.

New NetworkParameters {

minimumPlatformVersion=4

notaries=[NotaryInfo(identity=O=Notary, L=London, C=GB, validating=false)]

maxMessageSize=10485760

maxTransactionSize=524288000

whitelistedContractImplementations {

}

eventHorizon=PT720H

packageOwnership {

}

modifiedTime=2019-10-06T22:58:27.314Z

epoch=1

}

Bootstrapping complete!

BUILD SUCCESSFUL in 50s

11 actionable tasks: 11 executed

If successful, we’ll be able to find a new build folder in the project root. As we can see below, the folder structure will contain subfolders for each of the nodes we specified in the Gradle deployNodes task, a configuration file per node and runnodes batch file which will launch all the nodes for us.

PS D:cordabook3_chapterecho-java> cd build

PS D:cordabook3_chapterecho-javauild> dir

Directory: D:cordabook3_chapteruild

Mode LastWriteTime Length Name

---- ------------- ------ ----

d----- 10/6/2019 6:57 PM libs

d----- 10/6/2019 6:58 PM nodes

d----- 10/6/2019 6:57 PM resources

d----- 10/6/2019 6:57 PM tmp

PS D:cordabook3_chapteruild> cd nodes

PS D:cordabook3_chapteruild odes> dir

Directory: D:cordabook3_chapterecho-javauild odes

Mode LastWriteTime Length Name

---- ------------- ------ ----

d----- 10/6/2019 6:57 PM .cache

d----- 10/6/2019 6:58 PM Notary

d----- 10/6/2019 6:58 PM PartyA

d----- 10/6/2019 6:58 PM PartyB

-a---- 10/6/2019 6:58 PM 204 Notary_node.conf

-a---- 10/6/2019 6:58 PM 498 PartyA_node.conf

-a---- 10/6/2019 6:58 PM 500 PartyB_node.conf

-a---- 10/6/2019 6:57 PM 320 runnodes

-a---- 10/6/2019 6:57 PM 106 runnodes.bat

-a---- 10/6/2019 6:57 PM 1117999 runnodes.jar

Peeking inside one of these nodes, let’s say PartyA, we can see a bunch of files that are associated with this node. All of these files are specific to the PartyA node and modifying any of these files impact only the PartyA node.

PS D:cordabook3_chapterecho-javauild odes> cd .PartyA

PS D:cordabook3_chapterecho-javauild odesPartyA> dir

Directory: D:cordabook3_chapterecho-javauild odesPartyA

Mode LastWriteTime Length Name

---- ------------- ------ ----

d----- 10/6/2019 6:58 PM additional-node-infos

d----- 10/6/2019 6:58 PM certificates

d----- 10/6/2019 6:58 PM cordapps

d----- 10/6/2019 6:58 PM drivers

d----- 10/6/2019 6:58 PM logs

-a---- 10/6/2019 6:57 PM 63736152 corda.jar

-a---- 10/6/2019 6:58 PM 4498 network-parameters

-a---- 10/6/2019 6:57 PM 498 node.conf

-a---- 10/6/2019 6:58 PM 4689 nodeInfo-E4477B559304AADFC0638772C0956A38FA2E2A7A5EB0E65D0D83E58848318

79A

-a---- 10/6/2019 6:58 PM 2514944 persistence.mv.db

-a---- 10/6/2019 6:58 PM 8074 persistence.trace.db

-a---- 10/6/2019 6:58 PM 5 process-id

There are several different interesting files in here that we’ll dig into in the next chapter, but the most important are the node.conf which is a generated file that governs the node configuration, corda.jar which contains the Corda framework and the cordapps folder. The node.conf is generated by deployNodes from information in the build.gradle build script, such as port numbers. For now, we don’t need to modify anything in node.conf.

PS D:cordabook3_chapterecho-javauild odesPartyA> cat node.conf

devMode=true

myLegalName="O=PartyA,L=London,C=GB”

p2pAddress="localhost:10005”

rpcSettings {

address="localhost:10006”

adminAddress="localhost:10046”

}

security {

authService {

dataSource {

type=INMEMORY

users=[

{

password=test

permissions=[

ALL

]

user=user1

}

]

}

}

}

Looking into the cordapps folder we can see our CorDapp wrapped in two JAR files, the flows we created sitting in the workflows jar.

PS D:cordabook3_chapterecho-javauild odesPartyA> cd cordapps

PS D:cordabook3_chapterecho-javauild odesPartyAcordapps> dir

Directory: D:cordabook3_chapteruild odesPartyAcordapps

Mode LastWriteTime Length Name

---- ------------- ------ ----

d----- 10/6/2019 6:58 PM config

-a---- 10/6/2019 6:58 PM 4394 contracts-0.1.jar

-a---- 10/6/2019 6:58 PM 6190 workflows-0.1.jar

Launching the Echo CorDapp

Although the nodes are deployed they are not currently running. The node bits reside dormant on disk and need to be brought to life. To launch the nodes, we need to execute the runnodes script file and it will start up the nodes for us. Starting up the nodes will also launch our Echo CorDapp any other CorDapp sitting in the cordapps subfolder of each node.

To launch the nodes, inside the nodes subfolder execute the runnodes shell script like so.

PS D:cordabook3_chapterecho-javauild odes> . unnodes

Starting nodes in D:cordabook3_chapterecho-javauild odes

No file corda.jar found in D:cordabook3_chapterecho-javauild odes.cache

Starting corda.jar in D:cordabook3_chapterecho-javauild odesNotary on debug port 5005

Node will expose jolokia monitoring port on 7005

Running command: cmd /C start C:Program” “FilesJavajre1.8.0_211injava -Dcapsule.jvm.args=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005” “-javaagent:drivers/jolokia-jvm-1.6.0-agent.jar=port=7005,logHandlerClass=net.corda.node.JolokiaSlf4jAdapter -Dname=Notary -jar D:cordabook3_chapterecho-javauild odesNotarycorda.jar

Starting corda.jar in D:cordabook3_chapteruild odesPartyA on debug port 5006

Node will expose jolokia monitoring port on 7006

Running command: cmd /C start C:Program” “FilesJavajre1.8.0_211injava -Dcapsule.jvm.args=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5006” “-javaagent:drivers/jolokia-jvm-1.6.0-agent.jar=port=7006,logHandlerClass=net.corda.node.JolokiaSlf4jAdapter -Dname=PartyA -jar D:cordabook3_chapterecho-javauild odesPartyAcorda.jar

Starting corda.jar in D:cordabook3_chapterecho-javauild odesPartyB on debug port 5007

Node will expose jolokia monitoring port on 7007

Running command: cmd /C start C:Program” “FilesJavajre1.8.0_211injava -Dcapsule.jvm.args=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5007” “-javaagent:drivers/jolokia-jvm-1.6.0-agent.jar=port=7007,logHandlerClass=net.corda.node.JolokiaSlf4jAdapter -Dname=PartyB -jar D:cordabook3_chapterecho-javauild odesPartyBcorda.jar

Started 3 processes

Finished starting nodes

Since we’ve defined three nodes in the build.gradle file - PartyA, PartyB and a notary node, three JVM processes will launch, each representing a node with a CRaSH shell integrated in. Each JVM process and CRaSH shell will open in a window like in Figure 3-13 and 3-14. In these two figures, notice the white box that locates where we can identify which node is which. Remember to not close any of the windows, doing so may shut the node down.

Figure 1-13. The shell for PartyA’s node

Figure 1-14. The shell PartyB’s node

Invoking Echo flows

We can now invoke our flow from the command line of the CRaSH shell. Make sure you are typing into the Crash shell for PartyA and not PartyB or the notary nodes. Once you’ve identified PartyA’s node (see Figure 3-13), let’s pull a list of flows available to us in this node. To get a list of the flows registered in this node, we can use the flow list command. This will display the flows this node is aware of and we’ll see that the EchoInitiatorFlow flow is at the top of the list. The flow list command displays only flows annotated with @InitiatingFlow because only these types of flows can be launched.

>>> flow list

com.template.flows.EchoInitiatorFlow

net.corda.core.flows.ContractUpgradeFlow$Authorise

net.corda.core.flows.ContractUpgradeFlow$Deauthorise

net.corda.core.flows.ContractUpgradeFlow$Initiate

To invoke EchoInitiatorFlow we use the flow start command, passing to it the message and recipient node arguments:

flow start EchoInitiatorFlow message: “Hello, World!”, recipient: PartyB

Figure 1-15. Invoking EchoInitiatorFlow on PartyA’s node

Figure 1-16. PartyB’s node reacting and responding

And voila!, the two nodes are communicating. PartyA sends a message to PartyB, which in turn reverses and displays it.

As shown in Figure 3-15, from PartyA’s node we invoke EchoInitiatorFlow and pass it the Hello, World! message and recipient PartyB. An echo from PartyB with the message reversed returns when EchoResponderFlow is called. While EchoResponderFlow executes EchoInitiatorFlow blocks on the receive() method waiting for the echo message. In Figure 3-16 we see PartyB’s node receives and displays the message to the console, reverses it and sends it back to PartyA, completing an echo.

Shutting nodes down

To shut a node down, simply type exit or bye in the CRaSH shell as shown in Figure 3-17. This terminates the JVM process for the node and releases any locks on files in the node folder. Each node needs to be shut down individually. We’ll look in Chapter XXX if a shutdown is attempted and flows are still executing are in mid flight.

Figure 1-17. Shutting a node down by saying bye

If you make changes to your flow code you will need to redeploy the CorDdapp. To redeploy, make sure to shutdown all nodes and then run the Gradle deployNodes task to push out the newer version of the CorDapp.

Monitoring flows

Our CRaSH shell allows us to monitor flows executing on any one of the nodes. We can do this by issue the flow watch command. In Party B’s CRaSH shell, issue the flow watch command

>>> flow watch

Once the command runs, the shell waits for inbound flows and displays its activities. If we send more message to PartyB from PartyA’s node we’ll see the inbound flows on the flow watch screen in Party A’s shell.

Figure 1-18. Flow watch

Connecting to a node via SSH

If the large number of windows that popped up when you launched the Corda nodes is a little disorienting, especially if you’re potentially launching a larger number of nodes, the runnodes scripts allows you to run the nodes in the background. In fact, with the nodes running in the background you can also connect into any one of the nodes via SSH. This can be very convenient if you need to connect to nodes remotely.

To enable the SSH daemon in each of the Corda node, we can configure the SSH port inside of the build.gradle file so that it shows up in our node.conf file. We need to configure it for each of the nodes we expect to run the SSH daemon. Let’s set it up for PartyA’s node by adding sshdPort 2222 into the node configuration for Party A, as depicted below.

node {

name “O=PartyA,L=London,C=GB”

p2pPort 10005

rpcSettings {

address(“localhost:10006”)

adminAddress(“localhost:10046”)

}

sshdPort 2222

rpcUsers = [[ user: “user1”, “password”: “test”, “permissions”: ["ALL"]]]

}

Alternatively, you can add the configuration directly to the node.conf file of an existing deployed node, like below:

devMode=true

myLegalName="O=PartyA,L=London,C=GB”

.

.

security {

authService {

.

.

.

}

}

sshd {

port=2222

}

Once we have this, we can deploy or restart our nodes with the following switch

. unnodes.bat --headless

This will result in a flurry of messages like below:

PS D:cordabook3_chapterecho-javauild odes> . unnodes.bat --headless

Starting nodes in D:cordabook3_chapterecho-javauild odes

No file corda.jar found in D:cordabook3_chapterecho-javauild odes.cache

Starting corda.jar in D:cordabook3_chapterecho-javauild odesNotary on debug port 5005

.

.

Listening for transport dt_socket at address: 5007

______ __

/ ____/ _________/ /___ _

/ / __ / ___/ __ / __ `/ War does not determine who is right.

/ /___ /_/ / / / /_/ / /_/ / It determines who is left.

\____/ /_/ \__,_/\__,_/

--- Corda Open Source 4.1 (c11f6c1) -------------------------------------------------------------

Logs can be found in : D:cordabook3_chapterecho-javauild odesNotarylogs

______ __

/ ____/ _________/ /___ _

/ / __ / ___/ __ / __ `/ How did my parents fight boredom before the internet?

/ /___ /_/ / / / /_/ / /_/ / I asked my 17 siblings and they didn’t know either.

\____/ /_/ \__,_/\__,_/

--- Corda Open Source 4.1 (c11f6c1) -------------------------------------------------------------

! ATTENTION: This node is running in development mode! This is not safe for production deployment.

______ __

/ ____/ _________/ /___ _

/ / __ / ___/ __ / __ `/ How did my parents fight boredom before the internet?

/ /___ /_/ / / / /_/ / /_/ / I asked my 17 siblings and they didn’t know either.

\____/ /_/ \__,_/\__,_/

--- Corda Open Source 4.1 (c11f6c1) -------------------------------------------------------------

Logs can be found in : D:cordabook3_chapterecho-javauild odesPartyBlogs

! ATTENTION: This node is running in development mode! This is not safe for production deployment.

! ATTENTION: This node is running in development mode! This is not safe for production deployment.

Jolokia: Agent started with URL http://127.0.0.1:7005/jolokia/

Jolokia: Agent started with URL http://127.0.0.1:7006/jolokia/

Jolokia: Agent started with URL http://127.0.0.1:7007/jolokia/

Advertised P2P messaging addresses : localhost:10002

RPC connection address : localhost:10003

RPC admin connection address : localhost:10043

Advertised P2P messaging addresses : localhost:10005

RPC connection address : localhost:10006

RPC admin connection address : localhost:10046

Advertised P2P messaging addresses : localhost:10008

RPC connection address : localhost:10009

RPC admin connection address : localhost:10049

Loaded 2 CorDapp(s) : Contract CorDapp: Template CorDapp version 1 by vendor Corda Open Source with licence Apache License, Version 2.0, Workflow CorDapp: Template Flows version 1 by vendor Corda Open Source with licence Apache License, Version 2.0

Node for “Notary” started up and registered in 22.65 sec

Loaded 2 CorDapp(s) : Contract CorDapp: Template CorDapp version 1 by vendor Corda Open Source with licence Apache License, Version 2.0, Workflow CorDapp: Template Flows version 1 by vendor Corda Open Source with licence Apache License, Version 2.0

Node for “PartyA” started up and registered in 23.97 sec

SSH server listening on port : 2222

Loaded 2 CorDapp(s) : Contract CorDapp: Template CorDapp version 1 by vendor Corda Open Source with licence Apache License, Version 2.0, Workflow CorDapp: Template Flows version 1 by vendor Corda Open Source with licence Apache License, Version 2.0

Node for “PartyB” started up and registered in 21.24 sec

Once we have Party A’s Corda node, we can use an SSH client to connect. In Figure 3-20, we use PuTTY, a free SSH client for Windows. The username and password defined in our RPC section of the node.conf, typically user=user1 and password=test, are the default credentials. Using these credentials, we can successfully login into the node, as depicted in Figure 3-21.

Figure 1-19. Connecting to a headless node via SSH using PuTTY

Figure 1-20. Successful connection to the node via SSH

Because the nodes are headless, shutting the node down via bye or exit won’t work. To kill a node process, find the process-id file inside each node’s folder and use the process ID (PID) contained in it. Kill the process by specifying the PID with Unix / Linux’s kill or PowerShell’s stop-processes.

It is also possible to start nodes without starting the CRaSH shell service using --no-local-shell

The Kotlin equivalent

To build the Kotlin equivalent of our Echo CorDapp, we’ll start by cloning the Kotlin template and then loading it into an IntellIJ project.

PS D:cordabook3_chapter> git clone https://github.com/corda/cordapp-template-kotlin echo-kotlin

Cloning into ‘echo-kotlin’...

remote: Enumerating objects: 44, done.

remote: Counting objects: 100% (44/44), done.

remote: Compressing objects: 100% (30/30), done.

remote: Total 3485 (delta 10), reused 29 (delta 2), pack-reused 3441Receiving objects: 98% (3416/3485), 2.11 MiB | 4.20 MiB/s

Receiving objects: 100% (3485/3485), 2.21 MiB | 4.25 MiB/s, done.

Resolving deltas: 100% (1262/1262), done.

Once cloned and loaded into IntelliJ using the same instructions described in the earlier in this chapter, we’re ready to code our flows. Because multiple classes can be defined in a single Kotlin file, you’ll find both the initiator and responder flows reside in Flows.kt

Figure 1-21. Initiator and Responder all are in the same Flows.kt file

The steps the initiator and responder need to take are identical to our Java version but the syntax is more concise. Using Kotlin’s primary constructor, we can simultaneously declare a constructor and member variables and also rename the Initiator and Responder to EchoInitiatorFlow and EchoResponderFlow:

class EchoInitiatorFlow(val message:String, val recipient:String)

We then need to code our the EchoInitiatorFlow.call method, where the first thing it does is locate the recipient via the ServiceHub.

val partyRecipient = serviceHub.identityService.partiesFromName(recipient,true).first()

And finally dispatches the message to the recipient

val session = initiateFlow(partyRecipient)

session.send(message)

The EchoResponderFlow.call method captures the message via the receive method.

val inboundMessage: String = counterpartySession

.receive<String>()

.unwrap {d -> d}

And with the message we can reverse it using the Kotlin String class.

val reversed = inboundMessage.reversed()

println(“Reversed: {$reversed}”)

And send it back to EchoInitiatorFlow

counterpartySession.send(reversed)

Where it receives and displays the echo message

val echo = session.receive<String>().unwrap{d ->d}

println(“Echo message: $echo”)

All together, our Kotlin Echo CorDapp flows looks like this:

package com.template.flows

import co.paralleluniverse.fibers.Suspendable

import net.corda.core.flows.*

import net.corda.core.utilities.ProgressTracker

import net.corda.core.utilities.unwrap

// *********

// * Flows *

// *********

@InitiatingFlow

@StartableByRPC

class EchoInitiatorFlow (val message: String, val recipient: String) : FlowLogic<Unit>() {

override val progressTracker = ProgressTracker()

@Suspendable

override fun call() {

val partyRecipient = serviceHub.identityService.partiesFromName(recipient,true).first()

val session = initiateFlow(partyRecipient)

session.send(message)

val echo = session.receive<String>().unwrap{d ->d}

println(“Echo message: $echo”)

}

}

@InitiatedBy(EchoInitiatorFlow ::class)

class Responder(val counterpartySession: FlowSession) : FlowLogic<Unit>() {

@Suspendable

override fun call() {

println(“Counterparty: {$counterpartySession.counterparty.name}”)

val inboundMessage: String = counterpartySession

.receive<String>()

.unwrap {d -> d}

val reversed = inboundMessage.reversed()

println(“Reversed: {$reversed}”)

counterpartySession.send(reversed)

}

}