The example CorDapp¶

Downloading the example CorDapp¶

We need to download the example CorDapp from GitHub.

• Set up your machine by following the quickstart guide
• Clone the example CorDapp from the cordapp-example repository using the following command: git clone https://github.com/corda/cordapp-example
• Change directories to the freshly cloned repo: cd cordapp-example

Opening the example CorDapp in IntelliJ¶

Let’s open the example CorDapp in IntelliJ IDEA.

If opening a fresh IntelliJ instance

• Open IntelliJ

• A dialogue box will appear:

  

• Click open, navigate to the folder where you cloned the cordapp-example, and click OK

• IntelliJ will show several pop-up windows, one of which requires our attention:

  

• Click the ‘import gradle project’ link. Press OK on the dialogue that pops up

• Gradle will now download all the project dependencies and perform some indexing. This usually takes a minute or so.

  • If the ‘import gradle project’ pop-up does not appear, click the small green speech bubble at the bottom-right of the IDE, or simply close and re-open IntelliJ again to make it reappear.

If you already have IntelliJ open

• Open the File menu
• Navigate to Open ...
• Navigate to the directory where you cloned the cordapp-example
• Click OK

Project structure¶

The example CorDapp has the following directory structure:

.
├── config
│   ├── dev
│   │   └── log4j2.xml
│   └── test
│       └── log4j2.xml
├── doc
│   └── example_flow.plantuml
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── lib
│   ├── README.txt
│   └── quasar.jar
├── java-source
│   └── ...
├── kotlin-source
│   ├── build.gradle
│   └── src
│       ├── main
│       │   ├── kotlin
│       │   │   └── com
│       │   │       └── example
│       │   │           ├── api
│       │   │           │   └── ExampleApi.kt
│       │   │           ├── client
│       │   │           │   └── ExampleClientRPC.kt
│       │   │           ├── contract
│       │   │           │   └── IOUContract.kt
│       │   │           ├── flow
│       │   │           │   └── ExampleFlow.kt
│       │   │           ├── model
│       │   │           │   └── IOU.kt
│       │   │           ├── plugin
│       │   │           │   └── ExamplePlugin.kt
│       │   │           ├── schema
│       │   │           │   └── IOUSchema.kt
│       │   │           └── state
│       │   │               └── IOUState.kt
│       │   └── resources
│       │       ├── META-INF
│       │       │   └── services
│       │       │       └── net.corda.webserver.services.WebServerPluginRegistry
│       │       ├── certificates
│       │       │   ├── readme.txt
│       │       │   ├── sslkeystore.jks
│       │       │   └── truststore.jks
│       │       └── exampleWeb
│       │           ├── index.html
│       │           └── js
│       │               └── angular-module.js
│       └── test
│           └── kotlin
│               └── com
│                   └── example
│                       ├── Main.kt
│                       ├── contract
│                       │   └── IOUContractTests.kt
│                       └── flow
│                           └── IOUFlowTests.kt
├── .gitignore
├── LICENCE
├── README.md
├── TRADEMARK
├── build.gradle
├── gradle.properties
├── gradlew
├── gradlew.bat
└── settings.gradle

The key files and directories are as follows:

• The root directory contains some gradle files, a README and a LICENSE
• config contains log4j configs
• gradle contains the gradle wrapper, which allows the use of Gradle without installing it yourself and worrying about which version is required
• lib contains the Quasar jar which rewrites our CorDapp’s flows to be checkpointable
• kotlin-source contains the source code for the example CorDapp written in Kotlin

• kotlin-source/src/main/kotlin contains the source code for the example CorDapp
• kotlin-source/src/main/resources contains the certificate store, some static web content to be served by the nodes and the WebServerPluginRegistry file
• kotlin-source/src/test/kotlin contains unit tests for the contracts and flows, and the driver to run the nodes via IntelliJ

• java-source contains the same source code, but written in Java. CorDapps can be developed in any language targeting the JVM

Running the example CorDapp¶

There are two ways to run the example CorDapp:

• Via the terminal
• Via IntelliJ

In both cases, we will deploy a set of test nodes with our CorDapp installed, then run the nodes. You can read more about how we define the nodes to be deployed here.

   ______               __
  / ____/     _________/ /___ _
 / /     __  / ___/ __  / __ `/         It's kind of like a block chain but
/ /___  /_/ / /  / /_/ / /_/ /          cords sounded healthier than chains.
\____/     /_/   \__,_/\__,_/

--- Corda Open Source 0.12.1 (da47f1c) -----------------------------------------------

📚  New! Training now available worldwide, see https://corda.net/corda-training/

Logs can be found in                    : /Users/joeldudley/Desktop/cordapp-example/kotlin-source/build/nodes/PartyA/logs
Database connection url is              : jdbc:h2:tcp://10.163.199.132:54763/node
Listening on address                    : 127.0.0.1:10005
RPC service listening on address        : localhost:10006
Loaded plugins                          : com.example.plugin.ExamplePlugin
Node for "PartyA" started up and registered in 35.0 sec


Welcome to the Corda interactive shell.
Useful commands include 'help' to see what is available, and 'bye' to shut down the node.

Fri Jul 07 10:33:47 BST 2017>>>

Logs can be found in /Users/joeldudley/Desktop/cordapp-example/kotlin-source/build/nodes/PartyA/logs/web
Starting as webserver: localhost:10007
Webserver started up in 42.02 sec

Interacting with the example CorDapp¶

curl -X PUT 'http://localhost:10007/api/example/create-iou?iouValue=1&partyName=O=PartyB,L=New%20York,C=US'

Counter-party: Select from list
Value (Int):   5

>> Signing transaction with our private key.
>> Gathering the counterparty's signature.
>> Structural step change in child of Gathering the counterparty's signature.
>> Collecting signatures from counter-parties.
>> Verifying collected signatures.
>> Done
>> Obtaining notary signature and recording transaction.
>> Structural step change in child of Obtaining notary signature and recording transaction.
>> Requesting signature by notary service
>> Broadcasting transaction to participants
>> Done
>> Done

Welcome to the Corda interactive shell.
Useful commands include 'help' to see what is available, and 'bye' to shut down the node.

Fri Jul 07 16:36:29 BST 2017>>>

com.example.flow.ExampleFlow$Initiator
net.corda.core.flows.ContractUpgradeFlow$Initiator
net.corda.core.flows.ContractUpgradeFlow$Initiator
net.corda.finance.flows.CashExitFlow
net.corda.finance.flows.CashIssueAndPaymentFlow
net.corda.finance.flows.CashIssueFlow
net.corda.finance.flows.CashPaymentFlow

✅   Generating transaction based on new IOU.
✅   Verifying contract constraints.
✅   Signing transaction with our private key.
✅   Gathering the counterparty's signature.
    ✅   Collecting signatures from counter-parties.
    ✅   Verifying collected signatures.
✅   Obtaining notary signature and recording transaction.
    ✅   Requesting signature by notary service
            Requesting signature by Notary service
            Validating response from Notary service
    ✅   Broadcasting transaction to participants
✅   Done

Running Nodes Across Machines¶

The nodes can be split across machines and configured to communicate across the network.

After deploying the nodes, navigate to the build folder (kotlin-source/build/nodes) and move some of the individual node folders to a different machine (e.g. using a USB key). It is important that none of the nodes - including the controller node - end up on more than one machine. Each computer should also have a copy of runnodes and runnodes.bat.

For example, you may end up with the following layout:

• Machine 1: controller, nodea, runnodes, runnodes.bat
• Machine 2: nodeb, nodec, runnodes, runnodes.bat

You must now edit the configuration file for each node, including the controller. Open each node’s config file, and make the following changes:

• Change the Artemis messaging address to the machine’s IP address (e.g. p2pAddress="10.18.0.166:10006")
• Change the network map service’s address to the IP address of the machine where the controller node is running (e.g. networkMapService { address="10.18.0.166:10002" legalName="O=Controller,L=London,C=GB"). The controller will not have the networkMapService configuration entry

After starting each node, the nodes will be able to see one another and agree IOUs among themselves.

Debugging your CorDapp¶

Debugging is done via IntelliJ as follows:

1. Edit the node driver code in Main.kt based on the number of nodes you wish to start, along with any other configuration options. For example, the code below starts 4 nodes, with one being the network map service and notary. It also sets up RPC credentials for the three non-notary nodes

fun main(args: Array<String>) {
    // No permissions required as we are not invoking flows.
    val user = User("user1", "test", permissions = setOf())
    driver(isDebug = true) {
        startNode(getX500Name(O="Controller",L="London",C="GB"), setOf(ServiceInfo(ValidatingNotaryService.type)))
        val (nodeA, nodeB, nodeC) = Futures.allAsList(
                startNode(getX500Name(O="PartyA",L=London,C=GB"), rpcUsers = listOf(user)),
                startNode(getX500Name(O="PartyB",L=New York,C=US"), rpcUsers = listOf(user)),
                startNode(getX500Name(O="PartyC",L=Paris,C=FR"), rpcUsers = listOf(user))).getOrThrow()

        startWebserver(nodeA)
        startWebserver(nodeB)
        startWebserver(nodeC)

        waitForAllNodesToFinish()
    }
}

2. Select and run the “Run Example CorDapp” run configuration in IntelliJ
3. IntelliJ will build and run the CorDapp. The remote debug ports for each node will be automatically generated and printed to the terminal. For example:

[INFO ] 15:27:59.533 [main] Node.logStartupInfo - Working Directory: /Users/joeldudley/cordapp-example/build/20170707142746/PartyA
[INFO ] 15:27:59.533 [main] Node.logStartupInfo - Debug port: dt_socket:5007

4. Edit the “Debug CorDapp” run configuration with the port of the node you wish to connect to
5. Run the “Debug CorDapp” run configuration
6. Set your breakpoints and start interacting with the node you wish to connect to. When the node hits a breakpoint, execution will pause