CorDapp basics¶

App plugins¶

To create an app plugin you must you must extend from CordaPluginRegistry. The JavaDoc contains specific details of the implementation, but you can extend the server in the following ways:

1. Required flows: Specify which flows will be whitelisted for use in your web APIs.
2. Service plugins: Register your services (see below).
3. Web APIs: You may register your own endpoints under /api/ of the built-in web server.
4. Static web endpoints: You may register your own static serving directories for serving web content.
5. Registering your additional classes used in RPC.

Services¶

Services are classes which are constructed after the node has started. It is provided a PluginServiceHub which allows a richer API than the ServiceHub exposed to contracts. It enables adding flows, registering message handlers and more. The service does not run in a separate thread, so the only entry point to the service is during construction, where message handlers should be registered and threads started.

Starting nodes¶

To use an app you must also have a node server. To create a node server run the gradle deployNodes task.

This will output the node JAR to build/libs/corda.jar and several sample/standard node setups to build/nodes. For now you can use the build/nodes/nodea configuration as a template.

Each node server by default must have a node.conf file in the current working directory. After first execution of the node server there will be many other configuration and persistence files created in this workspace directory. The directory can be overridden by the --base-directory=<workspace> command line argument.

Installing apps¶

Once you have created your app JAR you can install it to a node by adding it to <node_dir>/plugins/. In this case the node_dir is the location where your node server’s JAR and configuration file is.

Starting your node¶

Now you have a node server with your app installed, you can run it by navigating to <node_dir> and running

java -jar corda.jar

The plugin should automatically be registered and the configuration file used.

The configuration file and workspace paths can be overidden on the command line e.g.

java -jar corda.jar --config-file=test.conf --base-directory=/opt/r3corda/nodes/test.

Otherwise the workspace folder for the node is the current working path.

Debugging your node¶

To enable remote debugging of the corda process use a command line such as:

java -Dcapsule.jvm.args="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" -jar corda.jar

This command line will start the debugger on port 5005 and pause the process awaiting debugger attachment.

Viewing persisted state of your node¶

To make examining the persisted contract states of your node or the internal node database tables easier, and providing you are using the default database configuration used for demos, you should be able to connect to the internal node database over a JDBC connection at the URL that is output to the logs at node start up. That URL will be of the form jdbc:h2:tcp://<host>:<port>/node.

The user name and password for the login are as per the node data source configuration.

The name and column layout of the internal node tables is in a state of flux and should not be relied upon to remain static at the present time, and should certainly be treated as read-only.

Building against Corda¶

Corda now supports publishing to Maven local to build against it. To publish to Maven local run the following in the root directory of Corda

./gradlew install

This will publish corda-$version.jar, finance-$version.jar, core-$version.jar and node-$version.jar to the group net.corda. You can now depend on these as you normally would a Maven dependency.

Gradle plugins for CorDapps¶

There are several Gradle plugins that reduce your build.gradle boilerplate and make development of CorDapps easier. The available plugins are in the gradle-plugins directory of the Corda repository.

./gradlew install

buildscript {
    ext.corda_version = '<enter the corda version you build against here>'
    ext.corda_gradle_plugins_version = '<enter the gradle plugins version here>' // This is usually the same as corda_version.
    ... your buildscript ...

    repositories {
        ... other repositories ...
        mavenLocal()
    }

    dependencies {
        ... your dependencies ...
        classpath "net.corda.plugins:cordformation:$corda_gradle_plugins_version"
        classpath "net.corda.plugins:quasar-utils:$corda_gradle_plugins_version"
        classpath "net.corda.plugins:publish-utils:$corda_gradle_plugins_version"
    }
}

apply plugin: 'net.corda.plugins.cordformation'
apply plugin: 'net.corda.plugins.quasar-utils'
apply plugin: 'net.corda.plugins.publish-utils'

repositories {
    mavenLocal()
    ... other repositories here ...
}

dependencies {
    compile "net.corda.core:$corda_version"
    compile "net.corda.finance:$corda_version"
    compile "net.corda.node:$corda_version"
    compile "net.corda.corda:$corda_version"
    ... other dependencies here ...
}

... your tasks ...

// Standard way to publish CorDapps to maven local with the maven-publish and publish-utils plugin.
publishing {
    publications {
        jarAndSources(MavenPublication) {
            from components.java
            // The two lines below are the tasks added by this plugin.
            artifact sourceJar
            artifact javadocJar
        }
    }
}

task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['build']) {
    directory "./build/nodes" // The output directory
    networkMap "Controller" // The artemis address of the node named here will be used as the networkMapService.address on all other nodes.
    node {
        name "Controller"
        nearestCity "London"
        advertisedServices = [ "corda.notary.validating" ]
        artemisPort 12345
        webPort 12346
        cordapps []
    }
    node {
        name "NodeA"
        nearestCity "London"
        advertisedServices = []
        artemisPort 31337
        webPort 31339
        cordapps []
    }
    node {
        name "NodeB"
        nearestCity "New York"
        advertisedServices = []
        artemisPort 31338
        webPort 31340
        cordapps []
    }
}