Running a sample CorDapp

Get started with the Corda 5 Developer Preview by running a sample CorDapp. Learn how to deploy and test a CorDapp before you modify the CorDapp template to write your own.

This sample CorDapp lets you launch probes between celestial bodies to send short messages. In this scenario, the solar system represents your local network. The celestial bodies are the nodes on your network. To learn more about nodes, see the node documentation .

The Solar System CorDapp has an optional smart contract implemented. You can use it to determine if all celestial bodies can receive probes, or if only planets can receive them.

The sample CorDapp contains these nodes:

  • Earth
  • Mars
  • Pluto

The CorDapp has a single flow that you use to send messages between planets: LaunchProbeFlow.

The flow takes in three parameters:

Parameter Definition Type
message A message to send with the probe. String
target The X500 name of the probe’s target. String
planetaryOnly Determines whether the probe is only able to travel to planets, or if it can visit any celestial body. Boolean

Before you start

Before you run the sample CorDapp:

If you’re new to Corda, check out the CorDapp documentation for key concepts.

Download the sample CorDapp

  1. Decide where you want to store the sample CorDapp.
  2. Open that directory in the command line.
  3. Run the following command to clone the repository:
git clone https://github.com/corda/corda5-solarsystem-contracts-demo.git

The sample project appears in your chosen directory.

Open the sample CorDapp in IntelliJ IDEA

Open the sample CorDapp in IntelliJ IDEA to explore the CorDapp’s structure.

  1. Open IntelliJ.
  2. Choose Open from the top menu.
  3. Navigate to the Corda5-SolarSystem directory and click OK.

The project containing the sample CorDapp opens.

Deploy the CorDapp using Corda CLI

  1. Navigate to the root directory of the project from the command line.

  2. Configure the network:

corda-cli network config docker-compose solar-system

  1. Run a Gradle command (or run a Gradle task in IntelliJ ) to build the CorDapp and generate the .cpb file:

./gradlew build

This command builds the CorDapp package (.cpk) files. Most CorDapps have two files: a contracts file and a workflows file. The command also builds the CorDapp package bundle (.cpb).

  1. Deploy the network using corda-cli and docker-compose:
corda-cli network deploy -n solar-system -f solar-system.yaml | docker-compose -f - up -d
  1. Wait for the network to be ready with: corda-cli network wait -n solar-system

  2. Check the CorDapp’s status using Corda CLI : corda-cli network status -n solar-system

You’ll be able to see the status of the node. The nodes are up and running when their status is Ready.

  1. Install the application on the network using Corda CLI.

In Corda 4, this process was much more involved. Now you can install the application on the network with a single command:

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

In this command, you must specify the network and the .cpb file. Depending on the Gradle setup, the .cpb will be in one of the build folders and the name may be different.

After running this command, your CorDapp is up and running.

  1. Double-check that everything is working properly:
    1. Open Docker Desktop.
    2. Go to Containers/Apps.
    3. Select the project.

A drop down opens, displaying each node, its status, and its port.

Test the CorDapp

The Corda 5 Developer Preview provides two options for testing your CorDapp. You can use Swagger UI to visualize and interact with the API. Alternatively, you can test the CorDapp using Corda’s Node CLI.

Test the sample CorDapp using Swagger UI

In Corda 4, you needed to build your own Spring application to test a CorDapp with Swagger UI. The Corda 5 Developer Preview comes with built-in HTTP-RPC. This lets you get Swagger UI up and running quickly, so you can test and interact with your APIs visually.

  1. Visit each node’s Swagger UI URL. You’ll need the ports you noted when deploying the CorDapp :

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

  1. Log in. Use these usernames and passwords for each node:
Planet Username Password
Earth earthling password
Mars martian password
Pluto plutonian password

These usernames and passwords are specified in the solar-system.yaml file.

  1. Check which flows are on your CorDapp.
  2. Go to the FlowStarterRPCOps heading.
  3. Run the GET request for registered flows: GET /flowstarter/registeredFlows
  4. Select Execute to run the flow. This flow does not take in any parameters.

This returns the LaunchProbeFlow.

  1. Start the LaunchProbeFlow by sending a POST request: POST /flowstarter/startFlow. Pass the following parameters:
{
  "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\"}"
    }
  }
}

In Corda 4, this process was more complicated because you needed a Java or Kotlin application to run the RPCClient. In the Corda 5 Developer Preview, you can run the RPCClient easily with JavaScript.

The parametersInJson field includes all parameters that the flow takes in. You must create a JSON string with another JSON inside it, then escape all the characters that matter. To escape the characters, insert \ before each " for each parameter and its value.

The X500 name of the receiving node must be included in the target field. The X500 names of all nodes can be found in the solar-system.yaml file.

The flow returns a 200 response, including the flowId (a uuid) and the clientId.

  1. Take the flowId from the previous step to check the flow’s status. Under the FlowStarterRPCOps heading, run the GET request for flow outcomes (GET /flowstarter/flowoutcome/{flowid}). Enter the flowId from the response in step 4.

The flow returns a 200 response, which includes these items in the response body:

  • Flow status
  • Signatures of both parties
  • ID of the state
  1. Test the contract code. This time, try to send a probe to Pluto with planetaryOnly set to true.
{
  "rpcStartFlowRequest": {
    "clientId": "launchpad-1",
    flowName": "net.corda.solarsystem.flows.LaunchProbeFlow",
    "parameters": {
      "parametersInJson": "{\"message\": \"Hello Pluto\", \"target\": \"C=GB, L=FIFTH, O=PLUTO, OU=DWARF_PLANET\", \"planetaryOnly\":\"true\"}"
    }
  }
}

The flow returns a 200 response, including the flowId (a uuid) and the clientId.

  1. Take the flowId from step 6 and run the GET request for flow outcomes again: GET /flowstarter/flowoutcome/{flowid}.

The flow returns a 200 response—but this time the flow has failed because Pluto is not a planet. The message says: Contract verification failed: Failed requirement: Planetary Probes must only visit planets and includes the contract name and transaction ID.

Test the sample CorDapp using Corda Node CLI

You can also use Corda Node CLI to test your CorDapp. This tool lets you perform the same tests as Swagger UI, but you do not need a web browser to run it.

  1. Add a node to Corda Node CLI so you can use the endpoint to run flows. Use the HTTP RPC port you noted when deploying the CorDapp :
corda-node-cli endpoint add -n earth --basic-auth -u earthling -P password https://localhost:<port>/api/v1/
  1. You are prompted with a message asking if you trust the node. Enter y for yes.

  2. Set the node you added to the Corda Node CLI as the default node. This means that the flows you run will be sent to that node.

corda-node-cli endpoint set -e earth
  1. List the flows to see what is available. These flows are all authenticated, so you must include the node’s username and password in this command:
corda-node-cli.cmd flow list -u earthling -P password

This returns the flows available in the CorDapp. This CorDapp only has one flow: net.corda.solarsystem.flows.LaunchProbeFlow

  1. Launch the flow to test its functionality. Pass in the parameters in the same JSON format. Unlike in Swagger UI, you do not need to include the clientId. However, you do need to add the username and password again.
corda-node-cli flow start -n LaunchProbeFlow -A message="hello" -A target="C=US, L=NINTH, O=PLUTO, OU=DWARF_PLANET" -A planetaryOnly=true -u earthling -P password

The flow returns the clientId and the flowId.

  1. Use the flowId from step 5 to check the status of the flow.
corda-node-cli.cmd flow status -s <flow ID> -u earthling -P password

This returns the same output as checking the flow status on Swagger UI. You see:

  • Flow status
  • Signatures of both parties
  • ID of the state

If you have any questions about the Corda Node CLI commands, run the --help command for more information.

Next steps

Now that you’ve run the Solar System demo CorDapp, try building your own CorDapp .

Was this page helpful?

Thanks for your feedback!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.

We're sorry this page wasn't helpful. Let us know how we can make it better!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Create an issue

Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.