ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-06-23 09:25:36 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'master' into release/4

Browse Source
This commit is contained in:
Katelyn Baker
2019-04-03 16:01:54 +01:00
parent 6e44193012 2685596798
commit 71114cd412
539 changed files with 4954 additions and 2258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/source/api-contract-constraints.rst
View File

@ -24,7 +24,7 @@ to it.
There are several types of constraint:
1. Hash constraint: exactly one version of the app can be used with this state.
2. Zone whitelist constraint: the compatibility zone operator lists the hashes of the versions that can be used with this contract class name.
2. Compatibility zone whitelisted (or CZ whitelisted) constraint: the compatibility zone operator lists the hashes of the versions that can be used with this contract class name.
3. Signature constraint: any version of the app signed by the given ``CompositeKey`` can be used.
4. Always accept constraint: any app can be used at all. This is insecure but convenient for testing.
@ -46,6 +46,8 @@ to issue the states was signed by Alice and Bob, every transaction must use an a
the constraint used by equivalent output states (i.e. output states that use the same contract class name) must match the
input state, so it can't be changed and you can't combine states with incompatible constraints together in the same transaction.
.. _implicit_vs_explicit_upgrades:
**Implicit vs explicit.** Constraints are not the only way to manage upgrades to transactions. There are two ways of handling
upgrades to a smart contract in Corda:
@ -136,15 +138,15 @@ From there it's suspended waiting to be retried on node restart.
This gives the node operator the opportunity to recover from those errors, which in the case of constraint violations means
adding the right cordapp jar to the ``cordapps`` folder.
.. _relax_hash_constraints_checking_ref:
Hash constrained states in private networks
-------------------------------------------
Where private networks started life using CorDapps with hash constrained states, we have introduced a mechanism to relax the checking of
these hash constrained states when upgrading to signed CorDapps using signature constraints.
The following java system property may be set to relax the hash constraint checking behaviour:
-Dnet.corda.node.disableHashConstraints="true"
The Java system property ``-Dnet.corda.node.disableHashConstraints="true"`` may be set to relax the hash constraint checking behaviour.
This mode should only be used upon "out of band" agreement by all participants in a network.
@ -191,56 +193,11 @@ During transaction building the ``AutomaticPlaceholderConstraint`` for output st
will be selected based on a variety of factors so that the above holds true. If it can't find attachments in storage or there are no
possible constraints, the ``TransactionBuilder`` will throw an exception.
Constraints migration to Corda 4
--------------------------------
How to use the ``SignatureAttachmentConstraint`` if states were already created on the network with the ``WhitelistedByZoneAttachmentConstraint``
-------------------------------------------------------------------------------------------------------------------------------------------------
1. As the original developer of the corDapp, the first step is to sign the latest version of the JAR that was released (see :doc:`cordapp-build-systems`).
The key used for signing will be used to sign all subsequent releases, so it should be stored appropriately. The JAR can be signed by multiple keys owned
by different parties and it will be expressed as a ``CompositeKey`` in the ``SignatureAttachmentConstraint`` (See :doc:`api-core-types`).
Use `JAR signing and verification tool <https://docs.oracle.com/javase/tutorial/deployment/jar/verify.html>`_ to sign the existing JAR.
The signing capability of :ref:`corda-gradle-plugins <cordapp_build_system_signing_cordapp_jar_ref>` cannot be used in this context as it signs the JAR while building it from source.
2. Whitelist this newly signed JAR with the Zone operator. The Zone operator should check that the JAR is signed and not allow any
more versions of it to be whitelisted in the future. From now on the developer(s) who signed the JAR are responsible for new versions.
3. Any flows that build transactions using this Cordapp will have the responsibility of transitioning states to the ``SignatureAttachmentConstraint``.
This is done explicitly in the code by setting the constraint of the output states to signers of the latest version of the whitelisted jar.
In the near future we will make this transition automatic if we detect that the previous 2 steps were executed.
4. As a node operator you need to add the new signed version of the contracts cordapp to the "cordapps" folder together with the latest version of the flows jar
that will contain code like:
.. container:: codeset
.. sourcecode:: kotlin
// This will read the signers for the deployed cordapp.
val attachment = this.serviceHub.cordappProvider.getContractAttachmentID(contractClass)
val signers = this.serviceHub.attachments.openAttachment(attachment!!)!!.signerKeys
// Create the key that will have to pass for all future versions.
val ownersKey = signers.first()
val txBuilder = TransactionBuilder(notary)
// Set the Signature constraint on the new state to migrate away from the WhitelistConstraint.
.addOutputState(outputState, constraint = SignatureAttachmentConstraint(ownersKey))
...
.. sourcecode:: java
// This will read the signers for the deployed cordapp.
SecureHash attachment = this.getServiceHub().getCordappProvider().getContractAttachmentID(contractClass);
List<PublicKey> signers = this.getServiceHub().getAttachments().openAttachment(attachment).getSignerKeys();
// Create the key that will have to pass for all future versions.
PublicKey ownersKey = signers.get(0);
TransactionBuilder txBuilder = new TransactionBuilder(notary)
// Set the Signature constraint on the new state to migrate away from the WhitelistConstraint.
.addOutputState(outputState, myContract, new SignatureAttachmentConstraint(ownersKey))
...
Please read :doc:`cordapp-constraint-migration` to understand how to consume and evolve pre-Corda 4 issued hash or CZ whitelisted constrained states
using a Corda 4 signed CorDapp (using signature constraints).
Debugging
---------
@ -276,8 +233,8 @@ The same example in Java:
});
Staring a node missing CorDapp(s)
*********************************
Starting a node missing CorDapp(s)
**********************************
When running the Corda node ensure all CordDapp JARs are placed in ``cordapps`` directory of each node.
By default Gradle Cordform task ``deployNodes`` copies all JARs if CorDapps to deploy are specified.

15
docs/source/api-flows.rst
View File

@ -613,6 +613,21 @@ flow to receive the transaction:
``idOfTxWeSigned`` is an optional parameter used to confirm that we got the right transaction. It comes from using ``SignTransactionFlow``
which is described below.
**Error handling behaviour**
Once a transaction has been notarised and its input states consumed by the flow initiator (eg. sender), should the participant(s) receiving the
transaction fail to verify it, or the receiving flow (the finality handler) fails due to some other error, we then have a scenario where not
all parties have the correct up to date view of the ledger (a condition where eventual consistency between participants takes longer than is
normally the case under Corda's `eventual consistency model <https://en.wikipedia.org/wiki/Eventual_consistency>`_). To recover from this scenario,
the receiver's finality handler will automatically be sent to the :doc:`node-flow-hospital` where it's suspended and retried from its last checkpoint
upon node restart, or according to other conditional retry rules explained in :ref:`flow hospital runtime behaviour <flow-hospital-runtime>`.
This gives the node operator the opportunity to recover from the error. Until the issue is resolved the node will continue to retry the flow
on each startup. Upon successful completion by the receiver's finality flow, the ledger will become fully consistent once again.
.. warning:: It's possible to forcibly terminate the erroring finality handler using the ``killFlow`` RPC but at the risk of an inconsistent view of the ledger.
.. note:: A future release will allow retrying hospitalised flows without restarting the node, i.e. via RPC.
CollectSignaturesFlow/SignTransactionFlow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The list of parties who need to sign a transaction is dictated by the transaction's commands. Once we've signed a

2
docs/source/api-persistence.rst
View File

@ -12,7 +12,7 @@ API: Persistence
Corda offers developers the option to expose all or some parts of a contract state to an *Object Relational Mapping*
(ORM) tool to be persisted in a *Relational Database Management System* (RDBMS).
The purpose of this, is to assist `vault <https://docs.corda.net/vault.html>`_
The purpose of this, is to assist :doc:`key-concepts-vault`
development and allow for the persistence of state data to a custom database table. Persisted states held in the
vault are indexed for the purposes of executing queries. This also allows for relational joins between Corda tables
and the organization's existing data.

2
docs/source/api-scanner.rst
View File

@ -36,7 +36,7 @@ broken Corda's API.
How it works
------------
The ``generateApi`` Gradle task writes a summary of Corda's public API into the file ``build/api/api-corda-<version>.txt``.
The ``generateApi`` Gradle task writes a summary of Corda's public API into the file ``build/api/api-corda-|corda_version|.txt``.
The ``.ci/check-api-changes.sh`` script then compares this file with the contents of ``.ci/api-current.txt``, which is a
managed file within the Corda repository.

8
docs/source/api-testing.rst
View File

@ -161,8 +161,8 @@ Further examples
* See the flow testing tutorial :doc:`here <flow-testing>`
* See the oracle tutorial :doc:`here <oracles>` for information on testing ``@CordaService`` classes
* Further examples are available in the Example CorDapp in
`Java <https://github.com/corda/cordapp-example/blob/release-V3/java-source/src/test/java/com/example/flow/IOUFlowTests.java>`_ and
`Kotlin <https://github.com/corda/cordapp-example/blob/release-V3/kotlin-source/src/test/kotlin/com/example/flow/IOUFlowTests.kt>`_
`Java <https://github.com/corda/samples/blob/release-V|platform_version|/cordapp-example/workflows-java/src/test/java/com/example/flow/IOUFlowTests.java>`_ and
`Kotlin <https://github.com/corda/samples/blob/release-V|platform_version|/cordapp-example/workflows-kotlin/src/test/kotlin/com/example/flow/IOUFlowTests.kt>`_
Contract testing
----------------
@ -380,5 +380,5 @@ Further examples
* See the flow testing tutorial :doc:`here <tutorial-test-dsl>`
* Further examples are available in the Example CorDapp in
`Java <https://github.com/corda/cordapp-example/blob/release-V3/java-source/src/test/java/com/example/flow/IOUFlowTests.java>`_ and
`Kotlin <https://github.com/corda/cordapp-example/blob/release-V3/kotlin-source/src/test/kotlin/com/example/flow/IOUFlowTests.kt>`_
`Java <https://github.com/corda/samples/blob/release-V|platform_version|/cordapp-example/workflows-java/src/test/java/com/example/flow/IOUFlowTests.java>`_ and
`Kotlin <https://github.com/corda/samples/blob/release-V|platform_version|/cordapp-example/workflows-kotlin/src/test/kotlin/com/example/flow/IOUFlowTests.kt>`_

55
docs/source/app-upgrade-notes.rst
View File

@ -30,17 +30,19 @@ Although the RPC API is backwards compatible with Corda 3, the RPC wire protocol
updated in lockstep with the node to use the new version of the RPC library. Corda 4 delivers RPC wire stability and therefore in future you
will be able to update the node and apps without updating RPC clients.
.. _cordapp_upgrade_version_numbers_ref:
Step 2. Adjust the version numbers in your Gradle build files
-------------------------------------------------------------
Alter the versions you depend on in your Gradle file like so:
.. sourcecode:: groovy
.. code:: groovy
ext.corda_release_version = '4.0'
ext.corda_gradle_plugins_version = '4.0.38'
ext.kotlin_version = '1.2.71'
ext.quasar_version = '0.7.10'
ext.corda_release_version = '|corda_version|'
ext.corda_gradle_plugins_version = '|gradle_plugins_version|'
ext.kotlin_version = '|kotlin_version|'
ext.quasar_version = '|quasar_version|'
.. note:: You may wish to update your kotlinOptions to use language level 1.2, to benefit from the new features. Apps targeting Corda 4
may not at this time use Kotlin 1.3, as it was released too late in the development cycle
@ -154,6 +156,8 @@ Would become:
See :ref:`cordapp_configuration_files_ref` for more information.
.. _cordapp_upgrade_finality_flow_ref:
Step 5. Security: Upgrade your use of FinalityFlow
--------------------------------------------------
@ -161,11 +165,25 @@ The previous ``FinalityFlow`` API is insecure. It doesn't have a receive flow, s
all signed transactions that are sent to it, without checks. It is **highly** recommended that existing CorDapps migrate
away to the new API, as otherwise things like business network membership checks won't be reliably enforced.
This is a three step process:
The flows that make use of ``FinalityFlow`` in a CorDapp can be classified in the following 2 basic categories:
* **non-initiating flows**: these are flows that finalise a transaction without the involvement of a counterpart flow at all.
* **initiating flows**: these are flows that initiate a counterpart (responder) flow.
There is a main difference between these 2 different categories, which is relevant to how the CorDapp can be upgraded.
The second category of flows can be upgraded to use the new ``FinalityFlow`` in a backwards compatible way, which means the upgraded CorDapp can be deployed at the various nodes using a *rolling deployment*.
On the other hand, the first category of flows cannot be upgraded to the new ``FinalityFlow`` in a backwards compatible way, so the changes to these flows need to be deployed simultaneously at all the nodes, using a *lockstep deployment*.
.. note:: A *lockstep deployment* is one, where all the involved nodes are stopped, upgraded to the new version of the CorDapp and then re-started.
As a result, there can't be any nodes running different versions of the CorDapp at any time.
A *rolling deployment* is one, where every node can be stopped, upgraded to the new version of the CorDapp and re-started independently and on its own pace.
As a result, there can be nodes running different versions of the CorDapp and transact with each other successfully.
The upgrade is a three step process:
1. Change the flow that calls ``FinalityFlow``.
2. Change or create the flow that will receive the finalised transaction.
3. Make sure your application's minimum and target version numbers are both set to 4 (see step 2).
3. Make sure your application's minimum and target version numbers are both set to 4 (see :ref:`cordapp_upgrade_version_numbers_ref`).
Upgrading a non-initiating flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -220,7 +238,7 @@ to record the finalised transaction:
:end-before: DOCEND SimpleNewResponderFlow
:dedent: 4
.. note:: All the nodes in your business network will need the new CorDapp, otherwise they won't know how to receive the transaction. **This
.. note:: As described above, all the nodes in your business network will need the new CorDapp, otherwise they won't know how to receive the transaction. **This
includes nodes which previously didn't have the old CorDapp.** If a node is sent a transaction and it doesn't have the new CorDapp loaded
then simply restart it with the CorDapp and the transaction will be recorded.
@ -358,6 +376,9 @@ automatically use them if your application JAR is signed. **We recommend all JAR
with developer certificates is deployed to a production node, the node will refuse to start. Therefore to deploy apps built for Corda 4
to production you will need to generate signing keys and integrate them with the build process.
.. note:: Please read the :doc:`cordapp-constraint-migration` guide to understand how to upgrade CorDapps to use Corda 4 signature constraints and consume
existing states on ledger issued with older constraint types (e.g. Corda 3.x states issued with **hash** or **CZ whitelisted** constraints).
Step 10. Security: Package namespace handling
---------------------------------------------
@ -411,4 +432,20 @@ Corda 4 adds several new APIs that help you build applications. Why not explore:
* The `new withEntityManager API <api/javadoc/net/corda/core/node/ServiceHub.html#withEntityManager-block->`_ for using JPA inside your flows and services.
* :ref:`reference_states`, that let you use an input state without consuming it.
* :ref:`state_pointers`, that make it easier to 'point' to one state from another and follow the latest version of a linear state.
* :ref:`state_pointers`, that make it easier to 'point' to one state from another and follow the latest version of a linear state.
Please also read the :doc:`CorDapp Upgradeability Guarantees <cordapp-upgradeability>` associated with CorDapp upgrading.
Step 14. Possibly update your checked in quasar.jar
---------------------------------------------------
If your project is based on one of the official cordapp templates, it is likely you have a ``lib/quasar.jar`` checked in. It is worth noting
that you only use this if you use the JUnit runner in IntelliJ. In the latest release of the cordapp templates, this directory has
been removed.
You have some choices here:
* Upgrade your ``quasar.jar`` to ``|quasar_version|``
* Delete your ``lib`` directory and switch to using the Gradle test runner
Instructions for both options can be found in :ref:`Running tests in Intellij <tutorial_cordapp_running_tests_intellij>`.

23
docs/source/azure-vm.rst
View File

@ -101,28 +101,7 @@ The nodes you will use to send and receive Yo messages require the Yo! CorDapp j
Connect to one of your Corda nodes (make sure this is not the Notary node) using an SSH client of your choice (e.g. Putty) and log into the virtual machine using the public IP address and your SSH key or username / password combination you defined in Step 1 of the Azure build process. Type the following command:
For Corda nodes running release M10
.. sourcecode:: shell
cd /opt/corda/cordapps
wget http://downloads.corda.net/cordapps/net/corda/yo/0.10.1/yo-0.10.1.jar
For Corda nodes running release M11
.. sourcecode:: shell
cd /opt/corda/cordapps
wget http://downloads.corda.net/cordapps/net/corda/yo/0.11.0/yo-0.11.0.jar
For Corda nodes running version 2
.. sourcecode:: shell
cd /opt/corda/plugins
wget http://ci-artifactory.corda.r3cev.com/artifactory/cordapp-showcase/yo-4.jar
Build the yo cordapp sample which you can find here: https://github.com/corda/samples/tree/release-V|platform_version|/yo-cordapp and install it in the cordapp directory.
Now restart Corda and the Corda webserver using the following commands or restart your Corda VM from the Azure portal:

6
docs/source/building-a-cordapp-index.rst
View File

@ -14,10 +14,8 @@ CorDapps
debugging-a-cordapp
versioning
upgrading-cordapps
cordapp-constraint-migration
cordapp-upgradeability
secure-coding-guidelines
flow-overriding
corda-api
flow-cookbook
cheat-sheet
vault
soft-locking

30
docs/source/building-the-docs.rst
View File

@ -4,6 +4,36 @@ Building the documentation
The documentation is under the ``docs`` folder, and is written in reStructuredText format. Documentation in HTML format
is pre-generated, as well as code documentation, and this can be done automatically via a provided script.
Building Using the Docker Image
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is the method used during the build. If you run:
.. code-block:: shell
./gradlew makeDocs
This will download a docker image from docker hub and run the build locally inside that by mounting quite a bit of the docs directory at
various places inside the image.
This image is pre-built with the dependencies that were in requirements.txt at the time of the docker build.
Changing requirements
---------------------
If you want to upgrade, say, the version of sphinx that we're using, you must:
* Upgrade the version number in requirements.txt
* Build a new docker image: ``cd docs && docker build -t corda/docs-builder:latest -f docs_builder/Dockerfile .``
* post doing this the build will run using your image locally
* you can also push this to the docker registry if you have the corda keys
* you can run ``docker run -it corda/docs-builder /bin/bash`` to interactively look in the build docker image (e.g. to see what is in the
requirements.txt file)
Building from the Command Line (non-docker)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Requirements
------------

2
docs/source/changelog.rst
View File

@ -20,7 +20,7 @@ Version 4.0
* New configuration property ``database.initialiseAppSchema`` with values ``UPDATE``, ``VALIDATE`` and ``NONE``.
The property controls the behavior of the Hibernate DDL generation. ``UPDATE`` performs an update of CorDapp schemas, while
``VALIDATE`` only verifies their integrity. The property does not affect the node-specific DDL handling and
complements ``database.initialiseSchema`` to disable DDL handling altogether.
complements ``database.initialiseSchema`` to disable DDL handling altogether.
* ``JacksonSupport.createInMemoryMapper`` was incorrectly marked as deprecated and is no longer so.

22
docs/source/cli-application-shell-extensions.rst
View File

@ -34,7 +34,7 @@ For example, for the Corda node, install the shell extensions using
.. code-block:: shell
java -jar corda-<version>.jar install-shell-extensions
java -jar corda-|corda_version|.jar install-shell-extensions
And then run the node by running:
@ -62,15 +62,11 @@ Once the shell extensions have been installed, you can upgrade them in one of tw
List of existing CLI applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------------------+--------------------------------------------------------------+--------------------------------+
| Description | JAR name | Alias |
+----------------------------------------------------------------+--------------------------------------------------------------+--------------------------------+
| :ref:`Corda node<starting-an-individual-corda-node>` | ``corda-<version>.jar`` | ``corda --<option>`` |
+----------------------------------------------------------------+--------------------------------------------------------------+--------------------------------+
| :doc:`Network bootstrapper<network-bootstrapper>` | ``corda-tools-network-bootstrapper-<version>.jar`` | ``bootstrapper --<option>`` |
+----------------------------------------------------------------+--------------------------------------------------------------+--------------------------------+
| :ref:`Standalone shell<standalone-shell>` | ``corda-tools-shell-cli-<version>.jar`` | ``corda-shell --<option>`` |
+----------------------------------------------------------------+--------------------------------------------------------------+--------------------------------+
| :doc:`Blob inspector<blob-inspector>` | ``corda-tools-blob-inspector-<version>.jar`` | ``blob-inspector --<option>`` |
+----------------------------------------------------------------+--------------------------------------------------------------+--------------------------------+
========================================================= ============================== ==========================================================
Description Alias JAR Name
========================================================= ============================== ==========================================================
:ref:`Corda node<starting-an-individual-corda-node>` ``corda --<option>`` ``corda-|corda_version|.jar``
:doc:`Network bootstrapper<network-bootstrapper>` ``bootstrapper --<option>`` ``corda-tools-network-bootstrapper-|corda_version|.jar``
:ref:`Standalone shell<standalone-shell>` ``corda-shell --<option>`` ``corda-tools-shell-cli-|corda_version|.jar``
:doc:`Blob inspector<blob-inspector>` ``blob-inspector --<option>`` ``corda-tools-blob-inspector-|corda_version|.jar``
========================================================= ============================== ==========================================================

2
docs/source/cli-ux-guidelines.rst
View File

@ -74,7 +74,7 @@ Parameter stability
~~~~~~~~~~~~~~~~~~~
* Avoid removing parameters. If, for some reason, a parameter needs to be renamed, add a new parameter with the new name and deprecate the old parameter, or alternatively
keep both versions of the parameter. See :ref:`cli-ux-backwards-compatibility` for more information.
keep both versions of the parameter. See :ref:`cli-ux-backwards-compatibility` for more information.
Notes for adding a new a command line application

105
docs/source/clientrpc.rst
View File

@ -70,7 +70,7 @@ RPC users are created by adding them to the ``rpcUsers`` list in the node's ``no
username=exampleUser
password=examplePass
permissions=[]
}
},
...
]
@ -93,7 +93,7 @@ You provide an RPC user with the permission to start a specific flow using the s
"StartFlow.net.corda.flows.ExampleFlow1",
"StartFlow.net.corda.flows.ExampleFlow2"
]
}
},
...
]
@ -111,7 +111,7 @@ You can also provide an RPC user with the permission to start any flow using the
permissions=[
"InvokeRpc.startFlow"
]
}
},
...
]
@ -132,7 +132,7 @@ You provide an RPC user with the permission to perform a specific RPC operation
"InvokeRpc.nodeInfo",
"InvokeRpc.networkMapSnapshot"
]
}
},
...
]
@ -152,7 +152,7 @@ You can provide an RPC user with the permission to perform any RPC operation (in
permissions=[
"ALL"
]
}
},
...
]
@ -182,8 +182,8 @@ passwords in hash-encrypted format and enable in-memory caching of users data:
security = {
authService = {
dataSource = {
type = "DB",
passwordEncryption = "SHIRO_1_CRYPT",
type = "DB"
passwordEncryption = "SHIRO_1_CRYPT"
connection = {
jdbcUrl = "<jdbc connection string>"
username = "<db username>"
@ -210,11 +210,11 @@ of ``INMEMORY`` type:
security = {
authService = {
dataSource = {
type = "INMEMORY",
type = "INMEMORY"
users = [
{
username = "<username>",
password = "<password>",
username = "<username>"
password = "<password>"
permissions = ["<permission 1>", "<permission 2>", ...]
},
...
@ -358,82 +358,33 @@ It is possible to not be able to connect to the server on the first attempt. In
method will throw an exception. The following code snippet is an example of how to write a simple retry mechanism for
such situations:
.. sourcecode:: Kotlin
.. literalinclude:: ../../samples/bank-of-corda-demo/src/main/kotlin/net/corda/bank/api/BankOfCordaClientApi.kt
:language: kotlin
:start-after: DOCSTART rpcClientConnectionWithRetry
:end-before: DOCEND rpcClientConnectionWithRetry
fun establishConnectionWithRetry(nodeHostAndPort: NetworkHostAndPort, username: String, password: String): CordaRPCConnection {
val retryInterval = 5.seconds
do {
val connection = try {
logger.info("Connecting to: $nodeHostAndPort")
val client = CordaRPCClient(
nodeHostAndPort,
object : CordaRPCClientConfiguration {
override val connectionMaxRetryInterval = retryInterval
}
)
val _connection = client.start(username, password)
// Check connection is truly operational before returning it.
val nodeInfo = _connection.proxy.nodeInfo()
require(nodeInfo.legalIdentitiesAndCerts.isNotEmpty())
_connection
} catch(secEx: ActiveMQSecurityException) {
// Happens when incorrect credentials provided - no point to retry connecting.
throw secEx
}
catch(ex: RPCException) {
// Deliberately not logging full stack trace as it will be full of internal stacktraces.
logger.info("Exception upon establishing connection: " + ex.message)
null
}
if(connection != null) {
logger.info("Connection successfully established with: $nodeHostAndPort")
return connection
}
// Could not connect this time round - pause before giving another try.
Thread.sleep(retryInterval.toMillis())
} while (connection == null)
}
.. warning:: The list of ``NetworkHostAndPort`` passed to this function should represent one or more addresses reflecting the number of
instances of a node configured to service the client RPC request. See ``haAddressPool`` in `CordaRPCClient`_ for further information on
using an RPC Client for load balancing and failover.
After a successful connection, it is possible for the server to become unavailable. In this case, all RPC calls will throw
an exception and created observables will no longer receive observations. Below is an example of how to reconnect and
back-fill any data that might have been missed while the connection was down. This is done by using the ``onError`` handler
on the ``Observable`` returned by ``CordaRPCOps``.
.. sourcecode:: Kotlin
.. literalinclude:: ../../samples/bank-of-corda-demo/src/main/kotlin/net/corda/bank/api/BankOfCordaClientApi.kt
:language: kotlin
:start-after: DOCSTART rpcClientConnectionRecovery
:end-before: DOCEND rpcClientConnectionRecovery
fun performRpcReconnect(nodeHostAndPort: NetworkHostAndPort, username: String, password: String) {
val connection = establishConnectionWithRetry(nodeHostAndPort, username, password)
val proxy = connection.proxy
In this code snippet it is possible to see that the function ``performRpcReconnect`` creates an RPC connection and implements
the error handler upon subscription to an ``Observable``. The call to this ``onError`` handler will be triggered upon failover, at which
point the client will terminate its existing subscription, close its RPC connection and recursively call ``performRpcReconnect``,
which will re-subscribe once the RPC connection is re-established.
val (stateMachineInfos, stateMachineUpdatesRaw) = proxy.stateMachinesFeed()
val retryableStateMachineUpdatesSubscription: AtomicReference<Subscription?> = AtomicReference(null)
val subscription: Subscription = stateMachineUpdatesRaw
.startWith(stateMachineInfos.map { StateMachineUpdate.Added(it) })
.subscribe({ clientCode(it) /* Client code here */ }, {
// Terminate subscription such that nothing gets past this point to downstream Observables.
retryableStateMachineUpdatesSubscription.get()?.unsubscribe()
// It is good idea to close connection to properly mark the end of it. During re-connect we will create a new
// client and a new connection, so no going back to this one. Also the server might be down, so we are
// force closing the connection to avoid propagation of notification to the server side.
connection.forceClose()
// Perform re-connect.
performRpcReconnect(nodeHostAndPort, username, password)
})
retryableStateMachineUpdatesSubscription.set(subscription)
}
In this code snippet it is possible to see that function ``performRpcReconnect`` creates an RPC connection and implements
the error handler upon subscription to an ``Observable``. The call to this ``onError`` handler will be made when failover
happens then the code will terminate existing subscription, closes RPC connection and recursively calls ``performRpcReconnect``
which will re-subscribe once RPC connection comes back online.
Client code if fed with instances of ``StateMachineInfo`` using call ``clientCode(it)``. Upon re-connecting, this code receives
all the items. Some of these items might have already been delivered to client code prior to failover occurred.
It is down to client code in this case handle those duplicate items as appropriate.
Within the body of the ``subscribe`` function itself, the client code receives instances of ``StateMachineInfo``. Upon re-connecting, this code receives
*all* the instances of ``StateMachineInfo``, some of which may already been delivered to the client code prior to previous disconnect.
It is the responsibility of the client code to handle potential duplicated instances of ``StateMachineInfo`` as appropriate.
Wire security
-------------

30
docs/source/conf.py
View File

@ -7,10 +7,28 @@ import sys, os
#
# TEXT SUBSTITUTIONS
rst_epilog = """
.. |java_version| replace:: 8u171
.. |kotlin_version| replace:: 1.2.71
"""
with open("../../constants.properties", "r") as f:
constants_properties_lines = f.readlines()
constants_properties_dict = dict([l.strip().split('=') for l in constants_properties_lines if not l.startswith("#") and not l.strip() == ""])
def cordaSourceReadReplace(app, docname, source):
result = source[0]
for key in app.config.corda_substitutions:
result = result.replace(key, app.config.corda_substitutions[key])
source[0] = result
corda_substitutions = {
"|corda_version|" : constants_properties_dict["cordaVersion"],
"|java_version|" : "8u"+constants_properties_dict["java8MinUpdateVersion"],
"|kotlin_version|" : constants_properties_dict["kotlinVersion"],
"|gradle_plugins_version|" : constants_properties_dict["gradlePluginsVersion"],
"|quasar_version|" : constants_properties_dict["quasarVersion"],
"|platform_version|" : constants_properties_dict["platformVersion"]
}
def setup(app):
app.add_config_value('corda_substitutions', {}, True)
app.connect('source-read', cordaSourceReadReplace)
############################################################################
@ -80,9 +98,9 @@ language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
exclude_patterns = ['./design/README.md']
if tags.has('pdfmode'):
exclude_patterns = ['./design']
exclude_patterns = ['./design', './design/README.md']
# The reST default role (used for this markup: `text`) to use for all
# documents.

8
docs/source/corda-configuration-file.rst
View File

@ -88,9 +88,11 @@ cordappSignerKeyFingerprintBlacklist
*Default:* not defined
crlCheckSoftFail
This is a boolean flag that when enabled (i.e. ``true`` value is set) causes the certificate revocation list (CRL) checking will use the soft fail mode.
The soft fail mode allows the revocation check to succeed if the revocation status cannot be determined because of a network error.
If this parameter is set to ``false`` rigorous CRL checking takes place, involving each certificate in the certificate path being checked needs to have the CRL distribution point extension set and pointing to a URL serving a valid CRL.
This is a boolean flag that when enabled (i.e. ``true`` value is set) causes certificate revocation list (CRL) checking to use soft fail mode.
Soft fail mode allows the revocation check to succeed if the revocation status cannot be determined because of a network error.
If this parameter is set to ``false`` rigorous CRL checking takes place. This involves each certificate in the certificate path being checked for a CRL distribution point extension, and that this extension points to a URL serving a valid CRL.
This means that if any CRL URL in the certificate path is inaccessible, the connection with the other party will fail and be marked as bad.
Additionally, if any certificate in the hierarchy, including the self-generated node SSL certificate, is missing a valid CRL URL, then the certificate path will be marked as invalid.
*Default:* true

144
docs/source/corda-network/UAT.md
View File

@ -1,10 +1,152 @@
Corda Network: UAT Environment
=============================
For owners of tested CorDapps with a firm plan to take them into production, a bespoke UAT environment is provided by R3 (generally, a commercal agreement will need to be in place). Here, such CorDapps can be further tested in the network configuration they will experience in production, utilising relevant Corda Network Services (including the Identity Operator, and trusted notaries).
For owners of tested CorDapps with a firm plan to take them into production, a bespoke UAT environment can be provided by R3. Here, such CorDapps can be further tested in the network configuration they will experience in production, utilising relevant Corda Network Services (including the Identity Operator, and trusted notaries).
Corda UAT is not intended for customers' full test cycles, as it is expected that the bulk of CorDapp testing will occur in simpler network configurations run by the CorDapp provider, but is available for testing of functionally complete and tested CorDapps in realistic network settings to simulate the real-world business environment, including the production settings of network parameters, Corda network services and supported Corda versions.
UAT is therefore more aligned to the testing of the operational characteristics of networked CorDapps rather than their specific functional features, although we recognise there can be overlap between the two. Realistic test data is therefore expected to be used and may include data copied from production environments and hence representing real world entities and business activities. It will be up to the introducer of such data to ensure that all relevant data protection legislation is complied with and, in particular, that the terms and conditions under which Corda Network Services processes such data is suitable for their needs. All test data will be cleared down from Corda Network Services on the completion of testing.
More information about UAT will continue to be uploaded on this site or related sub-sites.
Joining the UAT environment
---------------------------
*The below joining steps assume the potential participant is joining the UAT environment directly, and as such is not “sponsoring” or onboarding other participants. If this is the case, please contact your Corda representative for how to ‘sponsor’ end-participants onto UAT.*
**Pre-requisites:**
*Technical*
* One or more physical or virtual machines upon which to deploy Corda, with compatible operating system and a compatible Java version (e.g. Oracle JDK 8u131+)
* Corda software - either Open Source or Corda Enterprise (license from R3)
* A static external IP addresses must be available for each machine on which Corda will be run.
*Business*
* Appropriate contractual terms have been agreed for access to the Services
* Access to the appropriate environment has been agreed with your project representative with sufficient advance notice (4 weeks standard but may be longer if you have special service requirements) to ensure appropriate SLAs can be in place. Your project representative will be able to supply the booking template.
**Note**:
*Corda Network UAT is an R3 owned and operated environment and service designed to support parties intending to join Corda Network proper with realistic network test facilities. In contrast, Corda Network is a production network governed by an [independent Foundation](https://corda.network/governance/index.html) and has no responsibility for Corda Network UAT. Corda Network UAT seeks to provide a test environment which is as close as possible to Corda Network in its make-up and operation.*
Steps to join UAT environment
-----------------------------
**Step 1.** Obtain Corda software - either:
* Open Source, through [github](https://github.com/corda) under an Apache 2 license.
* Corda Enterprise, available via a Corda representative.
There is further guidance available on Corda docs for getting set up on Corda.
**Step 2.** Request the Trust Root from R3's Identity Operator by mailing uatdoorman@r3.com which will be sent back as a truststore.jks file. In future, the Trust Root will be packaged in the software distribution.
**Step 3.** [Deploy the node](https://docs.corda.net/deploying-a-node.html) - where applicable, with help from a Corda representative.
**Step 4.** [Configure the node](https://docs.corda.net/corda-configuration-file.html) – a node.conf file must be included in the root directory of every Corda node.
Configuring the node includes:
4.1. **Choosing an email address.** The email address should belong to a suitably authorised employee of the node operator organisation. The email address is only retained by the Operator for the purposes of contact in relation to identity checks and any administrative issues. It is not included in the certificate.
4.2. **Choosing a Distinguished Name** A DN must be unique within Corda Network. The DN is comprised of separate fields as per the table below. Only O and OU are used for the identity uniqueness check, and the other fields are considered as attributes of the identity.
All data fields must adhere to the following constraints:
* Only uses Latin, common and inherited unicode scripts
* Upper-case first letter
* At least two letters
* No leading or trailing whitespace
* Does not include the following characters: , , = , $ , " , ' , \
* Is in NFKC normalization form
* Does not contain the null character
| | Mandatory | Length (chars) | Validation | Purpose |
| --- | --- | --- | --- | --- |
| **Organisation (O)** | Y | 128 | As per above, and additionally:No double-spacing. May not contain the words &quot;node&quot; or &quot;server&quot;. | The O field for the legal entity defines the beneficial owner of states on the ledger. This should be set to the **legal name** of the organisation, as it appears on the official trade register within the jurisdiction in which the entity is registered. This is used to define the owning organisation of the node / certificate. |
| **Organisation Unit (OU)** | N | 64 | As per above | This field is generally used to denote sub-divisions or units of the organisation (legal entity). It may be used by node operators for internal purposes to separate nodes used for different purposes by the same legal entity. |
| **Locality (L)** | Y | 64 | As per above | The city or town in which the registered head-office of the legal entity is located. If the company operates from New York City but is registered in Wilmington, Delaware then please use Wilmington |
| **Country (C)** | Y | 2 | 2-digit ISO code | The country in which the registered head-office of the legal entity is located. |
| **State (S)** | N | 64 | As per above | If your country operates a State or Province system (e.g. USA and Canada) please add the State in which the registered head-office of the legal entity is located. Do not abbreviate. For example, &quot;CA&quot; is not a valid state name. &quot;California&quot; is correct. If the company operates from New York but is registered in Delaware, please use Delaware |
| **Common Name (CN)** | N | 64 | As per above | Available for use by the node operator for their own internal purposes. Often used for home website urls in www. |
The above fields must be populated accurately with respect to the legal status of the entity being registered. As part of standard onboarding checks for Corda Network, the Identity Operator may verify that these details have been accurately populated and reject requests where the population of these fields does not appear to be correct.
**4.3. Specify URLs For Initial Registration**
The settings below must be added to the node.conf at the end of the file:
```
networkServices {
doormanURL=“https://prod-doorman2-01.corda.network/ED5D077E-F970-428B-8091-F7FCBDA06F8C”
networkMapURL=“https://prod-netmap2-01.corda.network/ED5D077E-F970-428B-8091-F7FCBDA06F8C”
}
devMode = false
tlsCertCrlDistPoint : “http://crl.corda.network/nodetls.crl”
tlsCertCrlIssuer : “CN=Corda TLS CRL Authority,OU=Corda Network,O=R3 HoldCo LLC,L=New York,C=US”
```
**Step 5.** Run the initial registration.
Once the node.conf file is configured, the following should be typed to the command line
"java -jar <corda jar file> --initial-registration". This will send a Certificate Signing Request (with the relevant
name and email) to the Identity Operator.
Once the node.conf file is configured, the following should be typed to the command line "java -jar <corda jar file> --initial-registration --network-root-truststore-password trustpass". This will send a CSR (with the relevant DN and email) to the Network Manager service (Identity Operator / Network Map).
A message similar to the below will be printed to the console:
```
Legal Name: O=ABC LIMITED, L=New York, C=US
Email: john.smith@abc.com
Public Key: EC Public Key
X: d14bc17e650f2a317cbcb95e554f1e26808ca80f67ab804bbc911ec16673abbd
Y: 1978b02a8e693ecd534ceef835091c376cfc4e506decc69b91a872fc13ad1aeb
-----BEGIN CERTIFICATE REQUEST-----
MIIBLTCBywIBADBMMQswCQYDVQQGEwJVUzERMA8GA1UEBwwITmV3IFlvcmsxFjAU
BgNVBAoMDVIzIEhvbGRDbyBMTEMxEjAQBgNVBAsMCUM4MTUyOTE2NzBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABNFLwX5lDyoxfLy5XlVPHiaAjKgPZ6uAS7yRHsFm
c6u9GXiwKo5pPs1TTO74NQkcN2z8TlBt7Mabkahy/BOtGuugHTAbBgkqhkiG9w0B
CQExDgwMYWRtaW5AcjMuY29tMBQGCCqGSM49BAMCBggqhkjOPQMBBwNHADBEAiBA
KLF4NLrleNZPKMoxBrr/80fE3kVbFnYtkB2h0JhX1gIgPcV0X0xZQug+njKCyKgf
DkNUdQJPqhkBBEpgVqyZmE8=
-----END CERTIFICATE REQUEST-----
Submitting certificate signing request to Corda certificate signing server.
Successfully submitted request to Corda certificate signing server, request ID: 6CBB63558B4B2D9C94F8C14AB713432F60AF692EB30F2E12E628B089C517F3CF.
Start polling server for certificate signing approval.
```
Important: the Request ID given in the above should be noted and kept safe for future reference.
**Step 6.** Sign the [UAT Terms of Use](https://fs22.formsite.com/r3cev/CordaUATAgreement2019/index.html) legal document
*Sponsored Model*
Business Network Operators need to ensure their participants have signed the UAT Terms of Use before they can receive a participation certificate. The Terms of Use are available as a click-through agreement which will provide direct confirmation of acceptance to the Corda Network Operator. If BNOs prefer to organise acceptance themselves, then they must forward appropriate documentary evidence for each participant (either a signed hard copy with wet signature or a scan of such hard copy). You must specify the precise Distinguished Names in order to confirm that the correct entity has signed and an accurate certificate can be issued.
*Direct Model*
Direct participants should email the Identity Operator indicating acceptance of the in-force Terms of Use (prior to availability of click-through agreements either attach the relevant document or refer to the document by date, name and version number).
**Step 7. Identity Checks.**
The Identity Operator does verification checks – upon receipt of a CSR, a number of identity-related checks will be conducted, before issuing a certificate.
**Identity checks do not constitute formal Know Your Customer (KYC) or Enhanced Due Diligence (EDD) checks. Node operators and their users are responsible for carrying out appropriate due diligence on any participant in relation to transactions performed via Corda Network.**
Upon receipt of a CSR, the Identity Operator will conduct a number of identity-related checks before issuing a certificate:
1. The DN accurately reflects a real-world legal entity, as registered with an appropriate trade register
2. The node operator (participating entity) has signed the Corda Network Terms of Use
3. The contact email address provided is valid
4. The owner of the email address and an independent and suitably qualified person in the same organisation is aware of / approves the CSR
*Email contact*
The Corda Network Operator will contact the owner of the email address provided in the CSR and it is important that the owner of this email address is aware of and prepared to respond to contact from the Corda Network Operator in relation to the CSR submission, and that they are able to do so on a timely basis.
Issuance of the certificate cannot proceed until contact has been made and so any delay will add to the elapsed time to issue the certificate and enable the node to join the network. Communications will be sent from 'Corda Network UAT Onboarding' (uatdoorman@r3.com). The email owner should ensure that this address is whitelisted by their email provider.
**Step 8.** Once identity checks have been completed, a signed node CA certificate will be released by the Operator to the node. A node in polling mode will automatically download and install the certificate in its local trust store. It will also automatically generate additional identity and TLS certificates from the node CA certificate, which are required for subsequent operation of the node.
At this point, the node will terminate and will need to be restarted. Type "java -jar " into the command line. Once restarted, the node will then proceed to download the network map and discover other nodes within Corda Network. By the end of this process, joiners will be a participant in Corda Network and Corda Network Foundation.
**Confirming your implementation**
Installation and configuration of your Corda applications must be undertaken by the node operator. Instructions to install CorDapps can be found on https://docs.corda.net. Specifics on application usage or installation should be available from your CorDapp provider.
Business Network Operators should co-ordinate any post-install tests that may involve a small number of low value transactions on the business network to assure themselves of the correct setup of their node. Node operators should co-ordinate with their Business Network Operator in this regard. All node-initiated activity on the network from the point of connection is the responsibility of the node operator.
For further questions on this process, please contact us - preferably on the mailing list: https://groups.io/g/corda-network

8
docs/source/corda-network/index.md
View File

@ -24,7 +24,7 @@ The main benefit of Corda Network for participants is being able to move cash, d
or line of business to another. Business network operators also benefit by being able to access network-wide services, and reuse the
[trust root](https://corda.network/trust-root/index.html) and network services, instead of building and managing their own.
The Corda Network website has a [high level overview](https://corda.network/participation/implementation-steps.html) of the joining process.
The Corda Network website has a [high level overview](https://corda.network/participation/index.html) of the joining process.
Key services
============
@ -69,10 +69,10 @@ The Corda Network provides an endpoint serving an empty certificate revocation l
This is intended for deployments that do not provide a CRL infrastructure but still require strict CRL mode checking.
In order to use this, add the following to your configuration file:
.. parsed-literal::
.. parsed-literal::
tlsCertCrlDistPoint = "https://crl.cordaconnect.org/cordatls.crl"
tlsCertCrlIssuer = "C=US, L=New York, O=R3 HoldCo LLC, OU=Corda, CN=Corda Root CA"
tlsCertCrlDistPoint = "https://crl.cordaconnect.org/cordatls.crl"
tlsCertCrlIssuer = "C=US, L=New York, O=R3 HoldCo LLC, OU=Corda, CN=Corda Root CA"
This set-up ensures that the TLS-level certificates are embedded with the CRL distribution point referencing the CRL issued by R3.
In cases where a proprietary CRL infrastructure is provided those values need to be changed accordingly.

64
docs/source/cordapp-build-systems.rst
View File

@ -9,7 +9,7 @@ Building and installing a CorDapp
.. contents::
Cordapps run on the Corda platform and integrate with it and each other. This article explains how to build CorDapps.
CorDapps run on the Corda platform and integrate with it and each other. This article explains how to build CorDapps.
To learn what a CorDapp is, please read :doc:`cordapp-overview`.
CorDapp format
@ -25,7 +25,7 @@ JAR will contain:
Build tools
-----------
In the instructions that follow, we assume you are using Gradle and the ``cordformation`` plugin to build your
In the instructions that follow, we assume you are using Gradle and the ``cordapp`` plugin to build your
CorDapp. You can find examples of building a CorDapp using these tools in the
`Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotlin>`_ and the
`Java CorDapp Template <https://github.com/corda/cordapp-template-java>`_.
@ -45,42 +45,38 @@ Setting your dependencies
Choosing your Corda, Quasar and Kotlin versions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Several ``ext`` variables are used in a CorDapp's ``build.gradle`` file to define which versions are used to build your CorDapp:
Several ``ext`` variables are used in a CorDapp's ``build.gradle`` file to define version numbers that should match the version of
Corda you're developing against:
* ``ext.corda_release_version`` defines the version of Corda
* ``ext.corda_release_version`` defines the version of Corda itself
* ``ext.corda_gradle_plugins_version`` defines the version of the Corda Gradle Plugins
* ``ext.quasar_version`` defines the version of Quasar
* ``ext.quasar_version`` defines the version of Quasar, a library that we use to implement the flow framework
* ``ext.kotlin_version`` defines the version of Kotlin (if using Kotlin to write your CorDapp)
``corda_gradle_plugins_versions`` are given in the form ``major.minor.patch``. You should use the same ``major`` and
``minor`` versions as the Corda version you are using, and the latest ``patch`` version. A list of all the available
versions can be found here: https://bintray.com/r3/corda/cordapp. If in doubt, you should base yourself on the version
numbers used in the ``build.gradle`` file of the
`Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotlin>`_ and the
`Java CorDapp Template <https://github.com/corda/cordapp-template-java>`_.
The current versions used are as follows:
For example, to use version 3.0 of Corda, version 3.0.8 of the Corda gradle plugins, version 0.7.9 of Quasar, and
version 1.1.60 of Kotlin, you'd write:
.. code::
.. sourcecode:: groovy
ext.corda_release_version = 'corda-3.0'
ext.corda_gradle_plugins_version = '3.0.8'
ext.quasar_version = '0.7.9'
ext.kotlin_version = '1.1.60'
ext.corda_release_version = '|corda_version|'
ext.corda_gradle_plugins_version = '|gradle_plugins_version|'
ext.quasar_version = '|quasar_version|'
ext.kotlin_version = '|kotlin_version|'
In certain cases, you may also wish to build against the unstable Master branch. See :doc:`building-against-master`.
Corda dependencies
^^^^^^^^^^^^^^^^^^
The ``cordformation`` plugin adds two new gradle configurations:
The ``cordapp`` plugin adds three new gradle configurations:
* ``cordaCompile``, which extends ``compile``
* ``cordaRuntime``, which extends ``runtime``
* ``cordapp``, which extends ``compile``
``cordaCompile`` and ``cordaRuntime`` indicate dependencies that should not be included in the CorDapp JAR. These
configurations should be used for any Corda dependency (e.g. ``corda-core``, ``corda-node``) in order to prevent a
dependency from being included twice (once in the CorDapp JAR and once in the Corda JARs).
dependency from being included twice (once in the CorDapp JAR and once in the Corda JARs). The ``cordapp`` dependency
is for declaring a compile-time dependency on a "semi-fat" CorDapp JAR in the same way as ``cordaCompile``, except
that ``Cordformation`` will only deploy CorDapps contained within the ``cordapp`` configuration.
Here are some guidelines for Corda dependencies:
@ -88,15 +84,17 @@ Here are some guidelines for Corda dependencies:
``cordaCompile`` dependency, and ``net.corda:corda:$corda_release_version`` as a ``cordaRuntime`` dependency
* When building an RPC client that communicates with a node (e.g. a webserver), you should include
``net.corda:corda-rpc:$corda_release_version`` as a ``cordaCompile`` dependency
``net.corda:corda-rpc:$corda_release_version`` as a ``cordaCompile`` dependency.
* When you need to use the network bootstrapper to bootstrap a local network (e.g. when using ``Cordformation``), you
should include ``net.corda:corda-node-api:$corda_release_version`` as a ``cordaCompile`` dependency
should include ``net.corda:corda-node-api:$corda_release_version`` as either a ``cordaRuntime`` or a ``runtimeOnly``
dependency. You may also wish to include an implementation of SLF4J as a ``runtimeOnly`` dependency for the network
bootstrapper to use.
* To use Corda's test frameworks, add ``net.corda:corda-test-utils:$corda_release_version`` as a ``testCompile``
dependency. Never include ``corda-test-utils`` as a ``compile`` or ``cordaCompile`` dependency
dependency. Never include ``corda-test-utils`` as a ``compile`` or ``cordaCompile`` dependency.
* Any other Corda dependencies you need should be included as ``cordaCompile`` dependencies
* Any other Corda dependencies you need should be included as ``cordaCompile`` dependencies.
Here is an overview of the various Corda dependencies:
@ -114,7 +112,8 @@ Here is an overview of the various Corda dependencies:
* ``corda-jfx`` - JavaFX utilities with some Corda-specific models and utilities. Only use with JavaFX apps
* ``corda-mock`` - A small library of useful mocks. Use if the classes are useful to you
* ``corda-node`` - The Corda node. Do not depend on. Used only by the Corda fat JAR and indirectly in testing
frameworks
frameworks. (If your CorDapp _must_ depend on this for some reason then it should use the ``compileOnly``
configuration here - but please don't do this if you can possibly avoid it!)
* ``corda-node-api`` - The node API. Required to bootstrap a local network
* ``corda-node-driver`` - Testing utility for programmatically starting nodes from JVM languages. Use for tests
* ``corda-rpc`` - The Corda RPC client library. Used when writing an RPC client
@ -159,7 +158,7 @@ For further information about managing dependencies, see
Signing the CorDapp JAR
^^^^^^^^^^^^^^^^^^^^^^^
The ``cordapp`` plugin can sign the generated CorDapp JAR file using `JAR signing and verification tool <https://docs.oracle.com/javase/tutorial/deployment/jar/signing.html>`_.
The ``cordapp`` plugin can sign the generated CorDapp JAR file using `JAR signing and verification tool <https://docs.oracle.com/javase/tutorial/deployment/jar/signing.html>`__.
Signing the CorDapp enables its contract classes to use signature constraints instead of other types of the constraints,
for constraints explanation refer to :doc:`api-contract-constraints`.
By default the JAR file is signed by Corda development certificate.
@ -254,7 +253,7 @@ Then the build process can set the value for *custom.sigalg* system property and
./gradlew -Dcustom.sigalg="SHA256withECDSA" -Dsigning.keystore="/path/to/keystore.jks" -Dsigning.alias="alias" -Dsigning.storepass="password" -Dsigning.keypass="password"
To check if CorDapp is signed use `JAR signing and verification tool <https://docs.oracle.com/javase/tutorial/deployment/jar/verify.html>`_:
To check if CorDapp is signed use `JAR signing and verification tool <https://docs.oracle.com/javase/tutorial/deployment/jar/verify.html>`__:
.. sourcecode:: shell
@ -319,7 +318,7 @@ Below is a sample CorDapp Gradle dependencies block. When building your own CorD
cordapp "net.corda:bank-of-corda-demo:1.0"
// Some other dependencies
compile "org.jetbrains.kotlin:kotlin-stdlib-jre8:$kotlin_version"
compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
testCompile "org.jetbrains.kotlin:kotlin-test:$kotlin_version"
testCompile "junit:junit:$junit_version"
@ -524,6 +523,13 @@ For a CorDapp that contains flows and/or services we specify the `workflow` tag:
.. note:: It is possible, but *not recommended*, to include everything in a single CorDapp jar and use both the ``contract`` and ``workflow`` Gradle plugin tags.
.. warning:: Contract states may optionally specify a custom schema mapping (by implementing the ``Queryable`` interface) in its *contracts* JAR.
However, any associated database schema definition scripts (eg. Liquibase change set XML files) must currently be packaged in the *flows* JAR.
This is because the node requires access to these schema definitions upon start-up (*contract* JARs are now loaded in a separate attachments classloader).
This split also caters for scenarios where the same *contract* CorDapp may wish to target different database providers (and thus, the associated schema DDL may vary
to use native features of a particular database). The finance CorDapp provides an illustration of this packaging convention.
Future versions of Corda will de-couple this custom schema dependency to remove this anomaly.
.. _cordapp_contract_attachments_ref:
CorDapp Contract Attachments

185
docs/source/cordapp-constraint-migration.rst Normal file
View File

@ -0,0 +1,185 @@
.. highlight:: kotlin
.. role:: kotlin(code)
:language: kotlin
.. raw:: html
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
CorDapp constraints migration
=============================
.. note:: Before reading this page, you should be familiar with the key concepts of :doc:`Contract Constraints <api-contract-constraints>`.
Corda 4 introduces and recommends building signed CorDapps that issue states with signature constraints.
Existing on ledger states issued before Corda 4 are not automatically transitioned to new signature constraints when building transactions in Corda 4.
This document explains how to modify existing CorDapp flows to explicitly consume and evolve pre Corda 4 states, and outlines a future mechanism
where such states will transition automatically (without explicit migration code).
Faced with the exercise of upgrading an existing Corda 3.x CorDapp to Corda 4, you need to consider the following:
* What existing unconsumed states have been issued on ledger by a previous version of this CorDapp and using other constraint types?
If you have existing **hash** constrained states see :ref:`Migrating hash constraints<hash_constraint_migration>`.
If you have existing **CZ whitelisted** constrained states see :ref:`Migrating CZ whitelisted constraints<cz_whitelisted_constraint_migration>`.
If you have existing **always accept** constrained states these are not consumable nor evolvable as they offer no security and should only
be used in test environments.
* What type of contract states does my CorDapp use?
**Linear states** typically evolve over an extended period of time (defined by the lifecycle of the associated business use case), and
thus are prime candidates for constraints migration.
**Fungible states** are created by an issuer and transferred around a Corda network until explicitly exited (by the same issuer).
They do not evolve as linear states, but are transferred between participants on a network. Their consumption may produce additional new
output states to represent adjustments to the original state (e.g. change when spending cash). For the purposes of constraints migration,
it is desirable that any new output states are produced using the new Corda 4 signature constraint types.
Where you have long transaction chains of fungible states, it may be advisable to send them back to the issuer for re-issuance (this is
called "chain snipping" and has performance advantages as well as simplifying constraints type migration).
* Should I use the **implicit** or **explicit** upgrade path?
The general recommendation for Corda 4 is to use **implicit** upgrades for the reasons described :ref:`here <implicit_vs_explicit_upgrades>`.
**Implicit** upgrades allow pre-authorising multiple implementations of the contract ahead of time.
They do not require additional coding and do not incur a complex choreographed operational upgrade process.
.. warning:: The steps outlined in this page assume you are using the same CorDapp Contract (eg. same state definition, commands and verification code) and
wish to use that CorDapp to leverage the upgradeability benefits of Corda 4 signature constraints. If you are looking to upgrade code within an existing
Contract CorDapp please read :ref:`Contract and state versioning<contract_upgrading_ref>` and :doc:`cordapp-upgradeability` to understand your options.
Please also remember that *states are always consumable if the version of the CorDapp that issued (created) them is installed*.
In the simplest of scenarios it may be easier to re-issue existing hash or CZ whitelist constrained states (eg. exit them from the ledger using
the original unsigned CorDapp and re-issuing them using the new signed CorDapp).
.. _hash_constraint_migration:
Hash constraints migration
--------------------------
.. note:: These instructions only apply to CorDapp Contract JARs (unless otherwise stated).
Corda 4.0
~~~~~~~~~
Corda 4.0 requires some additional steps to consume and evolve pre-existing on-ledger **hash** constrained states:
1. All Corda Nodes in the same CZ or business network that may encounter a transaction chain with a hash constrained state must be started using
relaxed hash constraint checking mode as described in :ref:`relax_hash_constraints_checking_ref`.
2. CorDapp flows that build transactions using pre-existing *hash-constrained* states must explicitly set output states to use *signature constraints*
and specify the related public key(s) used in signing the associated CorDapp Contract JAR:
.. container:: codeset
.. sourcecode:: kotlin
// This will read the signers for the deployed CorDapp.
val attachment = this.serviceHub.cordappProvider.getContractAttachmentID(contractClass)
val signers = this.serviceHub.attachments.openAttachment(attachment!!)!!.signerKeys
// Create the key that will have to pass for all future versions.
val ownersKey = signers.first()
val txBuilder = TransactionBuilder(notary)
// Set the Signature constraint on the new state to migrate away from the hash constraint.
.addOutputState(outputState, constraint = SignatureAttachmentConstraint(ownersKey))
.. sourcecode:: java
// This will read the signers for the deployed CorDapp.
SecureHash attachment = this.getServiceHub().getCordappProvider().getContractAttachmentID(contractClass);
List<PublicKey> signers = this.getServiceHub().getAttachments().openAttachment(attachment).getSignerKeys();
// Create the key that will have to pass for all future versions.
PublicKey ownersKey = signers.get(0);
TransactionBuilder txBuilder = new TransactionBuilder(notary)
// Set the Signature constraint on the new state to migrate away from the hash constraint.
.addOutputState(outputState, myContract, new SignatureAttachmentConstraint(ownersKey))
3. As a node operator you need to add the new signed version of the contracts CorDapp to the ``/cordapps`` folder together with the latest version of the flows jar.
Please also ensure that the original unsigned contracts CorDapp is removed from the ``/cordapps`` folder (this will already be present in the
nodes attachments store) to ensure the lookup code in step 2 retrieves the correct signed contract CorDapp JAR.
Later releases
~~~~~~~~~~~~~~
The next version of Corda will provide automatic transition of *hash constrained* states. This means that signed CorDapps running on a Corda 4.x node will
automatically propagate any pre-existing on-ledger *hash-constrained* states (and generate *signature-constrained* outputs) when the system property
to break constraints is set.
.. _cz_whitelisted_constraint_migration:
CZ whitelisted constraints migration
-------------------------------------
.. note:: These instructions only apply to CorDapp Contract JARs (unless otherwise stated).
Corda 4.0
~~~~~~~~~
Corda 4.0 requires some additional steps to consume and evolve pre-existing on-ledger **CZ whitelisted** constrained states:
1. As the original developer of the CorDapp, the first step is to sign the latest version of the JAR that was released (see :doc:`cordapp-build-systems`).
The key used for signing will be used to sign all subsequent releases, so it should be stored appropriately. The JAR can be signed by multiple keys owned
by different parties and it will be expressed as a ``CompositeKey`` in the ``SignatureAttachmentConstraint`` (See :doc:`api-core-types`).
2. The new Corda 4 signed CorDapp JAR must be registered with the CZ network operator (as whitelisted in the network parameters which are distributed
to all nodes in that CZ). The CZ network operator should check that the JAR is signed and not allow any more versions of it to be whitelisted in the future.
From now on the development organisation that signed the JAR is responsible for signing new versions.
The process of CZ network CorDapp whitelisting depends on how the Corda network is configured:
- if using a hosted CZ network (such as `The Corda Network <https://docs.corda.net/head/corda-network/index.html>`_ or
`UAT Environment <https://docs.corda.net/head/corda-network/UAT.html>`_ ) running an Identity Operator (formerly known as Doorman) and
Network Map Service, you should manually send the hashes of the two JARs to the CZ network operator and request these be added using
their network parameter update process.
- if using a local network created using the Network Bootstrapper tool, please follow the instructions in
:ref:`Updating the contract whitelist for bootstrapped networks <bootstrapper_updating_whitelisted_contracts>` to can add both CorDapp Contract JAR hashes.
3. Any flows that build transactions using this CorDapp will have the responsibility of transitioning states to the ``SignatureAttachmentConstraint``.
This is done explicitly in the code by setting the constraint of the output states to signers of the latest version of the whitelisted jar:
.. container:: codeset
.. sourcecode:: kotlin
// This will read the signers for the deployed CorDapp.
val attachment = this.serviceHub.cordappProvider.getContractAttachmentID(contractClass)
val signers = this.serviceHub.attachments.openAttachment(attachment!!)!!.signerKeys
// Create the key that will have to pass for all future versions.
val ownersKey = signers.first()
val txBuilder = TransactionBuilder(notary)
// Set the Signature constraint on the new state to migrate away from the WhitelistConstraint.
.addOutputState(outputState, constraint = SignatureAttachmentConstraint(ownersKey))
.. sourcecode:: java
// This will read the signers for the deployed CorDapp.
SecureHash attachment = this.getServiceHub().getCordappProvider().getContractAttachmentID(contractClass);
List<PublicKey> signers = this.getServiceHub().getAttachments().openAttachment(attachment).getSignerKeys();
// Create the key that will have to pass for all future versions.
PublicKey ownersKey = signers.get(0);
TransactionBuilder txBuilder = new TransactionBuilder(notary)
// Set the Signature constraint on the new state to migrate away from the WhitelistConstraint.
.addOutputState(outputState, myContract, new SignatureAttachmentConstraint(ownersKey))
4. As a node operator you need to add the new signed version of the contracts CorDapp to the ``/cordapps`` folder together with the latest version of the flows jar.
Please also ensure that the original unsigned contracts CorDapp is removed from the ``/cordapps`` folder (this will already be present in the
nodes attachments store) to ensure the lookup code in step 3 retrieves the correct signed contract CorDapp JAR.
Later releases
~~~~~~~~~~~~~~
The next version of Corda will provide automatic transition of *CZ whitelisted* constrained states. This means that signed CorDapps running on a Corda 4.x node will
automatically propagate any pre-existing on-ledger *CZ whitelisted* constrained states (and generate *signature* constrained outputs).

77
docs/source/cordapp-upgradeability.rst Normal file
View File

@ -0,0 +1,77 @@
CorDapp Upgradeability Guarantees
=================================
Corda 4.0
---------
Corda 4 introduces a number of advanced features (such as signature constraints), and data security model improvements (such as attachments
trust checking and classloader isolation of contract attachments for transaction building and verification).
The following guarantees are made for CorDapps running on Corda 4.0
- Compliant CorDapps compiled with previous versions of Corda (from 3.0) will execute without change on Corda 4.0
.. note:: by "compliant", we mean CorDapps that do not utilise Corda internal, non-stable or other non-committed public Corda APIs.
Recommendation: security hardening changes in flow processing, specifically the ``FinalityFlow``, recommend upgrading existing CorDapp
receiver flows to use the new APIs and thus opting in to platform version 4. See :ref:`cordapp_upgrade_finality_flow_ref` for more information.
- All constraint types (hash, CZ whitelisted, signature) are consumable within the same transaction if there is an associated contract attachment that satisfies all of them.
- CorDapp Contract states generated on ledger using hash constraints are not directly migratable to signature constraints in this release.
Your compatibility zone operator may whitelist a JAR previously used to issue hash constrained states, and then you can follow the manual
process described in the paragraph below to migrate these to signature constraints. See :doc:`cordapp-constraint-migration` for more information.
- CorDapp Contract states generated on ledger using CZ whitelisted constraints are migratable to signature constraints using a manual process
that requires programmatic code changes. See :ref:`cz_whitelisted_constraint_migration` for more information.
- Explicit Contract Upgrades are only supported for hash and CZ whitelisted constraint types. See :ref:`explicit_contract_upgrades_ref` for more information.
- CorDapp contract attachments are not trusted from remote peers over the p2p network for the purpose of transaction verification.
A node operator must locally install *all* versions of a Contract attachment to be able to resolve a chain of contract states from its original version.
The RPC ``uploadAttachment`` mechanism can be used to achieve this (as well as conventional loading of a CorDapp by installing it in the nodes /cordapp directory).
See :ref:`cordapp_install_ref` and :ref:`cordapp_contract_attachments_ref` for more information.
- CorDapp contract attachment classloader isolation has some important side-effects and edge cases to consider:
1. Contract attachments should include all 3rd party library dependencies in the same packaged JAR - we call this a "Fat JAR",
meaning that all dependencies are resolvable by the classloader by only loading a single JAR.
2. Contract attachments that depend on other Contract attachments from a different packaged JAR are currently supported in so far as the Attachments Classloader
will attempt to resolve any external dependencies from the node's application classloader. It is thus paramount that dependent Contract
Attachments are loaded upon node startup from the respective /cordapps directory.
- Rolling upgrades are partially supported.
A Node operator may choose to manually upload (via the RPC attachments uploader mechanism) a later version of a Contract Attachment than
the version their node is currently using for the purposes of transaction verification (received from remote peers). However, they will only
be able to build new transactions with the version that is currently loaded (installed from the nodes /cordapps directory) in their node.
- Finance CorDapp (v4)
Whilst experimental, our test coverage has confirmed that states generated with the Finance CorDapp are interchangeable across Open Source
and Enterprise distributions. This has been made possible by releasing a single 4.0 version of the Finance Contracts CorDapp.
Please note the Finance application will be superseded shortly by the new Tokens SDK (https://github.com/corda/token-sdk)
Later releases
--------------
The following additional capabilities are under consideration for delivery in follow-up releases to Corda 4.0:
- CorDapp Contract states generated on ledger using hash constraints will be automatically migrated to signature constraints when building new transactions
where the latest installed contract Jar is signed as per :ref:`CorDapp Jar signing <cordapp_build_system_signing_cordapp_jar_ref>`.
- CorDapp Contract states generated on ledger using CZ whitelisted constraints will be automatically migrated to signature constraints when building new transactions
where the latest installed contract Jar is signed as per :ref:`CorDapp Jar signing <cordapp_build_system_signing_cordapp_jar_ref>`.
- Explicit Contract Upgrades will be supported for all constraint types: hash, CZ whitelisted and signature.
In practice, it should only be necessary to upgrade from hash or CZ whitelisted to new signature constrained contract types.
signature constrained Contracts are upgradeable seamlessly (through built in serialization and code signing controls) without requiring explicit upgrades.
- Contract attachments will be able to explicitly declare their dependencies on other Contract attachments such that these are automatically
loaded by the Attachments Classloader (rendering the 4.0 fallback to application classloader mechanism redundant).
This improved modularity removes the need to "Fat JAR" all dependencies together in a single jar.
- Rolling upgrades will be fully supported.
A Node operator will be able to pre-register (by hash or code signing public key) versions of CorDapps they are not yet ready to install locally,
but wish to use for the purposes of transaction verification with peers running later versions of a CorDapp.
.. note:: Trusted downloading and execution of contract attachments from remote peers will not be integrated until secure JVM sand-boxing is available.

8
docs/source/deploying-a-node.rst
View File

@ -26,10 +26,10 @@ handling, and ensures the Corda service is run at boot.
``mkdir /opt/corda; chown corda:corda /opt/corda``
3. Download the `Corda jar <https://r3.bintray.com/corda/net/corda/corda/>`_
(under ``/VERSION_NUMBER/corda-VERSION_NUMBER.jar``) and place it in ``/opt/corda``
(under ``/|corda_version|/corda-|corda_version|.jar``) and place it in ``/opt/corda``
4. (Optional) Download the `Corda webserver jar <http://r3.bintray.com/corda/net/corda/corda-webserver/>`_
(under ``/VERSION_NUMBER/corda-VERSION_NUMBER.jar``) and place it in ``/opt/corda``
(under ``/|corda_version|/corda-|corda_version|.jar``) and place it in ``/opt/corda``
5. Create a directory called ``cordapps`` in ``/opt/corda`` and save your CorDapp jar file to it. Alternatively, download one of
our `sample CorDapps <https://www.corda.net/samples/>`_ to the ``cordapps`` directory
@ -187,11 +187,11 @@ at boot, and means the Corda service stays running with no users connected to th
* A supported Java distribution. The supported versions are listed in :doc:`getting-set-up`
1. Create a Corda directory and download the Corda jar. Replace ``VERSION_NUMBER`` with the desired version. Here's an
1. Create a Corda directory and download the Corda jar. Here's an
example using PowerShell::
mkdir C:\Corda
wget http://jcenter.bintray.com/net/corda/corda/VERSION_NUMBER/corda-VERSION_NUMBER.jar -OutFile C:\Corda\corda.jar
wget http://jcenter.bintray.com/net/corda/corda/|corda_version|/corda-|corda_version|.jar -OutFile C:\Corda\corda.jar
2. Create a directory called ``cordapps`` in ``C:\Corda\`` and save your CorDapp jar file to it. Alternatively,
download one of our `sample CorDapps <https://www.corda.net/samples/>`_ to the ``cordapps`` directory

4
docs/source/design/data-model-upgrades/migrate-to-signature-constraint.md
View File

@ -69,7 +69,7 @@ A normal node would just download the signed jar using the normal process for th
### Caveats
###### Someone really wants to issue states with the HashConstraint, and ensure that can never change.
#### Someone really wants to issue states with the HashConstraint, and ensure that can never change.
- As mentioned above the transaction builder could only automatically transition states created pre-v4.
@ -80,7 +80,7 @@ A normal node would just download the signed jar using the normal process for th
The option in this case is to force such parties to actually create a new contract (maybe subclass the version they want), own it, and hardcode the check as above.
###### Some nodes haven't upgraded all their states by the time a new release is already being used on the network.
#### Some nodes haven't upgraded all their states by the time a new release is already being used on the network.
- A transaction mixing an original HashConstraint state, and a v2 Signature constraint state will not pass. The only way out is to strongly "encourage" nodes to upgrade before the new release.

25
docs/source/design/design-docs-index.rst Normal file
View File

@ -0,0 +1,25 @@
Design Docs
===========
.. conditional-toctree::
:maxdepth: 1
:if_tag: htmlmode
design-review-process.md
certificate-hierarchies/design.md
failure-detection-master-election/design.md
float/design.md
hadr/design.md
kafka-notary/design.md
monitoring-management/design.md
sgx-integration/design.md
reference-states/design.md
sgx-infrastructure/design.md
threat-model/corda-threat-model.md
data-model-upgrades/signature-constraints.md
data-model-upgrades/package-namespace-ownership.md
targetversion/design.md
data-model-upgrades/migrate-to-signature-constraint.md
versioning/contract-versioning.md
linear-pointer/design.md
maximus/design.md

4
docs/source/design/linear-pointer/design.md
View File

@ -73,7 +73,7 @@ class LinearPointer(override val pointer: UniqueIdentifier) : StatePointer {
}
```
#### Bi-directional link
### Bi-directional link
Symmetrical relationships can be modelled by embedding a `LinearPointer` in the pointed-to `LinearState` which points in the "opposite" direction. **Note:** this can only work if both states are `LinearState`s.
@ -81,7 +81,7 @@ Symmetrical relationships can be modelled by embedding a `LinearPointer` in the
It is important to note that this design only standardises a pattern which is currently possible with the platform. In other words, this design does not enable anything new.
#### Tokens
### Tokens
Uncoupling token type definitions from the notion of ownership. Using the `LinearPointer`, `Token` states can include an `Amount` of some pointed-to type. The pointed-to type can evolve independently from the `Token` state which should just be concerned with the question of ownership.

25
docs/source/design/monitoring-management/design.md
View File

@ -113,7 +113,7 @@ Expanding on the first goal identified above, the following requirements have be
Audit data should include sufficient contextual information to enable optimal off-line analysis.
Auditing should apply to all Corda node processes (running CorDapps, notaries, oracles).
#### Use Cases
### Use Cases
It is envisaged that operational management and support teams will use the metrics and information collated from this
design, either directly or through an integrated enterprise-wide systems management platform, to perform the following:
@ -177,7 +177,7 @@ There are a number of activities and parts to the solution proposal:
queue), and exposes key metrics using JMX (using role-based authentication using Artemis's JAAS plug-in support to
ensure Artemis cannot be controlled via JMX)..
##### Restrictions
### Restrictions
As of Corda M11, Java serialisation in the Corda node has been restricted, meaning MBeans access via the JMX port will no longer work.
@ -200,7 +200,7 @@ include:
| [Collectd](https://collectd.org/) | OS | Collector agent (written in C circa 2005). Data acquisition and storage handled by over 90 plugins. |
| [Telegraf](https://github.com/influxdata/telegraf) | OS | Collector agent (written in Go, active community) |
| [Graphite](https://graphiteapp.org/) | OS | Monitoring tool that stores, retrieves, shares, and visualizes time-series data. |
| [StatsD](https://github.com/etsy/statsd) | OS | Collector daemon that runs on the [Node.js](http://nodejs.org/) platform and listens for statistics, like counters and timers, sent over [UDP](http://en.wikipedia.org/wiki/User_Datagram_Protocol) or [TCP](http://en.wikipedia.org/wiki/Transmission_Control_Protocol) and sends aggregates to one or more pluggable backend services (e.g., [Graphite](http://graphite.readthedocs.org/)). |
| [StatsD](https://github.com/etsy/statsd) | OS | Collector daemon that runs on the [Node.js](http://nodejs.org/) platform and listens for statistics, like counters and timers, sent over [UDP](http://en.wikipedia.org/wiki/User_Datagram_Protocol) or [TCP](http://en.wikipedia.org/wiki/Transmission_Control_Protocol) and sends aggregates to one or more pluggable backend services (e.g., Graphite). |
| [fluentd](https://www.fluentd.org/) | OS | Collector daemon which collects data directly from logs and databases. Often used to analyze event logs, application logs, and clickstreams (a series of mouse clicks). |
| [Prometheus](https://prometheus.io/) | OS | End to end monitoring solution using time-series data (eg. metric name and a set of key-value pairs) and includes collection, storage, query and visualization. |
| [NewRelic](https://newrelic.com/) | £ | Full stack instrumentation for application monitoring and real-time analytics solution. |
@ -446,7 +446,6 @@ Primary node services exposed publicly via ServiceHub (SH) or internally by Serv
| CordaPersistence | SHI | CordaPersistence | INFO coverage within `HibernateConfiguration` |
| CordappProviderInternal | SHI | CordappProviderImpl | none |
| VaultServiceInternal | SHI | NodeVaultService | see SH |
| | | | |
Corda subsystem components:
@ -458,7 +457,6 @@ Corda subsystem components:
| NotaryService | RaftNonValidatingNotaryService | as above |
| NotaryService | BFTNonValidatingNotaryService | Logging coverage (info, debug) |
| Doorman | DoormanServer (Enterprise only) | Some logging (info, warn, error), and use of `println` |
| | | |
Corda core flows:
@ -467,19 +465,18 @@ Corda core flows:
| FinalityFlow | none | NotaryException | NOTARISING, BROADCASTING |
| NotaryFlow | none | NotaryException (NotaryError types: TimeWindowInvalid, TransactionInvalid, WrongNotary), IllegalStateException, some via `check` assertions | REQUESTING, VALIDATING |
| NotaryChangeFlow | none | StateReplacementException | SIGNING, NOTARY |
| SendTransactionFlow | none | FetchDataFlow.HashNotFound (FlowException) | |
| ReceiveTransactionFlow | none | SignatureException, AttachmentResolutionException, TransactionResolutionException, TransactionVerificationException | |
| ResolveTransactionsFlow | none | FetchDataFlow.HashNotFound (FlowException), ExcessivelyLargeTransactionGraph (FlowException) | |
| FetchAttachmentsFlow | none | FetchDataFlow.HashNotFound | |
| FetchTransactionsFlow | none | FetchDataFlow.HashNotFound | |
| FetchDataFlow | some logging (info) | FetchDataFlow.HashNotFound | |
| SendTransactionFlow | none | FetchDataFlow.HashNotFound (FlowException) | none |
| ReceiveTransactionFlow | none | SignatureException, AttachmentResolutionException, TransactionResolutionException, TransactionVerificationException | none |
| ResolveTransactionsFlow | none | FetchDataFlow.HashNotFound (FlowException), ExcessivelyLargeTransactionGraph (FlowException) | none |
| FetchAttachmentsFlow | none | FetchDataFlow.HashNotFound | none |
| FetchTransactionsFlow | none | FetchDataFlow.HashNotFound | none |
| FetchDataFlow | some logging (info) | FetchDataFlow.HashNotFound | none |
| AbstractStateReplacementFlow.Instigator | none | StateReplacementException | SIGNING, NOTARY |
| AbstractStateReplacementFlow.Acceptor | none | StateReplacementException | VERIFYING, APPROVING |
| CollectSignaturesFlow | none | IllegalArgumentException via `require` assertions | COLLECTING, VERIFYING |
| CollectSignatureFlow | none | as above | |
| CollectSignatureFlow | none | as above | none |
| SignTransactionFlow | none | FlowException, possibly other (general) Exception | RECEIVING, VERIFYING, SIGNING |
| ContractUpgradeFlow | none | FlowException | |
| | | | |
| ContractUpgradeFlow | none | FlowException | none |
Corda finance flows:

6
docs/source/design/sgx-infrastructure/details/attestation.md
View File

@ -1,9 +1,9 @@
### Terminology recap
**measurement**: The hash of an enclave image, uniquely pinning the code and related configuration
**report**: A datastructure produced by an enclave including the measurement and other non-static properties of the
* **measurement**: The hash of an enclave image, uniquely pinning the code and related configuration
* **report**: A datastructure produced by an enclave including the measurement and other non-static properties of the
running enclave instance (like the security version number of the hardware)
**quote**: A signed report of an enclave produced by Intel's quoting enclave.
* **quote**: A signed report of an enclave produced by Intel's quoting enclave.
# Attestation

30
docs/source/design/versioning/contract-versioning.md
View File

@ -39,7 +39,7 @@ Corda is designed such that the flow that builds the transaction (on its executi
But because input states are actually output states that are serialised with the previous transaction (built using a potentially different version of the contract), this means that states serialised with a version of the ContractJAR will need to be deserialisable with a different version.
.. image:: resources/tx-chain.png
.. image:: ../../resources/tx-chain.png
:scale: 25%
:align: center
@ -77,7 +77,7 @@ This design is not about:
### Assumptions and trade-offs made for the current version
##### We assume that ContractStates will never change their semantics in a way that would impact other Contracts or Flows that depend on them.
#### We assume that ContractStates will never change their semantics in a way that would impact other Contracts or Flows that depend on them.
E.g.: If various contracts depend on Cash, the assumption is that no new field will be added to Cash that would have an influence over the amount or the owner (the fundamental fields of Cash).
It is always safe to mix new CashStates with older states that depend on it.
@ -89,7 +89,7 @@ This is not a very strong definition, so we will have to create more formalised
If any contract breaks this assumption, in Corda 4 there will be no platform support the transition to the new version. The burden of coordinating with all the other cordapp developers and nodes is on the original developer.
##### Flow to Flow communication could be lossy for objects that are not ContractStates or Commands.
#### Flow to Flow communication could be lossy for objects that are not ContractStates or Commands.
Explanation:
Flows communicate by passing around various objects, and eventually the entire TransactionBuilder.
@ -99,7 +99,7 @@ The decision was that the node that sends data would decide (if his version is h
The objects that live on the ledger like ContractStates and Commands that the other party actually has to sign, will not be allowed to lose any data.
##### We assume that cordapp developers will correctly understand all implications and handle backwards compatibility themselves.
#### We assume that cordapp developers will correctly understand all implications and handle backwards compatibility themselves.
Basically they will have to realise that any version of a flow can talk to any other version, and code accordingly.
This get particularly tricky when there are reusable inline subflows involved.
@ -144,9 +144,9 @@ The Cordapp gradle plugin should be amended to differentiate between a "flows" m
In the build.gradle file of the contracts module, there should be a `version` property that needs be incremented for each release.
This `version' will be used for the regular release, and be part of the jar name.
This `version` will be used for the regular release, and be part of the jar name.
Also, when packaging the contract for release, the `version` should be added by the plugin to the manifest file, together with other properties like `target-platform-version.
Also, when packaging the contract for release, the `version` should be added by the plugin to the manifest file, together with other properties like `target-platform-version`.
When loading the contractJar in the attachment storage, the version should be saved as a column, so it is easily accessible.
@ -285,7 +285,7 @@ Terminology:
- Tx1, Tx2 - are transactions between parties.
#### Scenario 1 - Spending a state with an older contract.
### Scenario 1 - Spending a state with an older contract.
- V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party)
- V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount? = 0)
@ -299,7 +299,7 @@ Terminology:
Solution: This was analysed above. It will be solved by the non-downgrade rule and the serialization engine changes.
#### Scenario 2: - Running an explicit upgrade written against an older contract version.
### Scenario 2: - Running an explicit upgrade written against an older contract version.
- V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party)
- V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount? = 0)
- Another company creates a better com.gigacorp.token.GigaToken that is an UpgradedContract designed to replace the MegaToken via an explicit upgrade, but develop against V1 ( as V2 was not released at the time of development).
@ -313,7 +313,7 @@ Same as before:
Solution: This attack breaks the assumption we made that contracts will not be adding fields that change it fundamentally.
#### Scenario 3 - Flows installed by 2 peers compiled against different contract versions.
### Scenario 3 - Flows installed by 2 peers compiled against different contract versions.
- Alice runs V1 of the MegaToken FlowsJAR, while Bob runs V2.
- Bob builds a new transaction where he transfers a state with accumulatedDebt To Alice.
- Alice is not able to correctly evaluate the business proposition, as she does not know that there even exists an accumulatedDebt field, but still signs it as if it was debt free.
@ -321,7 +321,7 @@ Solution: This attack breaks the assumption we made that contracts will not be a
Solution: Solved by the assumption that peer-to-peer communication can be lossy, and the peer with the higher version is responsible to send the right data
#### Scenario 4 - Developer attempts to rename a field from one version to the next.
### Scenario 4 - Developer attempts to rename a field from one version to the next.
- V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount )
- V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, currentDebt: Amount)
@ -331,7 +331,7 @@ This would break as soon as you try to spend a V1 state with V2, because there i
Solution: Not possible for now, as it breaks the serialisation evolution rules. Could be added as a new feature in the future.
#### Scenario 5 - Contract verification logic becomes more strict in a new version. General concerns.
### Scenario 5 - Contract verification logic becomes more strict in a new version. General concerns.
- V1: check that amount > 10
- V2: check that amount > 12
@ -349,7 +349,7 @@ The question is how important it is, that amount is >12?
Solution: This is not addressed in the current design doc. It needs to be explored in more depth.
#### Scenario 6 - Contract verification logic becomes more strict in a new version. ???
### Scenario 6 - Contract verification logic becomes more strict in a new version. ???
- V1: check that amount > 10
- V2: check that amount > 12
@ -362,7 +362,7 @@ Solution: This is not addressed in the current design doc. It needs to be explor
Solution: Same as Scenario 5.
#### Scenario 7 - Contract verification logic becomes less strict.
### Scenario 7 - Contract verification logic becomes less strict.
- V1: check that amount > 12
- V2: check that amount > 10
@ -373,7 +373,7 @@ Because there was no change in the actual structure of the state it means the fl
Solution: This should not require any change.
#### Scenario 8 - Contract depends on another Contract.
### Scenario 8 - Contract depends on another Contract.
- V1: com.megacorp.token.MegaToken(amount: Amount, owner: Party)
- V2: com.megacorp.token.MegaToken(amount: Amount, owner: Party, accumulatedDebt: Amount? = 0)
@ -387,7 +387,7 @@ Alice swaps MegaToken-v2 for SuperToken-v1 with Bob in a transaction. If Alice s
Solution: Solved by the assumption we made that contracts don't change fundamentally.
#### Scenario 9 - A new command is added or removed
### Scenario 9 - A new command is added or removed
- V1 of com.megacorp.token.MegaToken has 3 Commands: Issue, Move, Exit
- V2 of com.megacorp.token.MegaToken has 4 Commands: Issue, Move, Exit, AddDebt
- V3 of com.megacorp.token.MegaToken has 3 Commands: Issue, Move, Exit

5
docs/source/flow-overriding.rst
View File

@ -75,6 +75,7 @@ with refactoring into `Base` and `Sub` classes. A simple example is shown below.
}
}
@InitiatedBy(Initiator.class)
public class SubResponder extends BaseResponder {
public SubResponder(FlowSession counterpartySession) {
super(counterpartySession);
@ -91,7 +92,7 @@ Corda would detect that both ``BaseResponder`` and ``SubResponder`` are configur
Corda will then calculate the hops to ``FlowLogic`` and select the implementation which is furthest distance, ie: the most subclassed implementation.
In the above example, ``SubResponder`` would be selected as the default responder for ``Initiator``
.. note:: The flows do not need to be within the same CordApp, or package, therefore to customise a shared app you obtained from a third party, you'd write your own CorDapp that subclasses the first."
.. note:: The flows do not need to be within the same CordApp, or package, therefore to customise a shared app you obtained from a third party, you'd write your own CorDapp that subclasses the first.
Overriding a flow via node configuration
----------------------------------------
@ -100,6 +101,8 @@ Whilst the subclassing approach is likely to be useful for most applications, th
This would be useful if for example, a specific CordApp user requires such a different responder that subclassing an existing flow
would not be a good solution. In this case, it's possible to specify a hardcoded flow via the node configuration.
.. note:: A new responder written to override an existing responder must still be annotated with ``@InitiatedBy`` referencing the base initiator.
The configuration section is named ``flowOverrides`` and it accepts an array of ``overrides``
.. container:: codeset

8
docs/source/generating-a-node.rst
View File

@ -9,7 +9,7 @@ A node can be created manually by creating a folder that contains the following
* The Corda JAR
* Can be downloaded from https://r3.bintray.com/corda/net/corda/corda/ (under /VERSION_NUMBER/corda-VERSION_NUMBER.jar)
* Can be downloaded from https://r3.bintray.com/corda/net/corda/corda/ (under /|corda_version|/corda-|corda_version|.jar)
* A node configuration file entitled ``node.conf``, configured as per :doc:`corda-configuration-file`
@ -17,7 +17,7 @@ A node can be created manually by creating a folder that contains the following
* **Optional:** A webserver JAR entitled ``corda-webserver.jar`` that will connect to the node via RPC
* The (deprecated) default webserver can be downloaded from http://r3.bintray.com/corda/net/corda/corda-webserver/ (under /VERSION_NUMBER/corda-VERSION_NUMBER.jar)
* The (deprecated) default webserver can be downloaded from http://r3.bintray.com/corda/net/corda/corda-webserver/ (under /|corda_version|/corda-webserver-|corda_version|.jar)
* A Spring Boot alternative can be found here: https://github.com/corda/spring-webserver
The remaining files and folders described in :doc:`node-structure` will be generated at runtime.
@ -26,7 +26,7 @@ The Cordform task
-----------------
Corda provides a gradle plugin called ``Cordform`` that allows you to automatically generate and configure a set of
nodes for testing and demos. Here is an example ``Cordform`` task called ``deployNodes`` that creates three nodes, defined
in the `Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotlin/blob/release-V3/build.gradle#L100>`_:
in the `Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotlin/blob/release-V|platform_version|/build.gradle#L95>`_:
.. sourcecode:: groovy
@ -251,7 +251,7 @@ following line to each node's ``node.conf`` file:
Where ``2222`` is the port you want to open to SSH into the shell.
Below you can find the example task from the `IRS Demo <https://github.com/corda/corda/blob/release-V3.0/samples/irs-demo/cordapp/build.gradle#L111>`_ included in the samples directory of main Corda GitHub repository:
Below you can find the example task from the `IRS Demo <https://github.com/corda/corda/blob/release/|platform_version|/samples/irs-demo/cordapp/build.gradle#L111>`_ included in the samples directory of main Corda GitHub repository:
.. sourcecode:: groovy

8
docs/source/hello-world-template.rst
View File

@ -46,18 +46,18 @@ For this tutorial, we will only be modifying the following files:
.. code-block:: java
// 1. The state
cordapp-contracts-states/src/main/java/com/template/TemplateState.java
contracts/src/main/java/com/template/states/TemplateState.java
// 2. The flow
cordapp/src/main/java/com/template/Initiator.java
workflows/src/main/java/com/template/flows/Initiator.java
.. code-block:: kotlin
// 1. The state
cordapp-contracts-states/src/main/kotlin/com/template/StatesAndContracts.kt
contracts/src/main/kotlin/com/template/states/TemplateState.kt
// 2. The flow
cordapp/src/main/kotlin/com/template/Flows.kt
workflows/src/main/kotlin/com/template/flows/Flows.kt
Progress so far
---------------

22
docs/source/index.rst
View File

@ -34,6 +34,8 @@ We look forward to seeing what you can do with Corda!
release-notes
app-upgrade-notes
node-upgrade-notes
corda-api
cheat-sheet
.. toctree::
:caption: Development
@ -88,24 +90,6 @@ We look forward to seeing what you can do with Corda!
contributing-index.rst
deterministic-modules.rst
design/design-docs-index.rst
changelog
.. conditional-toctree::
:caption: Design docs
:maxdepth: 2
:if_tag: htmlmode
design/design-review-process.md
design/certificate-hierarchies/design.md
design/failure-detection-master-election/design.md
design/float/design.md
design/hadr/design.md
design/kafka-notary/design.md
design/monitoring-management/design.md
design/sgx-integration/design.md
design/reference-states/design.md
design/sgx-infrastructure/design.md
design/threat-model/corda-threat-model.md
design/data-model-upgrades/signature-constraints.md
design/data-model-upgrades/package-namespace-ownership.md
design/targetversion/design.md

10
docs/source/key-concepts-djvm.rst
View File

@ -93,7 +93,9 @@ type's members. This is what controls things like ensuring that all methods impl
and normalisation of synchronised methods.
Lastly, there is a set of emitters. These are used to instrument the byte code for cost accounting purposes, and also
to inject code for checks that we want to perform at runtime or modifications to out-of-the-box behaviour.
to inject code for checks that we want to perform at runtime or modifications to out-of-the-box behaviour. Many of
these emitters will rewrite non-deterministic operations to throw ``RuleViolationError`` exceptions instead, which
means that the ultimate proof that a function is *truly* deterministic is that it executes successfully inside the DJVM.
Static Byte Code Analysis
@ -298,7 +300,7 @@ Open your terminal and navigate to the ``djvm`` directory in the Corda source tr
::
$ ./shell/install
$ djvm/shell/install
This will build the DJVM tool and install a shortcut on Bash-enabled systems. It will also generate a Bash completion
@ -342,7 +344,9 @@ The output should be pretty self-explanatory, but just to summarise:
Other commands to be aware of are:
* ``djvm check`` which allows you to perform the up-front static analysis without running the code.
* ``djvm check`` which allows you to perform some up-front static analysis without running the code. However, be aware
that the DJVM also transforms some non-deterministic operations into ``RuleViolationError`` exceptions. A successful
``check`` therefore does *not* guarantee that the code will behave correctly at runtime.
* ``djvm inspect`` which allows you to inspect what byte code modifications will be applied to a class.

5
docs/source/vault.rst → docs/source/key-concepts-vault.rst
View File

@ -1,6 +1,11 @@
Vault
=====
.. toctree::
:maxdepth: 1
soft-locking.rst
The vault contains data extracted from the ledger that is considered relevant to the node’s owner, stored in a relational model
that can be easily queried and worked with.

1
docs/source/key-concepts.rst
View File

@ -19,6 +19,7 @@ This section should be read in order:
key-concepts-flows
key-concepts-consensus
key-concepts-notaries
key-concepts-vault
key-concepts-time-windows
key-concepts-oracles
key-concepts-node

37
docs/source/network-bootstrapper.rst
View File

@ -24,12 +24,14 @@ You can find out more about network maps and network parameters from :doc:`netwo
Bootstrapping a test network
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Corda Network Bootstrapper can be downloaded from `here <https://www.corda.net/resources>`_.
The Corda Network Bootstrapper can be downloaded from `here <https://www.corda.net/resources>`__.
Create a directory containing a node config file, ending in "_node.conf", for each node you want to create. Then run the
Create a directory containing a node config file, ending in "_node.conf", for each node you want to create. "devMode" must be set to true. Then run the
following command:
``java -jar network-bootstrapper-VERSION.jar --dir <nodes-root-dir>``
.. sourcecode:: bash
java -jar corda-tools-network-bootstrapper-|corda_version|.jar --dir <nodes-root-dir>
For example running the command on a directory containing these files:
@ -76,6 +78,8 @@ alongside the config files. For example, if your directory has this structure:
The ``cordapp-a.jar`` and ``cordapp-b.jar`` will be installed in each node directory, and any contracts within them will be
added to the Contract Whitelist (see below).
.. _bootstrapper_whitelisting_contracts:
Whitelisting contracts
----------------------
@ -91,7 +95,8 @@ By default the Bootstrapper will whitelist all the contracts found in the unsign
Whitelisted contracts are checked by `Zone constraints`, while contract classes from signed JARs will be checked by `Signature constraints`.
To prevent certain contracts from unsigned JARs from being whitelisted, add their fully qualified class name in the ``exclude_whitelist.txt``.
These will instead use the more restrictive ``HashAttachmentConstraint``.
Refer to :doc:`api-contract-constraints` to understand the implication of different constraint types before adding ``exclude_whitelist.txt`` files.
To add certain contracts from signed JARs to whitelist, add their fully qualified class name in the ``include_whitelist.txt``.
Refer to :doc:`api-contract-constraints` to understand the implication of different constraint types before adding ``exclude_whitelist.txt`` or ``include_whitelist.txt`` files.
For example:
@ -150,7 +155,9 @@ can use the Network Bootstrapper on the following network structure:
Then run the Network Bootstrapper again from the root dir:
``java -jar network-bootstrapper-VERSION.jar --dir <nodes-root-dir>``
.. sourcecode:: bash
java -jar corda-tools-network-bootstrapper-|corda_version|.jar --dir <nodes-root-dir>
Which will give the following:
@ -190,6 +197,8 @@ such a generated keys, will be unaffected.
the same machine. If a network needs to be updated using the Bootstrapper once deployed, the nodes will need
collecting back together.
.. _bootstrapper_updating_whitelisted_contracts:
Updating the contract whitelist for bootstrapped networks
---------------------------------------------------------
@ -219,7 +228,9 @@ For example, with the following pre-generated network:
Then run the Network Bootstrapper again from the root dir:
``java -jar network-bootstrapper-VERSION.jar --dir <nodes-root-dir>``
.. sourcecode:: bash
java -jar corda-tools-network-bootstrapper-|corda_version|.jar --dir <nodes-root-dir>
To give the following:
@ -266,18 +277,22 @@ Overriding network parameters via a file
You can provide a network parameters overrides file using the following syntax:
``java -jar network-bootstrapper-VERSION.jar --network-parameter-overrides=<path_to_file>``
.. sourcecode:: bash
java -jar corda-tools-network-bootstrapper-|corda_version|.jar --network-parameter-overrides=<path_to_file>
Or alternatively, by using the short form version:
``java -jar network-bootstrapper-VERSION.jar -n=<path_to_file>``
.. sourcecode:: bash
java -jar corda-tools-network-bootstrapper-|corda_version|.jar -n=<path_to_file>
The network parameter overrides file is a HOCON file with the following fields, all of which are optional. Any field that is not provided will be
ignored. If a field is not provided and you are bootstrapping a new network, a sensible default value will be used. If a field is not provided and you
are updating an existing network, the value in the existing network parameters file will be used.
.. note:: All fields can be used with placeholders for environment variables. For example: ``${KEY_STORE_PASSWORD}`` would be replaced by the contents of environment
variable ``KEY_STORE_PASSWORD``. See: :ref:`corda-configuration-hiding-sensitive-data` .
variable ``KEY_STORE_PASSWORD``. See: :ref:`corda-configuration-hiding-sensitive-data` .
The available configuration fields are listed below:
@ -288,7 +303,7 @@ The available configuration fields are listed below:
:maxTransactionSize: The maximum permitted transaction size, in bytes.
:eventHorizon: The time after which nodes will be removed from the network map if they have not been seen during this period. This parameter uses
the ``parse`` function on the ``java.time.Duration`` class to interpret the data. See `here <https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence->`_
the ``parse`` function on the ``java.time.Duration`` class to interpret the data. See `here <https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence->`__
for information on valid inputs.
:packageOwnership: A list of package owners. See `Package namespace ownership`_ for more information. For each package owner, the following fields
@ -350,7 +365,7 @@ For each package to be registered, the following are required:
:keystoreAlias: The alias for the name associated with the certificate to be associated with the package namespace.
Using the `Example CorDapp <https://github.com/corda/cordapp-example>`_ as an example, we will initialise a simple network and then register and unregister a package namespace.
Checkout the Example CorDapp and follow the instructions to build it `here <https://docs.corda.net/tutorial-cordapp.html#building-the-example-cordapp>`_.
Checkout the Example CorDapp and follow the instructions to build it `here <https://docs.corda.net/tutorial-cordapp.html#building-the-example-cordapp>`__.
.. note:: You can point to any existing bootstrapped corda network (this will have the effect of updating the associated network parameters file).

19
docs/source/network-map.rst
View File

@ -48,6 +48,25 @@ The set of REST end-points for the network map service are as follows.
| GET | /network-map/my-hostname | Retrieve the IP address of the caller (and **not** of the network map). |
+----------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
Network maps hosted by R3 or other parties using R3's commercial network management tools typically also provide the following endpoints as a convenience to operators and other users
.. note:: we include them here as they can aid debugging but, for the avoidance of doubt, they are not a formal part of the spec and the node will operate even in their absence.
+----------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
| Request method | Path | Description |
+================+=========================================+==============================================================================================================================================+
| GET | /network-map/json | Retrieve the current public network map formatted as a JSON document. |
+----------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
| GET | /network-map/json/{uuid} | Retrieve the current network map for a private network indicated by the uuid parameter formatted as a JSON document. |
+----------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
| GET | /network-map/json/node-infos | Retrieve a human readable list of the currently registered ``NodeInfo`` files in the public network formatted as a JSON document. |
+----------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
| GET | /network-map/json/node-infos/{uid} | Retrieve a human readable list of the currently registered ``NodeInfo`` files in the specified private network map. |
+----------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
| GET | /network-map/json/node-info/{hash} | Retrieve a human readable version of a ``NodeInfo`` formatted as a JSON document. |
+----------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
HTTP is used for the network map service instead of Corda's own AMQP based peer to peer messaging protocol to
enable the server to be placed behind caching content delivery networks like Cloudflare, Akamai, Amazon Cloudfront and so on.
By using industrial HTTP cache networks the map server can be shielded from DoS attacks more effectively. Additionally,

17
docs/source/node-administration.rst
View File

@ -10,7 +10,10 @@ Logging
By default the node log files are stored to the ``logs`` subdirectory of the working directory and are rotated from time
to time. You can have logging printed to the console as well by passing the ``--log-to-console`` command line flag.
The default logging level is ``INFO`` which can be adjusted by the ``--logging-level`` command line argument. This configuration
option will affect all modules.
option will affect all modules. Hibernate (the JPA provider used by Corda) specific log messages of level ``WARN`` and above
will be logged to the diagnostic log file, which is stored in the same location as other log files (``logs`` subdirectory
by default). This is because Hibernate may log messages at WARN and ERROR that are handled internally by Corda and do not
need operator attention. If they do, they will be logged by Corda itself in the main node log file.
It may be the case that you require to amend the log level of a particular subset of modules (e.g., if you'd like to take a
closer look at hibernate activity). So, for more bespoke logging configuration, the logger settings can be completely overridden
@ -84,7 +87,7 @@ formats for accessing MBeans, and provides client libraries to work with that pr
Here are a few ways to build dashboards and extract monitoring data for a node:
* `hawtio <http://hawt.io>`_ is a web based console that connects directly to JVM's that have been instrumented with a
* `Hawtio <http://hawt.io>`_ is a web based console that connects directly to JVM's that have been instrumented with a
jolokia agent. This tool provides a nice JMX dashboard very similar to the traditional JVisualVM / JConsole MBbeans original.
* `JMX2Graphite <https://github.com/logzio/jmx2graphite>`_ is a tool that can be pointed to /monitoring/json and will
scrape the statistics found there, then insert them into the Graphite monitoring tool on a regular basis. It runs
@ -132,7 +135,7 @@ When starting Corda nodes using the 'driver DSL', you should see a startup messa
**Starting out-of-process Node USA Bank Corp, debug port is not enabled, jolokia monitoring port is 7005 {}**
The following diagram illustrates Corda flow metrics visualized using `hawtio <https://hawt.io>`_ :
The following diagram illustrates Corda flow metrics visualized using hawtio:
.. image:: resources/hawtio-jmx.png
@ -175,9 +178,8 @@ Take a simple node config that wishes to protect the node cryptographic stores:
By delegating to a password store, and using `command substitution` it is possible to ensure that sensitive passwords never appear in plain text.
The below examples are of loading Corda with the KEY_PASS and TRUST_PASS variables read from a program named ``corporatePasswordStore``.
Bash
~~~~
++++
.. sourcecode:: shell
@ -185,9 +187,8 @@ Bash
.. warning:: If this approach is taken, the passwords will appear in the shell history.
Windows PowerShell
~~~~~~~~~~~~~~~~~~
++++++++++++++++++
.. sourcecode:: shell
@ -203,7 +204,7 @@ For launching on Windows without PowerShell, it is not possible to perform comma
.. warning:: If this approach is taken, the passwords will appear in the windows command prompt history.
.. _ref-backup-recommendations:
.. _backup-recommendations:
Backup recommendations
----------------------

2
docs/source/node-commandline.rst
View File

@ -1,5 +1,5 @@
Node command-line options
====================
=========================
The node can optionally be started with the following command-line options:

10
docs/source/node-database.rst
View File

@ -32,11 +32,19 @@ configuration for PostgreSQL:
Note that:
* Database schema name can be set in JDBC URL string e.g. currentSchema=myschema
* Database schema name can be set in JDBC URL string e.g. *currentSchema=my_schema*
* Database schema name must either match the ``dataSource.user`` value to end up
on the standard schema search path according to the
`PostgreSQL documentation <https://www.postgresql.org/docs/9.3/static/ddl-schemas.html#DDL-SCHEMAS-PATH>`_, or
the schema search path must be set explicitly for the user.
* If your PostgresSQL database is hosting multiple schema instances (using the JDBC URL currentSchema=my_schema)
for different Corda nodes, you will need to create a *hibernate_sequence* sequence object manually for each subsequent schema added after the first instance.
Corda doesn't provision Hibernate with a schema namespace setting and a sequence object may be not created.
Run the DDL statement and replace *my_schema* with your schema namespace:
.. sourcecode:: groovy
CREATE SEQUENCE my_schema.hibernate_sequence INCREMENT BY 1 MINVALUE 1 MAXVALUE 9223372036854775807 START 8 CACHE 1 NO CYCLE;
SQLServer
---------

73
docs/source/node-explorer.rst
View File

@ -26,76 +26,37 @@ Running the UI
Running demo nodes
------------------
A demonstration Corda network topology is configured with 5 nodes playing the following roles:
Node Explorer is included with the :doc:`demobench` application, which allows
you to create local Corda networks on your desktop. For example:
1. Notary
2. Issuer nodes, representing two fictional central banks (UK Bank Plc issuer of GBP and USA Bank Corp issuer of USD)
3. Participant nodes, representing two users (Alice and Bob)
* Notary
* Bank of Breakfast Tea (*Issuer node* for GBP)
* Bank of Big Apples (*Issuer node* for USD)
* Alice (*Participant node*, for user Alice)
* Bob (*Participant node*, for user Bob)
DemoBench will deploy all nodes with Corda's Finance CorDapp automatically, and
allow you to launch an instance of Node Explorer for each. You will also be logged
into the Node Explorer automatically.
When connected to an *Issuer* node, a user can execute cash transaction commands to issue and move cash to itself or other
parties on the network or to exit cash (for itself only).
When connected to a *Participant* node a user can only execute cash transaction commands to move cash to other parties on the network.
The Demo Nodes can be started in one of two modes:
The Node Explorer is also available as a stand-alone JavaFX application. It is
available from the Corda repositories as ``corda-tools-explorer``, and can be
run as
1. Normal
Fresh clean environment empty of transactions.
Firstly, launch an Explorer instance to login to one of the Issuer nodes and issue some cash to the other participants (Bob and Alice).
Then launch another Explorer instance to login to a participant node and start making payments (eg. move cash).
You will only be able to exit (eg. redeem from the ledger) cash as an issuer node.
**Windows**::
gradlew.bat tools:explorer:runDemoNodes
**Other**::
./gradlew tools:explorer:runDemoNodes
2. Simulation
In this mode Nodes will automatically commence executing commands as part of a random generation process.
The simulation start with pre-allocating chunks of cash to each of the party in 2 currencies (USD, GBP), then it enter a loop to generate random events.
In each iteration, the issuers will execute a Cash Issue or Cash Exit command (at a 9:1 ratio) and a random party will execute a move of cash to another random party.
**Windows**::
gradlew.bat tools:explorer:runSimulationNodes
**Other**::
./gradlew tools:explorer:runSimulationNodes
.. note:: 5 Corda nodes will be created on the following port on localhost by default.
* Notary -> 20005 (Does not accept logins)
* UK Bank Plc -> 20011 (*Issuer node*)
* USA Bank Corp -> 20008 (*Issuer node*)
* Alice -> 20017
* Bob -> 20014
Explorer login credentials to the Issuer nodes are defaulted to ``manager`` and ``test``.
Explorer login credentials to the Participants nodes are defaulted to ``user1`` and ``test``.
Please note you are not allowed to login to the notary.
.. note:: When you start the nodes in Windows using the command prompt, they might not be killed when you close the
window or terminate the task. If that happens you need to manually terminate the Java processes running the nodes.
.. note:: Alternatively, you may start the demo nodes from within IntelliJ using either of the run configurations
``Explorer - demo nodes`` or ``Explorer - demo nodes (simulation)``
.. note:: It is also possible to start the Explorer GUI from IntelliJ via ``Explorer - GUI`` run configuration, provided that the optional TornadoFX plugin has been installed first.
java -jar corda-tools-explorer.jar
.. note:: Use the Explorer in conjunction with the Trader Demo and Bank of Corda samples to use other *Issuer* nodes.
Interface
---------
Login
User can login to any Corda node using the explorer. Alternatively, ``gradlew explorer:runDemoNodes`` can be used to start up demo nodes for testing.
Corda node address, username and password are required for login, the address is defaulted to localhost:0 if leave blank.
User can login to any Corda node using the explorer.
Corda node address, username and password are required for login, the address is defaulted to localhost:0 if left blank.
Username and password can be configured via the ``rpcUsers`` field in node's configuration file.
.. image:: resources/explorer/login.png

78
docs/source/node-flow-hospital.rst Normal file
View File

@ -0,0 +1,78 @@
Flow Hospital
=============
Overview
--------
The **flow hospital** refers to a built-in node service that manages flows that have encountered an error.
This service is responsible for recording, tracking, diagnosing, recovering and retrying. It determines whether errored flows should be retried
from their previous checkpoints or have their errors propagate. Flows may be recoverable under certain scenarios (eg. manual intervention
may be required to install a missing contract JAR version). For a given errored flow, the flow hospital service determines the next course of
action towards recovery and retry.
.. note:: The flow hospital will never terminate a flow, but will propagate its error back to the state machine, and ultimately, end user code to handle
if it ultimately proves impossible to resolve automatically.
This concept is analogous to *exception management handling* associated with enterprise workflow software, or
*retry queues/stores* in enterprise messaging middleware for recovering from failure to deliver a message.
Functionality
-------------
Flow hospital functionality is enabled by default in |release|. No explicit configuration settings are required.
There are two aspects to the flow hospital:
- run-time behaviour in the node upon failure, including retry and recovery transitions and policies.
- visualisation of failed flows in the Explorer UI.
.. _flow-hospital-runtime:
Run-time behaviour
~~~~~~~~~~~~~~~~~~
Specifically, there are two main ways a flow is hospitalized:
1. A counterparty invokes a flow on your node that isn’t installed (i.e. missing CorDapp):
this will cause the flow session initialisation mechanism to trigger a ``ClassNotFoundException``.
If this happens, the session initiation attempt is kept in the hospital for observation and will retry if you restart the node.
Corrective action requires installing the correct CorDapp in the node's "cordapps" directory.
.. warning:: There is currently no retry API. If you don’t want to install the cordapp, you should be able to call `killFlow` with the UUID
associated with the failing flow in the node's log messages.
2. Once started, if a flow experiences an error, the following failure scenarios are handled:
* SQLException mentioning a deadlock*:
if this happens, the flow will retry. If it retries more than once, a back off delay is applied to try and reduce contention.
Current policy means these types of failed flows will retry forever (unless explicitly killed). No intervention required.
* Database constraint violation:
this scenario may occur due to natural contention between racing flows as Corda delegates handling using the database's optimistic concurrency control.
As the likelihood of re-occurrence should be low, the flow will actually error and fail if it experiences this at the same point more than 3 times. No intervention required.
* Finality Flow handling - Corda 3.x (old style) ``FinalityFlow`` and Corda 4.x ``ReceiveFinalityFlow`` handling:
if on the receive side of the finality flow, any error will result in the flow being kept in for observation to allow the cause of the
error to be rectified (so that the transaction isn’t lost if, for example, associated contract JARs are missing).
Intervention is expected to be “rectify error, perhaps uploading attachment, and restart node” (or alternatively reject and call `killFlow`).
* `FlowTimeoutException`:
this is used internally by the notary client flow when talking to an HA notary. It’s used to cause the client to try and talk to a different
member of the notary cluster if it doesn't hear back from the original member it sent the request to within a “reasonable” time.
The time is hard to document as the notary members, if actually alive, will inform the requester of the ETA of a response.
This can occur an infinite number of times. i.e. we never give up notarising. No intervention required.
Futures
-------
The flow hospital will be extended in the following areas:
- Human Computer Interaction (HCI) with MQ integration <ref design/CID>
- Addition of Public APIs (and CRaSH utility functions) to trigger retries
- Improved back-off and retry policies
- Improved Explorer visualization operational controls (eg. ability to select and retry or terminate a failed flow).
- Tighter integration with Corda Enterprise monitoring and management tooling

1
docs/source/node-internals-index.rst
View File

@ -5,5 +5,4 @@ Node internals
:maxdepth: 1
node-services
vault
messaging

4
docs/source/node-upgrade-notes.rst
View File

@ -36,7 +36,7 @@ It's always a good idea to make a backup of your data before upgrading any serve
You can simply make a copy of the node's data directory to enable this. If you use an external non-H2 database please consult your database
user guide to learn how to make backups.
We provide some `backup recommendations <backup-recommendations>`_ if you'd like more detail.
We provide some :ref:`backup recommendations <backup-recommendations>` if you'd like more detail.
Step 3. Replace ``corda.jar`` with the new version
--------------------------------------------------
@ -60,4 +60,4 @@ You may now do any checks that you wish to perform, read the logs, and so on. Wh
``run setFlowsDrainingModeEnabled enabled: false``
Your upgrade is complete.
Your upgrade is complete.

BIN
docs/source/resources/certificate_structure.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 365 KiB

After

Width:  |  Height:  |  Size: 165 KiB

4
docs/source/running-a-notary.rst
View File

@ -35,14 +35,14 @@ Crash fault-tolerant (experimental)
===================================
Corda provides a prototype `Raft-based <http://atomix.io/>`_ highly available notary implementation. You can try it out on our
`notary demo <https://github.com/corda/corda/tree/release-V3.1/samples/notary-demo>`_ page. Note that it has known limitations
`notary demo <https://github.com/corda/corda/tree/release/|platform_version|/samples/notary-demo>`_ page. Note that it has known limitations
and is not recommended for production use.
Byzantine fault-tolerant (experimental)
=======================================
A prototype BFT notary implementation based on `BFT-Smart <https://github.com/bft-smart/library>`_ is available. You can
try it out on our `notary demo <https://github.com/corda/corda/tree/release-V3.1/samples/notary-demo>`_ page. Note that it
try it out on our `notary demo <https://github.com/corda/corda/tree/release/|platform_version|/samples/notary-demo>`_ page. Note that it
is still experimental and there is active work ongoing for a production ready solution. Additionally, BFT-Smart requires Java
serialization which is disabled by default in Corda due to security risks, and it will only work in dev mode where this can
be customised.

7
docs/source/shell.rst
View File

@ -26,9 +26,11 @@ Permissions
When accessing the shell (embedded, standalone, via SSH) RPC permissions are required. This is because the shell actually communicates
with the node using RPC calls.
* Watching flows (``flow watch``) requires ``InvokeRpc.stateMachinesFeed``
* Watching flows (``flow watch``) requires ``InvokeRpc.stateMachinesFeed``.
* Starting flows requires ``InvokeRpc.startTrackedFlowDynamic``, ``InvokeRpc.registeredFlows`` and ``InvokeRpc.wellKnownPartyFromX500Name``, as well as a
permission for the flow being started
permission for the flow being started.
* Killing flows (``flow kill``) requires ``InvokeRpc.killFlow``. This currently
allows the user to kill *any* flow, so please be careful when granting it!
The shell via the local terminal
--------------------------------
@ -231,6 +233,7 @@ The shell also has special commands for working with flows:
names and types of the arguments will be used to try and automatically determine which one to use. If the match
against available constructors is unclear, the reasons each available constructor failed to match will be printed
out. In the case of an ambiguous match, the first applicable constructor will be used
* ``flow kill`` kills a single flow, as identified by its UUID.
Parameter syntax
****************

12
docs/source/testnet-explorer-corda.rst
View File

@ -34,21 +34,21 @@ couple of resources.
.. code:: bash
wget https://ci-artifactory.corda.r3cev.com/artifactory/corda-releases/net/corda/corda-finance-contracts-/<VERSION>-corda/corda-finance-contracts-<VERSION>-corda.jar
wget https://ci-artifactory.corda.r3cev.com/artifactory/corda-releases/net/corda/corda-finance-workflows-/<VERSION>-corda/corda-finance-workflows-<VERSION>-corda.jar
wget https://ci-artifactory.corda.r3cev.com/artifactory/corda-releases/net/corda/corda-finance-contracts/|corda_version|/corda-finance-contracts-|corda_version|.jar
wget https://ci-artifactory.corda.r3cev.com/artifactory/corda-releases/net/corda/corda-finance-workflows/|corda_version|/corda-finance-workflows-|corda_version|.jar
This is required to run some flows to check your connections, and to issue/transfer cash to counterparties. Copy it to
the Corda installation location:
.. code:: bash
sudo cp /home/<USER>/corda-finance-<VERSION>-corda.jar /opt/corda/cordapps/
sudo cp /home/<USER>/corda-finance-*-|corda_version|.jar /opt/corda/cordapps/
#. Run the following to create a config file for the finance CorDapp:
.. code:: bash
echo "issuableCurrencies = [ USD ]" > /opt/corda/cordapps/config/corda-finance-<VERSION>-corda.conf
echo "issuableCurrencies = [ USD ]" > /opt/corda/cordapps/config/corda-finance-|corda_version|.conf
#. Restart the Corda node:
@ -70,7 +70,7 @@ couple of resources.
.. code:: bash
http://ci-artifactory.corda.r3cev.com/artifactory/corda-releases/net/corda/corda-tools-explorer/<VERSION>-corda/corda-tools-explorer-<VERSION>-corda.jar
http://ci-artifactory.corda.r3cev.com/artifactory/corda-releases/net/corda/corda-tools-explorer/|corda_version|/corda-tools-explorer-|corda_version|.jar
.. warning:: This Node Explorer is incompatible with the Corda Enterprise distribution and vice versa as they currently
use different serialisation schemes (Kryo vs AMQP).
@ -79,7 +79,7 @@ couple of resources.
.. code:: bash
java -jar corda-tools-explorer-<VERSION>-corda.jar
java -jar corda-tools-explorer-|corda_version|.jar
.. image:: resources/explorer-login.png

4
docs/source/tut-two-party-contract.rst
View File

@ -77,7 +77,7 @@ We can picture this transaction as follows:
Defining IOUContract
--------------------
Let's write a contract that enforces these constraints. We'll do this by modifying either ``TemplateContract.java`` or
``StatesAndContracts.kt`` and updating ``TemplateContract`` to define an ``IOUContract``:
``TemplateContract.kt`` and updating to define an ``IOUContract``:
.. container:: codeset
@ -194,4 +194,4 @@ We've now written an ``IOUContract`` constraining the evolution of each ``IOUSta
must be different entities
Next, we'll update the ``IOUFlow`` so that it obeys these contract constraints when issuing an ``IOUState`` onto the
ledger.
ledger.

4
docs/source/tutorial-attachments.rst
View File

@ -105,7 +105,7 @@ and if so, printed out.
.. container:: codeset
.. literalinclude:: ../../samples/attachment-demo/workflows/src/main/kotlin/net/corda/attachmentdemo/workflows/AttachmentDemo.kt
.. literalinclude:: ../../samples/attachment-demo/src/main/kotlin/net/corda/attachmentdemo/AttachmentDemo.kt
:language: kotlin
:start-after: DOCSTART 1
:end-before: DOCEND 1
@ -115,7 +115,7 @@ transaction and send it to the recipient node:
.. container:: codeset
.. literalinclude:: ../../samples/attachment-demo/workflows/src/main/kotlin/net/corda/attachmentdemo/workflows/AttachmentDemo.kt
.. literalinclude:: ../../samples/attachment-demo/src/main/kotlin/net/corda/attachmentdemo/AttachmentDemo.kt
:language: kotlin
:start-after: DOCSTART 2
:end-before: DOCEND 2

12
docs/source/tutorial-building-transactions.rst
View File

@ -48,15 +48,7 @@ Transactions in Corda contain a number of elements:
period during which the proposed transaction can be committed to the
ledger
A transaction is built by populating a ``TransactionBuilder``. Typically,
the ``TransactionBuilder`` will need to be exchanged back and forth between
parties before it is fully populated. This is an immediate consequence of
the Corda privacy model, in which the input states are likely to be unknown
to the other node.
Once the builder is fully populated, the flow should freeze the ``TransactionBuilder`` by signing it to create a
``SignedTransaction``. This is key to the ledger agreement process - once a flow has attached a node’s signature to a
transaction, it has effectively stated that it accepts all the details of the transaction.
A transaction is built by populating a ``TransactionBuilder``. Once the builder is fully populated, the flow should freeze the ``TransactionBuilder`` by signing it to create a ``SignedTransaction``. This is key to the ledger agreement process - once a flow has attached a node’s signature to a transaction, it has effectively stated that it accepts all the details of the transaction.
It is best practice for flows to receive back the ``TransactionSignature`` of other parties rather than a full
``SignedTransaction`` objects, because otherwise we have to separately check that this is still the same
@ -299,4 +291,4 @@ overall transaction id is still provable from the
not expose that data to the other node directly. A full example of this
can be found in the ``NodeInterestRates`` Oracle code from the
``irs-demo`` project which interacts with the ``RatesFixFlow`` flow.
Also, refer to the :doc:`tutorial-tear-offs`.
Also, refer to the :doc:`tutorial-tear-offs`.

49
docs/source/tutorial-cordapp.rst
View File

@ -224,8 +224,8 @@ Building the example CorDapp
├── certificates
├── corda.jar // The Corda node runtime
├── cordapps // The node's CorDapps
│   ├── corda-finance-contracts-4.0-corda.jar
│   ├── corda-finance-workflows-4.0-corda.jar
│   ├── corda-finance-contracts-|corda_version|.jar
│   ├── corda-finance-workflows-|corda_version|.jar
│   └── cordapp-example-0.1.jar
├── drivers
├── logs
@ -265,14 +265,14 @@ For each node, the ``runnodes`` script creates a node tab/window:
/ /___ /_/ / / / /_/ / /_/ / always say "Ah, Interesting!"
\____/ /_/ \__,_/\__,_/
--- Corda Open Source corda-3.0 (4157c25) -----------------------------------------------
--- Corda Open Source corda-|corda_version| (4157c25) -----------------------------------------------
Logs can be found in : /Users/joeldudley/Desktop/cordapp-example/workflows-kotlin/build/nodes/PartyA/logs
Database connection url is : jdbc:h2:tcp://localhost:59472/node
Incoming connection address : localhost:10005
Listening on port : 10005
Loaded CorDapps : corda-finance-corda-3.0, cordapp-example-0.1, corda-core-corda-3.0
Loaded CorDapps : corda-finance-corda-|corda_version|, cordapp-example-0.1, corda-core-corda-|corda_version|
Node for "PartyA" started up and registered in 38.59 sec
@ -481,6 +481,47 @@ Integration tests
~~~~~~~~~~~~~~~~~
You can run the CorDapp's integration tests by running the ``Run Integration Tests - Kotlin`` run configuration.
.. _tutorial_cordapp_running_tests_intellij:
Running tests in IntelliJ
~~~~~~~~~~~~~~~~~~~~~~~~~
We recommend editing your IntelliJ preferences so that you use the Gradle runner - this means that the quasar utils
plugin will make sure that some flags (like ``-javaagent`` - see :ref:`below <tutorial_cordapp_alternative_test_runners>`) are
set for you.
To switch to using the Gradle runner:
* Navigate to ``Build, Execution, Deployment -> Build Tools -> Gradle -> Runner`` (or search for `runner`)
* Windows: this is in "Settings"
* MacOS: this is in "Preferences"
* Set "Delegate IDE build/run actions to gradle" to true
* Set "Run test using:" to "Gradle Test Runner"
.. _tutorial_cordapp_alternative_test_runners:
If you would prefer to use the built in IntelliJ JUnit test runner, you can add some code to your ``build.gradle`` file and
it will copy your quasar JAR file to the lib directory. You will also need to specify ``-javaagent:lib/quasar.jar``
and set the run directory to the project root directory for each test.
Add the following to your ``build.gradle`` file - ideally to a ``build.gradle`` that already contains the quasar-utils plugin line:
.. sourcecode:: groovy
apply plugin: 'net.corda.plugins.quasar-utils'
task installQuasar(type: Copy) {
destinationDir rootProject.file("lib")
from(configurations.quasar) {
rename 'quasar-core(.*).jar', 'quasar.jar'
}
}
and then you can run ``gradlew installQuasar``.
Debugging your CorDapp
----------------------

9
docs/source/tutorial-integration-testing.rst
View File

@ -126,3 +126,12 @@ about ``CashIssueAndPaymentFlow`` and ``CashPaymentFlow``.
You can find the complete test at ``example-code/src/integration-test/java/net/corda/docs/java/tutorial/test/JavaIntegrationTestingTutorial.java``
(Java) and ``example-code/src/integration-test/kotlin/net/corda/docs/kotlin/tutorial/test/KotlinIntegrationTestingTutorial.kt`` (Kotlin) in the
`Corda repo <https://github.com/corda/corda>`_.
.. note::
To make sure the driver classes are included in your project you will need the following in your ``build.gradle`` file in the module in
which you want to test:
.. sourcecode:: groovy
testCompile "$corda_release_group:corda-node-driver:$corda_release_version"

2
docs/source/tutorial-test-dsl.rst
View File

@ -99,7 +99,7 @@ Let's add a ``CommercialPaper`` transaction:
}
We can add a transaction to the ledger using the ``transaction`` primitive. The transaction in turn may be defined by
specifying ``input``s, ``output``s, ``command``s and ``attachment``s.
specifying ``input``\s, ``output``\s, ``command``\s and ``attachment``\s.
The above ``input`` call is a bit special; transactions don't actually contain input states, just references
to output states of other transactions. Under the hood the above ``input`` call creates a dummy transaction in the

12
docs/source/upgrading-cordapps.rst
View File

@ -259,6 +259,8 @@ a drain is complete there should be no outstanding checkpoints or running flows.
A node can be drained or undrained via RPC using the ``setFlowsDrainingModeEnabled`` method, and via the shell using
the standard ``run`` command to invoke the RPC. See :doc:`shell` to learn more.
.. _contract_upgrading_ref:
Contract and state versioning
-----------------------------
@ -269,7 +271,12 @@ There are two types of contract/state upgrade:
2. *Explicit:* By creating a special *contract upgrade transaction* and getting all participants of a state to sign it
using the contract upgrade flows
This section of the documentation focuses only on *explicit* upgrades.
The general recommendation for Corda 4 is to use **implicit** upgrades for the reasons described :ref:`here <implicit_vs_explicit_upgrades>`.
.. _explicit_contract_upgrades_ref:
Performing explicit contract and state upgrades
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In an explicit upgrade, contracts and states can be changed in arbitrary ways, if and only if all of the state's
participants agree to the proposed upgrade. The following combinations of upgrades are possible:
@ -278,9 +285,6 @@ participants agree to the proposed upgrade. The following combinations of upgrad
* A state is upgraded while the contract stays the same
* The state and the contract are updated simultaneously
Performing explicit contract and state upgrades
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Preserve the existing state and contract definitions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Currently, all nodes must **permanently** keep **all** old state and contract definitions on their node's classpath

6
docs/source/versioning.rst
View File

@ -44,11 +44,13 @@ advertise a minimum platform version of 4 and a target version of 5. These numbe
If this app is loaded into a Corda 6 node, that node may implement backwards compatibility workarounds for your app that make it slower,
less secure, or less featureful. You can opt-in to getting the full benefits of the upgrade by changing your target version to 6. By doing
this, you promise that you understood all the changes in Corda 6 and have thoroughly tested your app to prove it works.
this, you promise that you understood all the changes in Corda 6 and have thoroughly tested your app to prove it works. This testing should
include ensuring that the app exhibits the correct behaviour on a node running at the new target version, and that the app functions
correctly in a network of nodes running at the same target version.
Target versioning is one of the mechanisms we have to keep the platform evolving and improving, without being permanently constrained to
being bug-for-bug compatible with old versions. When no apps are loaded that target old versions, any emulations of older bugs or problems
can be disabled (in Corda 4, an example of this is the old FinalityFlow handler that would accept any transactions into the vault, context free).
can be disabled.
Publishing versions in your JAR manifests
-----------------------------------------

2
docs/source/writing-a-cordapp.rst
View File

@ -42,7 +42,7 @@ You should base your project on one of the following templates:
* `Kotlin Template CorDapp <https://github.com/corda/cordapp-template-kotlin>`_ (for CorDapps written in Kotlin)
Please use the branch of the template that corresponds to the major version of Corda you are using. For example,
someone building a CorDapp on Corda 3.2 should use the ``release-V3`` branch of the template.
someone building a CorDapp on Corda 4.1 should use the ``release-V4`` branch of the template.
Build system
^^^^^^^^^^^^