2017-01-06 11:05:37 +00:00
|
|
|
CorDapp basics
|
|
|
|
==============
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2017-01-06 11:05:37 +00:00
|
|
|
A CorDapp is an application that runs on the Corda platform using the platform APIs and plugin system. They are self
|
2016-08-24 20:03:20 +00:00
|
|
|
contained in separate JARs from the node server JAR that are created and distributed.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-11-25 14:29:13 +00:00
|
|
|
App plugins
|
2016-08-24 15:19:11 +00:00
|
|
|
-----------
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-08-24 15:19:11 +00:00
|
|
|
.. note:: Currently apps are only supported for JVM languages.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2017-02-28 08:12:18 +00:00
|
|
|
To create an app plugin you must extend from `CordaPluginRegistry`_. The JavaDoc contains
|
2016-08-24 14:33:43 +00:00
|
|
|
specific details of the implementation, but you can extend the server in the following ways:
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2017-01-25 13:45:39 +00:00
|
|
|
1. Required flows: Specify which flows will be whitelisted for use in your RPC calls.
|
2016-09-23 09:55:40 +00:00
|
|
|
2. Service plugins: Register your services (see below).
|
2017-01-25 13:45:39 +00:00
|
|
|
3. Web APIs: You may register your own endpoints under /api/ of the bundled web server.
|
|
|
|
4. Static web endpoints: You may register your own static serving directories for serving web content from the web server.
|
2017-02-28 08:12:18 +00:00
|
|
|
5. Whitelisting your additional contract, state and other classes for object serialization. Any class that forms part
|
|
|
|
of a persisted state, that is used in messaging between flows or in RPC needs to be whitelisted.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-08-24 15:19:11 +00:00
|
|
|
Services
|
|
|
|
--------
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-11-25 13:35:05 +00:00
|
|
|
Services are classes which are constructed after the node has started. It is provided a `PluginServiceHub`_ which
|
2016-11-22 16:30:17 +00:00
|
|
|
allows a richer API than the `ServiceHub`_ exposed to contracts. It enables adding flows, registering
|
2016-08-24 20:03:20 +00:00
|
|
|
message handlers and more. The service does not run in a separate thread, so the only entry point to the service is during
|
2016-08-24 15:19:11 +00:00
|
|
|
construction, where message handlers should be registered and threads started.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
|
|
|
|
2016-11-25 14:29:13 +00:00
|
|
|
Starting nodes
|
2016-08-24 15:19:11 +00:00
|
|
|
--------------
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-11-08 13:49:18 +00:00
|
|
|
To use an app you must also have a node server. To create a node server run the ``gradle deployNodes`` task.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-08-24 15:30:35 +00:00
|
|
|
This will output the node JAR to ``build/libs/corda.jar`` and several sample/standard
|
2016-08-24 20:03:20 +00:00
|
|
|
node setups to ``build/nodes``. For now you can use the ``build/nodes/nodea`` configuration as a template.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-08-31 08:48:19 +00:00
|
|
|
Each node server by default must have a ``node.conf`` file in the current working directory. After first
|
2017-01-06 19:38:48 +00:00
|
|
|
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.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-08-24 15:19:11 +00:00
|
|
|
.. note:: Outside of development environments do not store your node directories in the build folder.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-11-08 13:49:18 +00:00
|
|
|
.. warning:: Also note that the bootstrapping process of the ``corda.jar`` unpacks the Corda dependencies into a
|
|
|
|
temporary folder. It is therefore suggested that the CAPSULE_CACHE_DIR environment variable be set before
|
|
|
|
starting the process to control this location.
|
2016-08-31 08:48:19 +00:00
|
|
|
|
2016-11-25 14:29:13 +00:00
|
|
|
Installing apps
|
2016-09-23 09:55:40 +00:00
|
|
|
---------------
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-08-24 15:19:11 +00:00
|
|
|
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.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-08-24 15:19:11 +00:00
|
|
|
.. note:: If the directory does not exist you can create it manually.
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2016-11-25 14:29:13 +00:00
|
|
|
Starting your node
|
2016-08-23 09:25:06 +00:00
|
|
|
------------------
|
|
|
|
|
2017-03-21 13:45:18 +00:00
|
|
|
Now you have a node server with your app installed, you can run it by navigating to ``<node_dir>`` and running:
|
2016-08-23 09:25:06 +00:00
|
|
|
|
2017-03-21 13:45:18 +00:00
|
|
|
.. code-block:: shell
|
|
|
|
|
|
|
|
Windows: java -jar corda.jar
|
|
|
|
UNIX: ./corda.jar
|
2016-08-23 09:25:06 +00:00
|
|
|
|
|
|
|
The plugin should automatically be registered and the configuration file used.
|
|
|
|
|
|
|
|
.. warning:: If your working directory is not ``<node_dir>`` your plugins and configuration will not be used.
|
|
|
|
|
2016-08-31 08:48:19 +00:00
|
|
|
The configuration file and workspace paths can be overidden on the command line e.g.
|
|
|
|
|
2017-03-21 13:45:18 +00:00
|
|
|
``./corda.jar --config-file=test.conf --base-directory=/opt/r3corda/nodes/test``.
|
2016-08-31 08:48:19 +00:00
|
|
|
|
2017-01-06 19:38:48 +00:00
|
|
|
Otherwise the workspace folder for the node is the current working path.
|
2016-08-31 08:48:19 +00:00
|
|
|
|
2016-11-25 14:29:13 +00:00
|
|
|
Debugging your node
|
2016-09-23 09:55:40 +00:00
|
|
|
-------------------
|
2016-08-31 08:48:19 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2016-11-25 14:29:13 +00:00
|
|
|
Viewing persisted state of your node
|
2016-10-04 18:01:09 +00:00
|
|
|
------------------------------------
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2017-01-18 12:42:22 +00:00
|
|
|
.. _CordaPluginRegistry: api/kotlin/corda/net.corda.core.node/-corda-plugin-registry/index.html
|
|
|
|
.. _PluginServiceHub: api/kotlin/corda/net.corda.core.node/-plugin-service-hub/index.html
|
|
|
|
.. _ServiceHub: api/kotlin/corda/net.corda.core.node/-service-hub/index.html
|
2016-10-05 10:35:12 +00:00
|
|
|
|
2016-11-25 14:29:13 +00:00
|
|
|
Building against Corda
|
2016-10-05 10:35:12 +00:00
|
|
|
----------------------
|
|
|
|
|
2017-03-21 13:45:18 +00:00
|
|
|
To publish to your local Maven repository (in ``~/.m2`` on Unix and ``%HOMEPATH%\.m2`` on Windows) run the following
|
|
|
|
in the root directory of the Corda code:
|
2016-10-05 10:35:12 +00:00
|
|
|
|
|
|
|
.. code-block:: shell
|
|
|
|
|
2016-11-03 15:58:46 +00:00
|
|
|
./gradlew install
|
2016-10-05 10:35:12 +00:00
|
|
|
|
2016-11-04 10:28:42 +00:00
|
|
|
This will publish corda-$version.jar, finance-$version.jar, core-$version.jar and node-$version.jar to the
|
2017-03-21 13:45:18 +00:00
|
|
|
group net.corda. You can now depend on these as you normally would a Maven dependency, using the group id
|
|
|
|
``net.corda``.
|
2016-10-10 11:25:50 +00:00
|
|
|
|
2017-01-06 11:05:37 +00:00
|
|
|
There are several Gradle plugins that reduce your build.gradle boilerplate and make development of CorDapps easier.
|
2016-10-10 11:25:50 +00:00
|
|
|
The available plugins are in the gradle-plugins directory of the Corda repository.
|
|
|
|
|
2017-03-21 13:45:18 +00:00
|
|
|
To install to your local Maven repository the plugins that CorDapp gradle files require, enter the ``gradle-plugins``
|
|
|
|
directory and then run ``../gradle install``. The plugins will now be installed to your local Maven repository.
|
2016-10-10 11:25:50 +00:00
|
|
|
|
2016-11-25 14:29:13 +00:00
|
|
|
Using Gradle plugins
|
2017-01-06 11:05:37 +00:00
|
|
|
~~~~~~~~~~~~~~~~~~~~
|
2016-10-10 11:25:50 +00:00
|
|
|
|
2017-01-06 11:05:37 +00:00
|
|
|
To use the plugins, if you are not already using the CorDapp template project, you must modify your build.gradle. Add
|
2016-10-10 11:25:50 +00:00
|
|
|
the following segments to the relevant part of your build.gradle.
|
|
|
|
|
2016-10-10 15:25:48 +00:00
|
|
|
.. code-block:: groovy
|
2016-10-10 11:25:50 +00:00
|
|
|
|
|
|
|
buildscript {
|
|
|
|
ext.corda_version = '<enter the corda version you build against here>'
|
2016-11-25 16:56:09 +00:00
|
|
|
ext.corda_gradle_plugins_version = '<enter the gradle plugins version here>' // This is usually the same as corda_version.
|
2016-10-10 15:25:48 +00:00
|
|
|
... your buildscript ...
|
2016-10-10 11:25:50 +00:00
|
|
|
|
|
|
|
repositories {
|
2016-10-10 15:25:48 +00:00
|
|
|
... other repositories ...
|
2016-10-10 11:25:50 +00:00
|
|
|
mavenLocal()
|
|
|
|
}
|
|
|
|
|
|
|
|
dependencies {
|
2016-10-10 15:25:48 +00:00
|
|
|
... your dependencies ...
|
2016-11-25 16:56:09 +00:00
|
|
|
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"
|
2016-10-10 11:25:50 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2016-11-10 13:14:38 +00:00
|
|
|
apply plugin: 'net.corda.plugins.cordformation'
|
|
|
|
apply plugin: 'net.corda.plugins.quasar-utils'
|
|
|
|
apply plugin: 'net.corda.plugins.publish-utils'
|
2016-10-10 15:25:48 +00:00
|
|
|
|
|
|
|
repositories {
|
|
|
|
mavenLocal()
|
|
|
|
... other repositories here ...
|
|
|
|
}
|
|
|
|
|
|
|
|
dependencies {
|
2016-11-10 13:14:38 +00:00
|
|
|
compile "net.corda.core:$corda_version"
|
|
|
|
compile "net.corda.finance:$corda_version"
|
|
|
|
compile "net.corda.node:$corda_version"
|
|
|
|
compile "net.corda.corda:$corda_version"
|
2016-10-10 15:25:48 +00:00
|
|
|
... other dependencies here ...
|
|
|
|
}
|
|
|
|
|
2016-10-10 15:34:11 +00:00
|
|
|
... your tasks ...
|
|
|
|
|
2017-01-06 11:05:37 +00:00
|
|
|
// Standard way to publish CorDapps to maven local with the maven-publish and publish-utils plugin.
|
2016-10-10 15:35:16 +00:00
|
|
|
publishing {
|
|
|
|
publications {
|
|
|
|
jarAndSources(MavenPublication) {
|
|
|
|
from components.java
|
|
|
|
// The two lines below are the tasks added by this plugin.
|
|
|
|
artifact sourceJar
|
|
|
|
artifact javadocJar
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2016-10-10 11:25:50 +00:00
|
|
|
|
2016-10-10 15:25:48 +00:00
|
|
|
Cordformation
|
2017-01-06 11:05:37 +00:00
|
|
|
~~~~~~~~~~~~~
|
2016-10-10 15:25:48 +00:00
|
|
|
|
2017-01-06 11:05:37 +00:00
|
|
|
Cordformation is the local node deployment system for CorDapps, the nodes generated are intended to be used for
|
2016-10-10 15:25:48 +00:00
|
|
|
experimenting, debugging, and testing node configurations and setups but not intended for production or testnet
|
|
|
|
deployment.
|
|
|
|
|
2016-11-10 13:14:38 +00:00
|
|
|
To use this gradle plugin you must add a new task that is of the type ``net.corda.plugins.Cordform`` to your
|
2016-10-10 15:27:02 +00:00
|
|
|
build.gradle and then configure the nodes you wish to deploy with the Node and nodes configuration DSL.
|
2017-02-08 10:34:54 +00:00
|
|
|
This DSL is specified in the `JavaDoc <api/index.html>`_. An example of this is in the CorDapp template and below
|
2016-10-10 15:27:02 +00:00
|
|
|
is a three node example;
|
2016-10-10 15:25:48 +00:00
|
|
|
|
|
|
|
.. code-block:: text
|
|
|
|
|
2017-04-04 14:45:41 +00:00
|
|
|
task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
|
2016-10-10 15:25:48 +00:00
|
|
|
directory "./build/nodes" // The output directory
|
2016-12-22 14:48:27 +00:00
|
|
|
networkMap "Controller" // The artemis address of the node named here will be used as the networkMapService.address on all other nodes.
|
2016-10-10 15:25:48 +00:00
|
|
|
node {
|
2016-10-11 15:55:50 +00:00
|
|
|
name "Controller"
|
2016-10-10 15:25:48 +00:00
|
|
|
nearestCity "London"
|
2016-11-08 14:26:30 +00:00
|
|
|
advertisedServices = [ "corda.notary.validating" ]
|
2017-03-17 10:32:14 +00:00
|
|
|
p2pPort 10002
|
|
|
|
rpcPort 10003
|
|
|
|
webPort 10004
|
2017-03-31 09:36:34 +00:00
|
|
|
h2Port 11002
|
2016-10-11 15:41:12 +00:00
|
|
|
cordapps []
|
2016-10-10 15:25:48 +00:00
|
|
|
}
|
|
|
|
node {
|
|
|
|
name "NodeA"
|
|
|
|
nearestCity "London"
|
2016-11-08 14:26:30 +00:00
|
|
|
advertisedServices = []
|
2017-03-17 10:32:14 +00:00
|
|
|
p2pPort 10005
|
|
|
|
rpcPort 10006
|
|
|
|
webPort 10007
|
2017-03-31 09:36:34 +00:00
|
|
|
h2Port 11005
|
2016-10-11 15:41:12 +00:00
|
|
|
cordapps []
|
2016-10-10 15:25:48 +00:00
|
|
|
}
|
|
|
|
node {
|
|
|
|
name "NodeB"
|
|
|
|
nearestCity "New York"
|
2016-11-08 14:26:30 +00:00
|
|
|
advertisedServices = []
|
2017-03-17 10:32:14 +00:00
|
|
|
p2pPort 10008
|
|
|
|
rpcPort 10009
|
|
|
|
webPort 10010
|
2017-03-31 09:36:34 +00:00
|
|
|
h2Port 11008
|
2016-10-11 15:41:12 +00:00
|
|
|
cordapps []
|
2016-10-10 15:25:48 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
You can create more configurations with new tasks that extend Cordform.
|
|
|
|
|
|
|
|
New nodes can be added by simply adding another node block and giving it a different name, directory and ports. When you
|
2017-03-21 13:45:18 +00:00
|
|
|
run this task it will install the nodes to the directory specified and a script will be generated to run the nodes with
|
|
|
|
one command (``runnodes``). On MacOS X this script will run each node in a new terminal tab, and on Linux it will open
|
|
|
|
up a new XTerm for each node. On Windows the (``runnodes.bat``) script will run one node per window.
|
2016-10-10 15:25:48 +00:00
|
|
|
|
2017-01-06 11:05:37 +00:00
|
|
|
Other CorDapps can also be specified if they are already specified as classpath or compile dependencies in your
|
2016-11-08 14:26:30 +00:00
|
|
|
``build.gradle``.
|