From d243ef298ad8a31c31c0fa67bd24fdfcb2c56702 Mon Sep 17 00:00:00 2001 From: RogerWillis Date: Mon, 31 Oct 2016 11:30:57 +0000 Subject: [PATCH 1/4] Beginnings of CorDapp SDK tutorial --- docs/source/index.rst | 1 + docs/source/tutorial-cordapp.rst | 235 +++++++++++++++++++++++++++++++ 2 files changed, 236 insertions(+) create mode 100644 docs/source/tutorial-cordapp.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 13cbaea05a..5a6cb79c15 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -68,6 +68,7 @@ Read on to learn: tutorial-contract tutorial-contract-clauses tutorial-test-dsl + tutorial-cordapp tutorial-clientrpc-api flow-state-machines flow-testing diff --git a/docs/source/tutorial-cordapp.rst b/docs/source/tutorial-cordapp.rst new file mode 100644 index 0000000000..5da66f9e4c --- /dev/null +++ b/docs/source/tutorial-cordapp.rst @@ -0,0 +1,235 @@ +.. highlight:: kotlin +.. raw:: html + + + + +Using the Corda SDK +=================== + +This guide covers how to get started with the `cordapp-template`, the Corda SDK. + +Installing Corda modules +------------------------ + +Firstly, follow the :doc:`getting set up ` page to download the r3prototyping repository, JDK and +IntelliJ. + +At the time of writing the r3prototyping repository comprises of the following Gradle projects: + +* **buildSrc** contains necessary gradle plugins to build Corda. +* **client** contains the RPC client framework. +* **contracts** defines a range of elementary contracts such as abstract fungible assets, cash, +* **core** containing the core Corda libraries such as crypto functions, types for Corda's building blocks; states, + contracts, transactions, attachments, etc. and some interfaces for nodes and protocols. +* **experimental** contains a range of things which have not yet been code reviewed. +* **explorer** which is a GUI front-end for Corda. +* **gradle-plugins** contains a series of plugins necessary for building Corda and publishing JARs. +* **node** contains anything specifically required for creating, running and managing nodes (eg: node driver, servlets, + node services, messaging), persistence +* **test-utils** Defines some helpers for testing such as a DSL for defining contracts as well as a framework for creating + mock Corda networks. + +Once you've cloned the r3prototyping repository check-out the M4 release tag onto a new local branch. + +``git checkout -b corda-m4 tags/release-M0.4`` + +.. note:: You may also opt to work with `origin/master` if you wish to have access to new features but potentially + sacrafice stability. + +Next step is to publish the Corda JARs to your local Maven repository. By default the Maven local repository can be +found: + +* ``~/.m2`` on Unix/Mac OS X +* ``C:\Documents and Settings\{your-username}\.m2`` on windows. + +Publishing can ber done with running the following Gradle task from the root project directory: + +Unix/Mac OSX: + +``./gradlew publishToMavenLocal`` + +Windows: + +``gradlew.bat publishToMavenLocal`` + +This will install all required modules, along with sources and JavaDocs to your local Maven repository. + +.. note:: From the open source release date, CorDapp developers will be able to obtain the Corda JARs directly from + Maven instead of having to clone the r3prototyping repository and publish the Corda JARs to your local Maven + repository. + +As subsequent milestone versions of Corda are released you can pull the new changes from the r3prototyping repository, +check-out the new milestone release and publish the new milestone release to your local Maven repository. + +Getting the CorDapp-template SDK +-------------------------------- + +CorDapps were introduced in Corda milestone M4. They allow developers to arbitrarily extend the functionality of a Corda +node with additional services, protocols and contracts. Typically, you should expect to start all Corda based +development projects using the SDK we provide. It contains the necessary bare-bones for you to begin building your own +CorDapp. + +We maintain a separate repository for the Corda-SDK. You can find the repository `here `_. + +You can clone the repository with the following command: + +``git clone https://bitbucket.org/R3-CEV/cordapp-template`` + +One you've cloned the respository, check-out the M4 version as a new local branch: + +``git checkout -b corcapp-m4 origin/M4`` + +As with the r3prototyping repository, you can also run from master if you wish to have access to new features but +potentially sacrifice stability. + +.. warning:: Make sure that you check-out the correct version of the CorDapp template. E.g. if you are working with + Corda core M4 then use the M4 version of the CorDapp template. + +We recommend you develop your CorDapp with IntelliJ. Boot up IntelliJ and point it to `open...` + +CorDapp-template Project Structure +---------------------------------- + +The CorDapp template contains comprises of the following directory structure: + +.. sourcecode:: shell + + . cordapp-template + ├── README.md + ├── build.gradle + ├── config + │   ├── dev + │   │   └── log4j2.xml + │   └── test + │   └── log4j2.xml + ├── gradle + │   └── wrapper + │   ├── gradle-wrapper.jar + │   └── gradle-wrapper.properties + ├── gradle.properties + ├── gradlew + ├── gradlew.bat + ├── lib + │   ├── README.txt + │   └── quasar.jar + ├── settings.gradle + └── src + ├── main +    │   ├── java +    │   ├── kotlin +    │   │   └── com +    │   │   └── example +    │   │   ├── Main.kt +    │   │   ├── api +    │   │   │   └── ExampleApi.kt +    │   │   ├── client +    │   │   │   └── ExampleClientRPC.kt +    │   │   ├── contract +    │   │   │   ├── ExampleContract.kt +    │   │   │   └── ExampleState.kt +    │   │   ├── model +    │   │   │   └── ExampleModel.kt +    │   │   ├── plugin +    │   │   │   └── ExamplePlugin.kt +    │   │   └── protocol +    │   │   └── ExampleProtocol.kt + │   └── resources + │   ├── META-INF + │   │   └── services + │   │   └── com.r3corda.core.node.CordaPluginRegistry + │   ├── certificates + │   │   ├── readme.txt + │   │   ├── sslkeystore.jks + │   │   └── truststore.jks + │   └── exampleWeb + │   ├── index.html + │   └── js + │   └── example.js + └── test + ├── java + ├── kotlin + │   └── com + │   └── example + │   └── ExampleTest.kt +    └── resources + +* The **root directory** contains some gradle files and a README. +* **config** contains necessary gradle plugins to build Corda. +* **buildSrc** contains necessary gradle plugins to build Corda. +* **buildSrc** contains necessary gradle plugins to build Corda. +* **buildSrc** contains necessary gradle plugins to build Corda. + +The cordapp-template SDK includes the framework for a basic CorDapp setup. + +All CorDapps must sub-class the CordaPlugin Registry class. + +.. sourcecode:: kotlin + + /** + * Implement this interface on a class advertised in a META-INF/services/com.r3corda.core.node.CordaPluginRegistry file + * to extend a Corda node with additional application services. + */ + abstract class CordaPluginRegistry { + /** + * List of JAX-RS classes inside the contract jar. They are expected to have a single parameter constructor that takes a ServiceHub as input. + * These are listed as Class<*>, because in the future they will be instantiated inside a ClassLoader so that + * Cordapp code can be loaded dynamically. + */ + open val webApis: List> = emptyList() + + /** + * Map of static serving endpoints to the matching resource directory. All endpoints will be prefixed with "/web" and postfixed with "\*. + * Resource directories can be either on disk directories (especially when debugging) in the form "a/b/c". Serving from a JAR can + * be specified with: javaClass.getResource("").toExternalForm() + */ + open val staticServeDirs: Map = emptyMap() + + /** + * A Map with an entry for each consumed protocol used by the webAPIs. + * The key of each map entry should contain the ProtocolLogic class name. + * The associated map values are the union of all concrete class names passed to the protocol constructor. + * Standard java.lang.* and kotlin.* types do not need to be included explicitly. + * This is used to extend the white listed protocols that can be initiated from the ServiceHub invokeProtocolAsync method. + */ + open val requiredProtocols: Map> = emptyMap() + + /** + * List of additional long lived services to be hosted within the node. + * They are expected to have a single parameter constructor that takes a ServiceHubInternal as input. + * The ServiceHubInternal will be fully constructed before the plugin service is created and will + * allow access to the protocol factory and protocol initiation entry points there. + */ + open val servicePlugins: List> = emptyList() + } + +# Edit the deployNodes gradle task as required. +# Can add or remove nodes. + +./gradlew deployNodes + +cd build/nodes +sh runnodes + +# All the nodes will startup in the current terminal window. +# Check the deployNodes gradle task to see what port numbers to use. +# You can see that all the nodes offer a web server and api server. + +Build.gradle +------------ + +* corda version. Needs to match that of the corda core version you are using. +* understanding the build gradle file. deploy nodes specifically. How to deploy different classes of node. Deploy nodes is + used to run small test networks of nodes on your local machine. you need a network map service and a notary at a minimum. +* node.conf +* running the nodes. +* Accessing the static served content. +* Accessing the http API. +* Defining new node services. +* Defining new protocols. +* defining new contracts. +* definining new states. +* defining new data structures. +* running from intelliJ (the driver DSL). + + From ce64dbeba7f046c71ffbcc6999bbd8221a480bdf Mon Sep 17 00:00:00 2001 From: RogerWillis Date: Mon, 31 Oct 2016 15:52:10 +0000 Subject: [PATCH 2/4] Added some additional sections and fixed some typos --- docs/source/tutorial-cordapp.rst | 271 +++++++++++++++++++++++++++---- 1 file changed, 239 insertions(+), 32 deletions(-) diff --git a/docs/source/tutorial-cordapp.rst b/docs/source/tutorial-cordapp.rst index 5da66f9e4c..4c991235f6 100644 --- a/docs/source/tutorial-cordapp.rst +++ b/docs/source/tutorial-cordapp.rst @@ -78,7 +78,7 @@ You can clone the repository with the following command: One you've cloned the respository, check-out the M4 version as a new local branch: -``git checkout -b corcapp-m4 origin/M4`` +``git checkout -b cordapp-m4 origin/M4`` As with the r3prototyping repository, you can also run from master if you wish to have access to new features but potentially sacrifice stability. @@ -86,33 +86,32 @@ potentially sacrifice stability. .. warning:: Make sure that you check-out the correct version of the CorDapp template. E.g. if you are working with Corda core M4 then use the M4 version of the CorDapp template. -We recommend you develop your CorDapp with IntelliJ. Boot up IntelliJ and point it to `open...` +We recommend you develop your CorDapp with IntelliJ. Boot up IntelliJ. Navigate to ``File > Open ...``. Select the +folder which you cloned the cordapp-template repository to. When IntelliJ advises you that your Gradle project is +unlinked (via a little bubble which pops up), click on ``import Gradle project``. + +IntelliJ will resolve all the Corda dependencies along with sources and JavaDocs. You are now good to start building +your first CorDapp! CorDapp-template Project Structure ---------------------------------- The CorDapp template contains comprises of the following directory structure: -.. sourcecode:: shell +.. sourcecode:: bash . cordapp-template ├── README.md ├── build.gradle ├── config - │   ├── dev - │   │   └── log4j2.xml - │   └── test - │   └── log4j2.xml + │   ├── ... ├── gradle - │   └── wrapper - │   ├── gradle-wrapper.jar - │   └── gradle-wrapper.properties + │   └── ... ├── gradle.properties ├── gradlew ├── gradlew.bat ├── lib - │   ├── README.txt - │   └── quasar.jar + │   ├── ... ├── settings.gradle └── src ├── main @@ -154,13 +153,120 @@ The CorDapp template contains comprises of the following directory structure: │   └── ExampleTest.kt    └── resources -* The **root directory** contains some gradle files and a README. -* **config** contains necessary gradle plugins to build Corda. -* **buildSrc** contains necessary gradle plugins to build Corda. -* **buildSrc** contains necessary gradle plugins to build Corda. -* **buildSrc** contains necessary gradle plugins to build Corda. +In the file structure above, there are a number of auxillary files and folders you don't need to pay too much attention +to: -The cordapp-template SDK includes the framework for a basic CorDapp setup. +* The **root directory** contains some gradle files and a README. +* **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 is required for runtime instrumentation of classes by Quasar. + +The other parts are of greater importance and covered below. + +The build.gradle File +--------------------- + +It is usually necessary to make a couple of changes to the **build.gradle** file. + +**The buildscript** + +The buildscript is always located at the top of the file. It specifies version numbers for dependencies, among other +things. Ensure that ``corda_version`` is the same as the Corda core modules you published to Maven local. If not then +``git checkout`` the correct version of the cordapp-template. + +.. sourcecode:: groovy + + buildscript { + ext.kotlin_version = '1.0.4' + ext.corda_version = '0.5-SNAPSHOT' // Ensure this version is the same as the corda core modules you are using. + ext.quasar_version = '0.7.6' + ext.jersey_version = '2.23.1' + + repositories { + ... + } + + dependencies { + ... + } + } + +**Project dependencies** + +If you have any additional external dependencies for your CorDapp then add them below the comment at the end of this +code snippet.package. Use the format: + +``compile "{groupId}:{artifactId}:{versionNumber}"`` + +.. sourcecode:: groovy + + dependencies { + compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version" + testCompile group: 'junit', name: 'junit', version: '4.11' + + // Corda integration dependencies + compile "com.r3corda:client:$corda_version" + compile "com.r3corda:core:$corda_version" + compile "com.r3corda:contracts:$corda_version" + compile "com.r3corda:node:$corda_version" + compile "com.r3corda:corda:$corda_version" + compile "com.r3corda:test-utils:$corda_version" + + ... + + // Cordapp dependencies + // Specify your cordapp's dependencies below, including dependent cordapps + } + +For further information about managing depdencies with Gradle look `here `_. + +**CordFormation** + +This is the local node deployment system for CorDapps, the nodes generated are intended to be used for experimenting, +debugging, and testing node configurations and setups but not intended for production or testnet deployment. + +In the CorDapp build.gradle file you'll find a ``deployNodes`` task, this is where you configure the nodes you would +like to deploy for testing. See further details below: + +.. sourcecode:: groovy + + task deployNodes(type: com.r3corda.plugins.Cordform, dependsOn: ['build']) { + directory "./build/nodes" // The output directory. + networkMap "Controller" // The artemis address of the node to be used as the network map. + node { + name "Controller" // Artemis name of node to be deployed. + dirName "controller" // Directory to which the node will + nearestCity "London" // For use with the network visualiser. + advertisedServices = ["corda.notary.validating"] // A list of services you wish the node to offer. + artemisPort 12345 + webPort 12346 // Usually 1 higher than the Artemis port. + cordapps = [] // Add package names of CordaApps. + } + node { + name "NodeA" + dirName "nodea" + nearestCity "London" + advertisedServices = [] + artemisPort 31337 + webPort 31339 + cordapps = [] + } + ... + } + +You can add any number of nodes, with any number of services / CorDapps by editing the templates in ``deployNodes``. The +only requirement is that you must specify a node to run as the network map service and one as the notary service. + +.. note:: CorDapps in the current cordapp-template project are automatically registered with all nodes defined in + ``deployNodes``, although we expect this to change in the near future. + +.. warning:: Make sure that there are no port clashes! + +Service Provider Configuration File +----------------------------------- + +some chat about resources/META-INF/com.r3corda.core.node.CordaPluginRegistry. All CorDapps must sub-class the CordaPlugin Registry class. @@ -203,10 +309,113 @@ All CorDapps must sub-class the CordaPlugin Registry class. open val servicePlugins: List> = emptyList() } -# Edit the deployNodes gradle task as required. -# Can add or remove nodes. +You sub-class it like this: -./gradlew deployNodes +.. sourcecode:: kotlin + + class Plugin() : CordaPluginRegistry() { + ... to be completed ... + } + +**Static Served Content** + +Some chat about serving static content. E.g. from resources/exampleWeb. + +**Protocols** + +To be completed. + +**Services** + +Take an instance of ``ServicehubInternal``, which gives you access to a whole bunch of stuff. To be completed. + +The CorDapp Skeleton +-------------------- + +* MainKt +* api +* client +* contract +* model +* plugin +* protocol + +**API** + +.. sourcecode:: kotlin + + // API is accessible from /api/example. All paths specified below are relative to it. + @Path("example") + class ExampleApi(val services: ServiceHub) { + + ... + + /** + * Displays all current example deals in the ledger + */ + @GET + @Path("deals") + @Produces(MediaType.APPLICATION_JSON) + fun getDeals(): Any { + val states = services.vaultService.linearHeadsOfType() + return states + } + + /** + * This initiates a protocol to agree a deal with the other party. Once the protocol finishes it will + * have written this deal to the ledger. + */ + @PUT + @Path("{party}/create-deal") + fun createDeal(swap: ExampleModel, @PathParam("party") partyName: String): Response { + val otherParty = services.identityService.partyFromName(partyName) + if(otherParty != null) { + // The line below blocks and waits for the future to resolve. + services.invokeProtocolAsync(ExampleProtocol.Requester::class.java, swap, otherParty).get() + return Response.status(Response.Status.CREATED).build() + } else { + return Response.status(Response.Status.BAD_REQUEST).build() + } + } + } + +**Client** + +Some chat about the client RPC framework. + +**Contract** + +Stuff to go here. + +**Model** + +.. sourcecode:: kotlin + + /** + * A simple class with arbitrary data to be written to the ledger. In reality this could be a representation + * of some kind of trade such as an IRS swap for example. + */ + data class ExampleModel(val swapRef: String, val data: String) + +**Protocols** + +Stuff to go here. + +Deploying Your Nodes Locally +---------------------------- + +Some chat about ``./gradlew deployNodes``. + +Talk about what is deployed and in what directories. + +Node.conf. + +/plugins folder. + +Starting your nodes +------------------- + +**Via the command line** cd build/nodes sh runnodes @@ -215,21 +424,19 @@ sh runnodes # Check the deployNodes gradle task to see what port numbers to use. # You can see that all the nodes offer a web server and api server. -Build.gradle ------------- +** Via IntelliJ** + +Running from intelliJ (via the driver DSL). + +Using the cordapp-template project +---------------------------------- -* corda version. Needs to match that of the corda core version you are using. -* understanding the build gradle file. deploy nodes specifically. How to deploy different classes of node. Deploy nodes is - used to run small test networks of nodes on your local machine. you need a network map service and a notary at a minimum. -* node.conf -* running the nodes. * Accessing the static served content. * Accessing the http API. +* Accessing via the client RPC framework. +* Persistence, etc. * Defining new node services. * Defining new protocols. * defining new contracts. * definining new states. -* defining new data structures. -* running from intelliJ (the driver DSL). - - +* defining new data structures. \ No newline at end of file From 435e7da93fa076d21951d533724718572c5ec0d5 Mon Sep 17 00:00:00 2001 From: RogerWillis Date: Thu, 17 Nov 2016 18:31:17 +0000 Subject: [PATCH 3/4] Changed SDK tutorial based on latest repo changes and some feedback. Addressed some review comments. Latest changes to SDK tutorial based on review comments. Corda SDK -> CorDapp Template Addressed review comments + added some new sections. Added pic of run config drop down menu. Added a couple of additional sections. Refactored the 'how to make a cordapp' how to a separate docs pages and stubbed it out for comments. Added index.rst Additional changes based on feedback. Addressed review comments. Removed spurious buuildinfo file. Minor changes based on richard's comments. Still waiting on resolution of dev experience preference. Changed milestone release workflow. Users now should checkout a specific tag. --- docs/source/creating-a-cordapp.rst | 4 +- docs/source/index.rst | 6 +- docs/source/resources/intellij-welcome.png | Bin 0 -> 31175 bytes .../source/resources/run-config-drop-down.png | Bin 0 -> 27786 bytes .../resources/unlinked-gradle-project.png | Bin 0 -> 8697 bytes docs/source/tutorial-cordapp.rst | 909 +++++++++++++----- 6 files changed, 661 insertions(+), 258 deletions(-) create mode 100644 docs/source/resources/intellij-welcome.png create mode 100644 docs/source/resources/run-config-drop-down.png create mode 100644 docs/source/resources/unlinked-gradle-project.png diff --git a/docs/source/creating-a-cordapp.rst b/docs/source/creating-a-cordapp.rst index 9f2d279382..6538c6580c 100644 --- a/docs/source/creating-a-cordapp.rst +++ b/docs/source/creating-a-cordapp.rst @@ -1,5 +1,5 @@ -Creating a CorDapp -================== +CorDapps Background +=================== A Cordapp is an application that runs on the Corda platform using the platform APIs and plugin system. They are self contained in separate JARs from the node server JAR that are created and distributed. diff --git a/docs/source/index.rst b/docs/source/index.rst index 5a6cb79c15..1128c12b0d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,5 @@ -Welcome to the Corda! -===================== +Welcome to the Corda documentation! +=================================== .. warning:: This build of the docs is from the *master branch*, not a milestone release. It may not reflect the current state of the code. @@ -59,6 +59,7 @@ Read on to learn: :caption: CorDapps creating-a-cordapp + tutorial-cordapp .. toctree:: :maxdepth: 2 @@ -68,7 +69,6 @@ Read on to learn: tutorial-contract tutorial-contract-clauses tutorial-test-dsl - tutorial-cordapp tutorial-clientrpc-api flow-state-machines flow-testing diff --git a/docs/source/resources/intellij-welcome.png b/docs/source/resources/intellij-welcome.png new file mode 100644 index 0000000000000000000000000000000000000000..4c3192b54745ddac65919fdbfda7faf21944f302 GIT binary patch literal 31175 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%0DUnE%fP>F?sodzE2C>TNMB(FGy4`S|*BY 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 VX>f#?{`^xwR!T{-Ox(!t{{SCnz?1+0 literal 0 HcmV?d00001 diff --git a/docs/source/tutorial-cordapp.rst b/docs/source/tutorial-cordapp.rst index 4c991235f6..15a25d59e8 100644 --- a/docs/source/tutorial-cordapp.rst +++ b/docs/source/tutorial-cordapp.rst @@ -4,104 +4,611 @@ -Using the Corda SDK -=================== +Using the CorDapp Template +========================== -This guide covers how to get started with the `cordapp-template`, the Corda SDK. +This guide covers how to get started with the `cordapp-template`. Please note there are two Corda repositories: -Installing Corda modules +* ``corda`` which contains the core platform code and sample CorDapps. +* ``cordapp-template`` which contains a template CorDapp you can use to bootstrap your own CorDapps. It is the subject + of this tutorial and should help you understand the basics of building a CorDapp. + +We recommend you read the non-technical white paper and technical white paper before you get started with Corda. + +Getting started +--------------- + +There are two ways to get started with the CorDapp template. You can either work from a milestone release of Corda or a +SNAPSHOT release of Corda. + +**Using a monthly Corda milestone release.** If you wish to develop your CorDapp using the most recent milestone release +then you can get started simply by cloning the ``cordapp-template`` repository. Gradle will grab all the required dependencies +for you from our `public Maven repository `_. + +**Using a Corda SNAPSHOT build.** Alternatively, if you wish to work from the master branch of the Corda repo which contains +the most up-to-date Corda feature set then you will need to clone the ``corda`` repository and publish the latest master +build (or previously tagged releases) to your local Maven repository. You will then need to ensure that Gradle +grabs the correct dependencies for you from Maven local by changing the ``corda_version`` in ``build.gradle``. This will be +covered below in `Using a SNAPSHOT release`_. + +Firstly, follow the :doc:`getting set up ` page to download the JDK, IntelliJ and git if you didn't +already have it. + +Working from milestone releases +------------------------------- + +If you wish to build a CorDapp against a milestone release then please use these instructions. + +The process for developing your CorDapp from a milestone release is the most simple way to get started and is the preferred +approach. + +We publish all our milestone releases to a public Maven repository on a monthly basis. As such, Gradle will automatically +grab the appropriately versioned (specified in the ``cordapp-template``'s ``build.gradle`` file) dependencies for you from Maven. +All you have to do is check out the release tag of the template version you wish to use. + +By default, the ``master`` branch of the ``cordapp-template`` points to a SNAPSHOT release of Corda, this is because it is +being constantly updated to reflect the changes in the master branch of the `corda` repository. + +.. note:: If you wish to use a SNAPSHOT release then follow the instructions below: `Using a SNAPSHOT release`_. + +To clone the ``cordapp-template`` repository, use the following command: + +``git clone https://github.com/corda/cordapp-template`` + +Now change directories to the freshly cloned repo: + +``cd cordapp-template`` + +To enumerate all the tagged releases. Use: + +``git tag`` + +To checkout a specific tag, use: + +``git checkout -b [local_branch_name] tags/[tag_name]`` + +where ``local_branch_name`` is a name of your choice and ``tag_name`` is the name of the tag you wish to checkout. + +Gradle will handle all the dependencies for you. Now you are now ready to get started `building the CorDapp Template`_. + +Using a SNAPSHOT release ------------------------ -Firstly, follow the :doc:`getting set up ` page to download the r3prototyping repository, JDK and -IntelliJ. +If you wish to build a CorDapp against the most current version of Corda, follow these instructions. -At the time of writing the r3prototyping repository comprises of the following Gradle projects: +The Corda repository comprises the following folders: * **buildSrc** contains necessary gradle plugins to build Corda. * **client** contains the RPC client framework. -* **contracts** defines a range of elementary contracts such as abstract fungible assets, cash, -* **core** containing the core Corda libraries such as crypto functions, types for Corda's building blocks; states, +* **config** contains logging configurations and the default node configuration file. +* **core** containing the core Corda libraries such as crypto functions, types for Corda's building blocks: states, contracts, transactions, attachments, etc. and some interfaces for nodes and protocols. -* **experimental** contains a range of things which have not yet been code reviewed. -* **explorer** which is a GUI front-end for Corda. -* **gradle-plugins** contains a series of plugins necessary for building Corda and publishing JARs. +* **docs** contains the Corda docsite in restructured text format as well as the built docs in html. The docs can be + accessed via ``/docs/index.html`` from the root of the repo. +* **finance** defines a range of elementary contracts (and associated schemas) and protocols, such as abstract fungible + assets, cash, obligation and commercial paper. +* **gradle** contains the gradle wrapper which you'll use to execute gradle commands. +* **gradle-plugins** contains some additional plugins which we use to deploy Corda nodes. +* **lib** contains some dependencies. * **node** contains anything specifically required for creating, running and managing nodes (eg: node driver, servlets, - node services, messaging), persistence -* **test-utils** Defines some helpers for testing such as a DSL for defining contracts as well as a framework for creating - mock Corda networks. + node services, messaging, persistence). +* **samples** contains all our Corda demos and code samples. +* **test-utils** contains some utilities for unit testing contracts ( the contracts testing DSL) and protocols (the + mock network) implementation. +* **tools** contains the explorer which is a GUI front-end for Corda. -Once you've cloned the r3prototyping repository check-out the M4 release tag onto a new local branch. +Firstly navigate to the folder on your machine you wish to clone the Corda repository to. Then use the following command +to clone the Corda repository: -``git checkout -b corda-m4 tags/release-M0.4`` +``git clone https://github.com/corda/corda.git`` -.. note:: You may also opt to work with `origin/master` if you wish to have access to new features but potentially - sacrafice stability. +Now change directories: -Next step is to publish the Corda JARs to your local Maven repository. By default the Maven local repository can be +``cd corda`` + +Once you've cloned the ``corda`` repository and are in the repo directory you have the option to remain on the master +branch or checkout a specific branch. Use: + +``git branch --all`` + +to enumerate all the branches. To checkout a specific branch, use: + +``git checkout -b [local_branch_name] origin/[remote_branch_name]`` + +where ``local_branch_name`` is a name of your choice and ``remote_branch_name`` is the name of the remote branch you wish +to checkout. + +.. note:: When working with ``master`` you will have access to the most up-to-date feature set. However you will be + potentially sacrificing stability. We will endeavour to keep the ``master`` branch of the ``cordapp-template`` repo in sync + with the ``master`` branch of ``corda`` repo. A milestone tagged release would be more stable for CorDapp development. + +The next step is to publish the Corda JARs to your local Maven repository. By default the Maven local repository can be found: -* ``~/.m2`` on Unix/Mac OS X -* ``C:\Documents and Settings\{your-username}\.m2`` on windows. +* ``~/.m2/repository`` on Unix/Mac OS X +* ``%HOMEPATH%\.m2`` on windows. -Publishing can ber done with running the following Gradle task from the root project directory: +Publishing can be done with running the following Gradle task from the root project directory: -Unix/Mac OSX: +Unix/Mac OSX: ``./gradlew install`` -``./gradlew publishToMavenLocal`` +Windows: ``gradlew.bat install`` + +This will install all required modules, along with sources and JavaDocs to your local Maven repository. The ``version`` +and ``groupid`` of Corda installed to Maven local is specified in the ``build.gradle`` file in the root of the ``corda`` +repository. You shouldn't have to change these values unless you want to publish multiple versions of a SNAPSHOT, e.g. +if you are trying out new features, in this case you can change ``version`` for each SNAPSHOT you publish. + +.. note:: **A quick point on corda version numbers used by Gradle.** + + In the ``build.gradle`` file for your CorDapp, you can specify the ``corda_version`` to use. It is important that when + developing your CorDapp that you use the correct version number. For example, when wanting to work from a SNAPSHOT + release, the release numbers are suffixed with 'SNAPSHOT', e.g. if the latest milestone release is M6 then the + SNAPSHOT release will be 0.7-SNAPSHOT, and so on. As such, you will set your ``corda_version`` to ``'0.7-SNAPSHOT'`` + in the ``build.gradle`` file in your CorDapp. Gradle will automatically grab the SNAPSHOT dependencies from your local + Maven repository. Alternatively, if working from a milestone release, you will use the version number only, for example + ``0.6`` or ``0.7``. + + Lastly, as the Corda repository evolves on a daily basis up until the next milestone release, it is worth nothing that + the substance of two SNAPSHOT releases of the same number may be different. If you are using a SNAPSHOT and need help + debugging an error then please tell us the **commit** you are working from. This will help us ascertain the issue. + +As additional feature branches are merged into Corda you can ``git pull`` the new changes from the ``corda`` repository. +If you are feeling inquisitive, you may also wish to review some of the current feature branches. All new features are +developed on separate branches. To enumerate all the current branches use: + +``git branch --all`` + +and to check out an open feature branch, use: + +``git checkout -b [local_branch_name] origin/[branch_name]`` + +.. note:: Publishing Corda JARs from unmerged feature branches might cause some unexpected behaviour / broken CorDapps. + It would also replace any previously published SNAPSHOTS of the same version. + +.. warning:: If you do modify Corda after you have previously published it to Maven local then you must republish your + SNAPSHOT build such that Maven reflects the changes you have made. + +Once you have published the Corda JARs to your local Maven repository, you are ready to get started building your +CorDapp using the latest Corda features. + +Opening the CorDapp Template with IntelliJ +------------------------------------------ + +For those familiar with IntelliJ, you can skip this section. + +As noted in the getting started guide, we recommend using the IntelliJ IDE. Assuming you have already downloaded and +installed IntelliJ, lets now open the CorDapp Template with IntelliJ. + +**For those completely new to IntelliJ** + +Firstly, load up IntelliJ. A dialogue will appear: + +.. image:: resources/intellij-welcome.png + :width: 400 + +Click open, then navigate to the folder where you cloned the ``cordapp-template`` and click OK. + +Next, IntelliJ will show a bunch of pop-up windows. One of which requires our attention: + +.. image:: resources/unlinked-gradle-project.png + :width: 400 + +Click the 'import gradle project' link. A dialogue will pop-up. Press OK. Gradle will now begin obtianing all the +project dependencies and perform some indexing. It usually takes a minute or so. If you miss the 'import gradle project' +dialogue, simply close and re-open IntelliJ again to see it again. + +**Alternative approach** + +Alternatively, one can instruct IntelliJ to create a new project through cloning a repository. From the IntelliJ welcome +dialogue (shown above), opt to 'check out from version control', then select git and enter the git url for the CorDpp tempalte +(https://github.com/corda/cordapp-template). You'll then need to import the Gradle project when prompted, as explained above. + +**If you already have IntelliJ open** + +From the ``File`` menu, navigate to ``Open ...`` and then navigate to the directory where you cloned the ``cordapp-template``. +Alternatively, if you wish to clone from github directly then navigate to ``File > New > Project from existing sources ...`` +and enter the URL to the CorDapp Template (specified above). When instructed, be sure to import the Gradle project when prompted. + +**The Gradle plugin** + +IntelliJ can be used to run Gradle tasks through the Gradle plugin which can be found via ``View > Tool windows > Gradle``. +All the Gradle projects are listed in the window on the right hand side of the IDE. Click on a project, then 'tasks' to +see all available Gradle tasks. + +* For the CorDapp Template repo there will only be one Gradle project listed. +* For the Corda repo there will be many project listed, the root project ``corda`` and associated sub-projects: ``core``, + ``finance``, ``node``, etc. + +.. nate:: It's worth noting that when you change branch in the CorDapp template, the ``corda_version`` will change to + reflect the version of the branch you are working from. + +To execute a task, double click it. The output will be shown in a console window. + +Building the CorDapp template +============================= + +**From the command line** + +Firstly, return to your terminal window used above and make sure you are in the ``cordapp-template`` directory. + +To build the CorDapp template use the following command: + +Unix/Mac OSX: ``./gradlew deployNodes`` + +Windows: ``gradlew.bat deployNodes`` + +Building straight away will build the example CorDapp defined the the CorDapp template source. For more information on the example +CorDapp see, `the Example CorDapp`_ section, below. Gradle will then grab all the dependencies for you and build the +example CorDapp. + +The ``deployNodes`` Gradle task allows you easily create a formation of Corda nodes. In the case of the example CorDapp +we are creating `four` nodes. + +After the building process has finished to see the newly built nodes, you can navigate to the ``/build/nodes`` folder +located in the ``cordapp-template`` root directory. You can ignore the other folders in ``/build`` for now. The ``nodes`` +folder has the following structure: + +.. sourcecode:: none + + . nodes + ├── controller + │   ├── corda.jar + │   ├── dependencies + │   ├── node.conf + │   └── plugins + ├── nodea + │   ├── corda.jar + │   ├── dependencies + │   ├── node.conf + │   └── plugins + ├── nodeb + │   ├── corda.jar + │   ├── dependencies + │   ├── node.conf + │   └── plugins + ├── nodec + │   ├── corda.jar + │   ├── dependencies + │   ├── node.conf + │   └── plugins + ├── runnodes + └── runnodes.bat + +There will be one folder generated for each node you build (more on later when we get into the detail of the +``deployNodes`` Gradle task) and a ``runnodes`` shell script (batch file on Widnows). + +Each node folder contains the Corda JAR, a folder for dependencies and a folder for plugins (or CorDapps). There is also +a node.conf file. See :doc:`Corda configuration files `. + +**Building from IntelliJ** + +Open the Gradle window by selecting ``View > Tool windows > Gradle`` from the main menu. You will see the Gradle window +open on the right hand side of the IDE. Expand `tasks` and then expand `other`. Double click on `deployNodes`. Gradle will +start the build process and output progress to a console window in the IDE. + +Running the Sample CorDapp +========================== + +Running the Sample CorDapp from the command line +------------------------------------------------ + +To run the sample CorDapp navigate to the ``build/nodes`` folder and execute the ``runnodes`` shell script with: + +Unix: ``./runnodes`` or ``sh runnodes`` + +Windows: ``runnodes.bat`` + +The ``runnodes`` scripts should create a terminal tab for each node. In each terminal tab, you'll see the Corda welcome +message and some pertinent config information, see below: + +.. sourcecode:: none + + ______ __ + / ____/ _________/ /___ _ + / / __ / ___/ __ / __ `/ Computer science and finance together. + / /___ /_/ / / / /_/ / /_/ / You should see our crazy Christmas parties! + \____/ /_/ \__,_/\__,_/ + + --- DEVELOPER SNAPSHOT ------------------------------------------------------------ + + Logs can be found in : /Users/rogerwillis/Documents/Corda/cordapp-template/build/nodes/nodea/logs + Database connection url is : jdbc:h2:tcp://10.18.0.196:50661/node + Node listening on address : localhost:10004 + Loaded plugins : com.example.plugin.ExamplePlugin + Embedded web server is listening on : http://10.18.0.196:10005/ + Node started up and registered in 39.0 sec + +You'll need to refer to the above later on for the JDBC connection string and port numbers. + +Depending on the speed of your machine, it usually takes around 30 seconds for the nodes to finish starting up. If you +want to double check all the nodes are running you can query the 'status' end-point located at +``http://host:post/api/status``. + +When booted up, the node will generate a bunch of files and directories in addition to the ones covered above: + +.. sourcecode:: none + + . + ├── artemis + ├── attachments + ├── cache + ├── certificates + ├── corda.jar + ├── dependencies + ├── identity-private-key + ├── identity-public + ├── logs + ├── node.conf + ├── persistence.mv.db + └── plugins + +Notably: + +* **artemis** contains the internal files for Artemis MQ, our message broker. +* **attachments** contains any persisted attachments. +* **certificates** contains the certificate store. +* **identity-private-key** is the node's private key. +* **identity-public** is the node's public key. +* **logs** contains the node's log files. +* **persistence.mv.db** is the h2 database where transactions and other data is persisted. + +Additional files and folders are added as the node is running. + +Running CorDapps on separate machines +------------------------------------- + +Corda nodes can be run on separate machines with little additional configuration to the above instructions. + +When you have successfully ran the ``deployNodes`` gradle task, choose which nodes you would like to run on separate +machines. Copy the folders for those nodes from ``build/nodes`` to the other machines. Make sure that you set the +``networkMapAddress`` property in ``node.conf`` to the correct hostname:port where the network map service node is +hosted. + +The nodes can be run on each machine with ``java -jar corda.jar`` from the node's directory. + +Running the example CorDapp via IntelliJ +---------------------------------------- + +To run the example CorDapp via IntelliJ you can use the ``Run Example CorDapp`` run configuration. Select it from the drop +down menu at the top right-hand side of the IDE and press the green arrow to start the nodes. See image below: + +.. image:: resources/run-config-drop-down.png + :width: 400 + +The node driver defined in ``/src/main/kotlin/com/example/Main.kt`` allows you to specify how many nodes you would like +to run and the various configuration settings for each node. With the example CorDapp, the Node driver starts four nodes +and sets up an RPC user for all but the "Controller" node (which hosts the notary Service and network map service): + +.. sourcecode:: kotlin + + fun main(args: Array) { + // No permissions required as we are not invoking flows. + val user = User("user1", "test", permissions = setOf()) + driver(dsl = { + startNode("Controller", setOf(ServiceInfo(ValidatingNotaryService.type))) + startNode("NodeA", rpcUsers = listOf(user)) + startNode("NodeB", rpcUsers = listOf(user)) + startNode("NodeC", rpcUsers = listOf(user)) + waitForAllNodesToFinish() + }, isDebug = true) + } + +To stop the nodes, press the red "stop" button at the top right-hand side of the IDE. + +The node driver can also be used to as a basis for `debugging your CorDapp`_ + +Using the sample CorDapp +======================== + +Background +---------- + +The Example CorDapp implements a basic scenario where a buyer wishes to submit purchase orders to a seller. The scenario +defines four nodes: + +* **Controller** which hosts the network map service and validating notary service. +* **NodeA** who is the buyer. +* **NodeB** who is the seller. +* **NodeC** an unrelated third party. + +NodeA can generate purchase orders for lists and quantities of items and associated metadata such as delivery address +and delivery date. The flows used to facilitate the agreement process always results in an agreement with the seller as +long as the purchase order meets the contract constraints which are defined in ``PurchaseOrderContract.kt``. + +All agreed purchase orders between NodeA and NodeB become "shared facts" between NodeA and NodeB. But note that NodeC +won't see any of these transactions or have copies of any of the resulting ``PurchaseOrderState`` objects. This is +because data is only propagated on a need-to-know basis. + +Interfaces +---------- + +The CorDapp defines a few HTTP API end-points and also serves some static web content. The end-points allow you to +list purchase orders and add purchase orders. + +The nodes can be found using the following port numbers, defined in build.gradle and the respective node.conf file for +each node found in `build/nodes/NodeX`` etc: + +* ``Controller: localhost:10003`` +* ``NodeA: localhost:10005`` +* ``NodeB: localhost:10007`` +* ``NodeC: localhost:10009`` + +Note that the ``deployNodes`` Gradle task is used to generate the ``node.conf`` files for each node. + +As the nodes start-up they should tell you which host and port the embedded web server is running on. The API endpoints +served are as follows: + +* ``/api/example/who-am-i`` +* ``/api/example/get-peers`` +* ``/api/example/purchase-orders`` +* ``/api/example/{COUNTERPARTY}/create-purchase-order`` + +The static web content is served from ``/web/example``. + +A purchase order can be created via accessing the ``api/example/create-purchase-order`` end-point directly or through the +the web form hosted at ``/web/example``. + + .. warning:: **The content in ``web/example`` is only available for demonstration purposes and does not implement any + anti-XSS, anti-XSRF or any other security techniques. Do not copy such code directly into products meant for production use.** + +**Submitting a purchase order via HTTP API:** + +To create a purchase order from NodeA to NodeB, use: + +.. sourcecode:: bash + + echo '{"orderNumber": "1","deliveryDate": "2018-09-15","deliveryAddress": {"city": "London","country": "UK"},"items" : [{"name": "widget","amount": "3"},{"name": "thing","amount": "4"}]}' | curl -T - -H 'Content-Type: application/json' http://localhost:10005/api/example/NodeB/create-purchase-order + +Note the port number ``10005`` (NodeA) and NodeB referenced in the API end-point path. This command instructs NodeA to +create and send a purchase order to NodeB. Upon verification and completion of the process, both nodes (but not NodeC) will +have a signed, notarised copy of the purchase order. + +**Submitting a purchase order via web/example:** + +Navigate to the "create purchase order" button at the top left of the page, enter in the purchase order details e.g. + +.. sourcecode:: none + + Counter-party: Select from list + Order Number: 1 + Delivery Date: 2018-09-15 + City: London + Country Code: UK + Item name: Things + Item amount: 5 + +and click submit (note you can add additional item types and amounts). Upon pressing submit, the modal dialogue should close. +To check what validation is performed over the purchase order data, have a look at the ``PurchaseOrderContract.Place`` class in +``PurchaseOrderContract.kt`` which defines the following contract constraints (among others not included here): + +.. sourcecode:: kotlin + + // Purchase order specific constraints. + "We only deliver to the UK." by (out.po.deliveryAddress.country == "UK") + "You must order at least one type of item." by (out.po.items.size > 0) + "You cannot order zero or negative amounts of an item." by (out.po.items.map(Item::amount).all { it > 0 }) + "You can only order up to 10 items at a time." by (out.po.items.map(Item::amount).sum() <= 10) + val time = tx.timestamp?.midpoint + "The delivery date must be in the future." by (out.po.deliveryDate.toInstant() > time) + +**Once a purchase order has been submitted:** + +Inspect the terminal windows for the nodes. Assume all of the above contract constraints are met, you should see some +activity in the terminal windows for NodeA and NodeB (note: the green ticks are only visible on unix/mac): + +*NodeA:* + +.. sourcecode:: none + + ✅ Constructing proposed purchase order. + ✅ Sending purchase order to seller for review. + ✅ Received partially signed transaction from seller. + ✅ Verifying signatures and contract constraints. + ✅ Signing transaction with our private key. + ✅ Obtaining notary signature. + ✅ Requesting signature by Notary service + ✅ Validating response from Notary service + ✅ Recording transaction in vault. + ✅ Sending fully signed transaction to seller. + ✅ Done + +*NodeB:* + +.. sourcecode:: none + + ✅ Receiving proposed purchase order from buyer. + ✅ Generating transaction based on proposed purchase order. + ✅ Signing proposed transaction with our private key. + ✅ Sending partially signed transaction to buyer and wait for a response. + ✅ Verifying signatures and contract constraints. + ✅ Recording transaction in vault. + ✅ Done + +*NodeC:* + +.. sourcecode:: none + + You shouldn't see any activity. + +Next you can view the newly created purchase order by accessing the vault of NodeA or NodeB: + +*Via the HTTP API:* + +For NodeA. navigate to http://localhost:10005/api/example/purchase-orders. For NodeB, +navigate to http://localhost:10007/api/example/purchase-orders. + +*Via web/example:* + +Navigate to http://localhost:10005/web/example the refresh button in the top left-hand side of the page. You should +see the newly created agreement on the page. + +**Accessing the h2 database via h2 web console:** + +You can connect to the h2 database to see the current state of the ledger, among other data such as the current state of +the network map cache. Firstly, navigate to the folder where you downloaded the h2 web console as part of the pre-requisites +section, above. Change directories to the bin folder: + +``cd h2/bin`` + +Where there are a bunch of shell scripts and batch files. Run the web console: + +Unix: + +``sh h2.sh`` Windows: -``gradlew.bat publishToMavenLocal`` +``h2.bat`` -This will install all required modules, along with sources and JavaDocs to your local Maven repository. +The h2 web console should start up in a web browser tab. To connect we first need to obtain a JDBC connection string. Each +node outputs its connection string in the terminal window as it starts up. In a terminal window where a node is running, +look for the following string: -.. note:: From the open source release date, CorDapp developers will be able to obtain the Corda JARs directly from - Maven instead of having to clone the r3prototyping repository and publish the Corda JARs to your local Maven - repository. +``Database connection url is : jdbc:h2:tcp://10.18.0.150:56736/node`` -As subsequent milestone versions of Corda are released you can pull the new changes from the r3prototyping repository, -check-out the new milestone release and publish the new milestone release to your local Maven repository. +you can use the string on the right to connect to the h2 database: just paste it in to the JDBC URL field and click Connect. +You will be presented with a web application that enumerates all the available tables and provides an interface for you to +query them using SQL. -Getting the CorDapp-template SDK --------------------------------- +**Using the Example RPC client:** -CorDapps were introduced in Corda milestone M4. They allow developers to arbitrarily extend the functionality of a Corda -node with additional services, protocols and contracts. Typically, you should expect to start all Corda based -development projects using the SDK we provide. It contains the necessary bare-bones for you to begin building your own -CorDapp. +The ``/src/main/kotlin/com/example/client/ExampleClientRPC.kt`` file is a simple utility which uses the client RPC library +to connect to a node and log the 'placed' purchase orders. It will log any existing purchase orders and listen for any future +purchase orders. If you haven't placed any purchase orders when you connect to to one of the Nodes via RPC then the client will log +and future purchase orders which are agreed. -We maintain a separate repository for the Corda-SDK. You can find the repository `here `_. +To build the client use the following gradle task: -You can clone the repository with the following command: +``./gradlew runExampleClientRPC`` -``git clone https://bitbucket.org/R3-CEV/cordapp-template`` +*To run the client, via IntelliJ:* -One you've cloned the respository, check-out the M4 version as a new local branch: +Select the 'Run Example RPC Client' run configuration which, by default, connects to NodeA (Artemis port 10004). Click the +Green Arrow to run the client. You can edit the run configuration to connect on a different port. -``git checkout -b cordapp-m4 origin/M4`` +*Via command line:* -As with the r3prototyping repository, you can also run from master if you wish to have access to new features but -potentially sacrifice stability. +Run the following gradle task: -.. warning:: Make sure that you check-out the correct version of the CorDapp template. E.g. if you are working with - Corda core M4 then use the M4 version of the CorDapp template. +``./gradlew runExampleClientRPC localhost:10004`` -We recommend you develop your CorDapp with IntelliJ. Boot up IntelliJ. Navigate to ``File > Open ...``. Select the -folder which you cloned the cordapp-template repository to. When IntelliJ advises you that your Gradle project is -unlinked (via a little bubble which pops up), click on ``import Gradle project``. +To close the application use ``ctrl+C``. For more information on the client RPC interface and how to build an RPC client +application see: -IntelliJ will resolve all the Corda dependencies along with sources and JavaDocs. You are now good to start building -your first CorDapp! +* :doc:`Client RPC documentation ` +* :doc:`Client RPC tutorial ` CorDapp-template Project Structure ---------------------------------- -The CorDapp template contains comprises of the following directory structure: +The CorDapp template has the following directory structure: -.. sourcecode:: bash +.. sourcecode:: none . cordapp-template ├── README.md + ├── LICENSE ├── build.gradle ├── config │   ├── ... @@ -125,18 +632,21 @@ The CorDapp template contains comprises of the following directory structure:    │   │   ├── client    │   │   │   └── ExampleClientRPC.kt    │   │   ├── contract -    │   │   │   ├── ExampleContract.kt -    │   │   │   └── ExampleState.kt +    │   │   │   ├── PurchaseOrderContract.kt +    │   │   │   └── PurchaseOrderState.kt    │   │   ├── model -    │   │   │   └── ExampleModel.kt +    │   │   │   └── PurchaseOrder.kt    │   │   ├── plugin    │   │   │   └── ExamplePlugin.kt -    │   │   └── protocol -    │   │   └── ExampleProtocol.kt +    │   │   └── flow +    │   │   └── ExampleFlow.kt +    │   │   └── service +    │   │   └── ExampleService.kt + │   ├── python │   └── resources │   ├── META-INF │   │   └── services - │   │   └── com.r3corda.core.node.CordaPluginRegistry + │   │   └── net.corda.core.node.CordaPluginRegistry │   ├── certificates │   │   ├── readme.txt │   │   ├── sslkeystore.jks @@ -153,27 +663,36 @@ The CorDapp template contains comprises of the following directory structure: │   └── ExampleTest.kt    └── resources -In the file structure above, there are a number of auxillary files and folders you don't need to pay too much attention -to: +In the file structure above, the most important files and directories to note are: -* The **root directory** contains some gradle files and a README. +* 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 is required for runtime instrumentation of classes by Quasar. +* **src/main/kotlin** contains the source code for the example CorDapp. +* **src/main/python** contains a python script which accesses nodes via RPC. +* **src/main/resources** contains the certificate store, some static web content to be served by the nodes and the + PluginServiceRegistry file. +* **src/test/kotlin** contains unit tests for protocols, contracts, etc. -The other parts are of greater importance and covered below. +Some elements are covered in more detail below. The build.gradle File --------------------- -It is usually necessary to make a couple of changes to the **build.gradle** file. +It is usually necessary to make a couple of changes to the ``build.gradle`` file. Here will cover the most pertinent bits. **The buildscript** -The buildscript is always located at the top of the file. It specifies version numbers for dependencies, among other -things. Ensure that ``corda_version`` is the same as the Corda core modules you published to Maven local. If not then -``git checkout`` the correct version of the cordapp-template. +The buildscript is always located at the top of the file. It determines which plugins, task classes, and other classes +are available for use in the rest of the build script. It also specifies version numbers for dependencies, among other +things. + +If you are working from a Corda SNAPSHOT release which you have publish to Maven local then ensure that +``corda_version`` is the same as the version of the Corda core modules you published to Maven local. If not then change the +``kotlin_version`` property. Also, if you are working from a previous milestone release, then be sure to ``git checkout`` +the correct version of the CorDapp template from the ``cordapp-template`` repo. .. sourcecode:: groovy @@ -195,7 +714,7 @@ things. Ensure that ``corda_version`` is the same as the Corda core modules you **Project dependencies** If you have any additional external dependencies for your CorDapp then add them below the comment at the end of this -code snippet.package. Use the format: +code snippet.package. Use the standard format: ``compile "{groupId}:{artifactId}:{versionNumber}"`` @@ -206,12 +725,12 @@ code snippet.package. Use the format: testCompile group: 'junit', name: 'junit', version: '4.11' // Corda integration dependencies - compile "com.r3corda:client:$corda_version" - compile "com.r3corda:core:$corda_version" - compile "com.r3corda:contracts:$corda_version" - compile "com.r3corda:node:$corda_version" - compile "com.r3corda:corda:$corda_version" - compile "com.r3corda:test-utils:$corda_version" + compile "net.corda:client:$corda_version" + compile "net.corda:core:$corda_version" + compile "net.corda:contracts:$corda_version" + compile "net.corda:node:$corda_version" + compile "net.corda:corda:$corda_version" + compile "net.corda:test-utils:$corda_version" ... @@ -219,12 +738,12 @@ code snippet.package. Use the format: // Specify your cordapp's dependencies below, including dependent cordapps } -For further information about managing depdencies with Gradle look `here `_. +For further information about managing dependencies with `look at the Gradle docs `_. **CordFormation** This is the local node deployment system for CorDapps, the nodes generated are intended to be used for experimenting, -debugging, and testing node configurations and setups but not intended for production or testnet deployment. +debugging, and testing node configurations but not intended for production or testnet deployment. In the CorDapp build.gradle file you'll find a ``deployNodes`` task, this is where you configure the nodes you would like to deploy for testing. See further details below: @@ -232,24 +751,24 @@ like to deploy for testing. See further details below: .. sourcecode:: groovy task deployNodes(type: com.r3corda.plugins.Cordform, dependsOn: ['build']) { - directory "./build/nodes" // The output directory. - networkMap "Controller" // The artemis address of the node to be used as the network map. + directory "./build/nodes" // The output directory. + networkMap "Controller" // The artemis address of the node to be used as the network map. node { - name "Controller" // Artemis name of node to be deployed. - dirName "controller" // Directory to which the node will - nearestCity "London" // For use with the network visualiser. + name "Controller" // Artemis name of node to be deployed. + dirName "controller" // Directory to which the node will + nearestCity "London" // For use with the network visualiser. advertisedServices = ["corda.notary.validating"] // A list of services you wish the node to offer. - artemisPort 12345 - webPort 12346 // Usually 1 higher than the Artemis port. - cordapps = [] // Add package names of CordaApps. + artemisPort 10002 + webPort 10003 // Usually 1 higher than the Artemis port. + cordapps = [] // Add package names of CordaApps. } - node { + node { // Create an additional node. name "NodeA" dirName "nodea" nearestCity "London" advertisedServices = [] - artemisPort 31337 - webPort 31339 + artemisPort 10004 + webPort 10005 cordapps = [] } ... @@ -263,180 +782,64 @@ only requirement is that you must specify a node to run as the network map servi .. warning:: Make sure that there are no port clashes! +When you are finished editing your *CordFormation* the changes will be reflected the next time you run ``./gradlew deployNodes``. + Service Provider Configuration File ----------------------------------- -some chat about resources/META-INF/com.r3corda.core.node.CordaPluginRegistry. +If you are building a CorDapp from scratch or adding a new CorDapp to the CorDapp-template project then you must provide +a reference to your sub-class of ``CordaPluginRegistry`` in the provider-configuration file in located in the the +``resources/META-INF/services`` directory. -All CorDapps must sub-class the CordaPlugin Registry class. +Re-Deploying Your Nodes Locally +------------------------------- + +If you need to create any additional nodes you can do it via the ``build.gradle`` file as discussed above in +``the build.gradle file``_ and in more detail in the :ref:`cordFormation ` section. + +You may also wish to edit the ``/build/nodes//node.conf`` files for your nodes. For more information on +doing this, see the :doc:`Corda configuration file ` page. + +Once you have made some changes to your CorDapp you can redeploy it with the following command: + +Unix/Mac OSX: ``./gradlew deployNodes`` + +Windows: ``gradlew.bat deployNodes`` + +Debugging your CorDapp +---------------------- + +Debugging is done via IntelliJ and can be done using the following steps. + +1. Set your breakpoints. +2. Edit the node driver code in ``Main.kt`` to reflect how many nodes you wish to start along with any other + configuration options. For example, the below starts 4 nodes, with one being the network map service / notary and + sets up RPC credentials for 3 of the nodes. .. sourcecode:: kotlin - /** - * Implement this interface on a class advertised in a META-INF/services/com.r3corda.core.node.CordaPluginRegistry file - * to extend a Corda node with additional application services. - */ - abstract class CordaPluginRegistry { - /** - * List of JAX-RS classes inside the contract jar. They are expected to have a single parameter constructor that takes a ServiceHub as input. - * These are listed as Class<*>, because in the future they will be instantiated inside a ClassLoader so that - * Cordapp code can be loaded dynamically. - */ - open val webApis: List> = emptyList() + fun main(args: Array) { + // No permissions required as we are not invoking flows. + val user = User("user1", "test", permissions = setOf()) + driver(dsl = { + startNode("Controller", setOf(ServiceInfo(ValidatingNotaryService.type))) + startNode("NodeA", rpcUsers = listOf(user)) + startNode("NodeB", rpcUsers = listOf(user)) + startNode("NodeC", rpcUsers = listOf(user)) + waitForAllNodesToFinish() + }, isDebug = true) + } - /** - * Map of static serving endpoints to the matching resource directory. All endpoints will be prefixed with "/web" and postfixed with "\*. - * Resource directories can be either on disk directories (especially when debugging) in the form "a/b/c". Serving from a JAR can - * be specified with: javaClass.getResource("").toExternalForm() - */ - open val staticServeDirs: Map = emptyMap() +3. Select and run the “Run Example CorDapp” run configuration in IntelliJ. +4. IntelliJ will build and run the CorDapp. Observe the console output for the remote debug ports. The “Controller” + node will generally be on port 5005, with NodeA on port 5006 an so-on. - /** - * A Map with an entry for each consumed protocol used by the webAPIs. - * The key of each map entry should contain the ProtocolLogic class name. - * The associated map values are the union of all concrete class names passed to the protocol constructor. - * Standard java.lang.* and kotlin.* types do not need to be included explicitly. - * This is used to extend the white listed protocols that can be initiated from the ServiceHub invokeProtocolAsync method. - */ - open val requiredProtocols: Map> = emptyMap() +.. sourcecode:: none - /** - * List of additional long lived services to be hosted within the node. - * They are expected to have a single parameter constructor that takes a ServiceHubInternal as input. - * The ServiceHubInternal will be fully constructed before the plugin service is created and will - * allow access to the protocol factory and protocol initiation entry points there. - */ - open val servicePlugins: List> = emptyList() - } + Listening for transport dt_socket at address: 5008 + Listening for transport dt_socket at address: 5007 + Listening for transport dt_socket at address: 5006 -You sub-class it like this: +5. Edit the “Debug CorDapp” run configuration with the port of the node you wish to connect to. +6. Run the “Debug CorDapp” run configuration. -.. sourcecode:: kotlin - - class Plugin() : CordaPluginRegistry() { - ... to be completed ... - } - -**Static Served Content** - -Some chat about serving static content. E.g. from resources/exampleWeb. - -**Protocols** - -To be completed. - -**Services** - -Take an instance of ``ServicehubInternal``, which gives you access to a whole bunch of stuff. To be completed. - -The CorDapp Skeleton --------------------- - -* MainKt -* api -* client -* contract -* model -* plugin -* protocol - -**API** - -.. sourcecode:: kotlin - - // API is accessible from /api/example. All paths specified below are relative to it. - @Path("example") - class ExampleApi(val services: ServiceHub) { - - ... - - /** - * Displays all current example deals in the ledger - */ - @GET - @Path("deals") - @Produces(MediaType.APPLICATION_JSON) - fun getDeals(): Any { - val states = services.vaultService.linearHeadsOfType() - return states - } - - /** - * This initiates a protocol to agree a deal with the other party. Once the protocol finishes it will - * have written this deal to the ledger. - */ - @PUT - @Path("{party}/create-deal") - fun createDeal(swap: ExampleModel, @PathParam("party") partyName: String): Response { - val otherParty = services.identityService.partyFromName(partyName) - if(otherParty != null) { - // The line below blocks and waits for the future to resolve. - services.invokeProtocolAsync(ExampleProtocol.Requester::class.java, swap, otherParty).get() - return Response.status(Response.Status.CREATED).build() - } else { - return Response.status(Response.Status.BAD_REQUEST).build() - } - } - } - -**Client** - -Some chat about the client RPC framework. - -**Contract** - -Stuff to go here. - -**Model** - -.. sourcecode:: kotlin - - /** - * A simple class with arbitrary data to be written to the ledger. In reality this could be a representation - * of some kind of trade such as an IRS swap for example. - */ - data class ExampleModel(val swapRef: String, val data: String) - -**Protocols** - -Stuff to go here. - -Deploying Your Nodes Locally ----------------------------- - -Some chat about ``./gradlew deployNodes``. - -Talk about what is deployed and in what directories. - -Node.conf. - -/plugins folder. - -Starting your nodes -------------------- - -**Via the command line** - -cd build/nodes -sh runnodes - -# All the nodes will startup in the current terminal window. -# Check the deployNodes gradle task to see what port numbers to use. -# You can see that all the nodes offer a web server and api server. - -** Via IntelliJ** - -Running from intelliJ (via the driver DSL). - -Using the cordapp-template project ----------------------------------- - -* Accessing the static served content. -* Accessing the http API. -* Accessing via the client RPC framework. -* Persistence, etc. -* Defining new node services. -* Defining new protocols. -* defining new contracts. -* definining new states. -* defining new data structures. \ No newline at end of file From 9c9691ae773fb3baad319ab012571f7ad69ded0d Mon Sep 17 00:00:00 2001 From: RogerWillis Date: Tue, 29 Nov 2016 13:45:58 +0000 Subject: [PATCH 4/4] Addressed review points. Added a stub file in the getting started section that indicates devs should look at the cordapp tutorial. --- docs/source/building-cordapps.rst | 12 ++++++++++++ docs/source/index.rst | 1 + docs/source/tutorial-cordapp.rst | 29 ++++++++++++++++++----------- 3 files changed, 31 insertions(+), 11 deletions(-) create mode 100644 docs/source/building-cordapps.rst diff --git a/docs/source/building-cordapps.rst b/docs/source/building-cordapps.rst new file mode 100644 index 0000000000..6c21993bab --- /dev/null +++ b/docs/source/building-cordapps.rst @@ -0,0 +1,12 @@ +.. highlight:: kotlin +.. raw:: html + + + + +Building CorDapps +================= + +To get started building your own CorDapps checkout the following pages: + +1. :doc:`The CorDapp template `. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 1128c12b0d..4a710822ea 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,6 +30,7 @@ Read on to learn: inthebox getting-set-up running-the-demos + building-cordapps .. toctree:: :maxdepth: 2 diff --git a/docs/source/tutorial-cordapp.rst b/docs/source/tutorial-cordapp.rst index 15a25d59e8..da68ea5ac0 100644 --- a/docs/source/tutorial-cordapp.rst +++ b/docs/source/tutorial-cordapp.rst @@ -4,8 +4,8 @@ -Using the CorDapp Template -========================== +The CorDapp Template +==================== This guide covers how to get started with the `cordapp-template`. Please note there are two Corda repositories: @@ -13,7 +13,14 @@ This guide covers how to get started with the `cordapp-template`. Please note th * ``cordapp-template`` which contains a template CorDapp you can use to bootstrap your own CorDapps. It is the subject of this tutorial and should help you understand the basics of building a CorDapp. -We recommend you read the non-technical white paper and technical white paper before you get started with Corda. +We recommend you read the non-technical white paper and technical white paper before you get started with Corda: + +1. `The Introductory white paper `_ describes the + motivating vision and background of the project. It is the kind of document your boss should read. It describes why the + project exists and briefly compares it to alternative systems on the market. +2. `The Technical white paper `_ describes the entire + intended design from beginning to end. It is the kind of document that you should read, or at least, read parts of. Note + that because the technical white paper describes the intended end state, it does not always align with the implementation. Getting started --------------- @@ -360,7 +367,7 @@ Running CorDapps on separate machines Corda nodes can be run on separate machines with little additional configuration to the above instructions. -When you have successfully ran the ``deployNodes`` gradle task, choose which nodes you would like to run on separate +When you have successfully run the ``deployNodes`` gradle task, choose which nodes you would like to run on separate machines. Copy the folders for those nodes from ``build/nodes`` to the other machines. Make sure that you set the ``networkMapAddress`` property in ``node.conf`` to the correct hostname:port where the network map service node is hosted. @@ -429,18 +436,18 @@ list purchase orders and add purchase orders. The nodes can be found using the following port numbers, defined in build.gradle and the respective node.conf file for each node found in `build/nodes/NodeX`` etc: -* ``Controller: localhost:10003`` -* ``NodeA: localhost:10005`` -* ``NodeB: localhost:10007`` -* ``NodeC: localhost:10009`` +* Controller: ``localhost:10003`` +* NodeA: ``localhost:10005`` +* NodeB: ``localhost:10007`` +* NodeC: ``localhost:10009`` Note that the ``deployNodes`` Gradle task is used to generate the ``node.conf`` files for each node. As the nodes start-up they should tell you which host and port the embedded web server is running on. The API endpoints served are as follows: -* ``/api/example/who-am-i`` -* ``/api/example/get-peers`` +* ``/api/example/me`` +* ``/api/example/peers`` * ``/api/example/purchase-orders`` * ``/api/example/{COUNTERPARTY}/create-purchase-order`` @@ -475,7 +482,7 @@ Navigate to the "create purchase order" button at the top left of the page, ente Delivery Date: 2018-09-15 City: London Country Code: UK - Item name: Things + Item name: Wow such item Item amount: 5 and click submit (note you can add additional item types and amounts). Upon pressing submit, the modal dialogue should close.